docs(escrow): add storage schema and compatibility guidance

[oderahub]

Summary

Add schema-first storage documentation for the escrow contract, anchored to the current source while explicitly surfacing schema drift and inconsistencies.

Closes #21

Scope

This PR is documentation-only and does not modify contract behavior.

Rustdoc additions in escrow/src/lib.rs are source-accurate but not currently renderable via generated docs until the duplicate admin field and related compile blockers are fixed in a separate PR.

Changes

• Replaced drifted README migration/storage content with a canonical Storage Schema section
• Documented raw storage inventory (instance keys and struct layout)
• Added a narrative schema view for readability without hiding inconsistencies
• Introduced a divergence table highlighting mismatches between source and intended model
• Clarified field semantics, lifecycle status values, and invariants
• Added upgrade and compatibility guidance (versioning, migrations, breaking vs additive changes)
• Updated rustdoc in escrow/src/lib.rs to align with actual storage behavior
• Applied minimal consistency fixes to docs/EVENT_SCHEMA.md where it would contradict storage docs

Storage Model (High-Level)

• Instance storage keys:
  • "escrow" → InvoiceEscrow (full contract state)
  • "version" → u32 (schema version)
• One escrow per contract instance
• No keyed/per-user storage currently implemented

Known Divergences (Explicitly Documented)

• Duplicate admin field in InvoiceEscrow
• funding_deadline parameter in init is not persisted
• settled_amount exists but has incomplete/partial logic
• yield_bps type mismatch (i64 in struct vs u32 in inputs)
• DataKey::Escrow referenced but not defined

These are documented as source-level inconsistencies, not normalized in the schema.

Upgrade & Compatibility Notes

• Schema changes require SCHEMA_VERSION bumps and explicit migration
• Old struct layouts must remain decodable
• Additive changes are safe; field removal/reordering is breaking
• Migration must explicitly map all fields

Testing / Validation

Ran locally:

• cargo test

Result:

• Build fails before test execution due to a pre-existing source issue:
  duplicate admin field declaration and malformed duplicated method blocks
  in escrow/src/lib.rs. The compiler errors at the unclosed delimiter around
  lines 369–410, before any test logic is reached.
• cargo fmt --all -- --check also fails for the same reason.
• Neither failure was introduced by this PR. The crate was already in a
  non-compiling state on this branch prior to these documentation edits.
• escrow/src/test.rs additionally contains obvious branch drift (duplicate
  deploy helper, tests referencing confirm_payment, pause/unpause)
  that is unrelated to the storage schema documentation task.

Follow-up Work (Out of Scope for This PR)

• Source-fix PR needed: resolve duplicate admin field, undefined
  DataKey::Escrow, yield_bps type mismatch (i64 vs u32), and
  unclosed delimiter in lib.rs
• Test repair: remove or reconcile test.rs branch drift once the
  source is stabilized
• EVENT_SCHEMA.md full reconciliation: deferred; only contradiction-
  limiting edits were made here

[drips-wave]

@oderahub Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits