jason.woltje
193479b52d
Mosaic concepts pages now own the adapted content; source/license metadata under docs/reference/concepts. Adds ACT-1 agent-context planning capture, pinned concept test package + preparation utility, foundation observation notes (durability, evidence, federation, onboarding, workflow), and the #1495 consolidation assessment. TOOLS.md updated for the host-dev launcher.
96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# 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.
|