@coasys/ad4m 0.12.0-rc1-dev.2 → 0.12.0-rc1-dev.3

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.
Files changed (153) hide show
  1. package/jest.config.js +10 -3
  2. package/lib/index.cjs +6872 -5886
  3. package/lib/index.js +6868 -5874
  4. package/lib/src/Ad4mClient.d.ts +9 -16
  5. package/lib/src/Ad4mClient.js +46 -25
  6. package/lib/src/Literal.d.ts +1 -2
  7. package/lib/src/Literal.js +38 -35
  8. package/lib/src/SmartLiteral.d.ts +1 -2
  9. package/lib/src/SmartLiteral.js +30 -15
  10. package/lib/src/agent/AgentClient.d.ts +1 -4
  11. package/lib/src/agent/AgentClient.js +79 -99
  12. package/lib/src/ai/AIClient.d.ts +1 -2
  13. package/lib/src/ai/AIClient.js +224 -220
  14. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  15. package/lib/src/expression/ExpressionClient.js +73 -86
  16. package/lib/src/index.d.ts +1 -1
  17. package/lib/src/index.js +1 -1
  18. package/lib/src/language/LanguageClient.d.ts +1 -1
  19. package/lib/src/language/LanguageClient.js +52 -52
  20. package/lib/src/model/Ad4mModel.d.ts +1351 -144
  21. package/lib/src/model/Ad4mModel.js +3737 -228
  22. package/lib/src/model/Ad4mModel.test.js +522 -979
  23. package/lib/src/model/Subject.d.ts +3 -3
  24. package/lib/src/model/Subject.js +25 -25
  25. package/lib/src/model/decorators.d.ts +444 -100
  26. package/lib/src/model/decorators.js +686 -321
  27. package/lib/src/model/util.d.ts +6 -6
  28. package/lib/src/model/util.js +24 -24
  29. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +1 -5
  30. package/lib/src/neighbourhood/NeighbourhoodClient.js +179 -242
  31. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +1 -2
  32. package/lib/src/neighbourhood/NeighbourhoodProxy.js +28 -13
  33. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +5 -1
  34. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  35. package/lib/src/perspectives/PerspectiveClient.js +240 -316
  36. package/lib/src/perspectives/PerspectiveProxy.d.ts +99 -61
  37. package/lib/src/perspectives/PerspectiveProxy.js +485 -832
  38. package/lib/src/runtime/RuntimeClient.d.ts +1 -5
  39. package/lib/src/runtime/RuntimeClient.js +238 -412
  40. package/lib/src/shacl/SHACLFlow.test.js +105 -164
  41. package/lib/src/shacl/SHACLShape.d.ts +12 -17
  42. package/lib/src/shacl/SHACLShape.js +115 -128
  43. package/lib/src/shacl/SHACLShape.test.js +176 -244
  44. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  45. package/lib/src/shims/type-graphql.d.ts +32 -0
  46. package/lib/src/src/Ad4mClient.d.ts +28 -0
  47. package/lib/src/src/Address.d.ts +1 -0
  48. package/lib/src/src/DID.d.ts +1 -0
  49. package/lib/src/src/Exception.d.ts +7 -0
  50. package/lib/src/src/Literal.d.ts +7 -0
  51. package/lib/src/src/PubSub.d.ts +17 -0
  52. package/lib/src/src/SmartLiteral.d.ts +12 -0
  53. package/lib/src/src/agent/Agent.d.ts +110 -0
  54. package/lib/src/src/agent/AgentClient.d.ts +62 -0
  55. package/lib/src/src/agent/AgentResolver.d.ts +30 -0
  56. package/lib/src/src/agent/AgentStatus.d.ts +8 -0
  57. package/lib/src/src/ai/AIClient.d.ts +32 -0
  58. package/lib/src/src/ai/AIResolver.d.ts +75 -0
  59. package/lib/src/src/ai/Tasks.d.ts +37 -0
  60. package/lib/src/src/buildSchema.d.ts +1 -0
  61. package/lib/src/src/expression/Expression.d.ts +28 -0
  62. package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
  63. package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
  64. package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
  65. package/lib/src/src/index.d.ts +35 -0
  66. package/lib/src/src/jestSetup.d.ts +1 -0
  67. package/lib/src/src/language/Icon.d.ts +4 -0
  68. package/lib/src/src/language/Language.d.ts +206 -0
  69. package/lib/src/src/language/LanguageClient.d.ts +17 -0
  70. package/lib/src/src/language/LanguageContext.d.ts +37 -0
  71. package/lib/src/src/language/LanguageHandle.d.ts +9 -0
  72. package/lib/src/src/language/LanguageMeta.d.ts +35 -0
  73. package/lib/src/src/language/LanguageRef.d.ts +6 -0
  74. package/lib/src/src/language/LanguageResolver.d.ts +19 -0
  75. package/lib/src/src/links/Links.d.ts +39 -0
  76. package/lib/src/src/links/Links.test.d.ts +1 -0
  77. package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
  78. package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
  79. package/lib/src/src/model/Subject.d.ts +25 -0
  80. package/lib/src/src/model/decorators.d.ts +545 -0
  81. package/lib/src/src/model/util.d.ts +12 -0
  82. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
  83. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
  84. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
  85. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  86. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
  87. package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
  88. package/lib/src/src/perspectives/Perspective.d.ts +38 -0
  89. package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
  90. package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
  91. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
  92. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
  93. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
  94. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
  95. package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
  96. package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
  97. package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
  98. package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
  99. package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
  100. package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
  101. package/lib/src/src/typeDefs.d.ts +1 -0
  102. package/lib/src/src/unwrapApolloResult.d.ts +2 -0
  103. package/lib/src/src/utils.d.ts +25 -0
  104. package/lib/src/utils.d.ts +0 -8
  105. package/lib/src/utils.js +7 -21
  106. package/package.json +15 -14
  107. package/src/Ad4mClient.test.ts +1315 -1564
  108. package/src/Ad4mClient.ts +54 -55
  109. package/src/Literal.test.ts +26 -45
  110. package/src/Literal.ts +66 -82
  111. package/src/SmartLiteral.ts +58 -74
  112. package/src/agent/AgentClient.ts +99 -144
  113. package/src/ai/AIClient.ts +359 -409
  114. package/src/expression/ExpressionClient.ts +96 -142
  115. package/src/index.ts +1 -1
  116. package/src/language/LanguageClient.ts +113 -137
  117. package/src/model/Ad4mModel.test.ts +616 -1114
  118. package/src/model/Ad4mModel.ts +4361 -451
  119. package/src/model/Subject.ts +159 -0
  120. package/src/model/decorators.ts +1168 -667
  121. package/src/model/util.ts +54 -53
  122. package/src/neighbourhood/NeighbourhoodClient.ts +266 -392
  123. package/src/neighbourhood/NeighbourhoodProxy.test.ts +7 -3
  124. package/src/neighbourhood/NeighbourhoodProxy.ts +40 -58
  125. package/src/perspectives/PerspectiveClient.ts +540 -779
  126. package/src/perspectives/PerspectiveProxy.ts +2067 -2860
  127. package/src/runtime/RuntimeClient.ts +476 -775
  128. package/src/shacl/SHACLFlow.test.ts +129 -196
  129. package/src/shacl/SHACLShape.test.ts +190 -284
  130. package/src/shacl/SHACLShape.ts +200 -224
  131. package/src/utils.ts +17 -31
  132. package/tsconfig.json +10 -9
  133. package/src/model/IMPROVEMENTS.md +0 -482
  134. package/src/model/PREDICATE_COLLISION_FIX.md +0 -651
  135. package/src/model/README.md +0 -317
  136. package/src/model/SHACL_MUTATION_DECOUPLING.md +0 -356
  137. package/src/model/SUBSCRIPTION_STRATEGY.md +0 -317
  138. package/src/model/TC39_STAGE_3_DECORATORS.md +0 -609
  139. package/src/model/mutation.ts +0 -461
  140. package/src/model/parentUtils.ts +0 -91
  141. package/src/model/prolog/generatePrologFacts.ts +0 -176
  142. package/src/model/prolog/index.ts +0 -1
  143. package/src/model/query/ModelQueryBuilder.ts +0 -173
  144. package/src/model/query/fetchInstance.ts +0 -181
  145. package/src/model/query/hydration.ts +0 -273
  146. package/src/model/query/operations.ts +0 -510
  147. package/src/model/query/snapshot.ts +0 -126
  148. package/src/model/query/surrealCompiler.ts +0 -376
  149. package/src/model/schema/fromJSONSchema.ts +0 -411
  150. package/src/model/schema/metadata.ts +0 -148
  151. package/src/model/subscription.ts +0 -307
  152. package/src/model/transaction.ts +0 -60
  153. package/src/model/types.ts +0 -207
@@ -1,317 +0,0 @@
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 |