[dahlia]

handlerTimeout stops PostgreSQL/MySQL queues from waiting but leaves handlers running. Application transactions and late writes can therefore outlive the queue's ordering lock.

The guide separates queue-owned cleanup from application-owned resources and shows one cancellation budget shared across recursive document and context loads. It also explains how detached parallel workers affect backend timeouts, retries, and ordering, so readers do not mistake callback completion for completed work.

Fixes #1310.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-19T17:23:09.666592Z	—	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

📝 Walkthrough

The changes document existing queue handler timeout behavior for PostgreSQL and MySQL. They clarify detached worker limits and describe application-managed execution budgets and cleanup.

Changes: Queue timeout guidance

Layer / File(s)	Summary
Timeout behavior and backend options docs/manual/mq.md, packages/postgres/src/mq.ts, packages/postgres/src/mq.test.ts	Documents the PostgreSQL and MySQL 60-second defaults and zero-second opt-out. Clarifies that timeout stops the queue from waiting but does not terminate the handler.
Detached workers and ordering docs/manual/mq.md, docs/manual/tasks.md	Explains that detached workers can outlive the wrapped callback, so wrapped timeouts and native retries do not reliably cover their execution. Updates guidance about ordering and possible overlapping side effects.
Application budgets and cleanup docs/manual/mq.md	Adds an example that shares an abort budget across bounded recursive work. Explains cooperative cancellation, database statement timeouts, and application-owned cleanup.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 7f6a8

This documentation change clarifies queue timeout and cleanup limits without an established defect; no concrete merge risk remains.

Pre-merge checks: 4 · 1

Failed checks: 1 inconclusive

Check name	Status	Explanation	Resolution
Linked Issues check		For #1310, the supplied change summary and reviewed files show the requested documentation, PostgreSQL JSDoc, and regression-test comment updates. The summary also covers the 60-second and zero-disabl…	Provide the results or logs for the required documentation TypeScript checks, mise run check:md, mise run docs:build, and mise run check-each postgres. A readable whole-PR diff is also needed to verify the complete handler-timeout exa…

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main documentation changes about queue timeouts and application cleanup.
Description check		The description directly explains the documented timeout behavior, application-owned cleanup, detached workers, retries, and ordering effects covered by the changeset.
Out of Scope Changes check		The supplied change summary lists only docs/manual/mq.md, docs/manual/tasks.md, packages/postgres/src/mq.ts, and packages/postgres/src/mq.test.ts. These changes document existing timeout behav…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…

Full details: Out of Scope Changes check

Explanation

The supplied change summary lists only docs/manual/mq.md, docs/manual/tasks.md, packages/postgres/src/mq.ts, and packages/postgres/src/mq.test.ts. These changes document existing timeout behavior or correct a misleading test comment. The summary reports no runtime behavior change and no changelog fragment. These changes stay within #1310 scope.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (2 skipped: 2 unsupported.)

Full details: Linked Issues check

Explanation

For #1310, the supplied change summary and reviewed files show the requested documentation, PostgreSQL JSDoc, and regression-test comment updates. The summary also covers the 60-second and zero-disabled queue timeouts, queue-owned versus application-owned cleanup, late side effects, ordering limits, error/retry limits, ParallelMessageQueue detached workers, document-loader budgets, cooperative cancellation, and the tasks-manual link. The reviewed PostgreSQL JSDoc matches the requested soft-timeout behavior. However, the repository diff was unavailable, and the PR description reports no results for the required documentation TypeScript checks, mise run check:md, mise run docs:build, or mise run check-each postgres. Compliance with those automated validation requirements cannot be established.

Resolution

Provide the results or logs for the required documentation TypeScript checks, mise run check:md, mise run docs:build, and mise run check-each postgres. A readable whole-PR diff is also needed to verify the complete handler-timeout example and its links.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[coderabbitai]

🔇 Additional comments: 5

packages/postgres/src/mq.ts: 1

106-113: LGTM!

packages/postgres/src/mq.test.ts: 1

1337-1339: LGTM!

docs/manual/mq.md: 1

1043-1043: 📐 Maintainability & Code Quality

Keep the heading as written.

The file already uses ATX style for third-level headings, including nearby headings. The comment does not establish an applicable MD003 rule or a lint failure. Converting this heading would be an unsupported style change.

docs/manual/tasks.md: 1

187-194: LGTM!

docs/manual/mq.md-1062-1063: 1

1062-1063: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

Wrap the long lines in the example code.

Lines 1062 and 1063 are much longer than the surrounding code. The code block is exempt from Hongdown prose wrapping. Long lines are still hard to read in the rendered docs, because code blocks scroll horizontally. Break them across lines.

Proposed change

-  const timer = setTimeout(() => budget.abort(new Error("Work budget expired")), 30_000);
-  const withBudget = (loader: DocumentLoader): DocumentLoader => async (url, options) => {
+  const timer = setTimeout(
+    () => budget.abort(new Error("Work budget expired")),
+    30_000,
+  );
+  const withBudget = (loader: DocumentLoader): DocumentLoader =>
+  async (url, options) => {

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 547503b6-9918-4595-a997-f702b23988fb

📥 Commits

Reviewing files that changed from the base of the PR and between 1304e86 and 7f6a8b1.

📒 Files selected for processing: 4

• docs/manual/mq.md
• docs/manual/tasks.md
• packages/postgres/src/mq.test.ts
• packages/postgres/src/mq.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.