bunqueue AGENTS.md

AGENTS.md

This file applies to the entire repository unless a more specific AGENTS.md exists in a subdirectory.

Project overview

bunqueue is a high-performance job queue written in TypeScript for Bun. The server and embedded runtime are Bun-only. Persistence uses bun:sqlite; public clients may run in other runtimes through the network protocol.

Repository map

• src/application/: queue orchestration and use-case logic.
• src/domain/: jobs, shards, priority queues, counters, and limiters.
• src/infrastructure/: SQLite persistence and transport adapters.
• src/client/: public Queue/Worker APIs.
• test/: Bun unit, integration, regression, and reproduction tests.
• docs/: documentation site.
• sdk/: language SDKs and conformance fixtures.

Working rules

• Before every git commit and every git push, invoke the skeptic custom subagent and wait for its verdict. It must inspect the complete staged diff, identify at least three potential failure points per changed file, verify error handling, races, idempotency, type safety and test evidence, and run applicable checks. FAIL blocks the operation; CONDITIONAL requires the user's explicit confirmation. The project profiles live at .codex/agents/skeptic.toml and .claude/agents/skeptic.md.
• When a bug is reported, first add a regression test that reproduces it. Only after the test fails for the expected reason, use subagents to investigate fixes and prove the chosen fix with the passing regression test.
• Preserve user changes. Never run git reset, git checkout, git clean, or discard unrelated edits unless the user explicitly requests it.
• Keep all repository content in English, including source comments, tests, internal documentation, user-facing documentation and agent configuration.
• Keep changes narrowly scoped to the requested behavior. Do not refactor unrelated code while fixing a bug.
• Use rg/rg --files for repository searches and apply_patch for manual source edits.
• Runtime source is TypeScript ESM. Follow the existing 2-space, single-quote, semicolon style; Oxlint and Oxfmt are authoritative.
• Keep hot queue paths synchronous while a shard lock is held. Do not introduce an await inside a synchronous critical section.
• Maintain queue invariants together: heap membership, jobIndex, processing maps, counters, temporal indexes, group ownership, and concurrency slots must transition exactly once.
• SQLite filtering, ordering, and pagination must happen in a consistent order. Use deterministic tie-breakers for paginated queries and add migrations for schema or index changes.
• Do not silently change externally visible scheduling semantics. Add explicit regression coverage when priority, delay, FIFO-group, retry, or recovery behavior changes.
• Keep source files at or below 300 lines. Give each file one responsibility and export only what is needed; split a file instead of growing it beyond that boundary.
• Respect the lock hierarchy: jobIndex -> completedJobs -> shards[N] -> processingShards[N]. Read prerequisite state before acquiring the next lock and always release locks in finally.