stack/docs/plans/2026-09-06_foundation-federation-comms-topics.md

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

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:

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.