Skip to content

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

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/ in the one-paragraph domain-modeling format. Both existing records pass the
three-part admission test, so nothing was dropped or merged; the change is compression and the
citation cleanup that follows it.

Before / after

records words (body, excl. titles)
before 2 614
after 2 290

Per record: 0001 goes 375 -> 146 words, 0002 goes 239 -> 144.

Evaluation

old record outcome new number reason
0001-two-connection-providers-one-reference-only kept, compressed 0001 (unchanged) Hard to reverse: the two providers are public API and the WebSocket path's FromDI asymmetry is baked into every consumer. Surprising: two providers binding the same web.Request. Real trade-off: dishka's contiguous APP -> SESSION -> REQUEST was considered and rejected.
0002-scope-follows-the-handshake-probe kept, compressed 0002 (unchanged) Distinct decision from 0001 (runtime dispatch, not registry shape) with its own rejected alternatives: dishka's Connection == \"Upgrade\" header comparison and route-table dispatch. The header-only boundary is observable behaviour, so reversing it breaks handlers.

Numbers are already contiguous from 0001 and the original relative order is preserved, so no
renumbering and no git mv were needed.

Format changes

  • **Decision:** lead, the argument-per-section layout and the **Revisit trigger:** footers are
    removed from both records.
  • Each revisit trigger is folded into its paragraph only where it is the decision's real boundary:
    0001 ends on the HTTP/WebSocket injection asymmetry, 0002 on "scope follows the handshake headers
    and nothing else".
  • Em-dashes replaced with plain hyphens and commas throughout; wrapped at ~100 columns.
  • The intra-ADR reference in 0002 is now a proper [ADR-0001](0001-two-connection-providers-one-reference-only.md)
    link (0002 previously restated 0001's premise with no link).

Citations moved

where before after
tests/test_connection_providers.py:17 (ADR 0001) (docs/adr/0001-two-connection-providers-one-reference-only.md)
docs/agents/domain.md:35 ADR-0001 unchanged, number and slug both survive

The bare ADR 0001 form named no file on disk, so tests/test_adr_citations.py could not check it
and a rename or drop would have left it pointing at nothing. It is now the full path the test
resolves.

Stale claims

None. Every concrete claim in both records was re-verified against the current code before
rewriting, and all held:

  • aiohttp_request_provider / aiohttp_websocket_provider scopes and bound_type=None, in
    modern_di_aiohttp/main.py.
  • ProvidersRegistry.add_providers skipping a falsy bound_type instead of raising
    DuplicateProviderTypeError, while still setting _registered so the reference-only provider
    stays resolvable.
  • Container.build_child_container accepting any deeper scope, so APP -> REQUEST scope-skipping
    is permitted, which is what 0001's rejection of contiguous scopes rests on.
  • ContextProvider.fetch_context_value hopping to the ancestor at the provider's own scope, with
    ScopeSkippedError for the missing level.
  • WebSocketResponse.can_prepare (aiohttp 3.14.3) being synchronous and swallowing HTTPException.
    One refinement: it does raise RuntimeError(\"Already started\") when the response already has a
    writer, so 0002 now says it cannot raise on a fresh response object, which is what the
    middleware constructs, rather than the unqualified "never raises".

Two details the old records left out are now named, since they are what a reader hits first in the
code: integrations.bind derives the scope and context once the provider is picked, and
integrations.classify_connection's isinstance dispatch is unusable here precisely because both
providers bind web.Request.

Gates

gate result
uv run --no-sync pytest -q tests/test_adr_citations.py 7 passed
uv run --no-sync pytest -q 23 passed
uv run --no-sync ruff format --check (touched Python) 1 file already formatted
uv run --no-sync ruff check --no-fix (touched Python) All checks passed
uv run --no-sync eof-fixer . --check clean, exit 0
lychee --offline --no-progress (both ADRs, CONTEXT.md, AGENTS.md) 5 unique, 3 OK, 0 errors, 4 excluded

Nothing skipped: the suite needs no external services, and every tool was present in the venv.

Both records survive the admission test and keep their numbers and slugs. Each
is now a single paragraph: the **Decision:** lead, the section-per-argument
layout and the **Revisit trigger:** footers are gone, with each trigger folded
into the paragraph as the decision's boundary. No drops, no merges.

The 0001 citation in tests/test_connection_providers.py moves from the bare
"ADR 0001" form to the full docs/adr path the citation test can resolve.
@lesnik512
lesnik512 merged commit 1960300 into main Sep 19, 2026
8 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:28
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