Live Surface
The fifth of ArcFlow's eight layers. Owns standing queries — queries that an agent installs once and that emit deltas every time the result set changes.
One-sentence disambiguation: Live Surface watches the graph; Event Bus watches what publishers say. If the question is "what changed in my view of the graph?", you want the Live Surface. If the question is "what did the producer say?", you want the Event Bus.
A standing query is the inversion of a one-shot query. Instead of asking "what is true right now?" and getting an answer, an agent declares "keep this answer current" — and the engine emits the additions, removals, and changes as the underlying graph evolves.
Live Surface vs Event Bus — when to use which#
The two layers both produce streams of typed records, which is why they're often conflated. They differ in what the contract is about — a Cypher pattern's result set on one side, a topic name on the other:
| Property | Live Surface | Event Bus |
|---|---|---|
| What you subscribe to | A Cypher pattern's result set | A topic name (or wildcard pattern) |
| Who decides what's emitted | The engine, by observing graph mutations against the pattern | The publisher, by choosing what to send |
| Payload shape | Typed deltas (added / removed rows) — schema matches the RETURN clause | Whatever the publisher published — opaque to the bus |
| When events fire | When a graph mutation changes the pattern's result set | When a publisher calls publish(topic, payload) |
| Canonical question | "What changed in my view of the graph?" | "What did the producer say?" |
| Typical uses | Live dashboards; agent loops watching for new high-confidence facts; replication of derived state | Sensor telemetry; cross-process intent relay; ingest progress notifications; system events like _system.partitions.added |
| Wrong tool when… | The producer wants to send a message that isn't a Cypher result | You want to react to graph changes without writing a publisher |
The same agent often uses both: a standing query observes the graph and emits deltas (Live Surface); a workflow program turns those deltas into outbound notifications on a topic (Event Bus); downstream consumers subscribe to the topic. Same agent, two layers, separate contracts.
What the Live Surface provides#
| Capability | What it does |
|---|---|
CREATE LIVE VIEW | Install a Cypher pattern as a standing query; the engine maintains the result set automatically. |
| Delta stream | Every mutation that changes the view's output produces a typed delta record. |
| Subscription | An agent receives deltas via subscribe / poll / push. |
| Z-set algebra | Adds and removes are tracked through a multiset algebra — composable, deterministic, replayable. |
| Snapshot pinning | A subscriber can pin to a snapshot and replay deltas forward from there. |
Standing queries, always-current#
The Live Surface is built on standing queries — queries that stay installed in the engine and emit deltas as the world changes. What an agent gets is a query that stays current, with a delta stream that says exactly what changed. No polling, no re-running, no stale read.
Why this is its own layer#
Change notification has different concerns from query evaluation:
- The Query Engine compiles one Cypher pattern once. The Live Surface keeps a Cypher pattern resident, maintains its index structures, and re-evaluates only the subset of the result set that the latest mutation could have touched.
- The Event Bus carries arbitrary messages with delivery guarantees. The Live Surface carries query deltas — typed by the Cypher schema of the view.
- The Behavior Engine fires programs in response to events. The Live Surface produces the events that triggers consume.
Keeping these concerns separate lets an agent reason about them independently. A standing query is a contract about a result set; a topic is a contract about a stream of messages; a trigger is a contract about an action.
Why this matters for agents#
An agent that watches a standing query gets two guarantees one-shot queries cannot offer:
- Always-current. The agent never holds a stale read. The view reflects the latest committed state of the graph.
- Just the delta. The agent does not re-process the full result set on every change — only the additions and removals since the last delta.
This is the foundation that makes graph-native pub/sub usable for live agents — observability dashboards, autonomous decision loops, multi-agent coordination.
See also#
- Live Queries — the canonical surface reference + worked examples.
- Sync — using live queries for replication across nodes.
- LIVE Queries — the ArcFlow extension reference.
- Reactive Write-Back Views — combining standing queries with mutation paths.