@nestarc/inbox 0.0.0-stage → 0.2.0

package/dist/worker/inbox-worker.js

@@ -0,0 +1,343 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxWorker = void 0;
+const node_crypto_1 = require("node:crypto");
+const reliability_core_1 = require("../internal/reliability-core");
+const handler_context_1 = require("../internal/handler-context");
+const errors_1 = require("../contracts/errors");
+/** Internal polling worker. Business effects and completion are committed by storage.run(). */
+class InboxWorker {
+    storage;
+    options;
+    observer;
+    handlerContext;
+    workerId = (0, node_crypto_1.randomUUID)();
+    handlers = new Map();
+    active = new Set();
+    controllers = new Set();
+    claimPromise = null;
+    timer;
+    running = false;
+    stopped = false;
+    stopPromise;
+    constructor(storage, handlers, options, observer, handlerContext) {
+        this.storage = storage;
+        this.options = options;
+        this.observer = observer;
+        this.handlerContext = handlerContext;
+        for (const handler of handlers) {
+            if (this.handlers.has(handler.consumer)) {
+                throw new errors_1.InboxConfigurationError("Each consumer must have exactly one registered handler.");
+            }
+            this.handlers.set(handler.consumer, handler);
+        }
+        for (const consumer of options.consumers) {
+            if (!this.handlers.has(consumer)) {
+                throw new errors_1.InboxConfigurationError("Every worker-owned consumer must have a registered handler.");
+            }
+        }
+    }
+    /** Start background polling. Schema validation must have succeeded first. */
+    start() {
+        if (this.running || this.stopped || !this.options.enabled)
+            return;
+        this.running = true;
+        this.schedule(0);
+    }
+    /** Claim only free slots and wait for this batch. Concurrent calls cannot oversubscribe. */
+    async tick() {
+        if (this.stopped ||
+            this.claimPromise ||
+            this.options.consumers.length === 0)
+            return 0;
+        const capacity = this.options.concurrency - this.active.size;
+        if (capacity <= 0)
+            return 0;
+        const claiming = Promise.resolve().then(() => this.stopped
+            ? []
+            : this.storage.claim(this.options.consumers, capacity, this.workerId, this.options.leaseMs, this.options.maxAttempts));
+        this.claimPromise = claiming;
+        let records;
+        try {
+            records = await claiming;
+            // Shutdown can race the DB claim. Do not execute or renew newly returned claims;
+            // their durable leases will expire and another worker can recover them.
+            if (this.stopped)
+                return records.length;
+            const batch = records.map((record) => {
+                // Defer execution until the promise is tracked and capacity is reserved.
+                const task = Promise.resolve().then(() => this.process(record));
+                this.active.add(task);
+                void task.then(() => this.active.delete(task), () => this.active.delete(task));
+                return task;
+            });
+            this.claimPromise = null;
+            await Promise.all(batch);
+            return records.length;
+        }
+        finally {
+            if (this.claimPromise === claiming)
+                this.claimPromise = null;
+        }
+    }
+    /** Stop is terminal and idempotent. Expired in-flight work is recovered via its lease. */
+    stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        this.stopped = true;
+        this.running = false;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.stopPromise = this.drain();
+        return this.stopPromise;
+    }
+    schedule(delayMs) {
+        if (!this.running || this.stopped)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            if (!this.running || this.stopped)
+                return;
+            void this.tick().catch(() => this.observe({ type: "error", code: "CLAIM_FAILED" }));
+            this.schedule(this.options.pollIntervalMs);
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    async drain() {
+        let deadline;
+        const expired = new Promise((resolve) => {
+            deadline = setTimeout(() => {
+                for (const controller of this.controllers) {
+                    controller.abort(new errors_1.InboxLeaseLostError());
+                }
+                resolve();
+            }, this.options.shutdownTimeoutMs);
+        });
+        const settled = (async () => {
+            await this.claimPromise?.catch(() => undefined);
+            await Promise.allSettled([...this.active]);
+        })();
+        try {
+            await Promise.race([settled, expired]);
+        }
+        finally {
+            if (deadline)
+                clearTimeout(deadline);
+        }
+    }
+    async process(record) {
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        let heartbeatTimer;
+        let finished = false;
+        // Include connection-pool waiting. Lease renewals cannot keep a hung handler alive forever.
+        const deadline = setTimeout(() => controller.abort(new errors_1.InboxTimeoutError()), this.options.transactionMaxWaitMs + this.options.transactionTimeoutMs);
+        deadline.unref?.();
+        const scheduleHeartbeat = () => {
+            if (finished || controller.signal.aborted)
+                return;
+            heartbeatTimer = setTimeout(() => {
+                heartbeatTimer = undefined;
+                if (finished || controller.signal.aborted)
+                    return;
+                void (async () => {
+                    try {
+                        const owned = await this.storage.heartbeat(record.id, record.claimToken, this.options.leaseMs);
+                        if (!owned)
+                            controller.abort(new errors_1.InboxLeaseLostError());
+                    }
+                    catch {
+                        // A failed renewal cannot prove continued ownership. Stop business work;
+                        // never extend the same token after its lease has expired.
+                        controller.abort(new errors_1.InboxLeaseLostError());
+                    }
+                    finally {
+                        scheduleHeartbeat();
+                    }
+                })();
+            }, this.options.heartbeatIntervalMs);
+            heartbeatTimer.unref?.();
+        };
+        scheduleHeartbeat();
+        let classified;
+        try {
+            if (this.stopped)
+                throw new errors_1.InboxLeaseLostError();
+            const handler = this.handlers.get(record.consumer);
+            if (!handler ||
+                handler.eventType !== record.eventType ||
+                handler.schemaVersion !== record.schemaVersion) {
+                classified = {
+                    code: "UNSUPPORTED_MESSAGE",
+                    message: "The owned consumer does not support this event type or schema version.",
+                    permanent: true,
+                };
+                throw new errors_1.InboxPermanentError();
+            }
+            try {
+                const valid = handler.validate?.(record.payload);
+                // Runtime callers can bypass TypeScript. Async validators are not supported.
+                if (valid !== undefined && valid !== true) {
+                    if (valid &&
+                        typeof valid.then === "function") {
+                        void Promise.resolve(valid).catch(() => undefined);
+                    }
+                    throw new errors_1.InboxPermanentError();
+                }
+            }
+            catch {
+                classified = {
+                    code: "INVALID_PAYLOAD",
+                    message: "The payload failed consumer validation.",
+                    permanent: true,
+                };
+                throw new errors_1.InboxPermanentError();
+            }
+            await this.storage.run(record, async (tx) => {
+                const context = {
+                    tx,
+                    scope: record.scope,
+                    messageId: record.messageId,
+                    source: record.source,
+                    consumer: record.consumer,
+                    inboxId: record.id,
+                    attempt: record.attemptCount,
+                    signal: controller.signal,
+                    replay: record.replay,
+                    correlationId: record.correlationId,
+                    causationId: record.causationId,
+                };
+                await (0, reliability_core_1.withAbort)(controller.signal, () => (0, handler_context_1.runInHandlerContext)(context, () => handler.handle(record.payload, context), this.handlerContext));
+                // An ignored signal must still cause rollback before the completion CAS.
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+            }, {
+                timeoutMs: this.options.transactionTimeoutMs,
+                maxWaitMs: this.options.transactionMaxWaitMs,
+                lockTimeoutMs: this.options.lockTimeoutMs,
+            });
+            this.observe({ type: "completed", consumer: record.consumer });
+        }
+        catch (error) {
+            // Stop renewing as soon as a transaction fails, including while reconciling an
+            // unknown commit outcome on a new connection.
+            finished = true;
+            if (heartbeatTimer)
+                clearTimeout(heartbeatTimer);
+            if (error instanceof errors_1.InboxLeaseLostError ||
+                controller.signal.reason instanceof errors_1.InboxLeaseLostError) {
+                this.observe({
+                    type: "lease_lost",
+                    consumer: record.consumer,
+                    code: "LEASE_LOST",
+                });
+                return;
+            }
+            const failure = classified ?? classifyFailure(error);
+            await this.recordFailure(record, failure);
+        }
+        finally {
+            finished = true;
+            clearTimeout(deadline);
+            if (heartbeatTimer)
+                clearTimeout(heartbeatTimer);
+            this.controllers.delete(controller);
+        }
+    }
+    async recordFailure(record, failure) {
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        // Driver/network promises can remain pending beyond a transaction failure.
+        // Reconciliation must not retain a concurrency slot or start a late failure write.
+        const deadline = setTimeout(() => controller.abort(new errors_1.InboxTimeoutError()), Math.min(this.options.transactionMaxWaitMs + this.options.transactionTimeoutMs, 5000));
+        deadline.unref?.();
+        try {
+            // A commit can succeed even when the caller receives a transport error.
+            const current = await (0, reliability_core_1.withAbort)(controller.signal, () => this.storage.get(record.id));
+            if (current?.status === "COMPLETED") {
+                this.observe({
+                    type: current.claimToken === record.claimToken
+                        ? "completed"
+                        : "lease_lost",
+                    consumer: record.consumer,
+                });
+                return;
+            }
+            if (!current ||
+                current.status !== "PROCESSING" ||
+                current.claimToken !== record.claimToken) {
+                this.observe({
+                    type: "lease_lost",
+                    consumer: record.consumer,
+                    code: "LEASE_LOST",
+                });
+                return;
+            }
+            const delayMs = this.retryDelay(record.cycleAttemptCount);
+            const changed = await (0, reliability_core_1.withAbort)(controller.signal, () => this.storage.fail(record.id, record.claimToken, { code: failure.code, message: failure.message }, failure.permanent, delayMs, this.options.maxAttempts));
+            this.observe({
+                type: changed
+                    ? failure.permanent ||
+                        record.cycleAttemptCount >= this.options.maxAttempts
+                        ? "dead"
+                        : "retry"
+                    : "lease_lost",
+                consumer: record.consumer,
+                code: changed ? failure.code : "LEASE_LOST",
+            });
+        }
+        catch {
+            // Unavailable state is not evidence of failure. Leave the durable claim alone
+            // so another worker can reconcile it after its lease expires.
+            this.observe({
+                type: "error",
+                consumer: record.consumer,
+                code: "RECONCILIATION_FAILED",
+            });
+        }
+        finally {
+            clearTimeout(deadline);
+            this.controllers.delete(controller);
+        }
+    }
+    retryDelay(attempt) {
+        return (0, reliability_core_1.retryDelayMs)(attempt, {
+            baseMs: this.options.retryBaseMs,
+            maxMs: this.options.retryMaxMs,
+            jitter: "full",
+        });
+    }
+    observe(event) {
+        if (!this.observer)
+            return;
+        try {
+            void Promise.resolve(this.observer(event)).catch(() => undefined);
+        }
+        catch {
+            // Observation is best effort and cannot affect persisted processing state.
+        }
+    }
+}
+exports.InboxWorker = InboxWorker;
+function classifyFailure(error) {
+    if (error instanceof errors_1.InboxPermanentError) {
+        return {
+            code: "PERMANENT_ERROR",
+            message: "The handler rejected the message permanently.",
+            permanent: true,
+        };
+    }
+    if (error instanceof errors_1.InboxTimeoutError) {
+        return {
+            code: "PROCESSING_TIMEOUT",
+            message: "The handler exceeded its transaction deadline.",
+            permanent: false,
+        };
+    }
+    return {
+        code: "HANDLER_ERROR",
+        message: "Message processing failed.",
+        permanent: false,
+    };
+}
+//# sourceMappingURL=inbox-worker.js.map

package/dist/worker/inbox-worker.js.map

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

package/docs/adr/0001-durable-inbox.md

@@ -0,0 +1,40 @@
+# Durable inbox acceptance and transaction ownership
+
+Status: accepted for the 0.1 Preview implementation.
+
+Preview.1 extension: COMPLETED replay is a new receipt with a scoped idempotent request UUID and durable lineage. It never resets the original receipt. Schema v2 adds this lineage, with an explicit v1 upgrade. Optional tenancy context wraps the existing handler transaction; it cannot replace that transaction or skip handler execution.
+
+## Decision
+
+The package exposes durable acceptance followed by asynchronous processing. `accept()` owns its database transaction and resolves only after that transaction commits. The application may then acknowledge the broker delivery or return HTTP success. It must not interpret acceptance as completed business processing.
+
+After acceptance, the Inbox worker owns handler retries. A redelivery from the broker checks the existing identity and returns `duplicate`; it does not create a second retry schedule. Storage failures and unknown acceptance commit results remain the ingress transport's responsibility.
+
+Identity is the tuple `(scopeKind, scopeId, source, consumer, messageId)`. Global scope has an explicit non-null representation. Consumer names identify logical effects, not worker instances or deployment builds. A fingerprint covers event type, schema version, and canonical JSON payload; trace metadata is excluded. Conflicting content never overwrites the original record.
+
+## Transaction boundaries
+
+1. Acceptance inserts or observes a matching durable record and commits.
+2. Claiming commits a new token, an expiring lease, and an incremented attempt count in a short transaction.
+3. The handler executes in a new Prisma transaction supplied by Inbox. Its business writes, optional outbox writes, and fenced `COMPLETED` update commit together.
+
+The completion update requires `PROCESSING`, the current token, and a valid lease. Updating zero rows throws inside the transaction, rolling back all handler writes. A successful completion update holds its row lock through commit; lease expiry between that update and commit does not permit a second completion.
+
+Heartbeats and failure writes require the current processing token and unexpired lease. Recovery requires an expired processing lease. DEAD requeue requires the expected record version and preserves lifetime attempts and token history. Workers claim and recover only their configured consumers.
+
+## Consequences
+
+- Handler invocation is at least once; successfully committed effects in the same database transaction are deduplicated while the receipt is retained.
+- External HTTP requests, email, other database clients, and other databases cannot join this transaction. Handlers use an outbox for subsequent delivery.
+- Claim-time attempt accounting makes repeated crashes consume the retry budget. Exhaustion and permanent errors retain a DEAD record for operator action.
+- Completed identity and fingerprint retention are separate from payload retention. Removing a receipt ends its deduplication guarantee.
+- Business uniqueness across different message IDs and event ordering remain application concerns.
+- The library does not perform schema migrations, create the Prisma connection pool, implement broker clients, or offer a second synchronous processing mode in Preview.
+
+## Rejected alternative
+
+A caller-owned transactional deduplication helper would be smaller but leave retry scheduling and dead-letter handling to the broker. It may be considered as a separate future API. Combining it with durable acceptance under one ambiguous `process()` method would obscure ACK timing and retry ownership.
+
+## Verification
+
+The [implementation roadmap](../implementation-roadmap.md) defines acceptance criteria for concurrent receipt creation, stale claims, ambiguous commits, crash recovery, tenant scope, retention, and bounded shutdown. These guarantees require real PostgreSQL tests; in-memory simulations are insufficient evidence.

package/docs/benchmarks/2026-10-27-local.md

@@ -0,0 +1,31 @@
+# 로컬 MVP 성능 기준값
+
+실행일: 2026년 10월 27일 22시 30분 KST. 이 결과는 재현 가능한 소규모 로컬 기준값이며 서비스 처리 용량이나 SLA가 아니다.
+
+## 환경
+
+- Node 24.11.1, Prisma 7.10.1, PostgreSQL 16.15
+- macOS arm64, Apple M1 Pro, 논리 CPU 10개
+- Docker `postgres:16-alpine`, 임시 tmpfs 데이터, loopback 연결
+- payload 265바이트, Prisma pool 최대 12개와 관리 연결 2개
+- 수신 동시성 8, worker 동시성 4, 시나리오당 수신 요청 500회
+
+## 결과
+
+| 시나리오                    | 수신 요청/초 | 수신 p50 | 수신 p95 | 수신 p99 | worker 처리 소요 | 새 기록 / 중복 |
+| --------------------------- | -----------: | -------: | -------: | -------: | ---------------: | -------------: |
+| 새 테이블                   |    2,197.939 | 3.338 ms | 5.390 ms | 8.086 ms |       813.740 ms |        500 / 0 |
+| 완료 기록 1만 개 보존       |    2,735.363 | 2.742 ms | 4.440 ms | 6.553 ms |       774.389 ms |        500 / 0 |
+| 완료 기록 1만 개와 중복 90% |    2,242.860 | 3.420 ms | 4.930 ms | 5.971 ms |        76.884 ms |       50 / 450 |
+
+모든 시나리오에서 수신과 worker 오류는 0건이었다. 같은 transaction에서 기록한 업무 효과 수는 각각 500개, 500개, 50개로 확인했다. 표의 요청/초는 수신 단계의 처리량이며 handler의 지속 처리량과 다르다.
+
+## 재현과 해석
+
+```sh
+npm run benchmark
+```
+
+[benchmark.mjs](../../scripts/benchmark.mjs)는 테스트 실행기가 만든 임시 DB만 허용하며, 환경·지연 백분위·처리량·업무 효과 수·오류를 JSON으로 출력한다. 기존 애플리케이션 DB에는 실행하지 않는다.
+
+세 시나리오는 고정 순서로 한 번 실행했다. 뒤 시나리오의 JIT·cache 예열이 더 높은 수신 처리량의 원인일 수 있으므로 완료 기록이 많을수록 빨라진다는 결론을 내리지 않는다. tmpfs, 작은 payload, 짧은 handler, 동일 호스트 연결은 운영 환경과 다르다. 큰 payload, 디스크 I/O, 장시간 backlog, DB pool 포화, tenant별 공정성, 반복 표본과 분산 측정은 별도 부하 시험이 필요하다.

package/docs/benchmarks/2026-10-28-preview1-local.md

@@ -0,0 +1,87 @@
+# Preview 1 local performance measurements
+
+Measured on **28 October 2026, 20:49 KST**, using `@nestarc/inbox` **0.1.0-preview.1** and inbox **SQL schema version 2**. Three complete benchmark invocations ran serially, each against a newly created disposable PostgreSQL container. Every result is reported, including the slower fresh-table result in run 3.
+
+The measurements show the cost of durable receipt acceptance and a separate worker drain with one small database write per message. They do not establish sustained production capacity or a latency SLA.
+
+## Observed ranges across all three runs
+
+These are minimum–maximum values from the three runs, not confidence intervals. The p95 range describes three separately calculated p95 values; it is not a pooled percentile of all requests.
+
+| Scenario                                      |  Receive requests/s |     Receive p95 | Worker completions/s |  Worker drain time |
+| --------------------------------------------- | ------------------: | --------------: | -------------------: | -----------------: |
+| Fresh table, 500 unique messages              | 1,400.499–2,123.920 | 5.286–11.612 ms |      531.734–542.775 | 921.193–940.319 ms |
+| 10,000 retained receipts, 500 unique messages | 2,331.351–2,467.967 |  4.602–5.275 ms |      543.328–561.850 | 889.917–920.254 ms |
+| 10,000 retained receipts, 90% duplicates      | 1,812.640–2,061.929 |  5.290–6.622 ms |      523.475–561.857 |   88.991–95.516 ms |
+
+**All nine scenario results passed their correctness checks.** Across 4,500 receive calls, the benchmark observed 3,150 newly accepted messages, 1,350 duplicate receipts, and exactly 3,150 committed business effects. No acceptance or worker errors were observed. Each scenario finished with the expected completed count and no pending, processing, retryable, or dead records.
+
+Receive requests/s includes both newly accepted and duplicate calls. It measures `accept()` returning after its receipt transaction, **before business processing**. After the receive phase finishes, the benchmark calls `runOnce()` repeatedly to drain the backlog. Worker completions/s measures unique committed effects divided by that drain duration, including claims, handler transactions, fenced completion, and the final empty poll. The duplicate scenario drains only 50 unique messages rather than 500, so its shorter drain is not evidence of faster processing per message.
+
+## Every measured run
+
+| Run | Scenario                        | Receive requests/s | Receive p95 | Worker completions/s | Worker drain time | Accepted / duplicate |
+| --- | ------------------------------- | -----------------: | ----------: | -------------------: | ----------------: | -------------------: |
+| 1   | Fresh unique                    |          2,123.920 |    5.286 ms |              531.734 |        940.319 ms |              500 / 0 |
+| 1   | Retained 10,000, unique         |          2,331.351 |    5.275 ms |              543.328 |        920.254 ms |              500 / 0 |
+| 1   | Retained 10,000, 90% duplicates |          1,812.640 |    5.901 ms |              523.475 |         95.516 ms |             50 / 450 |
+| 2   | Fresh unique                    |          2,117.532 |    5.406 ms |              538.703 |        928.155 ms |              500 / 0 |
+| 2   | Retained 10,000, unique         |          2,467.967 |    5.244 ms |              561.850 |        889.917 ms |              500 / 0 |
+| 2   | Retained 10,000, 90% duplicates |          1,864.466 |    6.622 ms |              547.005 |         91.407 ms |             50 / 450 |
+| 3   | Fresh unique                    |          1,400.499 |   11.612 ms |              542.775 |        921.193 ms |              500 / 0 |
+| 3   | Retained 10,000, unique         |          2,358.995 |    4.602 ms |              558.711 |        894.918 ms |              500 / 0 |
+| 3   | Retained 10,000, 90% duplicates |          2,061.929 |    5.290 ms |              561.857 |         88.991 ms |             50 / 450 |
+
+The original JSON reports include p50, p99, elapsed times, exact counters, error maps, and environment metadata:
+
+- [Run 1](2026-10-28-preview1-run1.json), completed at `2026-10-28T11:49:05.582Z` / 20:49:05.582 KST.
+- [Run 2](2026-10-28-preview1-run2.json), completed at `2026-10-28T11:49:36.479Z` / 20:49:36.479 KST.
+- [Run 3](2026-10-28-preview1-run3.json), completed at `2026-10-28T11:49:53.903Z` / 20:49:53.903 KST.
+
+Each JSON is preserved from the benchmark's output, with the outer runner's setup log removed. The JSON's single-sample limitation applies to that individual invocation; this document combines three such invocations without dropping any sample.
+
+## Environment and workload
+
+| Setting                                   | Value                                                                              |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| Package / schema                          | `0.1.0-preview.1` / SQL version 2                                                  |
+| Node.js                                   | `24.22.1`                                                                          |
+| NestJS / Prisma                           | `11.2.8` / `7.10.1`                                                                |
+| PostgreSQL                                | `16.15`, aarch64 Linux musl                                                        |
+| Host                                      | macOS arm64, Apple M1 Pro, 10 logical CPUs                                         |
+| Docker engine                             | `29.8.2`, 10 CPUs and 8,319,504,384 bytes of memory reported by Docker             |
+| PostgreSQL image                          | `postgres:16-alpine`                                                               |
+| Image digest                              | `postgres@sha256:f4610795587492cd4fb887c2dc3de301b813278bb6f616992061141b5f15ac36` |
+| Storage and transport                     | Docker tmpfs database; loopback forwarded TCP                                      |
+| Prisma pool / fixture administration pool | Maximum 12 / 2 connections                                                         |
+| Receive / worker concurrency              | 8 / 4                                                                              |
+| Receive calls per scenario                | 500                                                                                |
+| JSON payload                              | 265 UTF-8 bytes                                                                    |
+| Retained history                          | 10,000 completed receipts with payloads purged                                     |
+| Worker effect                             | One `INSERT` in the same Prisma transaction as inbox completion                    |
+| Automatic polling                         | Disabled; explicit bounded `runOnce()` drain                                       |
+
+Each scenario truncates the fixture tables, optionally seeds retained receipts, runs `ANALYZE`, and issues concurrent `SELECT 1` queries to establish connections. This preparation is excluded from the timing. There are no warmup inbox writes. Within each invocation, scenarios always run in this order: fresh unique, retained unique, retained with 90% duplicates.
+
+## Reproduce
+
+With Docker running and the repository dependencies installed:
+
+```sh
+npm run benchmark
+npm run benchmark
+npm run benchmark
+```
+
+Use Node.js `24.22.1` to match this measurement. The runs here used that runtime with the npm cache set to `/private/tmp/nestarc-inbox-npm-cache`; the cache location does not affect the timed database operations.
+
+[The benchmark](../../scripts/benchmark.mjs) builds the package and uses [the fixture runner](../../scripts/with-test-db.mjs) to create a database on a random loopback port. The runner ignores an existing application `DATABASE_URL`, generates the test Prisma client, and removes its container afterward. All three invocations exited successfully and no labeled inbox fixture containers remained after the measurements.
+
+## Interpretation limits
+
+- Three short samples reveal some local variation, not a reliable estimate of long-running throughput. Run 3's fresh-table receive rate and p95 illustrate that variation; its cause was not measured.
+- Fixed scenario order allows later cases to benefit from process/JIT/cache warmup. These results do not imply that retaining more receipts makes the package faster.
+- A tmpfs database, loopback networking, 265-byte payloads, and one simple business write differ from disk-backed production databases, remote services, larger payloads, and application handlers.
+- Receive and worker phases run separately. This does not measure concurrent ingress and processing under a sustained backlog, pool saturation, or backpressure.
+- Replay, tenancy/RLS hooks, outbox emission, broker traffic, network faults, cold caches, and tenant fairness are not exercised by this benchmark. Their correctness tests are separate evidence.
+- The older Preview 0 report used a different Node version and code/schema. This is a fresh baseline, not a controlled before/after comparison or a comparison with other products.

package/docs/benchmarks/2026-10-28-preview1-run1.json

@@ -0,0 +1,120 @@
+{
+  "kind": "nestarc-inbox-local-baseline",
+  "measuredAt": "2026-10-28T11:49:05.582Z",
+  "packageVersion": "0.1.0-preview.1",
+  "metadata": {
+    "node": "v24.22.1",
+    "platform": "darwin",
+    "arch": "arm64",
+    "cpuModel": "Apple M1 Pro",
+    "hostLogicalCpus": 10,
+    "postgres": "PostgreSQL 16.15 on aarch64-unknown-linux-musl, compiled by gcc (Alpine 15.2.0) 15.2.0, 64-bit",
+    "image": "postgres:16-alpine",
+    "storage": "Docker tmpfs; loopback forwarded TCP",
+    "prisma": "7.10.1",
+    "connectionMax": 12,
+    "fixtureAdminConnectionMax": 2,
+    "acceptConcurrency": 8,
+    "workerConcurrency": 4,
+    "iterationsPerScenario": 500,
+    "payloadBytes": 265,
+    "retainedPayloads": "purged tombstones",
+    "warmup": "SELECT 1 at accept concurrency before each scenario; no warmup inbox writes",
+    "workerEffect": "One INSERT through the same Prisma transaction as inbox completion"
+  },
+  "scenarios": [
+    {
+      "name": "fresh_unique",
+      "retainedCompletedReceipts": 0,
+      "iterations": 500,
+      "expectedUniqueMessages": 500,
+      "duplicateRatio": 0,
+      "accepted": 500,
+      "duplicates": 0,
+      "accept": {
+        "elapsedMs": 235.414,
+        "requestsPerSecond": 2123.92,
+        "latencyMs": {
+          "p50": 3.501,
+          "p95": 5.286,
+          "p99": 9.834
+        }
+      },
+      "worker": {
+        "drainMs": 940.319,
+        "completedPerSecond": 531.734,
+        "batches": 125,
+        "committedEffects": 500
+      },
+      "errors": {
+        "accept": {},
+        "worker": {}
+      },
+      "verified": true
+    },
+    {
+      "name": "retained_10000_unique",
+      "retainedCompletedReceipts": 10000,
+      "iterations": 500,
+      "expectedUniqueMessages": 500,
+      "duplicateRatio": 0,
+      "accepted": 500,
+      "duplicates": 0,
+      "accept": {
+        "elapsedMs": 214.468,
+        "requestsPerSecond": 2331.351,
+        "latencyMs": {
+          "p50": 3.131,
+          "p95": 5.275,
+          "p99": 7.647
+        }
+      },
+      "worker": {
+        "drainMs": 920.254,
+        "completedPerSecond": 543.328,
+        "batches": 125,
+        "committedEffects": 500
+      },
+      "errors": {
+        "accept": {},
+        "worker": {}
+      },
+      "verified": true
+    },
+    {
+      "name": "retained_10000_duplicates_90pct",
+      "retainedCompletedReceipts": 10000,
+      "iterations": 500,
+      "expectedUniqueMessages": 50,
+      "duplicateRatio": 0.9,
+      "accepted": 50,
+      "duplicates": 450,
+      "accept": {
+        "elapsedMs": 275.841,
+        "requestsPerSecond": 1812.64,
+        "latencyMs": {
+          "p50": 4.26,
+          "p95": 5.901,
+          "p99": 6.941
+        }
+      },
+      "worker": {
+        "drainMs": 95.516,
+        "completedPerSecond": 523.475,
+        "batches": 13,
+        "committedEffects": 50
+      },
+      "errors": {
+        "accept": {},
+        "worker": {}
+      },
+      "verified": true
+    }
+  ],
+  "limitations": [
+    "One local sample on a disposable tmpfs database; no SLA or production capacity claim.",
+    "Scenarios run in a fixed order; later scenarios may benefit from JIT/cache warmup.",
+    "No sustained load, network faults, broker traffic, cold-cache runs, or fairness measurement.",
+    "Receipt seed and schema preparation are excluded from measurements."
+  ]
+}