amr/memex
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

chore: unify bold syntax to single asterisk in .org files and update legacy memex-amero references

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-01 12:37:45 -04:00
parent 78ba3112cb
commit d364f90ff6
102 changed files with 955 additions and 955 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
projects/agora/docs/agora-requirements-09-implementation.org
View File

@@ -28,18 +28,18 @@ Sovereign iOS/Android clients with hardware-backed security and offline-first de
*** The Abstraction Layer (UX/UI)
The client application MUST hide the complexity of DIDs and CIDs behind a familiar interface:
- **Biometric Unlock:** The app MUST use FaceID/Fingerprint to sign transactions. The user MUST NEVER see a raw private key during daily operations.
- **Status Indicators:** The UI MUST provide clear context, such as a "Seeding Now" icon when providing P2P bandwidth, and a "Protected by [NGO]" badge indicating which PDS is currently authoritative.
- *Biometric Unlock:* The app MUST use FaceID/Fingerprint to sign transactions. The user MUST NEVER see a raw private key during daily operations.
- *Status Indicators:* The UI MUST provide clear context, such as a "Seeding Now" icon when providing P2P bandwidth, and a "Protected by [NGO]" badge indicating which PDS is currently authoritative.
*** "View" Discovery & Rendering
Because the protocol relies on a Universal Note Schema, the UI MUST dynamically construct itself based on the payload.
- **MIME-Type Dispatcher:** The client MUST include a rendering engine that dispatches the correct UI component based on `object.type` and `mimeType` (e.g., loading a vertical player for `video/mp4` vs. a text renderer for `text/markdown`).
- **Custom Namespaces:** Applications MAY define custom metadata extensions (e.g., an `ext:ecommerce` namespace) to render specialized views like inventory trackers or shipping interfaces.
- *MIME-Type Dispatcher:* The client MUST include a rendering engine that dispatches the correct UI component based on `object.type` and `mimeType` (e.g., loading a vertical player for `video/mp4` vs. a text renderer for `text/markdown`).
- *Custom Namespaces:* Applications MAY define custom metadata extensions (e.g., an `ext:ecommerce` namespace) to render specialized views like inventory trackers or shipping interfaces.
*** The Action-Trigger API (Async Hooks)
The client MUST be capable of handling asynchronous events pushed from the Governance and Judicial layers.
- **Notification Schema:** The client MUST parse and render structured JSON events like `CONTRACT_DISPUTE_INITIATED` or `VOTE_REQUIRED`.
- **Auto-Execution:** The PDS MUST run background listeners capable of automatically executing finalized smart contract rulings (e.g., releasing HODL funds) even if the user's primary mobile client is offline.
- *Notification Schema:* The client MUST parse and render structured JSON events like `CONTRACT_DISPUTE_INITIATED` or `VOTE_REQUIRED`.
- *Auto-Execution:* The PDS MUST run background listeners capable of automatically executing finalized smart contract rulings (e.g., releasing HODL funds) even if the user's primary mobile client is offline.
*** Technical Stack
@@ -157,23 +157,23 @@ Due to the offline-first nature of Agora clients and multi-device usage, identic
- The Root Hash represents the current state of a Persona's PDS.
*** Conflict Detection
1. **Sync Handshake:** Client connects to PDS (or PDS to PDS). They exchange Root Hashes.
2. **Path Traversal:** If Root Hashes differ, they traverse down the tree exchanging hashes until they identify the divergent branches.
3. **Divergence Identification:** A conflict occurs when two different CIDs claim to be the direct chronological successor of the same parent CID (a "fork" in the object history), or when there are concurrent writes to a mutable pointer (like a Repo DID branch head).
1. *Sync Handshake:* Client connects to PDS (or PDS to PDS). They exchange Root Hashes.
2. *Path Traversal:* If Root Hashes differ, they traverse down the tree exchanging hashes until they identify the divergent branches.
3. *Divergence Identification:* A conflict occurs when two different CIDs claim to be the direct chronological successor of the same parent CID (a "fork" in the object history), or when there are concurrent writes to a mutable pointer (like a Repo DID branch head).
*** Deterministic Resolution Rules (LWW-Tiebreaker)
To automatically resolve conflicts without user intervention, Agora employs a deterministic algorithm based on logical clocks and cryptographic tie-breakers:
1. **Logical Clock (Lamport Timestamps):**
1. *Logical Clock (Lamport Timestamps):*
- Every Content Object includes a logical sequence number (`seq`) incremented with each update by the owner.
- The object with the highest `seq` wins.
2. **Wall-Clock Tiebreaker:**
2. *Wall-Clock Tiebreaker:*
- If `seq` numbers are identical (e.g., same state modified offline on two devices simultaneously), the `createdAt` timestamp is compared.
- The object with the most recent `createdAt` timestamp wins (Last-Write-Wins).
3. **Cryptographic Tiebreaker:**
3. *Cryptographic Tiebreaker:*
- If both `seq` and `createdAt` are perfectly identical, the system compares the CIDs (which are hashes).
- The CID with the numerically larger hash value wins. This guarantees a deterministic outcome across all nodes.
@@ -552,7 +552,7 @@ export class DeltaSyncEngine {
| Msgpack | None | 1.1x |
| JSON | None | 0.8x (larger) |
**Recommended:** CBOR + Zstd for bandwidth, CBOR for CPU-constrained devices.
*Recommended:* CBOR + Zstd for bandwidth, CBOR for CPU-constrained devices.
** Related Gaps