Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(entity-changes): publish consumer decision table for R8-M14

Josué53f2645a9923
diff --git a/docs/architecture/live-entity-change-consumer-semantics.md b/docs/architecture/live-entity-change-consumer-semantics.md
new file mode 100644
index 000000000..bdc66f396
--- /dev/null
+++ b/docs/architecture/live-entity-change-consumer-semantics.md
@@ -0,0 +1,41 @@
+# Live entity-change consumer semantics
+
+Live entity-change delivery is a latest-state convergence signal, not event-history playback.
+Healthy clients should converge to authoritative state within approximately five seconds; clients
+may coalesce intermediate changes while disconnected or under load.
+
+| Input | Desktop | Control UI | Required visible result |
+| --- | --- | --- | --- |
+| `heartbeat` | Update transport liveness only. | Update transport liveness only. | No query, list, selection, dialog, or preview mutation. |
+| User `scope.invalidated` | Softly revalidate active GFS state and open resources. | Use soft semantics if received. | Keep loaded pages and preview bytes until authoritative reads establish a change or denial. |
+| Operator `scope.invalidated` | Use the soft path if received. | Coalesce a bounded burst into one active and one trailing authoritative pass. | Preserve rows, selection, dialogs, errors, and unchanged previews while reads run. |
+| User navigation or pagination during refresh | Foreground work wins; background work cannot replace its destination. | Bind results to location, operation, cursor, and generation. Defer a pending scope refresh across load-more. | A stale page never appears in another folder; the pending refresh eventually runs. |
+| `resync_required` | Cancel obsolete background work and revalidate roots, current location, open tabs, and relevant caches. | Reconcile mounted, open, cached, and visible operator scope. | Settle on the returned cursor; purge anything the authoritative reads deny. |
+| `stream.closing` | Reconnect with bounded backoff. | Reconnect with bounded backoff. | A healthy max-lifetime close does not clear visible state. |
+| `session_expired` / HTTP 401 | Purge state that cannot remain authorized; rebind only to a newer committed session. | Follow the existing unauthorized-session path and stop the expired stream. | No dead subscriber or stale authorized bytes remain. |
+| Connect failure or rejected frame | Preserve visible state; honor retry guidance and reset backoff only after a valid supported frame. | Preserve visible state and use bounded backoff. | No destructive invalidation or hot retry loop. |
+| Background read failure | Keep the last visible state and retry background work only. | Keep the last visible state; do not use navigation or pagination clearing paths. | Rows, dialogs, selection, and user-visible errors remain intact. |
+| Actual resource change | Apply metadata only to the matching resource; reload bytes only when relevant metadata changed. | Update only the matching list, tree, cache, or preview. | Duplicate and older responses cannot regress the current view. |
+| Deletion or revocation | Purge affected bytes/object URLs and show the generic unavailable state. | Remove the affected resource and close only actions bound to it. | No inaccessible content remains; unrelated state is preserved. |
+| Root hierarchy refresh | Treat `/` as a valid root with no ancestors. | Treat `/` as a valid root with no ancestors. | No false hierarchy-recovery warning at the root. |
+| Main-frame navigation | Release the renderer stream after a committed navigation, renderer loss, or destruction. | N/A | A cancelled or in-place navigation does not strand the current renderer. |
+| Temporary team-context transition | Keep the long-lived stream bound to the committed session and environment. | N/A | A transient token is never sent to the stream endpoint. |
+
+## Ordering and recovery invariants
+
+- A response is current only for the resource identity, operation purpose, cursor, and generation
+ that initiated it.
+- Foreground navigation and pagination may supersede background work. Background work never
+ cancels user work; pagination does not discard a queued scope refresh.
+- Repeated invalidations coalesce, but a maximum wait bounds the delay before a trailing pass.
+- An unchanged authoritative preview retains its identity and bytes. A relevant version, content,
+ or metadata change uses the same generic preview reload boundary for every preview type.
+- Transient failures never prove revocation. Only authoritative deletion or 403/404 purges the
+ affected resource; session-wide 401 follows the authentication-expiry path.
+- Unknown or malformed frames are non-destructive and do not reset reconnect backoff.
+- User event delivery must not disclose unauthorized resource identity or change timing.
+
+## Scope
+
+The contract applies to GFS consumers and is reusable for future entity types. Shared File System
+(SFS) is explicitly outside this feature's scope.