docs: inbox-pattern.md + remove SQLite hold-transaction property

[blehnen]

Summary

Two changes follow up on PR #143 (inbox milestone) + issue #149 (SQLite outbox-only):

1. docs/inbox-pattern.md — consumer-side counterpart to docs/outbox-pattern.md. Covers the IRelationalWorkerNotification capability cast, the EnableHoldTransactionUntilMessageCommitted requirement, library-owned transaction lifecycle, supported-transports table, and an explicit "not supported on SQLite — single-writer lock" reference section. Includes sync + async SqlServer code examples and a PostgreSQL note.

2. Remove EnableHoldTransactionUntilMessageCommitted from SqLiteMessageQueueTransportOptions public surface. The property was once user-settable but the receive path's no-op was added long ago when SQLite hold-transaction support was disabled. Property is now satisfied via explicit ITransportOptions interface implementation only — variables typed as the concrete SQLite options class no longer see it, and direct access produces a compile error instead of silent no-op. ITransportOptions-typed access still compiles (getter false, setter discarded). SqlServer + PostgreSQL options classes are unchanged.

Why now / motivation

The CLAUDE.md lesson committed in PR #143 captured the structural reason (single-writer lock) hold-transaction inbox can't work on SQLite. The property's continued presence on the SQLite-typed class was a footgun: code that set it on SQLite silently did nothing. Hiding it makes the impossibility visible at compile-time on the dangerous use path (var opts = new SqLiteMessageQueueTransportOptions(); opts.EnableHoldTransactionUntilMessageCommitted = true; → compile error).

Breaking change

Yes — strictly limited to code that:

• Types a variable as the concrete SqLiteMessageQueueTransportOptions class (not ITransportOptions), AND
• Sets or reads EnableHoldTransactionUntilMessageCommitted.

Any such code was previously silently broken (the value never affected SQLite behavior). The compile error surfaces what was always true: this property is meaningless on SQLite.

Code that types as ITransportOptions still compiles and the property still no-ops, so polymorphic configuration code is unaffected.

What's deliberately NOT in this PR

• SQLite outbox. Tracked separately in issue Add outbox pattern support for SQLite (inbox not workable — single-writer lock) #149. The viability question for outbox is different (caller owns the transaction, accepts the concurrency hit) and the implementation is non-trivial.

Test plan

• CodeRabbit review.
• Jenkins green — full unit + integration test pass.
• Confirm SqlServer + PostgreSQL inbox tests (added in PR Inbox pattern support for relational transports #143) continue to pass — the docs + the SQLite-only property removal touch no production code on either of those transports.
• Spot-check docs/inbox-pattern.md — code examples compile against current API (IRelationalWorkerNotification.Transaction, consumer.Start<T>(handler, null), etc.).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Breaking Changes

  • SQLite queue configuration: EnableHoldTransactionUntilMessageCommitted property no longer directly accessible on the SQLite-specific options type.

• Documentation

  • Added Transactional Inbox Pattern guide covering atomic dequeue operations, handler integration, transport compatibility, and deployment requirements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a9351f50-1617-45d9-88b3-06c2695746a4

📥 Commits

Reviewing files that changed from the base of the PR and between 5c7731b and a288dcd.

📒 Files selected for processing (2)

• Source/DotNetWorkQueue.Transport.SQLite/Basic/SQLiteMessageQueueTransportOptions.cs
• docs/inbox-pattern.md

---

📝 Walkthrough

Walkthrough

This PR introduces the transactional inbox pattern for the DotNetWorkQueue library by documenting how handlers can achieve atomicity between dequeue and business writes via IRelationalWorkerNotification, while enforcing that SQLite transport cannot support this pattern by hiding the enablement property from the concrete options type.

Changes

Transactional Inbox Pattern with SQLite Transport Constraint

Layer / File(s)	Summary
SQLite transport constraint enforcement Source/DotNetWorkQueue.Transport.SQLite/Basic/SQLiteMessageQueueTransportOptions.cs	The EnableHoldTransactionUntilMessageCommitted property is removed from concrete SQLite options and replaced with an explicit interface implementation that always returns false with a discarded setter, preventing accidental property use while preserving interface-based access with detailed comments explaining the SQLite deadlock constraint.
Transactional inbox pattern documentation docs/inbox-pattern.md	Complete documentation of the transactional inbox pattern including pattern introduction and outbox contrast, Quick Start examples for SqlServer with sync and async handlers, detailed lifecycle contract covering handler obligations and transaction semantics, and transport compatibility matrix showing SQLite as non-viable.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• Add outbox pattern support for SQLite (inbox not workable — single-writer lock) #149: The code change directly modifies the EnableHoldTransactionUntilMessageCommitted property behavior on SQLite transport, which is the same queue option implicated in that issue's SQLite inbox/outbox transaction failures; this PR enforces the constraint and documents the workaround pattern.

Poem

A rabbit hops through inbox schemes,
Where transactions align like dreams,
SQLite must stand aside and rest—
For other transports do it best! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes both major changes: adding inbox-pattern documentation and removing the SQLite hold-transaction property from the public surface.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 89.78%. Comparing base (c3ee642) to head (a288dcd).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
...SQLite/Basic/SQLiteMessageQueueTransportOptions.cs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #150      +/-   ##
==========================================
- Coverage   89.81%   89.78%   -0.03%     
==========================================
  Files        1002     1002              
  Lines       29703    29703              
  Branches     2405     2405              
==========================================
- Hits        26678    26670       -8     
- Misses       2365     2368       +3     
- Partials      660      665       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.