docs(platform): say why in-place edits to shipped generations are inert

[QuantumExplorer]

Basic explanation

What this does: adds code comments only. Node code that already ran on the live network (the "shipped" versions of a function) must keep behaving exactly the same, forever, so a node syncing from the start computes the same state as everyone else. Our rule is that such code may only be edited when the edit provably cannot change anything, and the edited lines must say why. A few 4.2 edits were safe but did not say why, and a few shared helpers that old code now depends on carry no warning. This PR writes those explanations and warnings down.

Value: the next person editing these places sees why the current code is safe and that changing it would change what old protocol versions compute. That turns a silent trap into a documented one.

Risks: None. No code changes.

Issue being fixed or feature implemented

book/src/contributing/coding-conventions.md ("Shipped generations are frozen unless the change cannot modify consensus") asks for a comment at every in-place edit to a shipped generation naming why it is inert for every protocol version that selects it. A review of the 4.1 and 4.2 changes found edits that are inert but uncommented, and unversioned helpers that shipped generations call without any note saying so.

What was done?

• masternode_vote/balance/v0 (edited by fix(drive-abci): refuse a masternode vote on an unfunded poll as an unpaid consensus error #4904): a vote refused unpaid here, or one that failed inside execution before, never reaches a block, so the edit changes no block.
• try_from_schema/common::parse_token_costs (feat(platform)!: optional document token costs paid in credits when the token payment is left out #4828): document meta-schemas v0-v2 set additionalProperties: false on documentActionTokenCost, so protocol versions 1-13 read optional as false, as before.
• try_from_schema/common::parse_indices TTL agreement loop (feat(drive): time-range index TTL — O(1) flat-drop drainage and ephemeral-bytes fees #4581): only the generation 3 grammar admits timeRange, so generations 0-2 never enter it.
• finalize_block_proposal v0 (feat(drive-abci): ask Tenderdash for the next block right away when withdrawal work is queued #4741): the pending-withdrawal read is unbilled and only sets the Tenderdash hint.
• Warnings on unversioned helpers that shipped generations call: terminal_member_tree_type (add/remove reference v0), property_name_tree_type_and_ranked_axes and its per-level form (insert/update contract v0), Value::equal_underlying_data (replace transformer v0 and proof verification v0). Any change to what they return for inputs old versions can produce belongs in a new versioned method.

How Has This Been Tested?

cargo check -p drive -p drive-abci, cargo fmt --all. Comments only.

Breaking Changes

None.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · d56f313

• Bots — coderabbitai not yet · thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
• Self-review — post /self-reviewed once the bots are done
• Within your 5 open PRs
• Build running
• Approvals — you own every area touched; none needed

When every box is checked the PR Hygiene check passes and this can merge.

[coderabbitai]

Warning

Review limit reached

Next included review available in 21 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: dashpay/platform/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 90cfa27b-4da9-4454-87c3-20bcfbd0c930

📥 Commits

Reviewing files that changed from the base of the PR and between 4d4f38d and d56f313.

📒 Files selected for processing (6)

• packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs
• packages/rs-drive-abci/src/execution/engine/finalize_block_proposal/v0/mod.rs
• packages/rs-drive-abci/src/execution/validation/state_transition/state_transitions/masternode_vote/balance/v0/mod.rs
• packages/rs-drive/src/drive/document/index_level_tree_types.rs
• packages/rs-drive/src/drive/document/ranked_index_tree_type.rs
• packages/rs-platform-value/src/eq.rs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thepastaclaw]

🔍 Review in progress — actively reviewing now (commit d56f313) · triage: trivial

[thepastaclaw]

Final review — Phase 1 only (trivial change)

The exact-head diff changes comments only; no runtime behavior or version tables change. Two documentation inaccuracies are confirmed: the shared-parser notes incorrectly include generation 0, and the terminal-tree helper warning incorrectly says every protocol version selects remove_reference v0. Both are non-blocking wording corrections; the stated inertness conclusions remain intact.

💬 2 nitpick(s)

Review provenance

Source: reviewer 1: glm-5.3-flash (agent: phase1-reviewer, role: general); reviewer 2: glm-5.3-flash (agent: phase1-reviewer, role: architecture-layering); reviewer 3: glm-5.3-flash (agent: phase1-reviewer, role: platform-versioning); final verifier: gpt-6-astra (agent: astra-gate-verifier, role: final-verifier)

• Triage: trivial by gpt-6-astra (effort low) — The diff only adds or clarifies comments explaining consensus-inert edits and versioning constraints, with no changes to executable code or behavior.
• Phase 1 reviewers: glm-5.3-flash — general (completed, effort high); agent phase1-reviewer, glm-5.3-flash — architecture-layering (completed, effort high); agent phase1-reviewer, glm-5.3-flash — platform-versioning (completed, effort high); agent phase1-reviewer
• Phase 1 model: glm-5.3-flash — zai quota: 5h 93% left, weekly 33% left; passed over gemini-3.8-flash-high (antigravity below 15% reserve: weekly 13% left, 5h 100% left)
• Fresh verifier: gpt-6-astra — final-verifier; agent astra-gate-verifier
• Phase 2 reviewers: not run (triage rated this change trivial); this review comments and never approves

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs`:
- [NITPICK] packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/common/mod.rs:1200-1202: Attribute the shared-parser inertness proofs to generations 1–2
  This note and the corresponding parse_token_costs note at lines 1469–1472 say generation 0 runs the shared code, but its driver parses indices inline through `.as_slice().try_into()` in v0/mod.rs and never calls parse_document_type_core or parse_token_costs. Generation 1 calls the shared core, and generation 2 delegates to generation 1. Update both notes to identify generations 1–2 (protocol versions 9–13) as the callers and, if retaining coverage of protocol versions 1–8, explain that generation 0 never reaches these edits. This preserves the correct inertness conclusion while stating the actual reason for each generation.

In `packages/rs-drive/src/drive/document/index_level_tree_types.rs`:
- [NITPICK] packages/rs-drive/src/drive/document/index_level_tree_types.rs:228-234: Correct the remove_reference generation selected by protocol version 14
  The statement that every protocol version selects remove_reference_for_index_level_for_contract_operations v0 is false for protocol version 14. Its DRIVE_VERSION_V9 uses DRIVE_DOCUMENT_METHOD_VERSIONS_V4, which selects remove_reference v1; that implementation also calls terminal_member_tree_type at lines 131 and 251. Distinguish the v0 callers selected by protocol versions 1–13 from the v1 caller selected by protocol version 14. The frozen-helper warning remains valid; only its version-selection explanation needs correcting.

[github-actions]

Your move: thepastaclaw left review threads unresolved; resolve them.
Full checklist in the description.