[TimLFletcher]

Ticket: DOC-13956 (engineering change: MB-63560)

Needs engineering review before merge. The new text describes Data Service internals from Jim Walker's ticket comments and the kv_engine source. Jim Walker (or another KV engineer) should confirm the wording. Do not merge until that happens.

What changed

Adds a short Watermarks for Ephemeral Buckets subsection under Memory Watermarks in learn/buckets-memory-and-storage/memory.adoc. Following Jim Walker's comments on the ticket, it covers two points and nothing more:

1. Ephemeral buckets count only active vBucket memory and lower the high watermark by the share of vBuckets that are active. Jim noted this was undocumented: the existing section describes only the persistent-bucket watermarks.
2. From 8.0.2, auto-delete is throttled. The Data Service ejects a limited amount, then waits for DCP clients to receive the deletions before ejecting more (MB-63560).

No new page. buckets.adoc is unchanged, because Jim confirmed its description of ejection is still correct.

Files touched: modules/learn/pages/buckets-memory-and-storage/memory.adoc (+14 lines)

Sources

Claim	Source
Ephemeral paging uses different thresholds from the persistent-bucket high watermark; only active vBucket memory is considered; the replica-heavy rebalance example	Jim Walker, DOC-13956 comment, 2026-02-24
Pageable high watermark = mem_high_wat × (active + pending vBuckets) / total vBuckets	kv_engine engines/ep/src/ephemeral_bucket.cc, EphemeralBucket::getPageableMemHighWatermark() at 914d533
Ejected items stay as tombstones until DCP producers have sent them, so deletes don't immediately reduce memory; the pager waits until all cursors are past the highest paged-out seqno before running again	kv_engine commits 914d533 and 36381e5 (commit messages)
Each round of deletes is capped (at most high watermark minus low watermark)	kv_engine c29d5a7, fae62dc
Available from 8.0.2	MB-63560 build comments: first in couchbase-server-8.0.2-5277; also 7.6.12-8819 and 8.1.0-2015

Deliberately left out:

• the exact formula and the cap value, because they are internal and changed twice during the fix;
• the new stats pager_deleted and pager_throttled, which stat_definitions.json marks as "added 7.6.11", although the fix shipped in 7.6.12;
• the pageable low watermark calculation, which I have not traced in the source.

Open questions for the reviewer

1. Is it accurate to say the high watermark is lowered "in proportion to the share of the node's vBuckets that are active"? The code counts pending vBuckets as active for this purpose.
2. Should the docs say anything about the pageable low watermark?
3. Should pager_throttled / pager_deleted be mentioned so users can see when throttling happens?
4. Jim suggested a release note for MB-63560. None exists on any branch. Should one be added to the 8.0.2 fixes list, or is that left to the release-notes process?

Branches

• This PR: release/8.5 (Totoro, the ticket's label). Same change as couchbase/docs-server#4204 on release/8.0; the "Starting with Couchbase Server 8.0.2" wording is correct on both branches.
• release/7.6: not covered. The fix also shipped in 7.6.12. If the 7.6 docs should carry it, that needs its own PR with "7.6.12" as the version.

Verification

PASS[docs-server @ DOC-13956-8.5 vs baseline release/8.5]: no new build diagnostics.

The release/8.5 baseline was regenerated from a clean release/8.5 tip (e8e05ac2, 566 diagnostics) before this check. The old baseline was stale: the unmodified tip and this branch produced byte-identical output against it.

Anchor caveat: this adds a new anchor #ephemeral-watermarks. Nothing links to it yet. The build doesn't validate anchors, so check it by hand if you add a link.

No local Couchbase Server instance was run. The behaviour is taken from the ticket and the source at the commits above, not observed.

🤖 Generated with Claude Code