Federation (Core Domain)

How holons publish to each other — the federation publishing domain

The @holons/core/federation module is the implementation behind the federation concept. It is the layer that takes an item from one holon and makes it visible in another—or to many others, or to a specific geographic cell—under the rules each side has set for itself.

This is distinct from HoloSphere federation, which is about data sharing between spaces. The core federation domain sits one level up: it decides what gets published, to whom, and how before HoloSphere is asked to propagate it.

The mental model

Two questions answered by every federation publish:

What's being published? An item, wrapped in a hologram—a propagation-ready envelope with provenance metadata (publishedAt, source attribution, original id).
Where is it going? A target, expressed as one of three shapes:

Target

When to use it

{ kind: 'all' }

Broadcast to every federated partner — the default for general announcements

{ kind: 'partner', holonId }

Send to one specific partner holon

{ kind: 'hex', cell }

Drop into a geographic H3 cell (regional / bioregional flows)

Same operation, three reach patterns. A holon publishing a quest to its sibling co-op uses partner. A bioregional hub publishing observations to everyone in its region uses hex. A holon announcing a new offering uses all.

The publish surface

function publishToFederation(
  ctx: PublishContext,
  target: PublishTarget,
  options?: PublishOptions
): Promise<PublishOutcome>

`PublishContext`

What's being published:

interface PublishContext {
  holosphere: HoloSphere;
  holonId: string;     // home holon (the source)
  lens: string;        // which lens — tasks, expenses, …
  item: { id: string; [k: string]: any };
}

The id is required: the publisher needs a stable identifier so receivers can resolve the hologram back to its origin.

`PublishOptions`

How to publish:

interface PublishOptions {
  /** Also write to settings.hex if one is configured. Default true. */
  includeSettingsHex?: boolean;

  /** Federation source identity (e.g. nostr pubkey). Defaults to `holonId`. */
  federationSourceId?: string;

  /** Called when a put is rejected by HoloSphere ACL. */
  onWriteDenied?: (info: {
    target: string;
    lens: string;
    message: string;
  }) => void;
}

federationSourceId is the escape hatch for holons that key federation off something other than the home holon ID—typically a Nostr public key. UIs resolve their identity layer and pass it in.

onWriteDenied is how the UI gets notified when a target rejects the publish for permission reasons. The publish doesn't abort on a single denial; it continues with the other destinations and records the denial in the outcome.

`PublishOutcome`

What happened:

interface PublishOutcome {
  publishedTo: number;      // count of successful destinations
  destinations: string[];   // their IDs
  errors: string[];         // per-destination failures
  usedHolograms: boolean;
}

A publish never throws on a single bad destination; it accumulates errors and lets the caller decide how to surface them.

Settings-hex integration

A holon can configure a settings hex — an H3 cell that acts as its public bulletin board. When includeSettingsHex is true (the default), every "publish to all" also drops the hologram into that cell.

This is what enables geographically-keyed discovery: a regional aggregator subscribed to the hex sees every published item from every member holon in its region without those holons needing to know about it individually.

readSettingsHex(holosphere, holonId) reads the configured cell for a given holon. If unset, the cell-write side of the publish is skipped silently.

Snapshots

getFederationSnapshot(holosphere, holonId, federationSourceId?) is the read-only view of a holon's federation state:

interface FederationSnapshot {
  federated: string[];                     // partner IDs
  partnerNames: Record<string, string>;    // ID → display name
}

This is what powers UI lists ("who am I federated with?") and what publishToFederation itself consults when target is { kind: 'all' }.

The hologram pattern

Every publish wraps the source item in a hologram before propagating. The hologram includes:

a copy of the item,
the origin holon ID,
the origin lens,
a published-at timestamp,
the federation source ID (often a Nostr pubkey).

Why wrap? Because the same item may be in the origin holon's lens and in a partner's lens and in a hex cell—and consumers downstream need to know which copy they're looking at, who published it, and whether updates should track back to a canonical source.

The caller is responsible for stamping the source item with published / publishedAt / publishedTo markers (this is intentional—UIs often want to update their own item rendering at the same moment). The hologram itself is computed inside publishToFederation.

How permission denials surface

HoloSphere's federation uses ACLs at the destination: a partner can refuse writes to particular lenses. When the publisher hits a denial:

The error is detected by name (AuthorizationError) or message (Write access denied).
A short message is built (Unable to publish to <prefix>… — no write permission for <lens>).
The onWriteDenied callback fires (UIs use this to show a toast).
The denial goes into PublishOutcome.errors as a short string.
The publish continues to the remaining destinations.

This is what makes federation safely best-effort: a misconfigured partner doesn't block other partners from receiving the publish.

MCP tool surface

The MCP server exposes 3 tools in the federation domain:

publish_to_federation — the core publish, with full target/options support
get_federation_snapshot — read partner list and names
read_settings_hex — read the configured discovery cell

An MCP-connected agent can therefore make a holon publish, inspect its federation, and discover where its broadcasts land—all without UI involvement.