From 7f94074de0dd39c3137aa683cbc77614e29c7d0c Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Tue, 30 Dec 2025 11:09:44 -0800
Subject: [PATCH] Add federation architecture doc (gt-6r18e)

---
 docs/federation.md | 208 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 docs/federation.md

diff --git a/docs/federation.md b/docs/federation.md
new file mode 100644
index 00000000..5d77a8ce
--- /dev/null
+++ b/docs/federation.md
@@ -0,0 +1,208 @@
+# Federation Architecture
+
+> Multi-workspace coordination for Gas Town and Beads
+
+## Overview
+
+Federation enables multiple Gas Town instances to reference each other's work,
+coordinate across organizations, and track distributed projects.
+
+## Entity Model
+
+### Three Levels
+
+```
+Level 1: Entity    - Person or organization (flat namespace)
+Level 2: Chain     - Workspace/town per entity
+Level 3: Work Unit - Issues, tasks, molecules on chains
+```
+
+### URI Scheme
+
+Full work unit reference:
+
+```
+gt://entity/chain/rig/issue-id
+gt://steve@example.com/main-town/gastown/gt-xyz
+```
+
+Within a workspace, short form works:
+
+```
+gt-xyz           # Local
+gastown/gt-xyz   # Different rig, same chain
+```
+
+## Relationship Types
+
+### Employment
+
+Track which entities belong to organizations:
+
+```json
+{
+  "type": "employment",
+  "entity": "alice@example.com",
+  "organization": "acme.com"
+}
+```
+
+### Cross-Reference
+
+Reference work in another workspace:
+
+```json
+{
+  "references": [
+    {
+      "type": "depends_on",
+      "target": "gt://other-entity/chain/rig/issue-id"
+    }
+  ]
+}
+```
+
+### Delegation
+
+Distribute work across workspaces:
+
+```json
+{
+  "type": "delegation",
+  "parent": "gt://acme.com/projects/proj-123",
+  "child": "gt://alice@example.com/town/gastown/gt-xyz",
+  "terms": { "portion": "backend", "deadline": "2025-02-01" }
+}
+```
+
+## Agent Provenance
+
+Every agent operation is attributed:
+
+### Git Commits
+
+```bash
+# Set per agent session
+GIT_AUTHOR_NAME="gastown/crew/joe"
+GIT_AUTHOR_EMAIL="steve@example.com"  # Workspace owner
+```
+
+Result: `abc123 Fix bug (gastown/crew/joe <steve@example.com>)`
+
+### Beads Operations
+
+```bash
+BD_ACTOR="gastown/crew/joe"  # Set in agent environment
+bd create --title="Task"     # Actor auto-populated
+```
+
+### Event Logging
+
+All events include actor:
+
+```json
+{
+  "ts": "2025-01-15T10:30:00Z",
+  "type": "sling",
+  "actor": "gastown/crew/joe",
+  "payload": { "bead": "gt-xyz", "target": "gastown/polecats/Toast" }
+}
+```
+
+## Discovery
+
+### Workspace Metadata
+
+Each workspace has identity metadata:
+
+```json
+// ~/gt/.town.json
+{
+  "owner": "steve@example.com",
+  "name": "main-town",
+  "public_name": "steve-gastown"
+}
+```
+
+### Remote Registration
+
+```bash
+gt remote add acme gt://acme.com/engineering
+gt remote list
+```
+
+### Cross-Workspace Queries
+
+```bash
+bd show gt://acme.com/eng/ac-123    # Fetch remote issue
+bd list --remote=acme               # List remote issues
+```
+
+## Aggregation
+
+Query across relationships without hierarchy:
+
+```bash
+# All work by org members
+bd list --org=acme.com
+
+# All work on a project (including delegated)
+bd list --project=proj-123 --include-delegated
+
+# Agent's full history
+bd audit --actor=gastown/crew/joe
+```
+
+## Implementation Status
+
+- [ ] Agent identity in git commits
+- [ ] BD_ACTOR default in beads create
+- [ ] Workspace metadata file
+- [ ] Cross-workspace URI scheme
+- [ ] Remote registration
+- [ ] Cross-workspace queries
+- [ ] Delegation primitives
+
+## Use Cases
+
+### Multi-Repo Projects
+
+Track work spanning multiple repositories:
+
+```
+Project X
+├── gt://team/frontend/fe-123
+├── gt://team/backend/be-456
+└── gt://team/infra/inf-789
+```
+
+### Distributed Teams
+
+Team members in different workspaces:
+
+```
+Alice's Town → works on → Project X
+Bob's Town   → works on → Project X
+```
+
+Each maintains their own CV/audit trail.
+
+### Contractor Coordination
+
+Prime contractor delegates to subcontractors:
+
+```
+Acme/Project
+└── delegates to → Vendor/SubProject
+                   └── delegates to → Contractor/Task
+```
+
+Completion cascades up. Attribution preserved.
+
+## Design Principles
+
+1. **Flat namespace** - Entities not nested, relationships connect them
+2. **Relationships over hierarchy** - Graph structure, not tree
+3. **Git-native** - Federation uses git mechanics (remotes, refs)
+4. **Incremental** - Works standalone, gains power with federation
+5. **Privacy-preserving** - Each entity controls their chain visibility