Social Architecture

This document defines Aura's social organization model using two social planes plus the message contexts that run on top of them. The system layers privacy, consent, and governance into a Neighborhood Plane, a Web of Trust Plane, and the message contexts that consume their outputs.

1. Overview

1.1 Design Goals

The model produces human-scaled social structures with natural scarcity based on physical analogs. Organic community dynamics emerge from bottom-up governance. The design aligns with Aura's consent-based privacy guarantees and capability-based authorization.

1.2 Social Planes

The Neighborhood Plane models homes, neighborhoods, membership, moderation, and locality-scoped infrastructure. It answers who shares a local social space and which neighborhood-scoped providers are admissible.

The Web of Trust Plane models bilateral friend relationships and bounded introductions. It answers which providers have direct or introduced trust evidence. It does not own final route selection. It does not materialize the transitive trust graph as shared state.

Messages are communication contexts built on top of those planes. Direct messages are private relational contexts. Home messages are semi-public messaging for home members and participants.

1.3 Terminology

An authority (AuthorityId) is the cryptographic identity that holds capabilities and participates in consensus. A nickname is a local mapping from an authority to a human-understandable name. Each device maintains its own nickname mappings. There is no global username registry.

A nickname suggestion (nickname_suggestion) is metadata an authority optionally shares when connecting with someone. Users configure a default suggestion sent to all new connections. Users can share different suggestions with different people or opt out entirely.

Contact is unilateral reachability or identification state. It means the local user knows how to recognize or reach an authority. It does not imply bilateral trust. Removing a contact is therefore local: it deletes this authority's own record and does not notify the peer, whose contact record for this authority is unaffected. Ending bilateral trust is a Friend revocation, which both sides observe.

Friend is bilateral accepted trust in the Web of Trust Plane. Friend lifecycle facts live in relational contexts. Friends of friends are local derivations or bounded introduction evidence, not canonical shared graph state.

1.4 Unified Naming Pattern

The codebase uses a consistent naming pattern across entities (contacts, devices, discovered peers). The EffectiveName trait in aura-app/src/views/naming.rs defines the resolution order:

1. Local nickname (user-assigned override) if non-empty
2. Shared nickname_suggestion (what entity wants to be called) if non-empty
3. Fallback identifier (truncated authority/device ID)

This pattern ensures consistent display names across all UI surfaces while respecting both local preferences and shared suggestions.

2. Message Types

2.1 Direct Messages

Direct messages are small private relational contexts built on AMP. There is no hop-based expansion across homes. All participants must be explicitly added. New members do not receive historical message sync.

2.2 Home Messages

Home messages are semi-public messaging for home members and participants. They use the same AMP infrastructure as direct messages. When a new participant joins, current members send a window of recent messages.

Membership and participation are tied to home policy. Leaving the home revokes access. Multiple channels may exist per home for different purposes.

#![allow(unused)]
fn main() {
pub struct HomeMessage {
    home_id: HomeId,
    channel: String,
    content: Vec<u8>,
    author: AuthorityId,
    timestamp: TimeStamp,
}
}

The message structure identifies the home, channel, content, author, and timestamp. Historical sync is configurable, typically the last 500 messages.

3. Home Architecture

3.1 Home Structure

A home is an authority-scoped context with its own journal. The total storage allocation is 10 MB. Capability templates define limited, partial, full, participant, and moderator patterns. Local governance is encoded via policy facts.

#![allow(unused)]
fn main() {
pub struct Home {
    /// Unique identifier for this home
    pub home_id: HomeId,
    /// Total storage limit in bytes
    pub storage_limit: u64,
    /// Maximum number of participants
    pub max_participants: u8,
    /// Maximum number of neighborhoods this home can join
    pub neighborhood_limit: u8,
    /// Current participants (authority IDs)
    pub participants: Vec<AuthorityId>,
    /// Current moderators with their capabilities
    pub moderators: Vec<(AuthorityId, ModeratorCapabilities)>,
    /// Current storage budget tracking
    pub storage_budget: HomeStorageBudget,
}
}

The home structure contains the identifier, storage limit, configuration limits, participant list, moderator designation list with capabilities, and storage budget tracking.

3.2 Membership and Participation

Home participation derives from possessing capability bundles, meeting entry requirements defined by policy, and allocating participant-specific storage. In v1, each user belongs to exactly one home. Home creation is user-initiated: accounts do not receive a home automatically at account creation. Instead, a user creates their home from the Neighborhood screen when they are ready to start connecting with others and participating in social features.

Joining a home follows a defined sequence. The authority requests capability. Home governance approves using local policy via Biscuit evaluation and consensus. The authority accepts the capability bundle and allocates storage. Historical home messages sync from current members.

3.3 Moderator Designation

Moderators are designated via governance decisions in the home. A moderator must also be a member. A home invitation grants participant access; a moderator holding grant_moderator admits a participant to the member set with HomeAdmitMemberFact (the /admit <user> command), after which the member can be designated moderator. Moderator capability bundles include moderation, pin and unpin operations, and governance facilitation. Moderator designation is auditable because capability issuance is visible via relational facts.

3.4 Order-Independent Governance Reduction

Home governance facts are bans, unbans, mutes, unmutes, kicks, moderator grants and revocations, access overrides, channel mode, the capability configuration, and member joins and leaves. They follow the canonical domain fact model of docs/105 §4.2.1 (schema 3; kicks schema 4; social facts schema 6). The writer obtains the fact's CausalMetadata from the runtime (RuntimeBridge::causal_stamp with CausalStampKey::HomeGovernance), which advances its logical clock past every governance fact it holds for the home.

• Bans and mutes are tagged observed-remove sets keyed by target and channel scope. An unban or unmute revokes the bans or mutes of that key its writer observed. A concurrent ban the writer did not observe stays in force.
• Member admissions are a tagged observed-remove set keyed by target: an admission by a moderator holding grant_moderator makes a joined participant a member until a kick or leave of that target that observed it. An admission that arrives before the join takes effect when the member joins.
• Moderator designations are a tagged observed-remove set keyed by target. The creator is a permanent moderator. Roles are derived from the whole set, so a grant that arrives before the member joins takes effect when the member joins.
• Access overrides are a multi-value register per target. Concurrent surviving overrides resolve to the most restrictive level, then the later in causal order. The capability configuration is a multi-value register per home; concurrent survivors combine by per-level intersection.
• Channel mode is a multi-value register per home. A write supersedes only observed mode tags; concurrent surviving writes resolve to the lexicographically greatest flags. Only actors holding manage_channel contribute authorized writes. The committed register supplies the mode after synchronization and restart; frontends keep no independent mode cache.
• Membership is a tagged observed-remove set of episodes. Each MemberJoined starts the episode named by its member, context and episode (the accepted invitation id, or a fixed label for the creator); the inviter and the invitee commit the same join under that id, so their copies are one episode. A kick, and a MemberLeft (schema 4), revoke the episodes of that member the writer observed. A member stays in the roster while any episode is live, so a later rejoin, or one concurrent with the kick, survives in every delivery order, including a reinstalled member that rejoins and then pulls the old kick through relational-context sync (Transport §11.4). A kick the writer issued without observing any join of the target removes nothing.
• Kicks are also history entries shown in causal order.
• Authorization is evaluated against the moderator set and access state reduced from the whole fact set, not the state at arrival. A ban by a newly designated moderator holds in every delivery order. Override and capability-configuration writes name their actor, which must be a moderator holding grant_moderator; because access state and moderator designations depend on each other, reduction is stratified: moderators under default access, then the authorized access registers, then moderators under that access state.
• Without the HomeCreated fact the creator is unknown, so only targets of authorized designations have derived roles; other materialized roles are kept until creation is reduced. Relational-context sync serves HomeCreated with the governance facts.
• The home view lists home-wide bans and mutes only. Channel-scoped bans and mutes are enforced per channel by the runtime moderation query.
• Banned members leave the visible roster and return when the ban is lifted.

The pure reducer is aura_app::views::home::reduce_home_governance. The home signal view keeps each home's governance fact set and reduces it after every batch.

3.5 Order-Independent Lifecycle Reduction

The remaining SocialFact pairs (schema 6) reduce in aura_social::lifecycle over the whole fact set; physical timestamps never order them.

• Home existence is a tagged observed-remove set. Each HomeCreated is an add tagged by its content. A HomeDeleted by the home's creator revokes the creations it observed; a deletion by anyone else, or one that observed no creation, removes nothing. Deletion is terminal: a HomeId is minted once, so a recreated home is a new HomeId. A deleted home is never materialized, even when its creation arrives after the deletion.
• Neighborhood membership is a tagged observed-remove set of episodes per home and neighborhood. A HomeLeftNeighborhood revokes the joins its writer observed; a later join is a new episode and survives. The home view sets each home's fact-backed neighborhoods to the live set, rejoining in neighborhood-id order within the neighborhood budget.
• Storage readings (StorageUpdated) are a multi-value register per home. A write supersedes the writes its writer observed; concurrent survivors resolve to the largest usage, then the largest capacity, then the later write in causal order.
• Neighborhood names come from NeighborhoodCreated; duplicate creations of one id resolve to the smallest name.

SocialFact is registered in the agent FactRegistry with SocialFactReducer, which decodes through SocialFact::try_from_envelope. Moderator designations are HomeGrantModeratorFact and HomeRevokeModeratorFact only; member admissions are HomeAdmitMemberFact.

4. Neighborhood Architecture

4.1 Neighborhood Structure

A neighborhood is an authority type linking multiple homes. It contains a combined pinned infrastructure pool equal to the number of homes times 1 MB. A 1-hop link graph connects homes. Access-level and inter-home policy logic define movement rules.

#![allow(unused)]
fn main() {
pub struct Neighborhood {
    /// Unique identifier for this neighborhood
    pub neighborhood_id: NeighborhoodId,
    /// Member homes
    pub member_homes: Vec<HomeId>,
    /// 1-hop links between homes
    pub one_hop_links: Vec<(HomeId, HomeId)>,
}
}

The neighborhood structure contains the identifier, member homes, and 1-hop link edges.

4.2 Home Membership

Homes allocate 1 MB of their budget per neighborhood joined. In v1, each home may join a maximum of 4 neighborhoods. This limits 1-hop graph complexity and effect delegation routing.

5. Position and Traversal

5.1 Neighborhood Discovery Layers

Neighborhood-scoped discovery is represented through the DiscoveryLayer enum. It indicates the best neighborhood strategy to reach a target based on locality relationships:

#![allow(unused)]
fn main() {
pub enum DiscoveryLayer {
    /// No relationship with target - must use rendezvous/flooding discovery
    Rendezvous,
    /// We have neighborhood presence and can use traversal
    Neighborhood,
    /// Target is reachable via home-level relay
    Home,
    /// Target is personally known - we have a direct relationship
    Direct,
}
}

The discovery layer determines locality-aware discovery strategy and flow costs. aura-social may classify neighborhood candidates using these layers, but it does not own the final route choice. Runtime policy in aura-agent fuses neighborhood candidates with web-of-trust evidence and descriptor views.

Neighborhood discovery boards are bounded hint surfaces inside this plane. A board publication may advertise a signed, expiring, replay-bounded re-entry hint for stale-node bootstrap, but it is not a topology map. The publication does not enumerate the neighborhood graph and does not commit a runtime route. It only exposes enough scoped hint material for local runtime discovery to try a candidate.

5.2 Movement Rules

Movement is possible when a Biscuit capability authorizes entry, neighborhood policy allows movement along a 1-hop link, and home policy or invitations allow deeper access levels. Movement does not replicate pinned data. Visitors operate on ephemeral local state.

Traversal does not reveal global identity. Only contextual identities within encountered homes are visible.

6. Storage Constraints

6.1 Block-Level Allocation

Homes have a fixed size of 10 MB total. Allocation depends on neighborhood participation.

More neighborhood connections mean less local storage for home culture. This creates meaningful trade-offs.

6.2 Flow Budget Integration

Storage constraints are enforced via the flow budget system.

#![allow(unused)]
fn main() {
pub struct HomeFlowBudget {
    /// Home ID (typed identifier)
    pub home_id: HomeId,
    /// Current number of participants
    pub participant_count: u8,
    /// Storage used by participants (spent counter as fact)
    pub participant_storage_spent: u64,
    /// Number of neighborhoods joined
    pub neighborhood_count: u8,
    /// Total neighborhood allocations
    pub neighborhood_allocations: u64,
    /// Storage used by pinned content (spent counter as fact)
    pub pinned_storage_spent: u64,
}
}

The spent counters are persisted as journal facts. The count fields track current membership. Limits are derived at runtime from home policy and Biscuit capabilities. Participant storage limit is 1.6 MB for 8 participants at 200 KB each.

7. Fact Schema

7.1 Home Facts

Home facts enable Datalog queries.

home(home_id, created_at, storage_limit).
home_config(home_id, max_participants, neighborhood_limit).
participant(authority_id, home_id, joined_at, storage_allocated).
moderator(authority_id, home_id, designated_by, designated_at, capabilities).
pinned(content_hash, home_id, pinned_by, pinned_at, size_bytes).

These facts express home existence, configuration, participation, moderator designation, and pin state.

7.2 Neighborhood Facts

Neighborhood facts express neighborhood existence, home membership, 1-hop links, and access permissions.

neighborhood(neighborhood_id, created_at).
home_member(home_id, neighborhood_id, joined_at, allocated_storage).
one_hop_link(home_a, home_b, neighborhood_id).
access_allowed(from_home, to_home, capability_requirement).

7.3 Query Examples

Queries use Biscuit Datalog.

participants_of(Home) <- participant(Auth, Home, _, _).

visitable(Target) <-
    participant(Me, Current, _, _),
    one_hop_link(Current, Target, _),
    access_allowed(Current, Target, Cap),
    has_capability(Me, Cap).

The first query finds all participants of a home. The second finds homes a user can visit from their current position via 1-hop links.

Neighborhood discovery-board records are intentionally separate from these canonical topology facts. They are advisory publications consumed by runtime-local bootstrap selection. They must not change Neighborhood, SocialTopology, or other canonical neighborhood views into route-truth owners.

8. IRC-Style Commands

8.1 User Commands

User commands are available to all participants.

8.2 Moderator Commands

Moderator commands require moderator capabilities, and moderators must be members.

8.3 Command Execution

Commands execute through the guard chain.

flowchart LR
    A[Parse Command] --> B[CapGuard];
    B --> C[FlowGuard];
    C --> D[JournalCoupler];
    D --> E[TransportEffects];

The command is parsed into a structured type. CapGuard checks capability requirements. FlowGuard charges the moderation action budget. JournalCoupler commits the action fact. TransportEffects notifies affected parties.

9. Governance

9.1 Home Governance

Homes govern themselves through capability issuance, consensus-based decisions, member moderation designations, and moderation. Home governance uses Aura Consensus for irreversible or collective decisions.

9.2 Neighborhood Governance

Neighborhoods govern home admission, 1-hop graph maintenance, access rules, and shared civic norms. High-stakes actions use Aura Consensus.

10. Privacy Model

10.1 Contextual Identity

Identity in Aura is contextual and relational. Joining a home reveals a home-scoped identity. Leaving a home causes that contextual identity to disappear. Profile data shared inside a context stays local to that context.

10.2 Consent Model

Disclosure is consensual. The device issues a join request. Home governance approves using local policy. The authority accepts the capability bundle. This sequence ensures all participation is explicit.

11. V1 Constraints

For the initial release, the model is simplified with three constraints.

Each user is a member of exactly one home. This eliminates multi-membership complexity and allows core infrastructure to stabilize.

Each home has a maximum of 8 participants. This human-scale limit enables strong community bonds and manageable governance.

Each home may join a maximum of 4 neighborhoods. This limits 1-hop graph complexity and effect delegation routing overhead.

12. Infrastructure Roles

Homes and neighborhoods provide infrastructure services beyond social organization. The aura-social crate implements neighborhood facts, materialized views, and neighborhood-derived candidate production. Final route or retrieval choice belongs to the runtime.

12.1 Neighborhood Plane Responsibilities

The Neighborhood Plane provides broad locality-scoped candidate pools:

• neighborhood-derived Establish and Move candidates
• neighborhood-only Hold candidates for availability and deferred delivery
• locality-scoped storage and relay budgeting
• governance and moderation state for homes and neighborhoods

These outputs are permit and candidate inputs. They are not route commitments. For Hold, the neighborhood scope is the whole admissible interface while the runtime chooses a bounded rotating subset of holders inside that scope and keeps retention treatment uniform across deposits.

12.2 Web of Trust Plane Responsibilities

The Web of Trust Plane provides trust evidence:

• bilateral friendship state as relational-context facts
• bounded introduction evidence for introduced candidates
• permit input for Establish and Move
• bootstrap and accountability weight for trusted providers

Direct friendship is authoritative shared state. Friend-of-friend is local derivation or bounded introduction evidence. It is not canonical shared graph state.

Trust evidence may affect provider admission, weighting, and accountability preference. It must not create friend-shaped, FoF-shaped, guardian-shaped, or neighborhood-shaped route schemas. The provider should observe only the generic Establish, Move, or Hold service action.

12.3 Plane Fusion

The runtime fuses neighborhood candidates, web-of-trust evidence, descriptor views, and health data into provider selection:

This split prevents social-role labels from becoming wire-visible service classes.

Neighborhood-only and WoT-assisted candidate production must therefore emit the same Establish and Move descriptor, path, and envelope shapes. The only allowed differences are trust-evidence provenance and runtime-local weighting or selection state. Shared schemas must not grow neighborhood-, friend-, or FoF-specific variants.

12.4 Relay Selection

The SocialTopology provides neighborhood-derived relay candidate generation:

#![allow(unused)]
fn main() {
let topology = SocialTopology::new(local_authority, home, neighborhoods);
let candidates = topology.build_relay_candidates(&destination, |peer| is_reachable(peer));
}

Reachability checks filter unreachable peers. Candidate provenance may record same-home, neighborhood-hop, or guardian evidence. The runtime may use that provenance during local permit evaluation, but aura-social does not own the final route decision.

See Also

Database Architecture describes fact storage and queries. Transport and Information Flow covers AMP messaging. Authorization describes capability evaluation. Rendezvous Architecture describes rendezvous advertisement and selection boundaries.