# Federation, master registry and mosaic comms — owner direction

Date: 2026-09-06. Recorded by darkwing.
Status: captured forward architecture/API proposal, not an installed command or an
implementation/migration charter. Current offline inspector scope stays unchanged.

## Owner direction

Plan for federation and cross-site/cross-instance clustering from the foundation.
Maintain a master registry covering site, instance, project, workspace and agent.
The mosaic CLI registers those entities and their valid combinations.

Agent communications should use the public `mosaic comms` boundary. tmux must not
remain an agent-facing addressing/communication API; if retained, it is an internal
transport behind Mosaic. Other configurable transports may include durable Git
communications and a Mosaic backend using Matrix or another platform, self-hosted
or hosted services such as Discord/Slack. No backend is selected by this note.

## Proposed CLI, preserved from the owner

```text
mosaic comms
    --site      -S {uuid|name}
    --instance  -I {uuid|name}
    --project   -P {uuid|name}
    --workspace -W {uuid|name}
    --source    -s {uuid|name}
    --target    -t {uuid|name}
    --help
    --message   -m <text>
    --list      -l opt:<filter_text>
```

List returns available entries; exact filtering/output semantics remain to specify.

Addressing supports either a UUID of a registered agent instance bound into
site+instance+project+workspace+agent hierarchy, or combinations of UUIDs and names.
Owner wording: names resolve with the agent seat "little-endian"; the precise
qualified-name grammar/order needs specification rather than guessing.

A UUID at any level identifies its bound parent hierarchy, so ancestors need not
be redundantly supplied. The lowest-level UUID can anchor the remaining resolution.
UUID-to-UUID messaging is recommended for brevity and lack of ambiguity:

```sh
mosaic comms -S homelab -I main -P journal -W health -s <uuid> -t <name>
mosaic comms -s <uuid> -t <uuid>
```

These are proposed examples, not commands verified or invoked in this session.

## Design follow-through and open questions

- Separate reusable agent definitions from registered/scoped agent-instance or
  communication-endpoint identities. The accepted foundation allows one reusable
  agent across scopes; a scoped UUID must not silently turn that definition into
  a single-project identity. Define which entity each registry UUID identifies.
- Define logical master-registry authority and replication: single authoritative
  service, delegated site authorities or another consistency model. "Master registry"
  does not by itself decide deployment topology or make federation available.
- Resolve UUIDs to recorded parents without granting access. Conflicting explicit
  ancestors must refuse, not override a binding; names must resolve uniquely within
  an authorized namespace or refuse. No filename/cwd/seat-name membership inference.
- Clarify whether shared -S/-I/-P/-W flags constrain both endpoints or qualify only
  named endpoints when one endpoint UUID belongs elsewhere. Define the little-endian
  name syntax, escaping, aliases/renames, stale registrations and retirement.
- Authenticate the actual caller and check authority to use -s; a supplied source
  UUID/name is not proof of sender identity. Independently check destination scope,
  message type, visibility and cross-site trust. Listing/filtering must reveal only
  authorized entries. Transport delivery never grants reassignment authority.
- Keep addressing, authorization, message/receipt semantics and work truth independent
  of the transport. Different backends must not widen permissions or reinterpret
  messages as owner instructions, task acceptance or permission to change goals.
- Define durable enqueue/acknowledgement, stable message/request IDs, deduplication,
  ordering where required, retention/access controls and restart reconciliation.
  Git/tmux/backend presence alone does not establish delivery or exactly-once effects.
- Specify partition/stale-registry behavior, federation trust/key lifecycle, revocation
  propagation, site isolation and recovery. Continue unrelated authorized work where
  safe; fail closed rather than guess through uncertain authority.

Related: accepted technical map at 7345f330fc6bfae5aa1d896c78cfb7cbe62efbae;
2026-09-06_foundation-mechanical-workflow-topics.md;
2026-09-06_foundation-durability-observations.md;
2026-09-06_foundation-evidence-handoff-observations.md.

## Scope and migration boundary

This records the future platform boundary, not permission to implement federation,
create a registry, select/install a backend or modify the frozen inspector. No
worker is retasked. The proposed mosaic comms command is not claimed available.
The existing approved agent-send wrapper remains the current project transport
until an authorized replacement exists; no raw tmux workaround is introduced.
No external platform communication, credential handling or ~/.mosaic intervention
follows from this note. Registry semantics and transport migration need their own
reviewed charter before activation.