feat(sdk): indexOnly delete-by-values through the SDKs; book chapter

[QuantumExplorer]

Issue being fixed or feature implemented

Fifth and final PR of the indexOnly document types stack (rebased onto v4.2-dev after #4497 and #4494 merged): the client surface and long-term documentation.

What was done?

• rs-sdk: DocumentDeleteTransitionBuilder now keeps the full document when constructed via from_document (previously it discarded everything but the ids), and sign() refuses an id-only builder for an indexOnly type with guidance — the delete transition carries the document's values, and the batch factory selects the DocumentIndexOnlyDeleteTransition KIND from the doctype's storage mode (feat(dpp)!: indexOnly delete-by-values as its own transition kind #4497's design — delete-by-values is its own operation, not a version of the delete).
• wasm-sdk / js-evo-sdk: documentDelete routes a provided Document instance through from_document so its values ride along; the id-only plain-object form keeps working for stored document types. Queries and proofs need no client changes — FromProof for Documents flows through the synthesis path from feat(drive)!: indexOnly read surface — synthesize documents from index positions #4494.
• Book: new chapter book/src/drive/index-only-document-types.md covering the layout, the row commitment, the constraint matrix, the lifecycle, the synthesis read surface, and the cost story; registered in SUMMARY and cross-linked with the ranked-trees chapter.

How Has This Been Tested?

dash-sdk and wasm-sdk compile checks; the underlying flows are covered by the storage/ABCI/read-surface suites in the earlier PRs of the stack (including the SDK-equivalent executed-proof roundtrips).

Deferred with rationale: a platform-test-suite functional spec requires the legacy js-dash-sdk's delete factory to build the indexOnlyDelete kind first — the evo (wasm-sdk) flow is the covered path; tracked as a follow-up alongside startAt cursors, terminal-property where clauses, and the sum-axis/timeRange extensions.

Breaking Changes

None — client-side plumbing only.

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

Stack: #4491 (schema) → #4492 (storage) → #4493 (transitions/ABCI) → #4494 (queries/proofs) → this.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added documentation for index-only document types, including their lifecycle, constraints, reads, proofs, and storage benefits.
  • Added support for creating and deleting index-only documents while preserving the document data required for deletion.
  • Document creation now returns the confirmed document, including system-generated fields such as creation time.

• Documentation

  • Added index-only document types to the Drive documentation contents.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 82678480-4d4a-4cd2-8520-4b4872575225

📥 Commits

Reviewing files that changed from the base of the PR and between ae910e6 and 77c526f.

📒 Files selected for processing (5)

• book/src/SUMMARY.md
• book/src/drive/index-only-document-types.md
• packages/js-evo-sdk/src/documents/facade.ts
• packages/rs-sdk/src/platform/documents/transitions/delete.rs
• packages/wasm-sdk/src/state_transitions/document.rs

---

📝 Walkthrough

Walkthrough

This change documents index-only document types and updates document creation and deletion flows. Creation returns the confirmed document, including consensus-populated fields. Deletion preserves full document values for index-only types and validates deletion targets before signing.

Changes

Index-only document support

Layer / File(s)	Summary
Index-only protocol contract book/src/drive/index-only-document-types.md, book/src/SUMMARY.md	Documents protocol version 14 index-only storage, row commitments, constraints, lifecycle, reads, proofs, cost behavior, and the new table-of-contents entry.
Delete target resolution packages/rs-sdk/src/platform/documents/transitions/delete.rs	The delete builder retains full documents, validates document type and target consistency, rejects id-only deletes for indexOnly types, and tests full and minimal document resolution.
SDK document flow packages/wasm-sdk/src/state_transitions/document.rs, packages/js-evo-sdk/src/documents/facade.ts	Document creation returns the confirmed document. Document-instance deletion passes full values to the delete builder, while identifier-only deletion keeps the existing path.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant DocumentsFacade
  participant WasmSdk
  participant DocumentDeleteTransitionBuilder
  participant Platform
  Client->>DocumentsFacade: create(options)
  DocumentsFacade->>WasmSdk: documentCreate(options)
  WasmSdk->>Platform: submit document create transition
  Platform-->>WasmSdk: confirmed Document with system fields
  WasmSdk-->>DocumentsFacade: DocumentWasm
  DocumentsFacade-->>Client: confirmed Document
  Client->>WasmSdk: documentDelete(Document)
  WasmSdk->>DocumentDeleteTransitionBuilder: from_document(document)
  DocumentDeleteTransitionBuilder->>Platform: resolve and sign deletion

Loading

Suggested reviewers: lklimek, shumkov

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/index-only-sdk

---

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.}

[github-actions]

📖 Book Preview built successfully.

Download the preview from the workflow artifacts.
To view locally: download the artifact, unzip, and open index.html.

Updated at 2026-08-27T15:56:27.431Z

[thepastaclaw]

🕓 Ready for review — next in queue (commit 77c526f)
Queue position: 1/2 · 1 review active
ETA: start ~16:00 UTC · complete ~16:24 UTC (median 24m across 30 recent reviews; 2 slots)
Queued 2m ago · Last checked: 2026-08-27 16:00 UTC

[thepastaclaw]

Preliminary review — Codex only

The Rust/WASM routing now preserves full document values, but two in-scope blockers remain: id-only validation advances the cached nonce before returning, and WASM discards the confirmed create result needed to delete valid index-only documents that require $createdAt. The new routing also permits inconsistent builder state and lacks direct regression coverage, so changes are requested.
Source: Codex general, Rust-quality, and FFI reviewer lanes (exact backend model identifiers were not present in the supplied evidence); Claude Agent SDK final verifier (exact backend model identifier was not exposed); openclaw-agent/cliproxy/gpt-5.6-sol is orchestration-only and is not reviewer evidence.

Validated blockers were found in the Codex precheck. Opus is deferred until a fresh Codex revalidation clears the blocker gate.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (completed), gpt-5.6-sol — rust-quality (completed), gpt-5.6-sol — ffi-engineer (completed)
• Verifier: gpt-5.6-sol — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 2 blocking | 🟡 2 suggestion(s)

🤖 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-sdk/src/platform/documents/transitions/delete.rs`:
- [BLOCKING] packages/rs-sdk/src/platform/documents/transitions/delete.rs:175-201: Reject id-only deletes before reserving a nonce
  `get_identity_contract_nonce(..., true, ...)` increments the SDK's cached nonce before the newly added id-only/index-only validation returns an error. No transition is broadcast on this path, so each invalid call consumes only a local nonce. The cache deliberately preserves `max(cached, platform)` during refresh; after 24 such calls, the next valid transition is assigned a nonce beyond the protocol's missing-revision window and is rejected as `NonceTooFarInFuture`, while subsequent refreshes continue preserving and incrementing the poisoned value. Resolve the document type and reject the unsupported input before reserving the nonce.
- [SUGGESTION] packages/rs-sdk/src/platform/documents/transitions/delete.rs:21-30: Avoid independently mutable delete-target representations
  The new public `document: Option<Document>` exists alongside public `document_id` and `owner_id`, allowing callers to construct contradictory targets. When a document is present, `sign()` obtains the nonce using `self.owner_id`, while DPP derives the batch owner and transition ID from the stored document; `self.document_id` is ignored. Mutating the formerly canonical fields after `from_document`, or assigning `document` directly, can therefore reserve a nonce for one identity while constructing and signing a transition for another. Keep one canonical target representation, make the full-document field private, or validate that the duplicated ID and owner fields match before touching the nonce cache.
- [SUGGESTION] packages/rs-sdk/src/platform/documents/transitions/delete.rs:80-94: Add direct regression coverage for SDK delete variant routing
  No test exercises the client routing introduced here. The existing wasm-sdk deletion tests use the id-only plain-object form, so they never enter the new `Document` branch, and the rs-sdk tests do not verify that `from_document` retains values and selects a V1 delete for an index-only type. Add focused coverage for a successful full-document index-only delete, an id-only rejection that does not advance the nonce cache, the WASM `Document` dispatch, and a type requiring `$createdAt`; lower-layer transition, storage, and proof tests do not cover this SDK plumbing.

In `packages/wasm-sdk/src/state_transitions/document.rs`:
- [BLOCKING] packages/wasm-sdk/src/state_transitions/document.rs:461-466: Preserve the confirmed document needed for timestamp-indexed deletion
  The new `Document` branch forwards the original JS document, but a newly constructed `DocumentWasm` has `created_at: None`. During creation, Platform assigns the consensus block timestamp when `$createdAt` is required, and `put_to_platform_and_wait_for_response` returns a confirmed `Document` containing that timestamp; `documentCreate` currently discards that return value and leaves the original wrapper unchanged. Reusing the documented `Document` instance for deletion therefore reaches `DocumentDeleteTransitionV1::from_document`, which rejects it because the required `$createdAt` is absent. Return the confirmed `DocumentWasm` from creation or update the caller-visible wrapper so the Document-based delete path receives all consensus-populated system fields.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.00%. Comparing base (ae910e6) to head (77c526f).
⚠️ Report is 1 commits behind head on v4.2-dev.

Additional details and impacted files

@@            Coverage Diff            @@
##           v4.2-dev    #4495   +/-   ##
=========================================
  Coverage     83.00%   83.00%           
=========================================
  Files          2744     2744           
  Lines        367956   367956           
=========================================
  Hits         305411   305411           
  Misses        62545    62545           

Components	Coverage Δ
dpp	83.76% <ø> (ø)
drive	81.09% <ø> (ø)
drive-abci	85.89% <ø> (ø)
sdk	∅ <ø> (∅)
dapi-client	∅ <ø> (∅)
platform-version	∅ <ø> (∅)
platform-value	92.92% <ø> (ø)
platform-wallet	∅ <ø> (∅)
drive-proof-verifier	48.41% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[QuantumExplorer]

Reviewed