@nestarc/inbox 0.0.0-stage → 0.2.0

package/docs/releasing.md

@@ -0,0 +1,91 @@
+# GitHub Release에서 npm 배포
+
+`release.yml`은 GitHub Release의 **Publish release** 이벤트로 실행된다. `package.json` 버전이 `0.1.0`이면 태그는 `v0.1.0`, GitHub의 **Set as a pre-release**는 꺼져 있어야 한다. `-preview.1` 같은 prerelease 버전을 사용할 때만 이 옵션을 켠다. 태그만 push하거나 초안을 저장하면 배포하지 않는다.
+
+인증 방식은 다른 nestarc 패키지와 동일한 **npm Trusted Publishing(GitHub OIDC)** 이다. `NPM_TOKEN`이나 `NODE_AUTH_TOKEN` secret을 추가하지 않는다. 배포 job만 `npm` GitHub Environment와 `id-token: write`를 사용하며, 빌드와 테스트 job은 저장소 읽기 권한만 가진다.
+
+## 최초 연결
+
+1. 이 구현과 lockfile을 `nestarc/inbox`의 `main`에 반영한다.
+2. GitHub 저장소 **Settings → Environments → npm**을 준비한다. Deployment branches and tags는 Selected branches and tags로 설정하고 tag 패턴 `v*.*.*`를 허용한다. 팀 정책에 따라 reviewer를 추가할 수 있다.
+3. npm에 `@nestarc/inbox`가 아직 없으면 권한 있는 관리자가 최초 버전을 등록한다. npm의 Trusted Publisher 설정은 이미 존재하는 패키지가 필요하다. 최초 등록에도 아래 검증한 tarball을 사용하고, `0.1.0`은 `--tag latest`, preview는 `--tag next`로 게시한다. 이 작업은 계정 로그인·2FA가 필요한 일회성 절차이며 워크플로우에 장기 토큰을 넣는 대체 경로는 없다.
+4. npm 패키지 **Settings → Trusted Publisher → GitHub Actions**를 아래 값으로 연결한다. 현재 npm 설정에서 **Allow this trusted publisher to publish packages**를 활성화한다. stage만 허용된 설정으로는 이 워크플로우의 직접 publish가 성공하지 않는다.
+
+| 항목                 | 값            |
+| -------------------- | ------------- |
+| Organization or user | `nestarc`     |
+| Repository           | `inbox`       |
+| Workflow filename    | `release.yml` |
+| Environment          | `npm`         |
+
+최신 npm CLI에서 동일한 설정을 만드는 명령은 다음과 같다. 패키지 쓰기 권한과 2FA가 있는 관리자 계정에서 실행한다.
+
+```sh
+npm trust github @nestarc/inbox \
+  --file release.yml \
+  --repo nestarc/inbox \
+  --environment npm \
+  --allow-publish
+```
+
+공식 [Trusted Publishers 안내](https://docs.npmjs.com/trusted-publishers/)와 [npm trust 명령](https://docs.npmjs.com/cli/v11/commands/npm-trust/)을 참고한다. 새 연결은 npm이 정한 활성화 기한 안에 첫 게시를 성공시켜야 한다. 워크플로우는 GitHub hosted runner, Node 24, npm 11.5.1 이상을 사용하고 npm 버전이 부족하면 실패한다. 로컬 검증이나 dry-run으로 원격 OIDC 연결까지 확인할 수는 없다.
+
+최초 수동 등록 이후에는 버전을 올려 첫 OIDC 배포를 확인한다. 이미 게시된 동일 버전은 무결성 확인 후 건너뛰므로 Trusted Publisher의 실제 인증을 검증하지 않는다.
+
+## 릴리즈 절차
+
+1. 버전과 변경 기록을 갱신하고 `package.json`과 `package-lock.json`을 함께 커밋한다. 해당 커밋을 `main`에 병합한다.
+2. 필요하면 Actions의 **Release → Run workflow**로 검증한다. 이 경로는 전체 검증과 `npm publish --dry-run`까지만 실행하며 게시 권한을 요청하지 않는다.
+3. `main`에 포함된 커밋에 `v<package.json 버전>` 태그로 GitHub Release를 게시한다. 버전에 `-preview.1`, `-rc.1` 같은 prerelease 식별자가 있으면 GitHub prerelease 체크도 켠다.
+4. Release 실행에서 `publish` job 성공과 npm 버전·integrity 확인 결과를 확인한다.
+
+| 버전 예           | GitHub prerelease | npm dist-tag |
+| ----------------- | ----------------- | ------------ |
+| `0.1.0-preview.1` | 켬                | `next`       |
+| `0.1.0-rc.1`      | 켬                | `next`       |
+| `0.1.0`           | 끔                | `latest`     |
+
+현재 `publishConfig.tag`는 `latest`이며, 배포 명령은 버전에 따라 `latest` 또는 `next`를 명시해 기본 설정을 덮어쓴다. 태그·버전·prerelease 표시가 불일치하거나 태그 커밋이 `main` 이력에 없으면 테스트와 게시 전에 거절한다. 빌드 메타데이터가 있는 버전(`1.0.0+build`)은 받지 않는다.
+
+## 검증과 배포물
+
+CI와 Release는 `release-validation.yml`을 공유한다. Node 22에서 한 번 빌드한 후 `package.tgz`와 `metadata.json`을 보관한다. metadata는 저장소·commit·ref·버전, 파일 목록, SHA-256과 npm SHA-512 integrity를 기록한다. SQL 설치/upgrade 파일, JavaScript 및 타입 진입점이 필요하며 환경 파일·의존성 디렉터리·생성 client·private workspace 패키지와 archive link는 거절한다.
+
+Node 22/24 × PostgreSQL 16/18의 네 job이 같은 tarball을 내려받아 실제 DB 통합/복구 테스트와 독립 consumer 설치를 실행한다. Node 24/PostgreSQL 16에서는 tarball 내부 예제 8종을 실제 임시 브로커와 함께 검사한다. 각 consumer는 복사본을 읽기 전용으로 사용하며 실행 전후 원본·복사본·metadata 변경을 검사한다.
+
+네 조합과 별도 Node 24/PostgreSQL 16 운영 복구 job이 모두 성공해야 배포 job이 실행된다. 운영 job은 같은 커밋을 빌드하여 TCP 단절·blackhole, 연결 풀 포화, SIGTERM 종료, 실제 standby 승격, 제한된 tablespace 공간 고갈, RabbitMQ 재시작·retry·DLQ를 확인한다. 지속 부하 benchmark는 별도 수동 측정이며 CI의 성능 합격 기준으로 사용하지 않는다. 배포 job에서는 의존성 설치·빌드·재패킹을 하지 않고 해당 tarball을 `--ignore-scripts --provenance`로 게시한다. 게시 후 레지스트리의 integrity가 검증한 tarball과 같은지 확인한다.
+
+npm은 게시 요청을 받은 뒤 설치 가능 상태가 되기 전에 패키지를 검사한다. 공식 [게시 시점 검사 안내](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/)에 따르면 보통 약 5분, 혼잡하거나 추가 검토가 필요하면 15분 이상 걸릴 수 있다. 게시 성공 직후의 404만으로 실패나 미게시를 판단하지 않는다. 워크플로우는 30초 간격으로 진행 상황을 출력하며 최대 20분 동안 공개 여부와 integrity를 확인하고, 배포 job에는 총 30분을 허용한다. 내용 불일치와 404 이외의 조회 오류는 즉시 실패한다.
+
+확인 시간이 초과되어도 같은 버전을 다시 게시하거나 전체 publish job을 바로 재실행하지 않는다. npm의 검사 상태·알림을 확인하고, 원래 검증한 `package.tgz`와 `metadata.json`을 보존한 채 확인 명령만 다시 실행한다. 검사에 더 오래 걸리거나 수동 검토가 필요한 경우 이 제한 안에 공개되지 않을 수 있다.
+
+```sh
+node scripts/release-artifact.mjs verify-published "$INBOX_RELEASE_TARBALL" "$INBOX_RELEASE_METADATA"
+```
+
+같은 버전이 이미 존재하면 bytes가 같은 경우만 게시를 건너뛴다. 다른 bytes이거나 레지스트리 조회가 404 이외의 오류이면 실패한다. 기존 버전을 덮어쓰지 말고 원인을 확인한 다음 새 버전을 사용한다. 같은 버전의 재실행은 기존 dist-tag를 이동시키지 않는다.
+
+## 로컬 재현
+
+Node 22.14 이상과 Docker가 필요하다. 임시 디렉터리는 저장소 밖에 둔다.
+
+```sh
+npm ci
+npm run format:check
+npm run test:release
+npm run build
+npm run typecheck
+npm test
+npm run test:integration
+
+INBOX_CANDIDATE_DIR=$(mktemp -d)
+node scripts/release-artifact.mjs pack "$INBOX_CANDIDATE_DIR"
+export INBOX_RELEASE_TARBALL="$INBOX_CANDIDATE_DIR/package.tgz"
+export INBOX_RELEASE_METADATA="$INBOX_CANDIDATE_DIR/metadata.json"
+npm run test:package
+npm run test:examples
+node scripts/release-artifact.mjs verify "$INBOX_RELEASE_TARBALL" "$INBOX_RELEASE_METADATA"
+npm publish "$INBOX_RELEASE_TARBALL" --ignore-scripts --access public --tag latest --dry-run
+```
+
+`INBOX_RELEASE_TARBALL`과 `INBOX_RELEASE_METADATA`는 둘 다 절대 경로로 지정한다. 두 변수를 생략한 일반 `test:package` / `test:examples` 실행은 기존처럼 로컬에서 빌드와 pack을 수행한다.

package/docs/testing.md

@@ -0,0 +1,86 @@
+# Testing application handlers
+
+`@nestarc/inbox/testing` provides bounded helpers for integration tests using a real `InboxService` and the application's PostgreSQL test database. It has no additional runtime dependencies and works with any test runner. Apply the Inbox SQL schema through your test fixture before creating the service.
+
+## Process specific receipts
+
+Disable automatic polling to control when processing starts. Register your application's real handler and pass the admin view for its trusted tenant scope:
+
+```ts
+import { InboxService } from "@nestarc/inbox";
+import { drainInbox } from "@nestarc/inbox/testing";
+
+const inbox = new InboxService({
+  prisma,
+  handlers: [orderProjectionHandler],
+  worker: {
+    enabled: false,
+    retryBaseMs: 10,
+    retryMaxMs: 20,
+  },
+});
+
+try {
+  const receipt = await inbox.accept({
+    scope: { kind: "tenant", id: "tenant-a" },
+    source: "orders",
+    consumer: orderProjectionHandler.consumer,
+    messageId: "order-event-1",
+    eventType: orderProjectionHandler.eventType,
+    schemaVersion: orderProjectionHandler.schemaVersion,
+    payload: { orderId: "order-1" },
+  });
+
+  const [completed] = await drainInbox(
+    inbox,
+    inbox.admin.forTenant("tenant-a"),
+    [receipt.id],
+    { timeoutMs: 5_000 },
+  );
+
+  // completed.status is COMPLETED. Assert your actual business-table result too.
+  // A repeat delivery should return the same receipt and leave that result unchanged.
+} finally {
+  await inbox.close();
+  // Disconnect the application's Prisma client after the worker has stopped.
+}
+```
+
+`drainInbox(inbox, admin, receiptIds, options)` checks each requested receipt and calls the real `runOnce()` between state checks until every receipt is `COMPLETED`. A zero-claim poll does not finish the helper: the message may be waiting for a retry or lease expiry. Retries use the worker's real schedule and do not advance a fake database clock. Configure short retry delays explicitly in tests when appropriate.
+
+Receipt IDs select the completion assertions, **not the worker's claims**. `runOnce()` may process other receipts for its registered consumers, including other tenants. The scoped admin view restricts reads; it does not change worker ownership. Use an isolated database or dedicated test consumers, and avoid other workers when testing deterministic ordering. Receipt IDs are deduplicated, results preserve their first occurrence order, and an empty list returns immediately. A call accepts at most 1,000 IDs.
+
+## Observe an existing worker
+
+`waitForInboxRecord()` only reads a receipt; it never starts processing, requeues a failure or changes the database. Use it with automatic polling or a separately managed worker:
+
+```ts
+import { waitForInboxRecord } from "@nestarc/inbox/testing";
+
+const completed = await waitForInboxRecord(admin, receipt.id);
+
+// For a test deliberately exhausting retries:
+const dead = await waitForInboxRecord(admin, failedReceipt.id, {
+  status: "DEAD",
+  timeoutMs: 10_000,
+});
+```
+
+The expected status is `COMPLETED` by default, or `DEAD` when specified. Observing the other terminal state fails immediately. A missing or out-of-scope record remains pending until the timeout or pass limit; this helper cannot distinguish those two cases.
+
+## Limits and failures
+
+Both helpers accept these options:
+
+| Option           | Default | Meaning                                                                     |
+| ---------------- | ------- | --------------------------------------------------------------------------- |
+| `timeoutMs`      | `5000`  | Overall budget including database reads and worker calls                    |
+| `pollIntervalMs` | `10`    | Delay between state-check passes                                            |
+| `maxPasses`      | `1000`  | Maximum state-check passes; no new worker call starts after the final check |
+| `signal`         | None    | An `AbortSignal` that stops waiting and starting new polls                  |
+
+Numeric options must be positive 32-bit integers. A stalled `get()` or `runOnce()` is also covered by the overall timeout. Timeout or cancellation stops the helper's wait; an already running database operation or handler may still finish. Always close the service before disconnecting Prisma or tearing down the fixture. These helpers do not create or reset databases and do not replace the runtime's transaction timeouts.
+
+`InboxTestError` exposes `code` and a `records` snapshot containing only receipt IDs, last observed states and attempt counts. Codes are `TIMEOUT`, `ABORTED`, `PASS_LIMIT`, `UNEXPECTED_TERMINAL_STATE` and `INVALID_OPTIONS`. The helper's diagnostics omit payloads, tenant values and raw handler errors. Underlying database errors propagate unchanged so a broken database cannot be mistaken for an unfinished receipt.
+
+Use real timers for PostgreSQL integration tests: advancing a test runner's fake timers does not advance PostgreSQL retry or lease timestamps. A successful wait proves that the requested receipts reached the expected state; assert application rows and outbox results separately to verify business effects.

package/docs/usage.md

@@ -0,0 +1,266 @@
+# @nestarc/inbox usage
+
+This document describes the 0.2.0 API. Inbox durably receives messages and processes them with Prisma and PostgreSQL. The application owns authentication, broker acknowledgments, its Prisma client, and migration deployment. APIs and schema may change before 1.0; review the [changelog](../CHANGELOG.md) before upgrading. For application integration tests, see the [bounded testing helpers](testing.md).
+
+Install with `npm install @nestarc/inbox@0.2.0`. To evaluate a source build, run `npm ci` and `npm pack` in the repository, then install the resulting `nestarc-inbox-0.2.0.tgz` in your application.
+
+## Initialize the schema and Prisma client
+
+Apply the SQL exported as `@nestarc/inbox/sql/create-inbox-table.sql` through your application's migration process before starting Inbox. Runtime initialization checks the schema; it does not create or upgrade tables. Keep the inbox SQL tables in your migration history and do not let Prisma schema synchronization remove unmanaged tables.
+
+Versions 0.1.0 and 0.2.0 require schema version 2; upgrading from 0.1.0 needs no SQL migration. If you used schema v1 in a local development build, stop those processes, apply the exported `@nestarc/inbox/sql/migrate-v1-to-v2.sql`, then start 0.2.0 workers. The transactional migration preserves receipt identity, payloads, state, attempts, and tokens and may be applied again safely. It takes a table lock, so schedule the upgrade appropriately. Fresh installs use the current creation SQL. Old workers must not be restarted against v2. Local Preview.1 builds already use schema v2; the 0.1.0 promotion adds no schema change.
+
+Prisma 7 requires a driver adapter. Construct one application-owned client and pass it to Inbox:
+
+```ts
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "./generated/prisma/client";
+
+const prisma = new PrismaClient({
+  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+});
+```
+
+Use the API for your installed Prisma major. The [runnable examples](../examples/README.md) pin Prisma 7 and support the npm package or a local tarball; automated package checks use a tarball built from the checkout.
+
+## Register a consumer
+
+Register stable logical consumer names and explicitly enable the worker:
+
+```ts
+import { Module } from "@nestjs/common";
+import { InboxModule, InboxPermanentError } from "@nestarc/inbox";
+import type { Prisma } from "./generated/prisma/client";
+import type { InboxHandler } from "@nestarc/inbox";
+
+const handler: InboxHandler<{ orderId: string }, Prisma.TransactionClient> = {
+  consumer: "orders.projection.v1",
+  eventType: "order.created",
+  schemaVersion: 1,
+  validate(payload) {
+    return (
+      !!payload &&
+      typeof payload === "object" &&
+      !Array.isArray(payload) &&
+      typeof payload.orderId === "string"
+    );
+  },
+  async handle(payload, context) {
+    if (context.scope.kind !== "tenant") throw new InboxPermanentError();
+    await context.tx.orderProjection.create({
+      data: { tenantId: context.scope.id, orderId: payload.orderId },
+    });
+  },
+};
+
+@Module({
+  imports: [
+    InboxModule.forRoot({
+      prisma,
+      handlers: [handler],
+      worker: { enabled: true },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+The application defines its Prisma models and supplies `prisma` above. For dependency injection, use `InboxModule.forRootAsync({ imports, inject, useFactory })`; the factory returns the same options. Create handlers inside the factory when they depend on other Nest services.
+
+Worker processing is disabled unless `worker.enabled` is true. An ingress-only process supplies `consumers: ['orders.projection.v1']` and no handlers. A worker process registers handlers and may restrict processing through `worker.consumers`. Claiming, lease recovery, and exhausted-attempt handling stay inside that list. A missing handler for a configured worker consumer or a duplicate handler registration fails startup.
+
+Removing every worker for a consumer leaves its backlog pending. Monitor backlog age before removing a deployment. Unsupported event types or schema versions for a registered consumer are retained as DEAD; they are never silently acknowledged as completed business work.
+
+## Worker configuration
+
+| Option                        | Default                  | Meaning                                                                 |
+| ----------------------------- | ------------------------ | ----------------------------------------------------------------------- |
+| `worker.enabled`              | `false`                  | Start polling during application initialization                         |
+| `worker.consumers`            | Registered handler names | The worker's explicit ownership list                                    |
+| `worker.concurrency`          | `4`                      | Maximum claimed, active records; upper bound 100                        |
+| `worker.pollIntervalMs`       | `1000`                   | Delay between polling opportunities                                     |
+| `worker.leaseMs`              | `30000`                  | Database lease duration                                                 |
+| `worker.heartbeatIntervalMs`  | `5000`                   | Renewal interval; must be less than half the lease duration             |
+| `worker.transactionTimeoutMs` | `10000`                  | Maximum handler transaction duration                                    |
+| `worker.transactionMaxWaitMs` | `5000`                   | Maximum wait to acquire a Prisma transaction connection                 |
+| `worker.lockTimeoutMs`        | `1000`                   | Database lock-wait bound for the handler transaction                    |
+| `worker.shutdownTimeoutMs`    | `15000`                  | Bounded drain interval on shutdown                                      |
+| `worker.maxAttempts`          | `8`                      | Total claims per retry cycle, including the initial attempt and crashes |
+| `worker.retryBaseMs`          | `1000`                   | Base for exponential retry delay                                        |
+| `worker.retryMaxMs`           | `300000`                 | Maximum retry delay before jitter                                       |
+| `maxPayloadBytes`             | `262144`                 | Accepted JSON payload size in UTF-8 bytes                               |
+| `maxPendingMessages`          | Unset                    | Optional approximate backlog admission bound                            |
+
+Keep enough pool connections available for admission, heartbeat, and state changes in addition to handler transactions. Larger concurrency does not automatically improve throughput. Leave external network work out of the transaction and tune limits with measurements from your own database.
+
+For explicit execution without a continuously polling process, `InboxService.initialize()` checks the schema, `runOnce()` processes a bounded batch, and `close()` stops the worker. A Nest module invokes initialization and shutdown automatically. `close()` does not disconnect the application's Prisma client.
+
+## Accept a message and acknowledge it
+
+```ts
+const receipt = await inbox.accept({
+  scope: { kind: "tenant", id: verifiedTenantId },
+  source: "orders-service",
+  consumer: "orders.projection.v1",
+  messageId: event.id,
+  eventType: "order.created",
+  schemaVersion: 1,
+  payload: { orderId: event.orderId },
+});
+channel.ack(message);
+```
+
+`accept()` resolves only after its own transaction commits. It returns `{ kind: 'accepted' | 'duplicate', id, status }`. Both kinds permit transport acknowledgment. A duplicate can refer to a PENDING, PROCESSING, RETRYABLE, COMPLETED, or DEAD record; it never resets processing state or retry budgets. DEAD records require operator intervention.
+
+A storage exception or uncertain acceptance commit result must not produce a success ACK. Let the transport redeliver the same stable identity. Authentication failures, invalid input, and identity conflicts require an explicit rejection or transport dead-letter policy rather than a hot retry loop.
+
+Inbox does not acknowledge messages, return HTTP responses, or connect to brokers itself. [Runnable RabbitMQ and webhook examples](../examples/README.md) show those application boundaries.
+
+## Identity and payload
+
+The unique identity combines scope, source, consumer, and message ID. Scope is either `{ kind: 'tenant', id }` or `{ kind: 'global' }`. Tenant IDs are application-authenticated values; scope selection alone does not implement PostgreSQL RLS.
+
+Use a producer's stable event ID. Do not use a delivery tag, attempt count, or a new random ID for every redelivery. Renaming a consumer creates a different logical effect and permits processing again.
+
+Fingerprinting covers event type, schema version, and canonical JSON payload. Object key order does not change identity content; array order does. Trace headers, correlation ID, and causation ID are metadata and do not participate. Keep values that affect business decisions inside the payload.
+
+The same identity with different fingerprint throws `InboxConflictError` with code `IDENTITY_CONFLICT` and leaves the existing record unchanged. JSON must contain only supported JSON values. Non-finite numbers, undefined, arbitrary class instances, circular values, excessive depth, and values exceeding configured limits are rejected. No value is silently truncated to fit.
+
+## Handler transaction and retries
+
+Use only `context.tx` for handler writes. Inbox adds the fenced completion write and commits the whole transaction. Let transaction errors escape. Calling another Prisma client, nesting a separate transaction, or making an external API call breaks this atomic boundary.
+
+An outbox event can join the same transaction:
+
+```ts
+await outbox.emit(context.tx, new OrderProjectedEvent(payload.orderId), {
+  tenantId: context.scope.kind === "tenant" ? context.scope.id : undefined,
+  ...(context.scope.kind === "global"
+    ? { tenantScope: "global" as const }
+    : {}),
+  causationId: context.messageId,
+});
+```
+
+Handler invocations can repeat. Successfully committed same-database effects are deduplicated while the completion receipt remains. Different event IDs for the same business action still require an application unique constraint. Ordering is not guaranteed.
+
+Claims consume an attempt before handler execution, so crashes consume retry budget too. A normal error schedules a durable retry using capped exponential backoff and full jitter. `InboxPermanentError`, invalid handler payloads, unsupported schemas, and exhausted attempts lead to DEAD. Error details are redacted before persistence and observation.
+
+Heartbeats extend only an owned, unexpired lease. Stale completion rolls back handler writes. `context.signal` is an advisory cancellation signal; handlers should stop cooperative work when it aborts. Database and callback timeouts bound the transaction even when a handler ignores that signal. No cancellation mechanism can undo an external API call.
+
+When a completion commit response is lost, Inbox reads the current record before deciding on a failure transition. If that read is unavailable, it leaves recovery to the durable lease rather than overwriting a potentially completed record.
+
+## Configuration
+
+The default settings favor short database work. All durations are milliseconds.
+
+| Option                                                 | Default                             |
+| ------------------------------------------------------ | ----------------------------------- |
+| `worker.enabled`                                       | `false`                             |
+| `worker.concurrency` / `pollIntervalMs`                | `4` / `1000`                        |
+| `worker.leaseMs` / `heartbeatIntervalMs`               | `30000` / `5000`                    |
+| `worker.transactionTimeoutMs` / `transactionMaxWaitMs` | `10000` / `5000`                    |
+| `worker.lockTimeoutMs` / `shutdownTimeoutMs`           | `1000` / `15000`                    |
+| `worker.maxAttempts`                                   | `8`, including the initial attempt  |
+| `worker.retryBaseMs` / `retryMaxMs`                    | `1000` / `300000`, with full jitter |
+| `maxPayloadBytes`                                      | `262144` (256 KiB)                  |
+| `maxPendingMessages`                                   | No configured admission limit       |
+
+Handler deadlines bound heartbeats. Failure reconciliation has a separate deadline of at most five seconds so an unavailable status query cannot hold a worker slot forever. Configure the application's Prisma driver pool with enough connections for business transactions and control queries; Inbox does not create a second pool.
+
+## Administration
+
+Bind the tenant scope before reading or changing records:
+
+```ts
+const tenant = admin.forTenant(authenticatedTenantId);
+const page = await tenant.list({ status: "DEAD", limit: 50 });
+const item = await tenant.get(recordId);
+if (item?.status === "DEAD") {
+  await tenant.requeue({
+    id: item.id,
+    expectedVersion: item.rowVersion,
+    reason: "Handler corrected and deployed",
+    actor: operatorId,
+  });
+}
+const stats = await tenant.stats();
+```
+
+The application authorizes the operator and derives the tenant scope. `forGlobal()` manages intentionally global records, not all tenants. `InboxPrivilegedAdminService` is an explicitly enabled, cross-tenant operator surface; configure `privilegedAdmin: true` only in an authorized control-plane application and never expose it directly as a tenant-facing controller. For `forRootAsync`, that opt-in belongs at the top level beside `imports`, `inject`, and `useFactory`, not in the returned factory options.
+
+Requeue only accepts DEAD with the observed version. Concurrent or repeated stale operations fail with `InboxStateConflictError`. It keeps the original payload, identity, claim token, lifetime attempts, and requeue history counters, and resets the current retry-cycle budget. COMPLETED receipts cannot be reset through requeue; use the separate explicit replay API below.
+
+### Explicit replay of a completed message
+
+Replay deliberately permits another logical processing operation. It creates a new PENDING receipt and leaves the original completion and deduplication identity unchanged. Choose a handler whose business semantics allow reprocessing, for example a projection rebuild consumer. Business uniqueness and external side effects still need their own contracts.
+
+```ts
+const original = await admin.forTenant(authenticatedTenantId).get(originalId);
+if (original?.status === "COMPLETED") {
+  const replay = await admin.forTenant(authenticatedTenantId).replay({
+    id: original.id,
+    expectedVersion: original.rowVersion,
+    requestId: persistedOperatorRequestUuid,
+    targetConsumer: "orders.projection.rebuild.v1",
+    actor: operatorId,
+    reason: "Rebuild the projection after deploying the corrected handler",
+  });
+  // replay.kind is accepted or duplicate; replay.record is the new receipt.
+}
+```
+
+Generate and persist one UUID per intended operator request, then reuse it unchanged after timeouts. The UUID is unique within the original tenant/global scope. Reusing it with different arguments throws `InboxReplayConflictError`. Retrying the same request returns its existing receipt even after payload cleanup. A new request needs a retained COMPLETED payload and the observed version; otherwise it fails. Payload mutation is not supported. The destination consumer must have a deployed matching handler; replay does not create one. `record.replay` and `context.replay` expose original inbox ID, source version, request ID, actor, reason, and request time. Payload cleanup preserves this lineage.
+
+### Tenant context in the handler transaction
+
+Install the optional `@nestarc/tenancy` peer and inject its context and service:
+
+```ts
+InboxModule.forRootAsync({
+  imports: [TenancyModule],
+  inject: [PrismaService, TenancyService],
+  useFactory: (prisma, tenancy) => ({
+    prisma,
+    handlers,
+    handlerContext: createInboxTenancyContext({
+      context: new TenancyContext(),
+      tenancy,
+    }),
+    worker: { enabled: true },
+  }),
+});
+```
+
+Use the application's raw Prisma client, not the tenancy extension that opens transactions of its own. The adapter binds async tenant context and sets the service's canonical PostgreSQL tenant setting with transaction-local `set_config` before invoking the handler on the same `context.tx`. The setting clears on commit or rollback. The application authenticates the scope, installs policies using that setting, and runs with a non-owner, non-superuser, non-BYPASSRLS database role. Inbox control tables are worker-owned; tenant isolation policies apply to application data. Scope selection alone does not authorize access.
+
+`TenancyModule` 0.16.2 exports `TenancyService`, not the `TenancyContext` provider. Its public `new TenancyContext()` shares the package's async-local storage with the injected service. Import the configured tenancy module and the application's Prisma provider module into the factory module; the runnable example shows the full wiring.
+
+Global messages default to a permanent rejection. `global: "shared"` explicitly permits shared-table work with an empty tenant setting; it does not bypass RLS or expose tenant rows. Generic `handlerContext(context, next)` wrappers must invoke and await `next()` exactly once; skipping it, invoking it twice, or swallowing a handler failure cannot produce a successful completion. Canceled work cannot start the handler after delayed context setup.
+
+The tested tenancy version is 0.16.2, whose Node engine range is stricter than Inbox's: use Node 22.23.4+ on the 22 branch or 24.22.1+ on the 24 branch for that optional integration.
+
+List results contain `records` and `nextCursor`. Pass the cursor back with the same filters to continue. Pagination order does not imply event execution order. Statistics count retained records and report the oldest pending work, so large histories have a query cost.
+
+## Retention and observability
+
+Completed payload cleanup is explicit:
+
+```ts
+await admin.forTenant(authenticatedTenantId).purgeCompletedPayload({
+  before: new Date("2026-01-01T00:00:00Z"),
+  limit: 100,
+});
+```
+
+This removes eligible COMPLETED payloads while preserving identity and fingerprint. It does not delete PENDING, PROCESSING, RETRYABLE, or DEAD payloads. Retained receipts keep old redeliveries deduplicated. Manually deleting a receipt ends that guarantee; restoring an older database backup also restores an older deduplication history.
+
+`observer(event)` receives bounded, redacted observations for accepted, duplicate, completed, retry, dead, lease-lost, and infrastructure-error outcomes. Observers are best-effort and must not be used as a durable audit trail. Avoid high-cardinality metrics labels and monitor backlog age, DEAD count, pool pressure, and processing delay. Unknown or inactive consumers can otherwise accumulate pending work without a running owner.
+
+The optional `maxPendingMessages` admission check is approximate under concurrency; it is not a strict quota. Duplicate acceptance remains valid when that limit is reached. Database exhaustion or admission rejection must remain a failed acceptance, never a success ACK.
+
+## Shutdown and compatibility
+
+Enable Nest shutdown hooks for operating-system signals, and close the Nest application before disconnecting its Prisma pool. Inbox stops new claims, drains active work within its shutdown limit, and aborts timed-out work so leases can recover. The process manager's grace period should accommodate application cleanup.
+
+Support declarations must match the executed compatibility suite. See repository validation results for tested Node, NestJS, Prisma, and PostgreSQL versions; the planning matrix is not itself evidence of support. Release migrations, actual SQL assets, and packed-consumer tests are part of that contract.