fix(dpp): compile wasm-dpp2 after propertyAgreement and expose it on reference metadata

[QuantumExplorer]

Issue being fixed or feature implemented

v4.2-dev does not compile right now. #4450 (refersTo reference metadata) and #4505 (propertyAgreement on permanentDocument references) were developed in parallel and merged without a rebase between them: #4450's exhaustive destructure of DocumentPropertyReferenceTarget::PermanentDocument doesn't mention the property_agreement field #4505 added, so wasm-dpp2 fails E0027 — and wasm-sdk / js-evo-sdk with it. No CI ran on the combination before the merge.

What was done?

Rather than papering over the field with .., surface it — the metadata accessor exists to report what a contract declares, and propertyAgreement is now part of that:

• reference_to_js destructures property_agreement and, when non-empty, emits it as a plain { referring: referenced } object on the permanentDocument reference. Absent — not {}-valued — when the declaration carries none, matching the schema's own omission and the absent-field convention of the other optional target fields.
• The hand-written TS custom section documents the new optional field (emits into dist/dpp.d.ts; the compressed d.ts never carries these types, unchanged).
• Specs: the fixture's self-referencing parentNoteId now declares an agreement; two new specs pin presence (deep-equal) and absence (not.have.property). 1157 wasm-dpp2 specs pass.
• js-evo-sdk README's refersTo section shows the new field.

How Has This Been Tested?

• cargo check -p wasm-dpp2 -p wasm-sdk --all-targets (fails E0027 on v4.2-dev, passes here)
• cargo clippy -p wasm-dpp2 -p wasm-sdk --all-features --all-targets -- -D warnings clean
• wasm32 test lane (cargo test -p wasm-sdk --target wasm32-unknown-unknown) — 6 passed; this lane is not run by CI, and it is where feat: expose protocol v14 ranked queries and document references to JavaScript #4450-style breaks hide
• yarn workspace @dashevo/wasm-dpp2 build + test — 1157 passing; lint 0 errors (1 pre-existing warning in an unrelated spec)

Breaking Changes

None — additive JS metadata field; no consensus surface touched.

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

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Document references can now define property agreements, linking specific properties between referenced documents.
  • Property agreement metadata is preserved when declared and omitted when unavailable.

• Documentation

  • Added README guidance and an example for configuring property agreements on permanent document references.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8b02add3-9405-4302-baed-7ded51986776

📥 Commits

Reviewing files that changed from the base of the PR and between 5ef3bf6 and 1e70b04.

📒 Files selected for processing (3)

• packages/js-evo-sdk/README.md
• packages/wasm-dpp2/src/data_contract/document_type_reference.rs
• packages/wasm-dpp2/tests/unit/DocumentPropertyReference.spec.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The change adds optional propertyAgreement mappings to permanent-document references. Serialization emits the field only for non-empty mappings. Tests and README examples cover declared and omitted agreements.

Property agreement references

Layer / File(s)	Summary
Reference contract and serialization packages/wasm-dpp2/src/data_contract/document_type_reference.rs	The permanent-document target supports optional property agreement mappings. Serialization emits propertyAgreement only when the mapping is non-empty.
Reference fixtures, tests, and documentation packages/wasm-dpp2/tests/unit/DocumentPropertyReference.spec.ts, packages/js-evo-sdk/README.md	The test reference and Reference type include the optional mapping. Tests verify declared mappings and omission when absent. The README documents the field.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 1e70b

This PR adds an optional propertyAgreement field to permanent-document reference metadata while preserving omission when no agreement exists. The change is localized and tested, with no actionable merge-blocking risk remaining beyond normal checks and review.

Suggested reviewers: shumkov

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the compilation fix and the exposure of propertyAgreement on reference metadata, which are the main changes in the pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/document-reference-property-agreement

---

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 1e70b04)
Stage: Codex precheck starting
ETA: complete ~17:56 UTC (median 20m across 30 recent reviews)
Running 5m · Last checked: 2026-08-28 17:40 UTC

[QuantumExplorer]

Superseded by #4515, which cherry-picks this fix and bundles the two other v4.2-dev build breaks (fmt gate from #4510, E0063 in dpp's reference-mirror test) so a single merge makes the base green.