Semantic contracts
A semantic contract describes what a caller can rely on for one product type: its identity, supported operations, stored state, observable results, and failure behavior. It links each invariant to its implementation and concrete tests. An API existing, a test compiling, and a test passing are different facts.
This first contract set covers the Rust account runtime and Android, with a complete reading path for text messages, edits, deletions, and effective message queries. It does not declare the entire SDK complete. Other language facades and other product families retain their existing documentation and maturity status.
Read the contracts
| Contract | Responsibility |
|---|---|
| Authenticated event | The shared authentication and ciphertext boundary. |
| Durable delivery | Committed operations, relay acceptance, and retry recovery. |
| Account storage | Atomic account state, logical identity, and account binding. |
| Observable state | Committed query snapshots, observation, and closure. |
| Text message | Message creation, receipt, edits, deletions, queries, and history. |
The shared contracts own cross-cutting invariants. A text-message test does not need another cryptographic vector corpus: it depends on the authenticated-event contract, while testing the message-specific effects of a valid event.
Contract and evidence are separate
Each numbered rule has a stable invariant ID. The prose on its owning page is
the normative behavior. Metadata in compatibility/contracts records the page
anchor, responsible layer, operation IDs, implementation symbols, concrete test
cases, dependencies, and required environments. It does not maintain a second
copy of the behavioral rule.
| Evidence state | Meaning |
|---|---|
verified | Matching execution evidence satisfies the invariant and its dependencies for the required environments. |
failed | An applicable execution reported failure. |
missing | Required execution evidence is absent. |
stale | Evidence belongs to different source or artifact inputs. |
skipped | A required test did not execute. |
incomplete | Available records cannot establish the complete required result. |
A linked test indicates the scenario that checks a rule. Its name alone is not
proof, and a passing scenario is not an exhaustive exploration of all possible
histories. The limitations section of each contract identifies what remains
unverified. The generated evidence report records revisions, environments and
execution references; a documentation build without that report displays
missing, never an inferred pass.
rust-host exercises Rust semantics. android-jvm exercises the authored
Kotlin facade against the host Rust library. android-device exercises Android
instrumentation against its recorded APK and pinned AAR. An emulator can supply
runtime correctness evidence for its recorded environment; physical-device and
release-artifact requirements must be identified separately in the report.
Documentation ownership
These pages own product behavior and database guarantees. Existing architecture pages own wire formats, cryptographic policy, SQL implementation choices and package boundaries. Operation guides own recipes; generated references own exact signatures. An Android application must use the returned SDK state and keep its OS-specific responsibilities in its own integration documentation.
Families awaiting this review
The following families are pending contract review, not newly absent SDK features: conversation membership/subjects, replies and forwards as independent use cases, reactions, typing, contacts/profile, account settings and read-state sync, media transfers and public asset replacement, account lifecycle/migration, relay discovery/synchronization, notifications and push integration.
See the capability ledger for their existing implementation and release declarations. A future family receives a contract only after its code paths, persistence effects, public observations and tests have been inspected. Merely adding its name to this index does not complete that work.