Federation Architecture

> Status: Design spec - not yet implemented

> 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.

Why Federation?

Real enterprise projects don't live in a single repo:

Microservices: 50 repos, tight dependencies, coordinated releases
Platform teams: Shared libraries used by dozens of downstream projects
Contractors: External teams working on components you need to track
Acquisitions: New codebases that need to integrate with existing work

Traditional tools force you to choose: unified tracking (monorepo) or team autonomy (multi-repo with fragmented visibility). Federation provides both: each workspace is autonomous, but cross-workspace references are first-class.

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 (HOP protocol):

hop://entity/chain/rig/issue-id
hop://[email protected]/main-town/greenplace/gp-xyz

Cross-repo reference (same platform):

beads://platform/org/repo/issue-id
beads://github/acme/backend/ac-123

Within a workspace, short forms are preferred:

gp-xyz             # Local (prefix routes via routes.jsonl)
greenplace/gp-xyz  # Different rig, same chain
./gp-xyz           # Explicit current-rig ref

See ~/gt/docs/hop/GRAPH-ARCHITECTURE.md for full URI specification.

Relationship Types

Employment

Track which entities belong to organizations:

{
  "type": "employment",
  "entity": "[email protected]",
  "organization": "acme.com"
}

Cross-Reference

Reference work in another workspace:

{
  "references": [
    {
      "type": "depends_on",
      "target": "hop://other-entity/chain/rig/issue-id"
    }
  ]
}

Delegation

Distribute work across workspaces:

{
  "type": "delegation",
  "parent": "hop://acme.com/projects/proj-123",
  "child": "hop://[email protected]/town/greenplace/gp-xyz",
  "terms": { "portion": "backend", "deadline": "2025-02-01" }
}

Agent Provenance

Every agent operation is attributed. See Identity for the complete BD_ACTOR format convention.

Git Commits

# Set per agent session
GIT_AUTHOR_NAME="greenplace/crew/joe"
GIT_AUTHOR_EMAIL="[email protected]"  # Workspace owner

Result: abc123 Fix bug (greenplace/crew/joe <[email protected]>)

Beads Operations

BD_ACTOR="greenplace/crew/joe"  # Set in agent environment
bd create --title="Task"        # Actor auto-populated

Event Logging

All events include actor:

{
  "ts": "2025-01-15T10:30:00Z",
  "type": "sling",
  "actor": "greenplace/crew/joe",
  "payload": { "bead": "gp-xyz", "target": "greenplace/polecats/Toast" }
}

Discovery

Workspace Metadata

Each workspace has identity metadata:

// ~/gt/.town.json
{
  "owner": "[email protected]",
  "name": "main-town",
  "public_name": "steve-greenplace"
}

Remote Registration

gt remote add acme hop://acme.com/engineering
gt remote list

Cross-Workspace Queries

bd show hop://acme.com/eng/ac-123    # Fetch remote issue
bd list --remote=acme                # List remote issues

Aggregation

Query across relationships without hierarchy:

# 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=greenplace/crew/joe

Implementation Status

[x] Agent identity in git commits
[x] BD_ACTOR default in beads create
[x] Workspace metadata file (.town.json)
[x] Cross-workspace URI scheme (hop://, beads://, local forms)
[ ] Remote registration
[ ] Cross-workspace queries
[ ] Delegation primitives

Use Cases

Multi-Repo Projects

Track work spanning multiple repositories:

Project X
├── hop://team/frontend/fe-123
├── hop://team/backend/be-456
└── hop://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

Flat namespace - Entities not nested, relationships connect them
Relationships over hierarchy - Graph structure, not tree
Git-native - Federation uses git mechanics (remotes, refs)
Incremental - Works standalone, gains power with federation
Privacy-preserving - Each entity controls their chain visibility

Enterprise Benefits

Challenge

Without Federation

With Federation

Cross-repo dependencies	"Check with backend team"	Explicit dependency tracking
Contractor visibility	Email updates, status calls	Live status, same tooling
Release coordination	Spreadsheets, Slack threads	Unified timeline view
Agent attribution	Per-repo, fragmented	Cross-workspace CV
Compliance audit	Stitch together logs	Query across workspaces

Federation isn't just about connecting repos - it's about treating distributed engineering as a first-class concern, with the same visibility and tooling you'd expect from a monorepo, while preserving team autonomy.