docs: 1.x ADRs — SDK split, instance surface, and messaging contract - #2109
Merged
ethanwinters merged 4 commits intoAug 18, 2026
Merged
Conversation
✅ Deploy Preview for carbon-ai-chat-components ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for ai-chat-components-react ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for carbon-ai-chat-demo ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced Aug 10, 2026
Open
ethanwinters
force-pushed
the
adr-1x-sdk-instance-and-messaging
branch
from
August 10, 2026 15:04
c4bb819 to
a338feb
Compare
ethanwinters
marked this pull request as ready for review
August 10, 2026 15:04
davidmenendez
left a comment
davidmenendez
left a comment
Contributor
There was a problem hiding this comment.
content looks good to me! quick question: this should be in numerical order. not sure why it suddenly went from 2-3-4-5-7-9-23! is there a specific reason for this?
Contributor
Author
|
@davidmenendez made the mistake of assigning adr numbers in the issues and then had to break some of the adrs up into multiple adrs, meaning I got stuck with adding new issues at the end of the list. Going forward, won't assign numbers in the issues, but didn't want to unwind 20+ issues that reference each other now. |
ethanwinters
force-pushed
the
adr-1x-sdk-instance-and-messaging
branch
from
August 11, 2026 12:01
a338feb to
99c9db6
Compare
Seven related ADRs. Suggested review order: 1. ADR-0002 — the strategic split: framework-agnostic core, React wrapper, and headless SDK all ship from one package 2. ADR-0025 — deep review this last, but skim for orientation now; shows the assembled SDK surface so the shape of the destination is clear before reading the steps to get there 3. ADR-0023 — callbacks survive the split unchanged through a parameterized config; names the two halves 4. ADR-0005 — walks the instance member list and validates the partition assumption ADR-0002 rests on 5. ADR-0004 — chat state moves to per-field scoped stores; deprecates getState() 6. ADR-0009 — every conversation verb is reached through instance.messaging 7. ADR-0007 — both message-delivery APIs run on one store pipeline 8. ADR-0025 — full review now that the sibling records are in hand 9. ADR-0003 — instance lifetime belongs to the acquire, not the host mount
Fills the discussion field on all eight records now that the tracking issues exist. validate:adrs goes green: a proposed record needs a comment venue, and each one now points at its own.
Rejected option C argued that a surviving getState() would be permanent because no release after 2.0.0 takes breaking changes. No 3.0.0 is scheduled, but none is ruled out either. The argument holds on the weaker premise: the next major has no date, so the deprecated getter names no removal release and the two read models coexist indefinitely.
ethanwinters
force-pushed
the
adr-1x-sdk-instance-and-messaging
branch
from
August 11, 2026 14:38
9dea3d0 to
fbf9a42
Compare
ethanwinters
enabled auto-merge
August 11, 2026 17:41
davidmenendez
approved these changes
Aug 18, 2026
Merged
via the queue into
carbon-design-system:main
with commit Aug 18, 2026
376b8e4
28 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2033
Closes #2034
Closes #2035
Closes #2036
Closes #2040
Closes #2080
Eight architecture decision records for the 1.x SDK and messaging work, merging as
proposed. No code changes —docs/adr/only.Each record decides one thing and takes its own comment window, so an objection to one never blocks the rest. Together they cover the package split, what the instance surface becomes, how state is read, and what the send promise means.
Changelog
New
ChatInstancesurvives the split as the composition of both halvesinstance.messagingChanged
docs/adr/README.md— index rows, regenerated bynpm run sync:adrsTesting / Reviewing
Suggested review order. The records cross-reference each other, so reading them by number is harder than this path:
getState()instance.messagingComment on the record's own issue, not on this PR. Review comments stop being findable once a PR merges, which is the whole reason the venue is an issue. Each record has one:
All eight windows close 2026-08-18 at the earliest. Silence is not agreement — nothing is accepted until a maintainer sets the status.
Gates:
Four records read above the 8–11 band: 0005 and 0007 at 11.1, 0023 at 11.3, 0025 at 11.0.