Skip to content

Base copy: a resident peer without residencyStubCopy stores a residency stub as a complete record #1127

Open

Description

@kriszyp

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 invalidate only to a learned peer that advertises residencyStubCopy. Any other peer, including one whose capability bag is not learned yet, gets the pre-gate put: replicationConnection.ts L7225-L7229.
  • DESIGN.md states 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

  1. Accept and close once the release lines that predate residencyStubCopy are out of support.
  2. Withhold the stub put from a listed peer that lacks the capability, as the closed guard PR did. This reverses the documented "never a skip" rule (DESIGN.md L92 and L362), so decide that first. Code: one condition at replicationConnection.ts L7225-L7229, plus the legacy-peer case in unitTests/replication/residencyWire.test.mjs ("copies a stub exactly as before the gate to a peer with …").

Evidence and confidence

  • Read from main at e6570e0d. Not reproduced on current main: a repro needs a node that does not advertise residencyStubCopy, such as a previous release from the mixedVersionRollingUpgrade.test.mjs harness.
  • 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

🤖 Generated by Claude Sonnet 5.5; posted via @kriszyp.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:replicationReplication, cluster sync, peer connections

    Type

    No type

    Fields

    Priority

    P3

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions