Skip to content

docs(adr): compress to 2 records in the domain-modeling format - #24

Merged
lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs
Sep 19, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Rewrites docs/adr/ from 2 records (681 words) to 2 (297 words), one paragraph each, in the shape the domain-modeling ADR format asks for. Both records pass the admission test on separate boundaries, so nothing is dropped or merged, the numbering is already contiguous from 0001 in the original order, and no file is renamed.

Evaluation

Each record was tested against the admission test: hard to reverse, surprising without context, the result of a real trade-off.

Old Outcome New Reason
0001 per-task scope rides taskiq dependencies kept 0001 The mechanism is public API, a middleware is what a reader would expect (Dishka's taskiq integration uses one), and the rejection turns on taskiq's generator-dependency caching and finalization contract.
0002 only worker lifecycle is wired kept 0002 The unwired CLIENT_STARTUP / CLIENT_SHUTDOWN pair is an explicit no that a reader would otherwise read as an omission, and it trades a client-side container's lifetime against holding app-scoped resources in a process that resolves nothing.

The **Decision:** lines and both **Revisit trigger:** blocks are gone. 0001's trigger was a restatement of the taskiq contract the paragraph already gives, and 0002's was the client-resolves case the paragraph already names, so neither was the real boundary of the decision. 0002's sub-rule about the unconditional container.open() is a rule the record relies on and survives as one sentence.

Citations

None moved. The repo-wide sweep finds one reference, ADR-0001 in docs/agents/domain.md, whose number and slug are unchanged; the file tree in that same document still lists both filenames correctly. tests/test_adr_citations.py passes.

Stale claims corrected

0002 said that on a second worker cycle, resolving without reopening "would raise ContainerClosedError". That is no longer true on the pinned modern-di>=3,<4 (3.4.0 is installed): as of 3.1 a container is open from construction, and Container._prepare reopens a closed one implicitly, emitting ContainerClosedWarning. ContainerClosedError is kept importable for back-compat, documents itself as no longer raised, and is scheduled for removal in 4.0. The record now says the unconditional open() reopens deliberately instead of leaving modern-di to reopen implicitly with that warning.

Everything else was verified against the code: build_di_container is the async generator TaskiqDepends, no TaskiqMiddleware exists, setup_di registers only the two worker events and calls container.open() unconditionally, taskiq_dependencies defaults use_cache=True and calls dep.athrow on the error path, InMemoryBroker.startup fires both lifecycle pairs while AsyncBroker.startup picks one by is_worker_process, and the in-process caveat is documented in README.md.

Gates

  • pytest -q tests/test_adr_citations.py: 7 passed.
  • pytest -q (full suite): 17 passed, 1 warning (a pre-existing DeprecationWarning from taskiq_dependencies on the three-arg athrow signature, unrelated to this change). No directories were skipped; this repo's suite needs no external services.
  • ruff format --check and ruff check --no-fix: skipped, no Python file is touched by this change.
  • eof-fixer . --check: clean, exit 0.
  • lychee --offline --no-progress over both touched Markdown files plus CONTEXT.md and AGENTS.md: 4 unique links, 2 OK, 0 errors, 3 excluded.

Both records survive the admission test on separate boundaries, so
nothing is dropped, merged or renumbered. Each is now a single
paragraph without the Decision/Revisit-trigger scaffolding.

Corrects a stale claim in 0002: modern-di no longer raises
ContainerClosedError on a closed container (3.1 reopens implicitly with
ContainerClosedWarning), so the unconditional open() now avoids that
warning rather than an error.
@lesnik512
lesnik512 merged commit 5028f54 into main Sep 19, 2026
8 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant