docs: correct what "the same instance" promises two attached clients - #262
Open
Yaraslaut wants to merge 2 commits into
Open
docs: correct what "the same instance" promises two attached clients#262Yaraslaut wants to merge 2 commits into
Yaraslaut wants to merge 2 commits into
Conversation
shared_instances.md said two connections attached to key 42 "see each other's state". README.md says the opposite for the cross-client case -- subscriptions are in-process, there is no server-initiated push, and two clients sharing an instance do not see each other's results until they ask again. Two documents, one feature, contradicting each other. The README is the accurate one. shared_instances.md now says what sharing does promise: both handlers point at one underlying instance, so each round trip observes the same durable state and a write is visible to the other client on its next action -- but nothing propagates on its own, because subscribe<R> fans out only to handlers on the same Bridge. Also records the assumption the section's own justification rests on: the directory is per-process. `_directory`, `_models`, `_owners`, `_attachCount`, `_connectionScopes` and `_nextId` are ordinary non-static members of one RemoteServer object -- verified in remote.hpp, not assumed -- so two RemoteServer processes behind one endpoint have independent directories and a key resolves to a different instance in each. That is the divergence keyed sharing exists to prevent, reintroduced one layer up and silently. Scope correction against the issue: it also asks for the same qualification in backend.md, "which also frames the directory as server-side". It does not. backend.md's single mention of the directory is about which mutex guards it alongside the connection-scope map; it makes no cross-client or cross-process claim, so there is nothing there to correct and it is left alone. Closes #217
The original run was cancelled by the supersede-obsolete-runs concurrency rule (#257) shortly after it merged, and re-running the cancelled workflows produced attempts that were themselves cancelled within minutes. An empty commit gives the PR a fresh head so its checks run from a clean slate. No content change.
Yaraslaut
force-pushed
the
docs/217-shared-instance-visibility
branch
from
August 24, 2026 21:15
80a87e6 to
bca4026
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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
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 #217.
A spec contradicting a spec
shared_instances.mdsaid two connections attached to key 42 "see each other'sstate".
README.mdsays the opposite for the cross-client case:Two documents, one feature, directly disagreeing. The README is the accurate one.
What sharing actually promises
shared_instances.mdnow states it precisely: both handlers point at oneunderlying instance, so each read/write round trip observes the same durable
state, and a write by one client is visible to the other on that other client's
next action. Nothing propagates on its own —
subscribe<R>fans out only tohandlers on the same
Bridge, never across connections or processes.That distinction is the whole thing: shared state, not shared notifications.
The assumption the section's own justification rested on
The passage justified server-side directory placement without ever stating that
it holds only for a single
RemoteServerprocess. I verified this ratherthan taking the issue's word —
_directory,_models,_owners,_attachCount,_connectionScopesand_nextIdare ordinary non-static membersof one
RemoteServerobject inremote.hpp, with no membership protocol, sharedstore, or placement layer.
So two
RemoteServerprocesses behind one endpoint have independent,non-communicating directories, and a key resolves to a different instance in
each — the exact divergence keyed sharing exists to prevent, reintroduced one
layer up, silently. That is now written down, along with the fact that a
deployment needing one instance per key across replicas must route keys to a
fixed process itself.
Scope correction
The issue also asks for the same qualification in
docs/spec/core/backend.md,"which also frames the directory as server-side". It does not. backend.md's
single mention of the directory is about which mutex guards it alongside the
connection-scope map — it makes no cross-client or cross-process claim, so there
is nothing there to correct, and I left it alone rather than adding text to
satisfy the issue's description.
(A convenient side effect: this PR no longer touches
backend.md, which #261also edits.)
Verification
Documentation only — no code changes.
scripts/check_spec_citations.shpasses.The three factual claims (non-static directory members, the
shared_instances.mdwording, the contradicting README line) were each checkedagainst
masterrather than carried over from the issue; the README line is at458, not the 449 the issue cites.