Repository navigation
Open
Labels
area:replicationReplication, cluster sync, peer connectionsReplication, cluster sync, peer connections
Description
Summary
In a base copy, a resident peer that does not advertise residencyStubCopy is sent this node's INVALIDATED residency stub as a complete put. If that peer has no row for the record, it stores the stub's index-only projection as the full record.
Main documents this as accepted behavior during rolling upgrades ("never a skip"), and it stops once every peer advertises the capability. Filed so the decision stays tracked after the base-copy guard PR was closed as superseded.
What happens
- The copy walk sends a stub as
invalidateonly to a learned peer that advertisesresidencyStubCopy. Any other peer, including one whose capability bag is not learned yet, gets the pre-gateput:replicationConnection.tsL7225-L7229. DESIGN.mdstates the rule: "never a skip: the copy may be that peer's only source for the row" (L92).- A listed resident that already holds the row at the same version skips the
put. A receiver without the row stores the projection "as complete — today's behavior until it upgrades" (L362-L366).
The affected peer is all three of: it predates residencyStubCopy, it is a listed resident, and it lacks the row (rebuilt from nothing, or newly named).
Scope
- Mixed-version clusters only. No peer is affected once every peer advertises
residencyStubCopy. - Silent: the peer serves the index-only projection as the record.
- Unverified: rows already stored this way are probably not repaired by the upgrade, because core's equal-version resident guard would keep them as full records against a later
invalidate. Reasoned from the docs, not tested.
Options when picking this up
- Accept and close once the release lines that predate
residencyStubCopyare out of support. - Withhold the stub
putfrom a listed peer that lacks the capability, as the closed guard PR did. This reverses the documented "never a skip" rule (DESIGN.mdL92 and L362), so decide that first. Code: one condition atreplicationConnection.tsL7225-L7229, plus the legacy-peer case inunitTests/replication/residencyWire.test.mjs("copies a stub exactly as before the gate to a peer with …").
Evidence and confidence
- Read from
mainate6570e0d. Not reproduced on current main: a repro needs a node that does not advertiseresidencyStubCopy, such as a previous release from themixedVersionRollingUpgrade.test.mjsharness. - The same outcome was reproduced before the gate existed: the closed PR's cluster test rebuilt a resident from nothing and it held
{"home":…}as a complete row (invalidated: false).
References
- Record-based setResidency destroys already-stored local values on ordinary writes (invalidated stub overwrite, no delete entry) - byId variant preserves; per-thread-static scoping makes it thread-dependent
- Never send an INVALIDATED residency stub as a complete record from the base copy or GET_RECORD (closed as superseded)
- fix: preserve residency stubs across replication and remote reads (adds the
residencyStubCopygate) - Gate the stub-sending copy sender on a peer capability instead of a preparatory release
- fix: propagate residency read failures and refresh stub indexes (core's equal-version resident guard)
🤖 Generated by Claude Sonnet 5.5; posted via @kriszyp.
Metadata
Metadata
Assignees
Labels
area:replicationReplication, cluster sync, peer connectionsReplication, cluster sync, peer connections
Type
Fields
Priority
P3
Activity