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 3 records (991 words) to 2 (297 words), one paragraph each, in the shape the domain-modeling ADR format asks for. Survivors are renumbered 0001-0002 in their original order and every citation moves with them.

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 aio coverage flake fixed in the test dropped - Not hard to reverse: it is two # pragma: no cover comments in one test, deleted the day coveragepy ships a fix, and tests/test_aio.py already carries the reason as a three-line comment next to them. No survivor relies on the rule, so nothing was folded.
0002 protobuf request message not a provider kept 0001 A dependency and scope boundary: the explicit no keeps protobuf out of the runtime dependency set, and a future reader would otherwise add the provider. Its closing clause about integrations.bind vs classify_connection and its revisit trigger fold into the paragraph.
0003 streaming servicer methods must be generators kept 0002 A public contract narrower than gRPC's and narrower than dishka's, with a silent and severe failure mode if the wrapper shape is guessed. The revisit trigger is the real boundary of the decision, so it stays as the closing sentence.

No merges: 0001 and 0002 are separate boundaries (dependency surface vs. wrapper lifetime) and share no rule.

Citations

One citation moved. docs/agents/domain.md named ADR-0001 (aio coverage flake fixed in the test) in its ADR-conflict example and listed 0001-aio-coverage-flake-fixed-in-the-test.md / 0002-protobuf-request-message-not-a-provider.md in its file-structure tree; both now name the surviving records. Nothing in modern_di_grpc/, tests/, README.md, CONTEXT.md, AGENTS.md, pyproject.toml or the workflows cited an ADR. The repo-wide sweep finds no reference to an old or dropped number.

Stale claims

Every concrete claim in the two survivors was checked against the code and holds: grpc_context_provider is providers.ContextProvider(ServicerContext, scope=Scope.REQUEST), dependencies is ["grpcio>=1.48,<2", "modern-di>=3,<4"] with protobuf only in the dev group, _build_child calls integrations.bind (never classify_connection, which does exist in modern_di.integrations), _wrap_stream_sync / _wrap_stream_aio are generators, and inject builds exactly three wrapper shapes.

One stale claim was found in the dropped record: it named the gate as the CLI flag --cov-fail-under=100, which appears nowhere in the repo. The gate is fail_under = 100 under [tool.coverage.report] in pyproject.toml, and just test-ci passes only --cov=. and the report flags. Since the record is dropped, the correction is recorded here rather than rewritten.

Gates

  • pytest -q tests/test_adr_citations.py: 7 passed.
  • pytest -q (full suite): 37 passed. Nothing in tests/ needs an external service; the gRPC servers are in-process on loopback.
  • ruff format --check: 22 files already formatted. ruff check --no-fix: all checks passed. eof-fixer . --check: clean. No Python was touched by this change, so all three are informational.
  • lychee --offline --no-progress over both new ADRs, docs/agents/domain.md, CONTEXT.md and AGENTS.md: 3 unique links, 2 OK, 0 errors.
  • ty check was not run: it is part of just lint-ci, not a gate for this change, and no Python was touched.

Drops 0001 (aio coverage flake fixed in the test): a two-line `# pragma: no cover` is
cheap to reverse and the reason already sits in the test as a comment.

Keeps 0002 and 0003 unmerged - they are separate boundaries - rewritten as one
paragraph each and renumbered 0001 and 0002. No merges.
@lesnik512
lesnik512 merged commit 0cddca9 into main Sep 19, 2026
7 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:27
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