Skip to content

docs(adr): compress to 1 record in the domain-modeling format - #54

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 1 record (299 words) to 1 (127 words), one paragraph, in the shape
ADR-FORMAT.md asks for. The record survives the admission test, so nothing is dropped, merged or
renumbered: it keeps 0001-own-the-lifespan-composition.md, and every existing citation resolves
unchanged.

Evaluation

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

Old Outcome New Reason
0001 own the lifespan composition kept, compressed 0001 Reusing FastAPI's shipped composition helper is the obvious path, so the deliberate deviation is exactly what a reader would otherwise try to "fix"; reverting it changes the state a user's lifespan yields.

Removed from the prose: the **Decision:** line, the three bolded argument headings, and the
**Revisit trigger:** section. The trigger (a public passthrough helper appears upstream) is not
the boundary of the decision, only its natural expiry, and it follows from the two reasons the
paragraph already gives.

Citations

None moved. CONTEXT.md cites [ADR-0001](docs/adr/0001-own-the-lifespan-composition.md) and
docs/agents/domain.md mentions ADR-0001; both still resolve, and the file structure sample in
domain.md still names the right filename. The repo-wide sweep finds no reference to an old or
dropped number.

Stale claims corrected

The old record said the merge path would replace the original lifespan's passthrough, "its None or
its mapping, verbatim", with a freshly built dict. Current fastapi.routing._merge_lifespan_context
yields None when both states are None (an explicit old-ASGI branch), so the rebuild only happens
when one of them is a mapping. The paragraph now says that.

Verified against the code and unchanged: setup_di installs _compose_lifespan onto
app.router.lifespan_context; pyproject.toml pins fastapi>=0.100,<1; the private import was
dropped in 2.8.0 (#20, the first tag containing it); _compose_lifespan enters the container with
async with so a second cycle reopens it. The named test
test_lifespan_reopens_container_across_cycles still exists in tests/test_lifespan.py, but the
paragraph no longer names it, since the test name is the kind of detail that goes stale silently.

Gates

Gate Result
pytest -q tests/test_adr_citations.py 7 passed
pytest -q (full suite) 17 passed
ruff format --check 18 files already formatted
ruff check --no-fix All checks passed
eof-fixer . --check clean
lychee --offline over the touched ADR, CONTEXT.md, AGENTS.md 3 OK, 0 errors, 2 excluded

No directory needed external services, so none was skipped. No Python changed, so the ruff gates only
confirm the tree was already clean.

No drops and no merges: the single record survives the admission test and keeps
its number and slug. Rewritten as one paragraph, 299 words to 127, dropping the
**Decision:** line, the bolded argument headings and the revisit trigger.

Corrects a stale claim: `_merge_lifespan_context` yields `None` when both states
are `None`, so the merge rebuilds the user's state as a fresh dict only when one
of them is a mapping.
@lesnik512
lesnik512 merged commit debd0dc 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