Skip to content

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

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 (535 words) to 2 (306 words), one paragraph each, in the shape the domain-modeling ADR format asks for. Both records pass the admission test, so nothing is dropped and nothing is merged; numbering and filenames are unchanged. What goes is the format: the **Decision:** lead, the rejected-alternative bullet lists, and the **Revisit trigger:** block. Same treatment as modern-python/compose2pod#102.

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 metrics recorders not unified kept 0001 Hard to reverse (a unification is a rewrite of both adapters), surprising (two switches on the same event names read as duplication a reader will try to "fix"), and a real trade-off (a declarative (kind, name, label set) table was weighed and rejected).
0002 free-threading is compat-only kept 0002 Hard to reverse (a published classifier and a support claim are not quietly withdrawn), surprising (free-threaded support that deliberately adds no parallelism, plus a required env var), and a real trade-off (four alternatives were weighed, including exploiting the parallelism).

0002's revisit trigger is folded in rather than kept as a block: DISABLE_SQLALCHEMY_CEXT_RUNTIME=1 is the real boundary of the guarantee, not a scheduling note, so it is stated as the scope of the decision with #160 as the issue link. 0001's parity-contract-test bullet survives as a clause, since the rejection is the non-obvious half of the decision.

Citations

None move. The only ADR reference in the repo is the ADR-0001 example in docs/agents/domain.md, which still names record 0001 and the same subject; the file-structure listing in the same file is unchanged. The repo-wide sweep for adr/NNNN and ADR-NNNN across *.py, *.md, *.toml and *.yml finds no old or dropped number.

Stale claims

None. Every concrete claim was re-checked against the tree and holds: the two __call__ switches in faststream_outbox/metrics/{prometheus,opentelemetry}.py with no shared table; dispatched as three Prometheus operations (_received_total.inc, _received_size.observe, _in_process.inc) and an explicit OpenTelemetry no-op; no parity contract test in tests/; the freethreaded CI job in .github/workflows/_checks.yml with its DISABLE_SQLALCHEMY_CEXT_RUNTIME=1 env and sys._is_gil_enabled() assertion, pinned to 3.14t; the Programming Language :: Python :: Free Threading :: 2 - Beta classifier in pyproject.toml; the docs note in docs/introduction/installation.md; and #160 still open. One wording change, not a correction: the classifier is now named explicitly instead of called "a classifier".

Gates

Gate Result
pytest -q tests/test_adr_citations.py 7 passed
pytest -q (full suite) 516 passed, 107 skipped - every skip is tests/test_integration.py / tests/test_client_contract.py reporting Postgres unreachable on the local DSN
ruff format --check 96 files already formatted
ruff check --no-fix all checks passed
eof-fixer . --check clean (exit 0)
lychee --offline --no-progress over both ADRs, CONTEXT.md, AGENTS.md 3 links, 2 OK, 0 errors, 1 excluded (the offline run skips the remote #160 link)

No Python was touched, so the ruff gates are informational here.

Both records pass the admission test, so nothing was dropped and nothing was
merged; numbering and filenames are unchanged. Each record is now a single
paragraph: the **Decision:** lead, the rejected-alternative bullet lists, and
the revisit trigger are folded into prose, with the free-threading revisit
trigger reduced to the scope boundary it actually states.
@github-actions

Copy link
Copy Markdown

Benchmark gate

✅ gate passed

scenario msg/s delete/msg WALrec/msg WALB/msg fpi upd del dead_tup
consumer/w1/b10 982 1.000 6.79 917 242 5000 5000 10000
consumer/w1/b100 986 1.000 6.83 919 243 5000 5000 10000
consumer/w2/b10 1101 1.000 6.81 966 242 5000 5000 10000
consumer/w2/b100 1341 1.000 6.73 955 243 5000 5000 10000
consumer/w4/b10 1040 1.000 6.76 969 262 5000 5000 10000
consumer/w4/b100 1578 1.000 6.86 1036 244 5000 5000 10000
consumer/w1/b100/tfbs100 5357 0.010 6.07 1116 243 5000 5000 10000
producer/w1/b100 2079 0.000 3.04 584 0 0 0 0

Gated (fails the build): delete_calls + tuple counters (upd/del/ins) + the producer's insert_calls, exact; select_calls within +2; wal_records within a 10% band. msg/s, WAL bytes and total calls are informational (timing/FPI noise).

@lesnik512
lesnik512 merged commit b500455 into main Sep 19, 2026
9 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