docs(adr): correct nats-core + nats-jetstream evaluation

[Aureliolo]

Summary

Corrects the "NATS Client Library" section of docs/architecture/decisions.md. The 2026-04-11 ADR (PR #1228, closing #1217) concluded that nats-core "lacks JetStream, KV store, and durable consumers" and used that to justify staying on nats-py==2.14.0. caspervonb pointed out on that PR that the conclusion is based on a misread of the modular client family: nats-core is the protocol layer, and JetStream/KV live in companion packages (nats-jetstream and nats-key-value), mirroring the nats.js v3 split.

The rewritten section records:

• A short Correction note citing caspervonb's comment and Re-evaluate nats-core + nats-jetstream migration: original ADR was based on misread packaging #2037 (sanctioned framing).
• The live package state (verified 2026-05-24 against the PyPI JSON API and nats-io/nats.py main): nats-core 0.2.0, nats-jetstream 0.3.0 (both Beta on PyPI), nats-key-value 0.1.0 (Beta, workspace-only, not yet on PyPI), and nats-py 2.14.0 still the current monolith.
• That upstream nats-io/nats.py PR #932 (the inspect.iscoroutinefunction fix for Python 3.14) merged 2026-05-13 but has not been tagged for release yet.
• A four-row candidate table replacing the prior wrong rejection of nats-core.
• A JetStream API-surface delta and a KV API-surface delta, both grounded in the actual call sites under src/synthorg/communication/bus/ and the upstream source files. Includes a confirmed regression risk for publish_batch: nats-jetstream 0.3.0 does not expose publish_async / publish_async_completed on either JetStream or Stream.
• A trigger-based revisit replacing the prior fixed 2026-06-10 checkpoint: (A) unpin to nats-py>=2.15 when that release ships, (B) re-evaluate migration when nats-key-value is on PyPI AND the family is at 1.0, (C) re-evaluate urgency if nats-py is silent for six months. Plus a 2026-08-01 calendar revisit so a quiet period does not let the trigger drift.

Decision: stay on nats-py==2.14.0 with the scoped filterwarnings entry, per user-confirmed Path A on 2026-05-24. No follow-up migration issue filed; acceptance criterion 4 of #2037 is satisfied vacuously by the user's choice and durably captured by the Trigger-based revisit section.

Scope

Docs-only. No changes to src/synthorg/communication/bus/**, pyproject.toml, or the scoped filterwarnings entry.

Test plan

• git diff main...HEAD confirms only docs/architecture/decisions.md is touched.
• Local pre-commit (markdownlint, trim trailing whitespace, fix end of files, no em-dashes, codespell) clean on commit.
• Local pre-push (lychee, doc numeric macros, etc.) clean on push.
• ADR claims spot-checked against the codebase by docs-consistency agent: every file path, API call, error type, and pin location confirmed accurate (see review coverage below).

Review coverage

Pre-reviewed by 3 agents on the corrected ADR:

• docs-consistency: zero findings; every concrete claim in the ADR verified against the codebase.
• comment-quality-rot: one Minor finding (migration framing carried over from the prior ADR text in the Context paragraph); fixed in 1b1ee7b1e.
• issue-resolution-verifier: all four acceptance criteria of Re-evaluate nats-core + nats-jetstream migration: original ADR was based on misread packaging #2037 marked RESOLVED.

Closes #2037

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request updates the architecture decision records regarding the NATS client library. It corrects a previous misinterpretation of the modular NATS client family's capabilities and provides a comprehensive technical analysis of the migration path. The decision to remain on the current monolithic nats-py client is maintained, with a clear, trigger-based plan for future re-evaluation.

Highlights

• ADR Correction: Corrected the NATS Client Library ADR to reflect that the modular nats-io/nats.py family does indeed support JetStream and KV store, contrary to the previous evaluation.
• Migration Strategy: Formalized a trigger-based revisit plan for migrating to the modular NATS client family, replacing the previous fixed-date checkpoint.
• Technical Analysis: Added detailed API-surface and KV-surface delta tables to document the effort and risks associated with a future migration, including a confirmed regression in publish_batch.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e271b3fb-a923-4af6-bfd6-22ff532a2958

📥 Commits

Reviewing files that changed from the base of the PR and between 1b1ee7b and bbed413.

📒 Files selected for processing (1)

• docs/architecture/decisions.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Lighthouse Site
• GitHub Check: Build Web Assets (melange)
• GitHub Check: Build Preview
• GitHub Check: Analyze (python)
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (1)

{README.md,docs/**/*.md}

📄 CodeRabbit inference engine (CLAUDE.md)

Numerics in README and public docs must be sourced from data/runtime_stats.yaml via <!--RS:NAME--> markers

Files:

• docs/architecture/decisions.md

🧠 Learnings (7)

📚 Learning: 2026-05-16T18:36:19.195Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/guides/contributing.md:95-95
Timestamp: 2026-05-16T18:36:19.195Z
Learning: In the SynthOrg repo, the “Doc Numeric Claims (MANDATORY)” RS-marker rule should be applied only to these docs: README.md; docs/index.md; docs/roadmap/index.md; docs/architecture/decisions.md; docs/reference/convention-gates.md. This rule is enforced by scripts/check_doc_numeric_macros.py (with runtime substitution by scripts/inject_runtime_stats.py), so reviewers should not flag similar numeric-claim issues in other paths (e.g., anything under docs/guides/). When checking those scoped files, the rule skips fenced code blocks and only flags digits that are adjacent to stat nouns (tests/providers/agents/stars/releases). Numeric CLI flags like “--num-workers=4” inside fenced bash code blocks are not subject to this rule.

Applied to files:

• docs/architecture/decisions.md

📚 Learning: 2026-05-16T18:36:31.446Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/reference/conventions.md:787-789
Timestamp: 2026-05-16T18:36:31.446Z
Learning: In Aureliolo/synthorg, follow the `Doc Numeric Claims (MANDATORY)` rule enforced by `scripts/check_doc_numeric_macros.py` only for these markdown files: `README.md`, `docs/index.md`, `docs/roadmap/index.md`, `docs/architecture/decisions.md`, and `docs/reference/convention-gates.md`. The gate flags digits that appear adjacent to the stat nouns `tests`, `providers`, `agents`, `stars`, and `releases`—those numeric claims must use the required `<!--RS:...-->` macro format. Do not apply this rule to prose that mentions Python version numbers (e.g., “Python 3.14” / “Python 3.15”); those should not be flagged as requiring `<!--RS:...-->`.

Applied to files:

• docs/architecture/decisions.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: In the synthorg repo, the “Doc Numeric Claims (MANDATORY)” RS-marker rule is enforced only for this exact set of Markdown files: README.md, docs/index.md, docs/roadmap/index.md, docs/architecture/decisions.md, and docs/reference/convention-gates.md. During code reviews, do not raise RS-marker/numeric-claims findings for numeric values in any other files (e.g., docs/getting_started.md, docs/guides/*, docs/reference/conventions.md), since they are not checked or injected by scripts/check_doc_numeric_macros.py or scripts/inject_runtime_stats.py.

Applied to files:

• docs/architecture/decisions.md

📚 Learning: 2026-05-16T18:36:31.446Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/reference/conventions.md:787-789
Timestamp: 2026-05-16T18:36:31.446Z
Learning: In Aureliolo/synthorg, do not require adding `<!--RS:...-->` “Doc Numeric Claims (MANDATORY)” numeric macros for Python version numbers mentioned in documentation prose (e.g., “Python 3.14”, “Python 3.15”). The `scripts/check_doc_numeric_macros.py` gate only applies to `README.md`, `docs/index.md`, `docs/roadmap/index.md`, `docs/architecture/decisions.md`, and `docs/reference/convention-gates.md`, and it only flags digits adjacent to specific stat nouns (tests/providers/agents/stars/releases), not language version mentions like “Python 3.14”.

Applied to files:

• docs/architecture/decisions.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: When reviewing Markdown in the synthorg repo, account for the CI gate `check_doc_numeric_macros.py`: it skips fenced code blocks entirely, and it only flags digits that are adjacent to these stat nouns: `tests`, `providers`, `agents`, `stars`, `releases`. Therefore, numeric examples such as CLI flag values (e.g., `--num-workers=4` in fenced bash blocks) and prose version numbers (e.g., `3.14`/`3.15`) are not expected to trigger this check; prioritize changes only when digits appear next to one of the listed nouns (e.g., “5 tests”, “10 stars”, etc.).

Applied to files:

• docs/architecture/decisions.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: When reviewing markdown files for the "Doc Numeric Claims (MANDATORY)" RS-marker rule, only require/flag missing RS markers in the files that are actually in-scope for the rule. The scope is enforced via an identical _SCOPED_FILES allowlist in scripts/check_doc_numeric_macros.py and scripts/inject_runtime_stats.py, and currently includes: README.md; docs/index.md; docs/roadmap/index.md; docs/architecture/decisions.md; docs/reference/convention-gates.md. For any other markdown files (e.g., docs/getting_started.md, docs/guides/*), missing RS markers for numeric claims are no-ops and should NOT be flagged.

Applied to files:

• docs/architecture/decisions.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: When reviewing Markdown in the synthorg repo against the `check_doc_numeric_macros.py` gate, account for its documented behavior: it skips fenced code blocks entirely, and it only flags digits that are adjacent to specific stat nouns (`tests`, `providers`, `agents`, `stars`, `releases`). As a result, CLI-style numbers (e.g., `--num-workers=4`) inside fenced bash code blocks should never be treated as violations of this gate; only non-fenced text needs checking, and only around those specific nouns.

Applied to files:

• docs/architecture/decisions.md

🔇 Additional comments (1)

docs/architecture/decisions.md (1)

116-177: LGTM!

---

Walkthrough

This PR updates the architectural decision document to correct a prior misread about the nats-core Python client library. The original ADR incorrectly stated that nats-core lacks JetStream, KV store, and durable consumer support; in fact, these features are provided by companion packages (nats-jetstream, nats-key-value, etc.) in a deliberately modular design. The changes restate the decision to remain on nats-py==2.14.0 with a scoped filterwarnings workaround, document current package availability and versions, inventory SynthOrg's actual NATS/JetStream/KV usage, compare API surface deltas between nats-py and the modular family, and replace a prior fixed-date checkpoint with explicit trigger-based revisit conditions (Triggers A–C) plus a calendar revisit date of 2026-08-01.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main change: a correction to the NATS Client Library evaluation documenting the proper packaging model of nats-core and nats-jetstream.
Description check	✅ Passed	The description is thorough and directly related to the changeset, explaining the correction from misreading to proper modular packaging, current package state, API deltas, trigger-based revisit, and decision rationale.
Linked Issues check	✅ Passed	The PR satisfies all four acceptance criteria of #2037: re-evaluated nats-core/nats-jetstream with correct packaging model, confirmed KV viability over nats-jetstream, updated docs/architecture/decisions.md with corrected factual content, and documented non-viability of migration in current PR (decision to stay on nats-py==2.14.0).
Out of Scope Changes check	✅ Passed	All changes are in-scope: only docs/architecture/decisions.md was modified; no src/, pyproject.toml, or filterwarnings changes were made, consistent with the stated scope and linked issue requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request updates the NATS client library architectural decision record to correct a previous misinterpretation of the modular nats-io/nats.py client family. The changes include a detailed comparison of API surfaces, a live package state analysis, and a new trigger-based revisit strategy. Feedback focuses on ensuring consistency with the project's dependency pinning strategy by recommending exact version pins for future releases instead of version ranges in the documentation.

[gemini-code-assist]

The project consistently uses exact version pins for dependencies in pyproject.toml (e.g., nats-py==2.14.0). The ADR suggests using a range (>=2.15), which deviates from this convention. It is better to specify an exact pin for the future release to maintain consistency.

**Decision:** Stay on `nats-py==2.14.0` with the scoped `filterwarnings` entry. Bump the pin to `nats-py==2.15.0` and drop the filter the moment that release ships (`nats-io/nats.py` PR [#932](https://github.com/nats-io/nats.py/pull/932), merged 2026-05-13, contains the `inspect.iscoroutinefunction` swap).

[gemini-code-assist]

To maintain consistency with the project's dependency pinning strategy, specify an exact version for the future nats-py release.

1. **Trigger A -- `nats-py 2.15+` is released:** bump the pin in `pyproject.toml` to `nats-py==2.15.0` (or the latest stable version), drop the scoped `filterwarnings` entry, run `uv run python -m pytest tests/ -m integration -k nats` to confirm no deprecation warnings fire, and update this section with the resolution outcome. This closes the Python 3.14 thread without any further migration consideration.