@coasys/ad4m 0.12.0-rc1-dev.1 → 0.12.0-rc1-dev.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/jest.config.js +4 -4
- package/lib/index.cjs +5999 -6046
- package/lib/index.js +5977 -6040
- package/lib/src/Ad4mClient.d.ts +16 -9
- package/lib/src/Ad4mClient.js +25 -46
- package/lib/src/Ad4mClient.test.d.ts +1 -0
- package/lib/src/Ad4mClient.test.js +1204 -0
- package/lib/src/Literal.d.ts +2 -1
- package/lib/src/Literal.js +35 -38
- package/lib/src/Literal.test.d.ts +1 -0
- package/lib/src/Literal.test.js +41 -0
- package/lib/src/SmartLiteral.d.ts +2 -1
- package/lib/src/SmartLiteral.js +15 -30
- package/lib/src/agent/AgentClient.d.ts +4 -1
- package/lib/src/agent/AgentClient.js +99 -79
- package/lib/src/ai/AIClient.d.ts +2 -1
- package/lib/src/ai/AIClient.js +220 -224
- package/lib/src/expression/ExpressionClient.d.ts +1 -1
- package/lib/src/expression/ExpressionClient.js +86 -73
- package/lib/src/index.d.ts +1 -1
- package/lib/src/index.js +1 -1
- package/lib/src/language/LanguageClient.d.ts +1 -1
- package/lib/src/language/LanguageClient.js +52 -52
- package/lib/src/model/Ad4mModel.d.ts +157 -937
- package/lib/src/model/Ad4mModel.js +212 -2799
- package/lib/src/model/Ad4mModel.test.js +1002 -561
- package/lib/src/model/decorators.d.ts +94 -426
- package/lib/src/model/decorators.js +333 -741
- package/lib/src/model/mutation.d.ts +81 -0
- package/lib/src/model/mutation.js +317 -0
- package/lib/src/model/parentUtils.d.ts +32 -0
- package/lib/src/model/parentUtils.js +64 -0
- package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
- package/lib/src/model/prolog/generatePrologFacts.js +139 -0
- package/lib/src/model/prolog/index.d.ts +1 -0
- package/lib/src/model/prolog/index.js +1 -0
- package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
- package/lib/src/model/query/ModelQueryBuilder.js +115 -0
- package/lib/src/model/query/QueryBuilder.d.ts +101 -0
- package/lib/src/model/query/QueryBuilder.js +193 -0
- package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
- package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
- package/lib/src/model/query/fetchInstance.d.ts +24 -0
- package/lib/src/model/query/fetchInstance.js +144 -0
- package/lib/src/model/query/hydration.d.ts +54 -0
- package/lib/src/model/query/hydration.js +214 -0
- package/lib/src/model/query/operations.d.ts +59 -0
- package/lib/src/model/query/operations.js +384 -0
- package/lib/src/model/query/snapshot.d.ts +59 -0
- package/lib/src/model/query/snapshot.js +106 -0
- package/lib/src/model/query/surrealCompiler.d.ts +42 -0
- package/lib/src/model/query/surrealCompiler.js +304 -0
- package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
- package/lib/src/model/schema/fromJSONSchema.js +264 -0
- package/lib/src/model/schema/metadata.d.ts +15 -0
- package/lib/src/model/schema/metadata.js +112 -0
- package/lib/src/model/subscription.d.ts +47 -0
- package/lib/src/model/subscription.js +231 -0
- package/lib/src/model/transaction.d.ts +27 -0
- package/lib/src/model/transaction.js +32 -0
- package/lib/src/model/types.d.ts +195 -0
- package/lib/src/model/types.js +8 -0
- package/lib/src/model/util.js +7 -7
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
- package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
- package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
- package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveClient.js +316 -240
- package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
- package/lib/src/perspectives/PerspectiveProxy.js +803 -444
- package/lib/src/runtime/RuntimeClient.d.ts +5 -1
- package/lib/src/runtime/RuntimeClient.js +412 -238
- package/lib/src/shacl/SHACLFlow.test.js +164 -105
- package/lib/src/shacl/SHACLShape.d.ts +17 -3
- package/lib/src/shacl/SHACLShape.js +127 -90
- package/lib/src/shacl/SHACLShape.test.js +244 -176
- package/lib/src/utils.d.ts +8 -0
- package/lib/src/utils.js +21 -7
- package/package.json +8 -13
- package/src/Ad4mClient.test.ts +1564 -1315
- package/src/Ad4mClient.ts +55 -54
- package/src/Literal.test.ts +45 -26
- package/src/Literal.ts +82 -66
- package/src/SmartLiteral.ts +74 -58
- package/src/agent/AgentClient.ts +144 -99
- package/src/ai/AIClient.ts +409 -359
- package/src/expression/ExpressionClient.ts +142 -96
- package/src/index.ts +1 -1
- package/src/language/LanguageClient.ts +137 -113
- package/src/model/Ad4mModel.test.ts +1128 -647
- package/src/model/Ad4mModel.ts +485 -3249
- package/src/model/IMPROVEMENTS.md +482 -0
- package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
- package/src/model/README.md +317 -0
- package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
- package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
- package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
- package/src/model/decorators.ts +689 -1046
- package/src/model/mutation.ts +461 -0
- package/src/model/parentUtils.ts +91 -0
- package/src/model/prolog/generatePrologFacts.ts +176 -0
- package/src/model/prolog/index.ts +1 -0
- package/src/model/query/ModelQueryBuilder.ts +173 -0
- package/src/model/query/fetchInstance.ts +181 -0
- package/src/model/query/hydration.ts +273 -0
- package/src/model/query/operations.ts +510 -0
- package/src/model/query/snapshot.ts +126 -0
- package/src/model/query/surrealCompiler.ts +376 -0
- package/src/model/schema/fromJSONSchema.ts +411 -0
- package/src/model/schema/metadata.ts +148 -0
- package/src/model/subscription.ts +307 -0
- package/src/model/transaction.ts +60 -0
- package/src/model/types.ts +207 -0
- package/src/model/util.ts +47 -48
- package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
- package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
- package/src/perspectives/PerspectiveClient.ts +779 -540
- package/src/perspectives/PerspectiveProxy.ts +2860 -2053
- package/src/runtime/RuntimeClient.ts +775 -476
- package/src/shacl/SHACLFlow.test.ts +196 -129
- package/src/shacl/SHACLShape.test.ts +284 -190
- package/src/shacl/SHACLShape.ts +225 -172
- package/src/utils.ts +31 -17
- package/tsconfig.json +9 -10
- package/src/model/Subject.ts +0 -159
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
# Ad4mModel Subscription Strategy
|
|
2
|
+
|
|
3
|
+
## Background
|
|
4
|
+
|
|
5
|
+
There are two distinct subscription systems in ad4m that need to be understood separately:
|
|
6
|
+
|
|
7
|
+
1. **Prolog query subscriptions** — `perspective.subscribeInfer(query)` → `QuerySubscriptionProxy` → `perspectiveQuerySubscription` GQL subscription. Used for live Prolog inference. **Actively used, not touched.**
|
|
8
|
+
2. **SurrealDB query subscriptions (server-push)** — `perspective.subscribeSurrealDB(query)` → `QuerySubscriptionProxy (isSurrealDB=true)` → `perspectiveSubscribeSurrealQuery` mutation → Rust server-side re-query loop → pubsub push → `perspectiveQuerySubscription` GQL subscription. **This is the old system being replaced.**
|
|
9
|
+
|
|
10
|
+
`Ad4mModel.subscribe()` is the new system that supersedes #2 entirely.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## The Old Architecture (Server-Push)
|
|
15
|
+
|
|
16
|
+
When a consumer called `perspective.subscribeSurrealDB(query)`, this is what happened:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Client Rust Executor
|
|
20
|
+
────── ─────────────
|
|
21
|
+
subscribeSurrealDB(query)
|
|
22
|
+
→ perspectiveSubscribeSurrealQuery mutation ──────────→ subscribe_and_query_surreal()
|
|
23
|
+
runs query immediately
|
|
24
|
+
inserts SurrealSubscribedQuery {
|
|
25
|
+
query, last_result,
|
|
26
|
+
last_keepalive: Instant::now(),
|
|
27
|
+
user_email,
|
|
28
|
+
}
|
|
29
|
+
← { subscriptionId, initialResult } ←────────────────
|
|
30
|
+
|
|
31
|
+
opens perspectiveQuerySubscription WS ──────────────→ (GQL subscription stream)
|
|
32
|
+
|
|
33
|
+
[every 30s]
|
|
34
|
+
→ perspectiveKeepAliveSurrealQuery ───────────────────→ query.last_keepalive = Instant::now()
|
|
35
|
+
|
|
36
|
+
[on any link change in perspective]
|
|
37
|
+
trigger_surreal_subscription_check = true
|
|
38
|
+
surreal_subscription_cleanup_loop wakes up
|
|
39
|
+
for each SurrealSubscribedQuery:
|
|
40
|
+
re-runs SurrealQL query
|
|
41
|
+
if result changed:
|
|
42
|
+
publishes to PERSPECTIVE_QUERY_SUBSCRIPTION_TOPIC
|
|
43
|
+
|
|
44
|
+
← perspectiveQuerySubscription fires ←───────────────
|
|
45
|
+
|
|
46
|
+
[on dispose]
|
|
47
|
+
→ perspectiveDisposeSurrealQuerySubscription ─────────→ removes from HashMap
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**Problems:**
|
|
51
|
+
|
|
52
|
+
- **Server-side state accumulation**: every active subscription is a `SurrealSubscribedQuery` entry in a `HashMap<String, SurrealSubscribedQuery>` inside `PerspectiveInstance`. The Rust process holds this state indefinitely until the client explicitly disposes or the keepalive times out.
|
|
53
|
+
- **Keepalive fragility**: if the client crashes, navigates away, or loses connectivity, the subscription leaks until the 30s timeout fires and the cleanup loop evicts it. During that window the server keeps re-running SurrealQL on every link change for a client that isn't listening.
|
|
54
|
+
- **Cleanup loop complexity**: `surreal_subscription_cleanup_loop`, `check_surreal_subscribed_queries`, `trigger_surreal_subscription_check`, `keepalive_surreal_query` — ~150 lines of Rust dedicated purely to managing lifecycle of a feature that can be eliminated.
|
|
55
|
+
- **Polling semantics hidden behind push API**: despite the push appearance, the Rust loop re-runs the full query on every link change. For large perspectives with many subscriptions, this is N query executions per link write where N = number of active subscriptions. No batching, no predicate filtering before re-query.
|
|
56
|
+
- **Round-trip latency for every update**: link change → Rust detects → re-queries SurrealDB → pubsub → WS → client. The client has the SurrealDB connection anyway and could have queried directly.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## The New Architecture (Client-Side)
|
|
61
|
+
|
|
62
|
+
`Ad4mModel.subscribe()` uses `PerspectiveProxy.addListener('link-added', ...)` and `addListener('link-removed', ...)`, which are backed by the existing `perspectiveLinkAdded` / `perspectiveLinkRemoved` GraphQL subscriptions — persistent WebSocket streams that already exist on every `PerspectiveProxy` instance.
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
Client (PerspectiveProxy + createSubscription) Rust Executor
|
|
66
|
+
────────────────────────────────────────── ─────────────
|
|
67
|
+
Ad4mModel.subscribe(perspective, options, cb)
|
|
68
|
+
|
|
69
|
+
registers listener on perspectiveLinkAdded/Removed
|
|
70
|
+
(these WS subscriptions already exist — no new
|
|
71
|
+
connections opened)
|
|
72
|
+
|
|
73
|
+
runs initial findAll() immediately ──────────────────→ SurrealQL query
|
|
74
|
+
← results ←─────────────────────────────────────────
|
|
75
|
+
|
|
76
|
+
invokes cb(results) immediately
|
|
77
|
+
|
|
78
|
+
[on any link change]
|
|
79
|
+
perspectiveLinkAdded fires on WS ──→
|
|
80
|
+
checkPredicateRelevance(link, metadata)
|
|
81
|
+
(is this predicate used by this model?)
|
|
82
|
+
if relevant:
|
|
83
|
+
re-runs findAll() ───────────────────────────────→ SurrealQL query
|
|
84
|
+
← results ←─────────────────────────────────────
|
|
85
|
+
invokes cb(results)
|
|
86
|
+
|
|
87
|
+
[on unsubscribe()]
|
|
88
|
+
removes listener from PerspectiveProxy arrays
|
|
89
|
+
(no server call needed — no server state to clean up)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**Properties:**
|
|
93
|
+
|
|
94
|
+
- **Zero server state**: no Rust HashMap entries, no keepalive, no cleanup loop, no timeout
|
|
95
|
+
- **No extra connections**: piggybacks on the link-event WS subscriptions that `PerspectiveProxy` already maintains for every perspective
|
|
96
|
+
- **Client controls re-query**: the debounce and predicate relevance check happen in the same process as the caller — no round-trip before deciding whether to re-query
|
|
97
|
+
- **Composable with IncludeMap**: `findAll()` with `include` runs multiple SurrealDB queries client-side. The old system had no concept of includes — it ran a single flat query and the client would have needed to hydrate separately anyway
|
|
98
|
+
- **Correct failure mode**: if the client disconnects, the listener is garbage-collected with the `PerspectiveProxy`. There is nothing to clean up on the server.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Multi-User Node Compatibility
|
|
103
|
+
|
|
104
|
+
This was the primary concern when evaluating whether the client-side approach was safe to adopt.
|
|
105
|
+
|
|
106
|
+
### How multi-user nodes actually work
|
|
107
|
+
|
|
108
|
+
Ad4m's multi-user node is **not** a stateless HTTP server. Every user connects via their own **persistent WebSocket connection** to the same executor process. Authentication is via JWT token containing `user_email`, resolved by `AgentContext::from_auth_token()`.
|
|
109
|
+
|
|
110
|
+
The `perspectiveLinkAdded` subscription resolver in Rust already handles multi-user isolation:
|
|
111
|
+
|
|
112
|
+
```rust
|
|
113
|
+
// subscription_resolvers.rs
|
|
114
|
+
async fn perspective_link_added(..., uuid: String) -> ... {
|
|
115
|
+
// 1. Verify the user's token grants access to this perspective
|
|
116
|
+
let user_email = user_email_from_token(context.auth_token.clone());
|
|
117
|
+
if !can_access_perspective(&user_email, &handle) {
|
|
118
|
+
return Err("Access denied");
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
// 2. Filter pubsub events by "uuid|agent_did"
|
|
122
|
+
// Each user's WS only receives link events for perspectives they own/can access
|
|
123
|
+
let filter = get_agent_did_filter(context.auth_token.clone(), ...);
|
|
124
|
+
subscribe_and_process::<PerspectiveLinkWithOwner>(pubsub, topic, filter).await
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Consequence:** when `Ad4mModel.subscribe()` attaches a listener via `addListener('link-added', cb)`, that listener is only triggered by link events that have already passed the `uuid|agent_did` filter on the server. The access control that the old server-push system had to re-implement on `SurrealSubscribedQuery.user_email` is inherited for free from the link-event WS subscription.
|
|
129
|
+
|
|
130
|
+
### Comparison
|
|
131
|
+
|
|
132
|
+
| Concern | Old server-push | New client-side |
|
|
133
|
+
| ---------------------------- | -------------------------------------------------- | ------------------------------------------- |
|
|
134
|
+
| Works with multi-user nodes | ✅ (explicit `user_email` on subscription state) | ✅ (inherits WS-level DID filter) |
|
|
135
|
+
| Access control correctness | ⚠️ race window between link event and cleanup loop | ✅ no race — filter applied at event source |
|
|
136
|
+
| Requires persistent WS | ✅ (for keepalive) | ✅ (for link-event stream) |
|
|
137
|
+
| Works with HTTP-only (no WS) | ✅ keepalive via polling | ❌ (see Future section) |
|
|
138
|
+
|
|
139
|
+
Both approaches require a persistent WebSocket. The new approach is not weaker — it has the same transport requirement but fewer moving parts.
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## Shared Subscription Registry (`createSubscription`)
|
|
144
|
+
|
|
145
|
+
A naive client-side implementation would create one `addListener` call per `Ad4mModel.subscribe()` call. If 10 React components each subscribe to `Post.subscribe(perspective, { where: { published: true } }, cb)`, that's 10 independent listeners each firing a SurrealDB query on every link change.
|
|
146
|
+
|
|
147
|
+
`createSubscription()` in `subscription.ts` prevents this via a shared registry:
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
WeakMap<PerspectiveProxy, Map<queryFingerprint, SubscriptionEntry>>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- **Same query + same perspective** → single shared `SubscriptionEntry` with one listener
|
|
154
|
+
- All 10 components share that one listener; only one SurrealDB query fires per link change
|
|
155
|
+
- When the last subscriber calls `unsubscribe()`, the `SubscriptionEntry` is torn down and the listener removed
|
|
156
|
+
- `stableQueryKey(query)` produces a deterministic fingerprint from the `Query<T>` object (JSON-stable, handles object key ordering)
|
|
157
|
+
- Late subscribers (attaching after the first result has arrived) immediately receive the cached result, then receive live updates — no initial re-query
|
|
158
|
+
|
|
159
|
+
This registry is the reason the client-side approach scales well for typical application use cases (multiple UI components observing the same model).
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Debounce
|
|
164
|
+
|
|
165
|
+
Rapid writes — e.g. a transaction writing 20 links at once — would trigger 20 re-queries without debouncing. `SubscribeOptions.debounce` (default: configurable, recommended 100–300ms for UI) collapses the burst into a single re-query after the last event.
|
|
166
|
+
|
|
167
|
+
Debounce is on `subscribe()` options, not on `Query<T>`, because it's a delivery concern not a data concern. `findAll()` is unaffected.
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Predicate Relevance Check
|
|
172
|
+
|
|
173
|
+
Before re-running a query, `createSubscription` checks whether the changed link's predicate is one that the model cares about. This is a fast in-memory check against `ModelMetadata.properties` and `ModelMetadata.relations` predicate lists. If the link change is for an unrelated predicate (e.g. a `rdf://comment` link changing when you're subscribed to `Post` which uses `rdf://title` and `flux://content`), no query is issued.
|
|
174
|
+
|
|
175
|
+
This is a significant optimisation in busy perspectives with many concurrent model types.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Future Scaling Path
|
|
180
|
+
|
|
181
|
+
The current approach has one real limitation: it requires a persistent WebSocket connection between each client and the executor. This is fine for the current deployment model (Electron app, `we` multi-user node, ad4m-connect). It would not work for a future hypothetical HTTP-only API.
|
|
182
|
+
|
|
183
|
+
**If that becomes necessary, the correct path is SurrealDB native `LIVE SELECT`**, not the old polling loop:
|
|
184
|
+
|
|
185
|
+
```sql
|
|
186
|
+
-- SurrealDB native live query (available today)
|
|
187
|
+
LIVE SELECT * FROM link WHERE predicate = 'rdf://title';
|
|
188
|
+
-- SurrealDB pushes a diff to the connection on every matching write
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
SurrealDB's native live queries eliminate the server-side polling loop entirely — the database itself pushes deltas. The Rust executor would subscribe to relevant `LIVE SELECT` results and push them via pubsub, which is a much cleaner server-push implementation than re-running full queries on every link change.
|
|
192
|
+
|
|
193
|
+
This is a future item, not a current concern. The client-side approach is correct for all current deployment targets.
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## AI Agents via MCP — Why This Is Not a Problem
|
|
198
|
+
|
|
199
|
+
AI agents interacting with AD4M through a Model Context Protocol server are a **request-response client**, not a reactive subscriber. The concern — that removing the server-push SurrealDB system breaks MCP agent access — does not hold.
|
|
200
|
+
|
|
201
|
+
### What MCP agents actually do
|
|
202
|
+
|
|
203
|
+
Every MCP tool call is a discrete invocation:
|
|
204
|
+
|
|
205
|
+
```
|
|
206
|
+
Agent → MCP tool: listPosts(perspectiveId, { where: { status: "published" } })
|
|
207
|
+
MCP server → Ad4mModel.findAll(perspective, { where: { status: "published" } })
|
|
208
|
+
→ SurrealQL query → results
|
|
209
|
+
MCP tool → Agent: [{ id, title, ... }, ...]
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
This is a plain `findAll()` call. Subscriptions never enter the picture. The agent queries when it needs data and receives an answer. There is no persistent listener to maintain, no keepalive to send, and nothing that requires the server-push infrastructure we deleted.
|
|
213
|
+
|
|
214
|
+
### The right MCP server design
|
|
215
|
+
|
|
216
|
+
An MCP server wrapping AD4M should be a **long-running process** that maintains a persistent `PerspectiveProxy` connection to the executor — the same as any other AD4M client (Flux, `we`, ad4m-connect). This means:
|
|
217
|
+
|
|
218
|
+
- The WS connection for `perspectiveLinkAdded` / `perspectiveLinkRemoved` already exists
|
|
219
|
+
- If a tool needs to watch for changes (e.g., `waitForNewMessage`), `Ad4mModel.subscribe()` works correctly — it piggybacks on that existing WS stream
|
|
220
|
+
- `findAll()` tool calls are pure query → response, no subscription required
|
|
221
|
+
|
|
222
|
+
A **stateless per-request** MCP server (Lambda-style, new connection per call) would make `Ad4mModel.subscribe()` pointless — a subscription that fires once and is then GC'd is just `findAll()`. But that design would have been equally broken with the old server-push system: the keepalive would never arrive, the `SurrealSubscribedQuery` entry would linger for 30 seconds, and the agent would have received zero change notifications anyway.
|
|
223
|
+
|
|
224
|
+
### The old server-push was actually worse for agents
|
|
225
|
+
|
|
226
|
+
An MCP server implementing "watch for changes" via the old `subscribeSurrealDB()` would have needed to:
|
|
227
|
+
|
|
228
|
+
1. Call `perspectiveSubscribeSurrealQuery` mutation and store the `subscriptionId`
|
|
229
|
+
2. Open a `perspectiveQuerySubscription` WebSocket stream to receive push updates
|
|
230
|
+
3. Send `perspectiveKeepAliveSurrealQuery` every 30 seconds or lose the subscription
|
|
231
|
+
4. Explicitly call `perspectiveDisposeSurrealQuerySubscription` on cleanup
|
|
232
|
+
|
|
233
|
+
That's four separate concerns, a persistent timer, and a resource leak risk if any step fails. The client-side approach needs none of it — attaching a listener and calling `unsubscribe()` is the entire API.
|
|
234
|
+
|
|
235
|
+
### If the MCP server is stateless (HTTP-only)
|
|
236
|
+
|
|
237
|
+
If the MCP server is genuinely stateless and has no persistent connection to the executor, the correct pattern for agents is **polling** — the agent re-calls the query tool whenever it needs fresh data. This is a deliberate choice that matches how LLM agents actually work in practice: an agent re-queries between reasoning steps, not via a background push stream.
|
|
238
|
+
|
|
239
|
+
The "HTTP-only / no subscriptions" limitation row in the summary table below applies equally to a stateless MCP server. The solution remains the same: SurrealDB native `LIVE SELECT` if a server-push path is ever needed for stateless HTTP clients.
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## Prolog Subscriptions (`subscribeInfer`) — Why They Stay Server-Side
|
|
244
|
+
|
|
245
|
+
### Are Prolog subscriptions still needed?
|
|
246
|
+
|
|
247
|
+
Yes. The SHACL migration (PR #654) disabled Prolog for the _model system's internal query pipeline_ — `Ad4mModel.findAll()` no longer generates Prolog queries, and the SDNA pipeline no longer stores model definitions as Prolog facts. But Prolog is explicitly preserved as an **opt-in tool for hand-crafted queries** — recursive graph traversal, multi-hop reachability, constraint solving — where it has genuine expressive advantages over SurrealQL. `subscribeInfer` is the live/reactive version of `infer()` for those use cases, and it is actively tested in `tests/js/tests/perspective.ts`.
|
|
248
|
+
|
|
249
|
+
### Why server-side is correct for Prolog (and not just a legacy holdover)
|
|
250
|
+
|
|
251
|
+
The critical difference from SurrealDB: **there is no Prolog engine on the client**. SurrealDB queries are sent over the same Apollo WS connection and executed against a process the client shares. Prolog inference requires a SWI-Prolog (or similar) engine with the perspective's triple facts loaded — that engine lives entirely inside the Rust executor.
|
|
252
|
+
|
|
253
|
+
The `PrologService` in `rust-executor` maintains a `SimpleEngine` struct per perspective per user, containing two dedicated `PrologEngine` instances:
|
|
254
|
+
|
|
255
|
+
- `query_engine` — for ad-hoc `infer()` calls
|
|
256
|
+
- `subscription_engine` — a **separate, dedicated engine kept warm specifically for subscription re-runs**
|
|
257
|
+
|
|
258
|
+
When `subscribeInfer(query)` registers a subscription, the Rust executor:
|
|
259
|
+
|
|
260
|
+
1. Calls `ensure_engine_updated()` to load/refresh the perspective's Prolog facts into the `subscription_engine`
|
|
261
|
+
2. Runs the query immediately on that warm engine for the initial result
|
|
262
|
+
3. On every subsequent link change, `check_subscribed_queries()` re-runs the query on the **already-warm** `subscription_engine` — no re-initialization, no facts reload
|
|
263
|
+
|
|
264
|
+
This dedicated warm engine is important. Loading a perspective's triple base into a fresh Prolog engine is non-trivial — the subscription pool exists specifically to amortize that cost across many re-runs.
|
|
265
|
+
|
|
266
|
+
### Could you do Prolog subscriptions client-side anyway?
|
|
267
|
+
|
|
268
|
+
Technically you could mirror the `Ad4mModel.subscribe()` pattern for Prolog:
|
|
269
|
+
|
|
270
|
+
```typescript
|
|
271
|
+
// Hypothetical client-side Prolog subscription
|
|
272
|
+
addListener("link-added", async () => {
|
|
273
|
+
const result = await perspective.infer(query);
|
|
274
|
+
callback(result);
|
|
275
|
+
});
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
This would work, but it is _worse_ than the server-push approach for Prolog specifically:
|
|
279
|
+
|
|
280
|
+
| Factor | Server-push (current) | Client-side `infer()` on each change |
|
|
281
|
+
| -------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------- |
|
|
282
|
+
| Engine warm-up cost | Paid once, engine stays warm | Paid on every re-run (or via separate keep-warm mechanism) |
|
|
283
|
+
| Filtered pool reference counting | `subscription_ended()` decrements pool refs correctly | Never decremented — pool resources would leak |
|
|
284
|
+
| Fact freshness | Server coordinates fact update → re-query atomically | Race: `infer()` may arrive before facts are updated for the new link |
|
|
285
|
+
| `run_query_smart` routing | Dedicated `subscription_engine` path | Goes through general `query_engine`, competing with ad-hoc queries |
|
|
286
|
+
|
|
287
|
+
The server-push model for Prolog is _architecturally motivated_, not just legacy. The server has context the client doesn't: it knows when the fact base has been updated, it has a pre-warmed engine, and it can reference-count pool resources correctly.
|
|
288
|
+
|
|
289
|
+
### The fundamental asymmetry
|
|
290
|
+
|
|
291
|
+
| | SurrealDB query subscription | Prolog query subscription |
|
|
292
|
+
| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
|
|
293
|
+
| Engine lives... | Client can connect to same SurrealDB | Server only (SWI-Prolog in Rust process) |
|
|
294
|
+
| Re-query cost | Stateless SQL-like query, negligible warm-up | Prolog engine init + fact loading, significant |
|
|
295
|
+
| Warm state benefit | None — each query is independent | High — `subscription_engine` stays loaded |
|
|
296
|
+
| Client can re-query directly? | ✅ Yes, same result, no overhead | ❌ No — must call `infer()` which goes to server anyway |
|
|
297
|
+
| Server-side advantage | None | Warm engine, atomic fact-update coordination, pool lifecycle |
|
|
298
|
+
|
|
299
|
+
**Conclusion:** `subscribeInfer` staying server-side is the _correct_ architecture for Prolog, for the same reasons `Ad4mModel.subscribe()` moving client-side is the correct architecture for SurrealDB. The asymmetry isn't inconsistency — it reflects the fundamentally different nature of the two query engines.
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## Summary
|
|
304
|
+
|
|
305
|
+
| Property | Old server-push | New client-side |
|
|
306
|
+
| ------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------- |
|
|
307
|
+
| Server state per subscription | ✅ HashMap entry + keepalive timer | ❌ none |
|
|
308
|
+
| Keepalive required | ✅ every 30s | ❌ not needed |
|
|
309
|
+
| Cleanup loop on server | ✅ ~150 lines Rust | ❌ deleted |
|
|
310
|
+
| Extra round-trip per update | ✅ link event → server re-query → push | ❌ client re-queries directly |
|
|
311
|
+
| IncludeMap hydration | ❌ server only ran flat query | ✅ full findAll() with includes |
|
|
312
|
+
| Shared registry (N components → 1 listener) | ❌ N server subscriptions | ✅ 1 shared listener |
|
|
313
|
+
| Debounce | ❌ not supported | ✅ configurable |
|
|
314
|
+
| Predicate relevance filtering | ❌ re-queries on every link change | ✅ skips irrelevant predicates |
|
|
315
|
+
| Multi-user node compatible | ✅ | ✅ (inherits WS-level DID filter) |
|
|
316
|
+
| HTTP-only compatible (future) | ✅ | ❌ (SurrealDB LIVE SELECT when needed) |
|
|
317
|
+
| MCP / AI agent compatible | ⚠️ keepalive burden, 4-step lifecycle | ✅ `findAll()` is plain query; `subscribe()` works in long-running MCP server |
|