Feature: Presence Port

[jhweir]

PR: The Ephemeral Port and Live Presence

Summary

Adds a fifth backend port to WE — Ephemeral, for transient agent-to-agent state — and its first
consumer, Presence. The visible result is "N online now" plus an avatar row in the space header,
showing who else is in the space right now.

The port is the load-bearing part. Presence proves it works; the WebRTC call module, live cursors,
typing indicators, and DM typing all ride the same seam afterwards.

Branch: feat/presence-port · 11 commits · 58 new tests · verified across two agents

Design rationale in full: notes/we/August-2026/presence-port.md.

---

Why a new port rather than QueryIR

QueryIR assumes durable entities declared in a model manifest, each with a globally-stable id.
Ephemeral state has none of those — no manifest entity to name, no id surviving a restart, nothing
persisted to query. Routing presence through $query would either corrupt the IR's guarantees or
require inventing a phantom entity type.

The rule this port exists to enforce, to be applied every time something is proposed for it:

If it must still be there after a refresh, it is not ephemeral.

Durable messaging (chat, DMs) therefore stays with DataSource. See "Non-consumer: user-to-user
messaging" in the design note — a two-person neighbourhood gives confidentiality by membrane, which
an ephemeral transport inside a shared space cannot.

---

What's in it

@we/schema-shared — the neutral core (DOM-free, fully unit-tested)

ephemeral.ts — the port:

ephemeral(dataset).channel(tag, { coalesce? }) → { publish(payload, to?), onMessage(cb) }

Dataset-scoped because a call happens in a space and DM typing in a DM neighbourhood.
Tag-namespaced so a feature module gets a namespace it cannot collide with. Payloads are opaque, so
presence, RTC, and cursors share one pipe without the transport knowing about any of them. The tag
maps onto a Socket.io event name, a Supabase channel topic, a Matrix to-device type, or a gossipsub
topic.

Plus EphemeralCapabilities and planEphemeral, mirroring AdapterCapabilities / planQuery.

presence.ts — Focus, Activity, PresenceState, Peer, derivePeers, applyFocusDepth,
peersMatching, callRosters, peerTone, sortByPresence, and createHeartbeatPresence.

@we/app-framework — the bindings

file	role
shared/ad4mEphemeralAdapter.ts	AD4M implementation, ~140 lines, sibling to ad4mAdapter.ts
shared/tabCoordinator.ts	focus-follows-leader election; only one tab publishes
frameworks/solid/stores/PresenceStore.tsx	lifecycle, focus publishing, profile join
schemas/…/HeaderLayout/SpaceHeader.ts	the visible feature

@we/components — one design-system addition

AvatarInfo.tone — a per-avatar ring colour as a semantic token (success / warning / danger /
primary / neutral), overriding the stack-level ring. Generic rather than presence-specific: any
stack may want to distinguish members. The design system owns the colour, so neither templates nor
stores ever name one.

---

Design decisions worth reviewing

unicast is a tri-state, not a boolean

unicast: "native" | "emulated" | "none";

'emulated' means addressed-but-broadcast: every peer receives the payload and is trusted to discard
it. Fine for SDP/ICE, fatal for anything confidential. As a boolean, someone eventually builds a
private feature on unicast: true and it silently is not private — which is the state Flux is in
today, where every "directed" WebRTC signal and private emoji reaction is broadcast community-wide
and filtered client-side (webrtcStore.ts:88-92).

AD4M is 'emulated': it exposes real directed send (sendSignal / sendSignalU) but that is
known-broken, so the adapter addresses over broadcast. When it is fixed, flip one value and delete
the filter — grep unicast:emulated. No consumer changes. Same doctrine as the drill-down predicate
workaround already in ad4mAdapter.ts: a backend defect degrades to an adapter workaround, not a WE
outage.

Corollary, stated so it does not have to be rediscovered: confidentiality comes from membrane or
encryption, never from addressing.

authenticatedSender is declared, not assumed

AD4M supplies link.author from the executor, so a peer cannot write into another agent's presence
slot — which is what will make a work-claim lease trustworthy. A naive relay carries the sender in
the payload, where it is forgeable. Without the flag, a host could implement this port entirely
correctly and still ship spoofable presence.

focus is one value; activities is a list

A call is not a place you are instead of the Kanban board — it is something you are in while also
being somewhere. Routes are exclusive; participation is not.

Flux found this and modelled it flatly: currentRoute + callRoute + inCall + mediaSettings.
As a list, concurrent calls in one space fall out for free (Flux structurally cannot express
them — callRoute is one value, so one call per agent), and a feature module adds an activity type
without touching the schema.

availability (declared) vs liveness (measured)

Flux fuses them into one union and carries a standing // TODO: better distinguish between manually set agent status and signalling health (useSignallingService.ts:236). They are orthogonal: an
agent can be busy and online, or available and stale.

Only liveness is shown today. peerTone colours the avatar ring green / amber / red across
online / idle / stale. Nothing can set availability yet — no idle detector, no manual control
— so every peer reports available and rendering it would be dead weight decided on a guess. A test
pins the current behaviour so that when that UI lands, choosing how the two axes combine is a
deliberate change rather than something that falls out of code written today.

Departure is announced, not inferred

Leaving a space was indistinguishable from a crashed laptop: the agent simply stopped heartbeating
and ran the full decay ladder, so it lingered for a full offlineAfter (60s) in a space it left
instantly. Arrival was already one round trip via hello; bye makes departure symmetric, and peers
drop the agent outright rather than watching it fade.

An optimisation, not a guarantee — the transport is lossy and fire-and-forget, so a lost bye
just falls back to decay. Fast path explicit, slow path derived, exactly as hello relates to the
heartbeat.

One case that is easy to get wrong: an invisible agent sends no bye. It published nothing, so
peers hold no state to retract, and sending one would disclose the departure and therefore the
presence.

Ring colour, not opacity

The first attempt encoded two axes at once — ring colour for declared availability, opacity for
measured liveness — so both could be read together. It was reverted after testing, for a reason
that is structural rather than a matter of tuning:

Avatars in a stack overlap. Lowering opacity lets the avatar behind show through the one in
front, and the opaque separator ring is precisely what prevents that. Opacity and overlap cannot
coexist — no value would have worked.

It also simply read as more confusing; two axes is more than a glanceable indicator should carry. So
emphasis was removed from AvatarStack rather than left in the design system unused and quietly
broken in the component's own primary layout.

focus is hierarchical, and that is the privacy dial

{ datasetUri, path?, nodeId? }. Publish the deepest you know; consumers slice. Space presence is a
selector, not a different data model.

depth	peers learn
off	"James is online"
space	"…is in this space"
route	"…is looking at the budget page"
precise	"…is reading your post"

availability: 'invisible' is the separate, stronger control that stops publishing entirely.
Flux keeps broadcasting full state including route when invisible and merely hides it on receipt, so
any modified client sees invisible agents and where they are.

datasetUri, never perspective.uuid

AD4M perspective uuids are local per-agent — the same neighbourhood has a different one on every
peer, so a broadcast uuid is meaningless to whoever receives it. Same local-id vs global-uri split
already baked into DatasetHandle. This fails silently across peers while looking correct
locally, which is why it is in the type rather than in a comment.

Presence never fetches a profile

It carries agentId only; profiles come from adamStore.agents(), the cache $identities and the
$agent block already use. Flux's presence map is its profile cache, so it re-hydrates every peer
profile on every heartbeat — an N-peer Promise.all every five seconds.

Note the deliberate divergence from spaceStore.members, which filters out agents with no cached
profile. Presence does not: a peer with no profile still counts. So when profile fetching is failing,
"N online now" still shows a count while the members row goes empty. That is presence being
correctly more robust, not a bug.

App-lifetime, not view-lifetime; retain nothing, subscribe deliberately

Flux creates a signalling service per community view and stops it on unmount, so leaving the view
loses every peer with no path back except remounting. It also defines deleteCommunityService and
never calls it, so services accumulate holding frozen agent maps — retention without
subscription, which keeps state and lets it rot.

PresenceStore lives in StoreProvider and re-scopes on space change, tearing the old source down.
Retention buys nothing: presence is TTL'd, so a retained map is already stale, and the join handshake
repopulates in one round trip.

Subscription scope is current-space-only. Presence for every joined space would let the sidebar
show occupancy everywhere, but inbound traffic is (spaces × members ÷ heartbeat) signals per
second — 20 spaces × 30 members ÷ 5s ≈ 120/s, each crossing the executor's GraphQL boundary into
reactive state on the main thread. Widening this is a deliberate later decision and realistically
wants a backend that reports presence server-side.

---

Lifted from Flux, and what was fixed

Kept, because load-bearing:

• Adaptive scheduling — a change publishes immediately and pushes the next tick out a full
  interval, so navigating quickly does not double-send.
• Join handshake — a joiner sets hello, peers re-announce at once. Without it a joiner waits a
  whole interval against a stateless, lossy transport.
• Tab-leader election — leadership follows window focus; followers stay subscribed so their UI
  stays live.

Fixed:

Flux	here
agent map only relabels to offline, grows forever	TTL eviction
no departure signal — leaving decays like a crash	bye drops the peer at once
invisible still broadcasts route, filtered on receipt	invisible stops publishing
profiles re-fetched every heartbeat (watch {deep:true})	profiles never touched by presence
"directed" signals broadcast to everyone, filtered client-side	declared as unicast: 'emulated' so nothing builds privacy on it
full state JSON every 5s	small heartbeat; full state on change/handshake

---

Backpressure (coalesce)

channel(tag, { coalesce: true }) drops a publish while a previous one is still in flight.

Correct only for idempotent last-write-wins traffic, where the next beat carries the same state.
Explicitly wrong for a handshake: an RTC offer dropped because the previous send is slow is simply
lost. Default off; presence opts in.

Earned from a real failure. On an unhealthy executor sendBroadcast hangs until a 30s RPC timeout
while presence heartbeats every 5s, so six stuck calls accumulate at steady state — each adding load
to the backend that is already the problem — and a warning every five seconds buries the actual
fault. Failure logging now backs off geometrically (1st, 2nd, 4th, 8th…) and logs once on recovery
with the count.

---

Testing

Verified: 576 tests in @we/schema-shared (38 new) and 82 in @we/app-framework (20 new);
@we/schema-shared, @we/app-framework and @we/components typecheck; lint clean; all 13 template
schemas validate. Confirmed working live across two agents on separate machines.

The neutral core is tested against a fake channel and an injected clock, so liveness derivation, the
handshake, adaptive scheduling, eviction, activity replacement, and the invisible-stops-publishing
guarantee are all covered without a backend. The tab coordinator takes its channel, focus source, and
tab id as dependencies for the same reason, and is driven by an in-memory bus.

Three real defects were found by writing tests, all silent in production:

1. peersAtPath(peers, '/kanban') unioned peers across different spaces sharing a route path —
   the same class of mistake as broadcasting a local uuid, invisible in single-space testing.
   Replaced with peersMatching(peers, partialFocus), so a path cannot be expressed without its
   dataset.
2. Symmetric leadership conflict resolution never terminated. "Hear another leader → step down" makes
   both step down; nobody publishes until the timeout, then both take over again. Now the lower tab
   id survives — deterministic and total.
3. Pinning was a local exemption, which is not a total order: a pinned leader skipped the comparison
   for itself but never told the other leader to yield, so when the pinned tab held the higher id
   both published forever. Pinning is now asserted, with a fallback to the id comparison when both
   tabs are pinned (two calls in two tabs).

None of the three throws or logs. Each would have presented as an AD4M problem.

Live verification

Exercised across two agents on separate machines: peers appear, the ring tracks the decay ladder, and
departures drop immediately. This also confirms the adapter's two assumptions about AD4M's wire
behaviour, neither of which unit tests can reach — that link.author arrives populated (so a peer
cannot write into another agent's slot) and that sendBroadcastU does not loop back to the sender.

Getting there needed a fresh pair of neighbourhoods. An earlier attempt failed entirely, and the
diagnosis is worth keeping because it is not obvious and will recur:

• neighbourhood.sendBroadcast timed out on the 30s RPC deadline, repeatedly.
• agentByDID returned 500 — centralized-agent-language could not reach socket.ad4m.dev
  (Connection refused, os error 111), so no profile resolved.
• Space member data did not load either, and that comes from client.neighbourhood.otherAgents(),
  which touches none of this code.

socket.ad4m.dev backs both centralized-agent-language and centralized-p-diff-sync, and the
latter serves link sync and telepresence. So one unreachable host can explain every symptom at
once, with none of it being Holochain or presence. The check is
await client.runtime.knownLinkLanguageTemplates() — new spaces take [0].

AD4M's telepresence is not an out-of-band channel. p-diff-sync's sendBroadcast is a Holochain
zome call (bootstrap-languages/p-diff-sync/index.ts:346), so presence shares the conductor with data
sync. It does not depend on the perspective's links having synced — presence lights up before space
data loads — but a wedged conductor hangs it. On a websocket or Matrix host the two are genuinely
independent; EphemeralCapabilities does not currently express that difference.

Still worth re-checking on any future backend, in priority order:

1. The failure that looks fine with one agent — the broadcast source must carry a datasetUri
   starting neighbourhood://, not a perspective uuid. If wrong, online populates but onlineHere
   never does.
2. Join handshake — B appears for A within ~1s, not after a 5s wait.
3. Decay — kill the tab (don't navigate, that sends bye); ring goes green → amber at 15s → red at
   30s → gone at 60s.
4. Departure — navigate away; B disappears for A at once rather than decaying.
5. Personal space — the block is absent, no console errors.
6. Two tabs on one machine — A sees one B, following whichever tab B is focused on.

---

Deliberately deferred

• $presence renderer block + tier validation. The header reads presenceStore through
  $store, so this PR needs no renderer or @we/schema-shared render-path changes. A block is sugar
  and touches schema-solid — separate, riskier, and it shouldn't ride along.
• Availability UI, and showing it. setAvailability exists on the store but nothing calls it, so
  every peer reports available and only liveness reaches the ring. Wants an input-idle detector
  (no mouse/keyboard for N minutes → away), a manual control, and AgentSettings persistence in
  we-root — the pattern is already there alongside currentTemplateId / perspectiveOrder. Note
  that auto-derived away should not persist, while a manual "do not disturb" should.
• Privacy-dial UI. focusDepth exists on the store; nothing surfaces it yet. Also wants
  AgentSettings persistence.
• planEphemeral has no caller. Presence needs only fan-out, so it would always pass. The
  mechanism is there for the call module, which needs unicast.
• calls / activitiesOfType are unused until the call module.
• Multi-space subscription (sidebar occupancy dots). See the arithmetic above.
• Amber may flicker. idle means "missed three beats", so a wobbly connection dips the ring to
  amber and back. Deliberate for now — it makes the mechanism visible — but worth softening once it
  has been watched in real use.

---

Follows on

notes/we/August-2026/feature-modules.md — the call module is a feature module, and needs two
host capabilities that do not exist yet: an open shell-slot mechanism (shellRegistry is a closed
three-key object, and a call bar must persist across navigation) and store registration
(TemplateProvider builds its stores bag as an object literal). That work is the next PR; the call
module is the one after.

[netlify]

✅ Deploy Preview for coasys-we ready!

Name	Link
🔨 Latest commit	fbbf850
🔍 Latest deploy log	https://app.netlify.com/projects/coasys-we/deploys/6a6cf5aa9303130008eba341
😎 Deploy Preview	https://deploy-preview-97--coasys-we.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.