[Application][Chat] Build Elembra Chat bridge around Buzz without merging sources of truth

[senolcolak]

Parent

Part of #196. Architecture source of truth: #209 and ADR-0034.

Related prerequisite issues: #210, #211, #212. Identity/key lifecycle is tracked separately.

Goal

Implement Elembra Chat as a first-party Elembra Application with Buzz as its independent Engine.

Do not merge the RustShare/Elembra backend and Buzz into one source of truth. Do not embed Elembra private internals throughout Buzz.

Hard dependency rule

BAD
Buzz core -> Elembra DB / Files internals / permission internals

GOOD
Elembra Chat Bridge -> Buzz public protocol/API/SDK
Elembra Chat Bridge -> Elembra Application contracts

Source-of-truth boundaries

Buzz remains authoritative for:

• signed chat events;
• channels/threads/DMs;
• chat community/membership state required by Buzz;
• reactions/workflows/chat projections;
• cryptographic event signatures.

Elembra remains authoritative for:

• tenant/workspace/Principal identity;
• Application grants;
• Files resources/permissions;
• Memory catalog/index/RAG;
• Agent delegated cross-Application authority.

No shared database schema.

Scope

1. Chat Application manifest/contracts

Register io.elembra.chat as an Application with runtime.kind: bridge.

Declare:

• owned Chat resource types/action capabilities;
• Contributions to Elembra Shell;
• required Platform/Files/Memory contracts;
• integration events;
• health/degraded states.

2. Workspace/community mapping

Implement explicit tenant-scoped mapping:

Elembra WorkspaceId <-> Buzz community

Requirements:

• auditable;
• unique/validated within tenant rules;
• revocable/reconfigurable with explicit migration semantics;
• fail closed across tenants.

3. Principal/Buzz public-key mapping integration

Consume the identity-binding contract from the dedicated Chat identity issue.

The Bridge must not invent a second implicit mapping or assume OIDC subject = Buzz key.

4. Files attachments and resource references

Implement the flow from #211:

1. Files returns immutable/versioned ResourceRef + safe display metadata;
2. signed Buzz event stores the ref, not a permanent access URL;
3. opening/unfurling calls Files under current PrincipalContext;
4. Files reauthorizes at read time;
5. revocation in Files remains effective even though the Buzz event is historical/immutable.

Preview/unfurl data must be permission checked and minimized.

5. Memory projection

Bridge publishes selected Chat activity to Elembra Memory as reference/provenance records.

Default projection should contain:

• Buzz event ID/ref;
• workspace/community/channel context;
• mapped author Principal;
• event timestamp/type;
• signature/checksum/provenance;
• classification/retention reference;
• authorization owner/reference.

Do not make Elembra PostgreSQL a second authoritative Buzz message database merely to enable RAG.

Content materialization/indexing follows explicit workspace policy and ADR-0033.

6. Search integration

Initial design may combine/federate:

• Buzz/Chat source search under Chat authorization;
• Elembra Memory projections;
• Files/Mail/Notes search.

Opening/materializing a result reauthorizes with its source. A shared unrestricted index is forbidden.

7. Agent integration

An Elembra Agent participating in Chat has:

• its own Elembra Agent Principal;
• its own mapped Buzz identity when it signs/posts;
• explicit delegated actions for Files/Mail/Memory tools.

Chat membership is not blanket permission to other Applications.

8. Existing RustChat assessment/migration

Before deleting/reusing old RustChat code:

• inventory product/client functionality worth retaining;
• identify any real persisted user data requiring migration/export;
• identify integrations/UX that should be reimplemented over Buzz;
• explicitly reject old backend areas that duplicate Buzz.

Do not preserve the old RustChat backend merely for backward compatibility if Buzz replaces it.

9. Repository/upstream strategy

Prepare the target separate Chat repository strategy (likely kubedoio/elembra-chat) containing only:

• Buzz upstream tracking/delta strategy;
• branding/product layer;
• Elembra Chat Bridge;
• identity adapter;
• Files/Memory/Agent integrations;
• deployment;
• compatibility tests.

Keep Buzz core delta minimal and reviewable against upstream.

Failure model

• Chat remains useful if optional Memory indexing is down;
• Files/Notes/Mail remain useful if Buzz/Chat is down;
• cross-system effects use durable retry/idempotency;
• no distributed transaction spans Buzz and Elembra.

Explicit non-goals

• Mattermost compatibility if it increases effort materially;
• direct Buzz DB reads from Elembra;
• Elembra DB reads from Buzz core;
• OIDC bearer token replacing Buzz signing;
• copying all Buzz state into Elembra as authoritative rows;
• running RustChat and Buzz as parallel authoritative backends indefinitely.

Required tests

• tenant/workspace/community mapping isolation;
• Bridge outage/recovery with durable retry;
• Files attachment access denied after Files revocation while Chat history remains intact;
• no permanent access token in signed event fixture;
• Memory projection traces to Buzz source event;
• deleted/revoked source result does not leak through search/RAG;
• Agent Chat membership cannot bypass Files/Mail permission;
• Buzz can operate when optional Elembra Memory is unavailable;
• compatibility test detects unsupported Buzz upstream delta.

Acceptance criteria

• io.elembra.chat Application exists as bridge-backed Application.
• Buzz remains Chat source of truth.
• No shared private DB access exists.
• Workspace↔community mapping is explicit/auditable/fail-closed.
• Files attachments use ResourceRefs/read-time authorization.
• Memory projection preserves Buzz provenance.
• Agent identity/authority remains explicit.
• RustChat features/data have an explicit retain/migrate/drop decision.
• Buzz upstream strategy and compatibility suite are documented/implemented.

---

Status update (2026-08-13)

Delivered by PR #238 ("Elembra Chat Application v1 powered by Buzz", merged to main):

• io.elembra.chat Application manifest/registry entry, /apps/chat route, renderer/icon/object-href/sidebar integration, per-tenant enablement — scope §1 mostly done.
• Explicit auditable Workspace↔community mapping with fail-closed cross-tenant isolation (scope §2).
• Principal↔Buzz pubkey binding/admission/rotation with NIP-42 proof (scope §3 foundation — identity specifics tracked in [Application][Chat][Identity] Design and implement Elembra SSO ↔ Buzz key binding, recovery and revocation #215).
• Files attachments via ResourceRef + read-time Files authorization, elembra-ref tag (scope §5).
• Observation → chat_observed_events → durable outbox event → Memory projection with Buzz provenance (scope §6).
• Ask-this-channel + exact-message citations over the existing Memory pipeline (scope §7).
• Failure model: Files/Notes remain usable when Buzz is down; observation never touches the Memory catalog (scope "Failure model").

Remaining / not delivered:

• Buzz relay-side capability is not live upstream (ADR-0035): access/check, kind-9030/9031 admission/revocation, channel registry — the current deployment runs the coarse local gate. Scope §4 and the acceptance item "real relay endpoints implemented in the Buzz repository" block production buzz-mode authorization.
• Buzz bridge outbox consumer (optional io.elembra.chat.buzz-bridge.v1) is implemented but only exercises with a separately provisioned service key + live relay.
• RustChat retain/migrate/drop path is not implemented.
• Per-channel membership verification at the projection/Ask-candidacy layer (upstream channel-level adapter).
• Client channel-tagging and reply/thread wire formats (upstream, deferred).
• Separate Chat repository strategy (scope §9) is a strategic decision, not started.

Recommendation: keep this issue open as the tracker for the remaining items; the delivered slice is tracked by #238 and the Alpha-readiness plan (docs/architecture/elembra-chat-alpha-readiness.md).