docs: expand §4.4 mutation semantics with contract-level detail

[aguilar1x]

Summary

Rewrites §4.4 Mutation Semantics of did-stellar-v0.1.md from terse bullet points into per-operation subsections faithful to the did-stellar-registry contract, and trims the now-redundant client-flow lines in §4.6.

What changed

• §4.4.1–§4.4.4 — one subsection per lifecycle op (register, update, transfer_controller, deactivate). Each documents authorization, preconditions, what changes vs. what is preserved, the emitted event, error codes, plus an illustrative contract excerpt (from src/contract.rs) and before/after DidRecord examples.
• §4.4.5 — new per-operation error matrix.
• §4.6 — focused on the client-side read → prepare → sign → submit → retry flow; removed duplication now covered by §4.4 and added cross-references.

Contract behaviors now documented (previously omitted)

1. update pins the current controller and ignores next_record.controller — ownership changes go only through transfer_controller.
2. register overwrites caller-supplied bookkeeping fields (version, created_ledger, updated_ledger, deactivated).
3. VersionOverflow (code 19) guards version at u32::MAX instead of wrapping.

[almanax-ai]

Plan expired

Your subscription has expired. Please renew your subscription to continue using CI/CD integration and other features.

[coderabbitai]

📝 Walkthrough

Walkthrough

The DID Stellar v0.1 spec's §4.4 Mutation Semantics section is rewritten with a normative shared mutation pipeline, cross-operation invariants for bookkeeping fields and version monotonicity, and detailed per-operation rules. §4.6 gains a client-side lifecycle introduction and a rewritten deactivation flow with explicit steps.

Changes

DID Stellar Spec: Mutation Semantics & Operation Flows

Layer / File(s)	Summary
§4.4 Normative Mutation Semantics docs/did-spec/did-stellar-v0.1.md	Replaces brief per-operation bullets with a full normative contract pipeline (load/guard/authorize/validate/write/emit), defines forced bookkeeping fields (version, created_ledger, updated_ledger, deactivated), specifies u32::MAX overflow rejection and version monotonicity, and documents per-operation preconditions, field preservation/replacement rules, controller pinning for update, and deactivate tombstone/irreversibility semantics.
§4.6 Client lifecycle intro & Deactivation Flow rewrite docs/did-spec/did-stellar-v0.1.md	Adds a prepare → sign → submit lifecycle paragraph to §4.6 referencing §4.4 for contract-side semantics. Rewrites §4.6.4 Deactivation Flow as a stepwise sequence: client reads version, controller signs deactivate(did_id, expected_version), and post-confirmation states the DID is permanently tombstoned and requires a new register with a fresh did_id.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ACTA-Team/contracts-acta#11: Implements register, update, transfer_controller, and deactivate in the contract, including the version/deactivation invariants and error codes that this spec now normatively documents.

Poem

🐇 Hop, hop, the spec grows bright,
With pipelines and tombstones written right.
deactivate seals the DID's fate,
No more u32::MAX overflow debate!
The wallet signs, the ledger hears—
A cleaner spec to calm our fears. 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main docs change: expanding §4.4 mutation semantics with contract-level detail.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 docs/did-spec-mutation-semantics

---

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