How Macro Implements Bidirectional @linking Between Entities

Macro implements bidirectional @linking through a lightweight directed-graph table named macro_user_links that stores unidirectional edges from primary to child users, paired with symmetric lookup helpers enabling reverse traversal.

The macro-inc/macro repository handles cross-entity references such as mentions and inbox delegation through a sophisticated linking system. This article examines how the codebase achieves bidirectional @linking between entities using a single table design with dual-direction query capabilities.

The macro_user_links Table: Directed Graph Storage

The foundation of Macro's linking system rests in the macro_user_links table managed within crates/macro_db_client/src/macro_user_links.rs. Each row stores a directed edge containing three critical components: a primary Macro user ID, a child Macro user ID, and the link_id referencing a specific row in the email_links table.

Although the physical storage represents a single direction (primary → child → link), the schema enables precise scoping where each edge grants access to exactly one inbox. This design allows the system to revoke specific inbox access without affecting other delegations between the same users.

Core Operations and Edge Management

The database client provides atomic operations for manipulating delegation edges. These functions ensure idempotent inserts and safe deletion of links.

Inserting and Removing Edges

The insert_edge function creates delegation relationships while ignoring duplicate entries, making it safe for repeated calls. Located at macro_user_links.rs:12-38, this operation establishes the primary-to-child connection for a specific inbox.

// Grant primary `alice` access to child `bob`'s inbox identified by `link_id`
macro_user_links::insert_edge(&db, "alice", "bob", link_id).await?;

To remove access, the delete_edge function at macro_user_links.rs:40-64 removes the specific triple from the table. The edge_exists helper at macro_user_links.rs:66-94 validates whether a delegation is active before performing authorization-sensitive operations.

Authorization Checks

Before processing delegated requests, the system verifies edges using the existence check:

let has_edge = macro_user_links::edge_exists(&db, "alice", "bob", link_id).await?;

Bidirectional Lookup Helpers

To achieve bidirectional @linking without storing duplicate reverse edges, Macro implements symmetric query functions that traverse the graph in both directions.

Forward Traversal: Finding Child Inboxes

The children_for_primary function at macro_user_links.rs:96-115 enables forward traversal by returning all child Macro IDs accessible to a given primary user. The email service uses this to union linked inboxes with a user's own inbox when fetching messages.

// List all child inboxes alice can read
let children = macro_user_links::children_for_primary(&db, "alice").await?;

Reverse Traversal: Finding Primary Users

For reverse lookups, two specialized functions enable children to discover who can access their content. The get_primaries_for_child function at macro_user_links.rs:117-137 returns every primary user with delegation rights to a specific child.

When scoped to a particular inbox, get_primaries_for_link at macro_user_links.rs:139-161 identifies exactly which primaries can read that specific link_id. This powers the notification system's fan-out mechanism:

// Find every primary that can read bob's inbox `link_id`
let primaries = macro_user_links::get_primaries_for_link(&db, "bob", link_id).await?;

Integration Across the Stack

The linking system integrates throughout Macro's architecture, from database to user interface.

Email Service Integration

In crates/email/src/outbound/email_pg_repo/link.rs, the system creates and deletes email_links rows that serve as the targets for macro_user_links references. The email service combines these with children_for_primary queries to aggregate accessible inboxes for primary users.

Notification Fan-Out

The notification system leverages get_primaries_for_link to distribute child-inbox events to every authorized primary user. This ensures real-time updates propagate correctly across delegation boundaries without requiring duplicate storage of reverse relationships.

Frontend Exposure

The web client consumes these relationships through the GET /email/links endpoint, which returns an is_primary flag based on macro_user_links queries. The UI hook useEmailLinksQuery in apps/web/src/lib/queries/email/link.ts surfaces these permissions to determine interface rendering.

Authorization API

The authentication service exposes link existence checks via services/authentication_service/src/api/user/get_user_link_exists.rs, allowing API endpoints to verify delegation rights before processing cross-user requests.

Summary

• Macro implements bidirectional @linking through the macro_user_links table, storing directed edges from primary to child users scoped to specific inbox IDs.
• The insert_edge, delete_edge, and edge_exists functions in macro_user_links.rs provide atomic, idempotent operations for managing delegation.
• Forward traversal uses children_for_primary to find all child inboxes a primary can access.
• Reverse traversal uses get_primaries_for_child and get_primaries_for_link to discover which primaries can view specific children or inboxes.
• The system integrates across the stack, powering email aggregation, notification fan-out, and UI permission flags while maintaining storage efficiency through single-direction edges with symmetric queries.

Frequently Asked Questions

What database table stores Macro's @link relationships?

The macro_user_links table stores all delegation relationships as directed edges containing a primary user ID, child user ID, and link_id referencing the specific inbox being shared. This table is defined and managed in crates/macro_db_client/src/macro_user_links.rs.

How does Macro achieve bidirectional lookups without storing duplicate data?

Macro uses symmetric query helpers rather than duplicate storage. While edges store only the primary → child direction, the get_primaries_for_child and get_primaries_for_link functions perform reverse lookups by querying the same table with inverted WHERE clauses, enabling efficient bidirectional traversal without data duplication.

Can multiple primaries access the same child's inbox?

Yes. The schema supports many-to-many relationships where multiple primary users can have edges pointing to the same child and link_id combination. The get_primaries_for_link function specifically handles this case by returning all primaries authorized for a specific child's inbox.

How does the system prevent duplicate link creation?

The insert_edge function is idempotent by design. When attempting to create an edge that already exists, the operation ignores the duplicate insert rather than failing, ensuring safe repeated calls without requiring prior existence checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}