oneie
Version:
Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.
358 lines (294 loc) • 8 kB
Markdown
title: Connections
dimension: connections
category: connections.md
tags: ai, connections, knowledge, ontology, relationships, things
related_dimensions: events, knowledge, people, things
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
This document is part of the connections dimension in the connections.md category.
Location: one/connections/connections.md
Purpose: Documents connections: relationships between things
Related dimensions: events, knowledge, people, things
For AI agents: Read this to understand connections.
# Connections: Relationships Between Things
**If you're describing how thing X relates to thing Y, it's a connection.**
For complete connection type definitions, see **[Ontology.md](./ontology.md#connections-all-the-relationships)**
## The Connections Table
```typescript
{
_id: Id<"connections">,
fromThingId: Id<"things">,
toThingId: Id<"things">,
relationshipType: ConnectionType,
metadata?: {
// Optional relationship data
// Examples: balance, progress, revenueShare, role, permissions
},
strength?: number, // Relationship strength (0-1)
validFrom?: number, // When relationship started
validTo?: number, // When relationship ended
createdAt: number,
updatedAt?: number
}
```
## Connection Types
### Ownership (2)
- `owns` - A owns B
- `created_by` - A was created by B
### AI Relationships (3)
- `clone_of` - AI clone of person
- `trained_on` - AI trained on knowledge
- `powers` - AI powers feature
### Content Relationships (5)
- `authored` - Person authored content
- `generated_by` - Content generated by AI
- `published_to` - Content published to platform
- `part_of` - Content part of collection
- `references` - Content references other content
### Community Relationships (4)
- `member_of` - Person member of org/community
- `following` - Person follows person
- `moderates` - Person moderates community
- `participated_in` - Person participated in conversation
### Business Relationships (3)
- `manages` - Person manages person/team
- `reports_to` - Person reports to person
- `collaborates_with` - Person collaborates with person
### Token Relationships (3)
- `holds_tokens` - Person holds tokens (metadata: balance)
- `staked_in` - Tokens staked in pool
- `earned_from` - Tokens earned from activity
### Product Relationships (4)
- `purchased` - Person purchased product
- `enrolled_in` - Person enrolled in course (metadata: progress)
- `completed` - Person completed course
- `teaching` - AI teaching course
### Group Types (7)
Uses `metadata` for variants + protocol identity:
- `transacted` - Payment/subscription/invoice (metadata.transactionType + protocol)
- `notified` - Notifications (metadata.channel + notificationType)
- `referred` - Referrals (metadata.referralType)
- `communicated` - Agent/protocol communication (metadata.protocol + messageType)
- `delegated` - Task/workflow delegation (metadata.protocol + taskType)
- `approved` - Approvals (metadata.approvalType + protocol)
- `fulfilled` - Fulfillment (metadata.fulfillmentType + protocol)
## Common Patterns
### Pattern 1: Ownership
```typescript
// Creator owns AI clone
{
fromThingId: creatorId,
toThingId: cloneId,
relationshipType: "owns",
createdAt: Date.now()
}
// Organization owns content
{
fromThingId: organizationId,
toThingId: contentId,
relationshipType: "owns",
metadata: {
createdBy: userId, // User who created it
},
createdAt: Date.now()
}
```
### Pattern 2: Revenue Split
```typescript
// Collaborator owns 30% of course
{
fromThingId: collaboratorId,
toThingId: courseId,
relationshipType: "owns",
metadata: {
revenueShare: 0.3
},
createdAt: Date.now()
}
```
### Pattern 3: Token Holding
```typescript
// User holds 1000 tokens
{
fromThingId: userId,
toThingId: tokenId,
relationshipType: "holds_tokens",
metadata: {
balance: 1000,
network: "sui",
acquiredAt: Date.now()
},
createdAt: Date.now()
}
```
### Pattern 4: Course Enrollment
```typescript
// User enrolled in course
{
fromThingId: userId,
toThingId: courseId,
relationshipType: "enrolled_in",
metadata: {
progress: 0.45, // 45% complete
enrolledAt: Date.now(),
lastAccessedAt: Date.now()
},
createdAt: Date.now()
}
```
### Pattern 5: Organization Membership
```typescript
// User is member of organization
{
fromThingId: userId,
toThingId: organizationId,
relationshipType: "member_of",
metadata: {
role: "org_owner" | "org_user",
permissions: ["read", "write", "admin"],
invitedBy?: Id<"things">,
invitedAt?: number,
joinedAt: Date.now(),
},
createdAt: Date.now()
}
```
### Pattern 6: Payment Transaction (Consolidated)
```typescript
// User paid for product
{
fromThingId: userId,
toThingId: productId,
relationshipType: "transacted",
metadata: {
transactionType: "payment",
amount: 99.00,
currency: "USD",
paymentId: "pi_123456",
status: "completed",
protocol: "stripe" // or "x402", "ap2"
},
createdAt: Date.now()
}
```
### Pattern 7: Protocol Communication (Consolidated)
```typescript
// Agent communicated with external agent
{
fromThingId: oneAgentId,
toThingId: externalAgentId,
relationshipType: "communicated",
metadata: {
protocol: "a2a",
messageType: "task_delegation",
task: "research_market_trends",
messagesExchanged: 42
},
createdAt: Date.now()
}
```
## Protocol-Agnostic Design
Connections store protocol identity in `metadata.protocol`:
```typescript
// A2A Protocol
metadata: {
protocol: "a2a",
messageType: "task_delegation",
task: "research"
}
// ACP Protocol
metadata: {
protocol: "acp",
eventType: "purchase_initiated",
agentPlatform: "chatgpt"
}
// AP2 Protocol
metadata: {
protocol: "ap2",
mandateType: "intent",
autoExecute: true
}
// X402 Protocol
metadata: {
protocol: "x402",
network: "base",
txHash: "0x..."
}
```
## Querying Connections
### Get Entity's Relationships
```typescript
// Get all entities this entity owns
const owned = await db
.query("connections")
.withIndex("from_type", q =>
q.eq("fromThingId", thingId)
.eq("relationshipType", "owns")
)
.collect();
const ownedThings = await Promise.all(
owned.map(conn => db.get(conn.toThingId))
);
```
### Get Reverse Relationships
```typescript
// Get all entities that own this entity
const owners = await db
.query("connections")
.withIndex("to_type", q =>
q.eq("toThingId", thingId)
.eq("relationshipType", "owns")
)
.collect();
```
### Get Bidirectional Relationships
```typescript
// Get all collaborations (both directions)
const collaborations = await db
.query("connections")
.withIndex("bidirectional", q =>
q.eq("fromThingId", userId)
.eq("toThingId", partnerId)
)
.collect();
```
## Performance
### Indexes
```typescript
connections:
- from_type(fromThingId, relationshipType)
- to_type(toThingId, relationshipType)
- bidirectional(fromThingId, toThingId)
```
### Query Optimization
- Always use indexes
- Filter by relationship type when possible
- Use bidirectional index for symmetric relationships
- Batch relationship queries with Promise.all()
## Validation Rules
- `fromThingId` must exist
- `toThingId` must exist
- `relationshipType` must be valid
- Cannot connect thing to itself (usually)
- Relationship must make semantic sense
## Key Principles
- **Thing-to-thing** - Every connection links two things
- **Metadata for variants** - Use metadata for relationship-specific data
- **Protocol-agnostic** - Protocol identity in metadata.protocol
- **Bidirectional indexes** - Efficient queries in both directions
- **Flexible schema** - metadata allows extension without schema changes
- **Event-driven** - Connection changes log events
**Connections create the graph. Things are the nodes. Connections are the edges.**