Skip to content

docs: correct what "the same instance" promises two attached clients - #262

Open
Yaraslaut wants to merge 2 commits into
masterfrom
docs/217-shared-instance-visibility
Open

docs: correct what "the same instance" promises two attached clients#262
Yaraslaut wants to merge 2 commits into
masterfrom
docs/217-shared-instance-visibility

Conversation

@Yaraslaut

Copy link
Copy Markdown
Member

Closes #217.

A spec contradicting a spec

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:

subscribe<R> fans out to handlers on the same Bridge; there is no
server-initiated push, so two separate clients sharing an instance do not see
each other's results until they ask again.

Two documents, one feature, directly disagreeing. The README is the accurate one.

What sharing actually promises

shared_instances.md now states it precisely: both handlers point at one
underlying 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 to
handlers 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 RemoteServer process. I verified this rather
than taking the issue's word — _directory, _models, _owners,
_attachCount, _connectionScopes and _nextId are ordinary non-static members
of one RemoteServer object in remote.hpp, with no membership protocol, shared
store, or placement layer.

So two RemoteServer processes 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 #261
also edits.)

Verification

Documentation only — no code changes. scripts/check_spec_citations.sh passes.
The three factual claims (non-static directory members, the
shared_instances.md wording, the contradicting README line) were each checked
against master rather than carried over from the issue; the README line is at
458, not the 449 the issue cites.

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
Yaraslaut force-pushed the docs/217-shared-instance-visibility branch from 80a87e6 to bca4026 Compare August 24, 2026 21:15
@codecov

codecov Bot commented Aug 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

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.

shared_instances.md and README.md disagree about whether two attached clients see each other's results

1 participant