@abloatai/ablo 0.35.0 → 0.37.0

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 (622) hide show
  1. package/AGENTS.md +2 -2
  2. package/CHANGELOG.md +71 -1929
  3. package/NOTICE +2 -2
  4. package/README.md +23 -532
  5. package/assets/banner.png +0 -0
  6. package/dist/auth.d.ts +2 -0
  7. package/dist/auth.d.ts.map +1 -0
  8. package/dist/auth.js +2 -0
  9. package/dist/auth.js.map +1 -0
  10. package/dist/client.d.ts +3 -0
  11. package/dist/client.d.ts.map +1 -0
  12. package/dist/client.js +3 -0
  13. package/dist/client.js.map +1 -0
  14. package/dist/coordination.d.ts +2 -0
  15. package/dist/coordination.d.ts.map +1 -0
  16. package/dist/coordination.js +2 -0
  17. package/dist/coordination.js.map +1 -0
  18. package/dist/index.d.ts +3 -112
  19. package/dist/index.d.ts.map +1 -0
  20. package/dist/index.js +3 -161
  21. package/dist/index.js.map +1 -0
  22. package/dist/react.d.ts +4 -0
  23. package/dist/react.d.ts.map +1 -0
  24. package/dist/react.js +3 -0
  25. package/dist/react.js.map +1 -0
  26. package/dist/schema.d.ts +2 -0
  27. package/dist/schema.d.ts.map +1 -0
  28. package/dist/schema.js +2 -0
  29. package/dist/schema.js.map +1 -0
  30. package/dist/server.d.ts +2 -0
  31. package/dist/server.d.ts.map +1 -0
  32. package/dist/server.js +2 -0
  33. package/dist/server.js.map +1 -0
  34. package/dist/source-conformance.d.ts +2 -0
  35. package/dist/source-conformance.d.ts.map +1 -0
  36. package/dist/source-conformance.js +2 -0
  37. package/dist/source-conformance.js.map +1 -0
  38. package/dist/source-drizzle.d.ts +2 -0
  39. package/dist/source-drizzle.d.ts.map +1 -0
  40. package/dist/source-drizzle.js +2 -0
  41. package/dist/source-drizzle.js.map +1 -0
  42. package/dist/source-kysely.d.ts +2 -0
  43. package/dist/source-kysely.d.ts.map +1 -0
  44. package/dist/source-kysely.js +2 -0
  45. package/dist/source-kysely.js.map +1 -0
  46. package/dist/source-next.d.ts +2 -0
  47. package/dist/source-next.d.ts.map +1 -0
  48. package/dist/source-next.js +2 -0
  49. package/dist/source-next.js.map +1 -0
  50. package/dist/source.d.ts +2 -0
  51. package/dist/source.d.ts.map +1 -0
  52. package/dist/source.js +2 -0
  53. package/dist/source.js.map +1 -0
  54. package/dist/wire.d.ts +2 -0
  55. package/dist/wire.d.ts.map +1 -0
  56. package/dist/wire.js +2 -0
  57. package/dist/wire.js.map +1 -0
  58. package/docs/agents.md +2 -2
  59. package/docs/api-keys.md +13 -12
  60. package/docs/api.md +15 -53
  61. package/docs/audit.md +4 -3
  62. package/docs/cli.md +11 -11
  63. package/docs/client-behavior.md +9 -9
  64. package/docs/concurrency-convention.md +28 -42
  65. package/docs/coordination.md +228 -86
  66. package/docs/data-sources.md +5 -5
  67. package/docs/debugging.md +34 -12
  68. package/docs/deployment.md +8 -8
  69. package/docs/examples/agent-human.md +4 -4
  70. package/docs/examples/ai-sdk-tool.md +1 -1
  71. package/docs/examples/existing-python-backend.md +15 -4
  72. package/docs/examples/nextjs.md +27 -6
  73. package/docs/examples/scoped-agent.md +3 -3
  74. package/docs/examples/server-agent.md +2 -2
  75. package/docs/groups.md +57 -3
  76. package/docs/guarantees.md +37 -10
  77. package/docs/how-it-works.md +32 -8
  78. package/docs/idempotency.md +6 -6
  79. package/docs/identity.md +24 -24
  80. package/docs/index.md +8 -8
  81. package/docs/integration-guide.md +38 -16
  82. package/docs/internal/README.md +18 -0
  83. package/docs/internal/agent-fleet-coordination-design.md +171 -0
  84. package/docs/internal/agent-orchestration.md +58 -0
  85. package/docs/internal/commit-identifiers.md +91 -0
  86. package/docs/internal/concurrency-open-decisions.md +37 -0
  87. package/docs/internal/data-source-reverse-channel.md +150 -0
  88. package/docs/internal/per-field-conflict-detection.md +165 -0
  89. package/docs/internal/postgres-replication.md +64 -0
  90. package/docs/internal/serializable-schema.md +119 -0
  91. package/docs/internal/structure.md +32 -0
  92. package/docs/mcp.md +9 -9
  93. package/docs/migration.md +37 -18
  94. package/docs/projects.md +1 -1
  95. package/docs/quickstart.md +2 -2
  96. package/docs/react.md +24 -13
  97. package/docs/schema-contract.md +3 -3
  98. package/docs/sessions.md +91 -37
  99. package/docs/webhooks.md +9 -9
  100. package/examples/README.md +2 -2
  101. package/examples/data-source/README.md +1 -1
  102. package/examples/data-source/ablo-driver.ts +1 -1
  103. package/examples/data-source/customer-server.ts +1 -1
  104. package/examples/data-source/run.ts +1 -1
  105. package/examples/data-source/schema.ts +1 -1
  106. package/examples/quickstart.ts +2 -2
  107. package/llms.txt +12 -12
  108. package/package.json +64 -174
  109. package/dist/BaseSyncedStore.d.ts +0 -823
  110. package/dist/BaseSyncedStore.js +0 -1955
  111. package/dist/Database.d.ts +0 -335
  112. package/dist/Database.js +0 -1500
  113. package/dist/InstanceCache.d.ts +0 -233
  114. package/dist/InstanceCache.js +0 -1164
  115. package/dist/LazyReferenceCollection.d.ts +0 -177
  116. package/dist/LazyReferenceCollection.js +0 -461
  117. package/dist/Model.d.ts +0 -444
  118. package/dist/Model.js +0 -909
  119. package/dist/ModelRegistry.d.ts +0 -221
  120. package/dist/ModelRegistry.js +0 -537
  121. package/dist/NetworkMonitor.d.ts +0 -26
  122. package/dist/NetworkMonitor.js +0 -77
  123. package/dist/RuntimeContext.d.ts +0 -52
  124. package/dist/RuntimeContext.js +0 -80
  125. package/dist/SyncClient.d.ts +0 -551
  126. package/dist/SyncClient.js +0 -2199
  127. package/dist/adapters/alwaysOnline.d.ts +0 -14
  128. package/dist/adapters/alwaysOnline.js +0 -17
  129. package/dist/adapters/inMemoryStorage.d.ts +0 -31
  130. package/dist/adapters/inMemoryStorage.js +0 -110
  131. package/dist/ai-sdk/coordinatedTool.d.ts +0 -120
  132. package/dist/ai-sdk/coordinatedTool.js +0 -134
  133. package/dist/ai-sdk/coordinationContext.d.ts +0 -46
  134. package/dist/ai-sdk/coordinationContext.js +0 -106
  135. package/dist/ai-sdk/index.d.ts +0 -121
  136. package/dist/ai-sdk/index.js +0 -121
  137. package/dist/ai-sdk/wrap.d.ts +0 -65
  138. package/dist/ai-sdk/wrap.js +0 -39
  139. package/dist/auth/index.d.ts +0 -1
  140. package/dist/auth/index.js +0 -8
  141. package/dist/batching/index.d.ts +0 -55
  142. package/dist/batching/index.js +0 -147
  143. package/dist/cli.cjs +0 -288600
  144. package/dist/client/Ablo.d.ts +0 -231
  145. package/dist/client/Ablo.js +0 -149
  146. package/dist/client/abloClient.d.ts +0 -309
  147. package/dist/client/abloClient.js +0 -13
  148. package/dist/client/clientPrelude.d.ts +0 -52
  149. package/dist/client/clientPrelude.js +0 -60
  150. package/dist/client/consoleLogger.d.ts +0 -35
  151. package/dist/client/consoleLogger.js +0 -44
  152. package/dist/client/coreClient.d.ts +0 -60
  153. package/dist/client/coreClient.js +0 -118
  154. package/dist/client/createInternalComponents.d.ts +0 -46
  155. package/dist/client/createInternalComponents.js +0 -92
  156. package/dist/client/createModelProxy.d.ts +0 -228
  157. package/dist/client/createModelProxy.js +0 -818
  158. package/dist/client/humans.d.ts +0 -48
  159. package/dist/client/humans.js +0 -52
  160. package/dist/client/modelRegistration.d.ts +0 -10
  161. package/dist/client/modelRegistration.js +0 -312
  162. package/dist/client/options.d.ts +0 -461
  163. package/dist/client/options.js +0 -7
  164. package/dist/client/reactiveEngine.d.ts +0 -48
  165. package/dist/client/reactiveEngine.js +0 -910
  166. package/dist/client/resourceTypes.d.ts +0 -12
  167. package/dist/client/resourceTypes.js +0 -10
  168. package/dist/client/schemaConfig.d.ts +0 -44
  169. package/dist/client/schemaConfig.js +0 -185
  170. package/dist/client/validateAbloOptions.d.ts +0 -42
  171. package/dist/client/validateAbloOptions.js +0 -43
  172. package/dist/client/wsMutationExecutor.d.ts +0 -27
  173. package/dist/client/wsMutationExecutor.js +0 -72
  174. package/dist/context.d.ts +0 -29
  175. package/dist/context.js +0 -58
  176. package/dist/coordination/ClaimLog.d.ts +0 -26
  177. package/dist/coordination/ClaimLog.js +0 -32
  178. package/dist/coordination/index.d.ts +0 -1
  179. package/dist/coordination/index.js +0 -8
  180. package/dist/core/DatabaseManager.d.ts +0 -105
  181. package/dist/core/DatabaseManager.js +0 -387
  182. package/dist/core/QueryProcessor.d.ts +0 -75
  183. package/dist/core/QueryProcessor.js +0 -255
  184. package/dist/core/QueryView.d.ts +0 -79
  185. package/dist/core/QueryView.js +0 -218
  186. package/dist/core/StoreManager.d.ts +0 -112
  187. package/dist/core/StoreManager.js +0 -302
  188. package/dist/core/ViewRegistry.d.ts +0 -20
  189. package/dist/core/ViewRegistry.js +0 -55
  190. package/dist/core/index.d.ts +0 -33
  191. package/dist/core/index.js +0 -48
  192. package/dist/core/openIDBWithTimeout.d.ts +0 -65
  193. package/dist/core/openIDBWithTimeout.js +0 -153
  194. package/dist/core/queryUtils.d.ts +0 -45
  195. package/dist/core/queryUtils.js +0 -69
  196. package/dist/core/storeContract.d.ts +0 -145
  197. package/dist/core/storeContract.js +0 -12
  198. package/dist/docs/catalog.d.ts +0 -72
  199. package/dist/docs/catalog.js +0 -227
  200. package/dist/docs/index.d.ts +0 -10
  201. package/dist/docs/index.js +0 -10
  202. package/dist/environment.d.ts +0 -1
  203. package/dist/environment.js +0 -8
  204. package/dist/interfaces/index.d.ts +0 -311
  205. package/dist/interfaces/index.js +0 -9
  206. package/dist/keys/index.d.ts +0 -1
  207. package/dist/keys/index.js +0 -8
  208. package/dist/mutators/RecordingMutation.d.ts +0 -36
  209. package/dist/mutators/RecordingMutation.js +0 -182
  210. package/dist/mutators/Transaction.d.ts +0 -40
  211. package/dist/mutators/Transaction.js +0 -58
  212. package/dist/mutators/UndoManager.d.ts +0 -258
  213. package/dist/mutators/UndoManager.js +0 -658
  214. package/dist/mutators/defineMutators.d.ts +0 -60
  215. package/dist/mutators/defineMutators.js +0 -18
  216. package/dist/mutators/inverseOp.d.ts +0 -126
  217. package/dist/mutators/inverseOp.js +0 -71
  218. package/dist/mutators/mutateActions.d.ts +0 -45
  219. package/dist/mutators/mutateActions.js +0 -105
  220. package/dist/mutators/readerActions.d.ts +0 -33
  221. package/dist/mutators/readerActions.js +0 -57
  222. package/dist/mutators/undoApply.d.ts +0 -51
  223. package/dist/mutators/undoApply.js +0 -117
  224. package/dist/policy/index.d.ts +0 -21
  225. package/dist/policy/index.js +0 -20
  226. package/dist/query/client.d.ts +0 -61
  227. package/dist/query/client.js +0 -137
  228. package/dist/query/types.d.ts +0 -85
  229. package/dist/query/types.js +0 -16
  230. package/dist/react/AbloProvider.d.ts +0 -230
  231. package/dist/react/AbloProvider.js +0 -455
  232. package/dist/react/ClientSideSuspense.d.ts +0 -36
  233. package/dist/react/ClientSideSuspense.js +0 -17
  234. package/dist/react/DefaultFallback.d.ts +0 -24
  235. package/dist/react/DefaultFallback.js +0 -43
  236. package/dist/react/context.d.ts +0 -55
  237. package/dist/react/context.js +0 -29
  238. package/dist/react/index.d.ts +0 -61
  239. package/dist/react/index.js +0 -66
  240. package/dist/react/internalContext.d.ts +0 -33
  241. package/dist/react/internalContext.js +0 -3
  242. package/dist/react/useAblo.d.ts +0 -75
  243. package/dist/react/useAblo.js +0 -102
  244. package/dist/react/useCurrentUserId.d.ts +0 -22
  245. package/dist/react/useCurrentUserId.js +0 -34
  246. package/dist/react/useErrorListener.d.ts +0 -20
  247. package/dist/react/useErrorListener.js +0 -38
  248. package/dist/react/useMutationFailureListener.d.ts +0 -26
  249. package/dist/react/useMutationFailureListener.js +0 -38
  250. package/dist/react/useMutators.d.ts +0 -56
  251. package/dist/react/useMutators.js +0 -84
  252. package/dist/react/useReactive.d.ts +0 -35
  253. package/dist/react/useReactive.js +0 -123
  254. package/dist/react/useSyncStatus.d.ts +0 -59
  255. package/dist/react/useSyncStatus.js +0 -76
  256. package/dist/react/useUndoScope.d.ts +0 -34
  257. package/dist/react/useUndoScope.js +0 -81
  258. package/dist/schema/coordination.d.ts +0 -112
  259. package/dist/schema/coordination.js +0 -129
  260. package/dist/schema/ddl.d.ts +0 -97
  261. package/dist/schema/ddl.js +0 -491
  262. package/dist/schema/ddlLock.d.ts +0 -35
  263. package/dist/schema/ddlLock.js +0 -46
  264. package/dist/schema/diff.d.ts +0 -225
  265. package/dist/schema/diff.js +0 -289
  266. package/dist/schema/generate.d.ts +0 -19
  267. package/dist/schema/generate.js +0 -86
  268. package/dist/schema/index.d.ts +0 -41
  269. package/dist/schema/index.js +0 -76
  270. package/dist/schema/queries.d.ts +0 -201
  271. package/dist/schema/queries.js +0 -144
  272. package/dist/schema/select.d.ts +0 -40
  273. package/dist/schema/select.js +0 -87
  274. package/dist/schema/serialize.d.ts +0 -115
  275. package/dist/schema/serialize.js +0 -262
  276. package/dist/schema/sugar.d.ts +0 -109
  277. package/dist/schema/sugar.js +0 -83
  278. package/dist/schema/syncDeltaRow.d.ts +0 -6
  279. package/dist/schema/syncDeltaRow.js +0 -6
  280. package/dist/server/adapter.d.ts +0 -173
  281. package/dist/server/adapter.js +0 -18
  282. package/dist/server/commit.d.ts +0 -107
  283. package/dist/server/commit.js +0 -1
  284. package/dist/server/index.d.ts +0 -14
  285. package/dist/server/index.js +0 -2
  286. package/dist/server/readConfig.d.ts +0 -80
  287. package/dist/server/readConfig.js +0 -8
  288. package/dist/server/storageMode.d.ts +0 -23
  289. package/dist/server/storageMode.js +0 -17
  290. package/dist/source/adapter.d.ts +0 -81
  291. package/dist/source/adapter.js +0 -22
  292. package/dist/source/adapters/drizzle.d.ts +0 -48
  293. package/dist/source/adapters/drizzle.js +0 -219
  294. package/dist/source/adapters/kysely.d.ts +0 -42
  295. package/dist/source/adapters/kysely.js +0 -205
  296. package/dist/source/adapters/kyselyMutationCore.d.ts +0 -76
  297. package/dist/source/adapters/kyselyMutationCore.js +0 -125
  298. package/dist/source/adapters/memory.d.ts +0 -13
  299. package/dist/source/adapters/memory.js +0 -130
  300. package/dist/source/adapters/prisma.d.ts +0 -63
  301. package/dist/source/adapters/prisma.js +0 -202
  302. package/dist/source/conformance.d.ts +0 -37
  303. package/dist/source/conformance.js +0 -215
  304. package/dist/source/connector.d.ts +0 -95
  305. package/dist/source/connector.js +0 -266
  306. package/dist/source/connectorProtocol.d.ts +0 -154
  307. package/dist/source/connectorProtocol.js +0 -163
  308. package/dist/source/contract.d.ts +0 -195
  309. package/dist/source/contract.js +0 -164
  310. package/dist/source/factory.d.ts +0 -92
  311. package/dist/source/factory.js +0 -286
  312. package/dist/source/footprint.d.ts +0 -111
  313. package/dist/source/footprint.js +0 -0
  314. package/dist/source/idempotency.d.ts +0 -61
  315. package/dist/source/idempotency.js +0 -144
  316. package/dist/source/index.d.ts +0 -23
  317. package/dist/source/index.js +0 -30
  318. package/dist/source/migrations.d.ts +0 -21
  319. package/dist/source/migrations.js +0 -103
  320. package/dist/source/next.d.ts +0 -32
  321. package/dist/source/next.js +0 -25
  322. package/dist/source/pushQueue.d.ts +0 -134
  323. package/dist/source/pushQueue.js +0 -256
  324. package/dist/source/signing.d.ts +0 -92
  325. package/dist/source/signing.js +0 -162
  326. package/dist/source/types.d.ts +0 -401
  327. package/dist/source/types.js +0 -59
  328. package/dist/stores/ObjectStore.d.ts +0 -115
  329. package/dist/stores/ObjectStore.js +0 -393
  330. package/dist/stores/ObjectStoreContract.d.ts +0 -38
  331. package/dist/stores/ObjectStoreContract.js +0 -1
  332. package/dist/stores/SyncActionStore.d.ts +0 -97
  333. package/dist/stores/SyncActionStore.js +0 -504
  334. package/dist/stores/syncAction.d.ts +0 -26
  335. package/dist/stores/syncAction.js +0 -16
  336. package/dist/surface.d.ts +0 -36
  337. package/dist/surface.js +0 -75
  338. package/dist/sync/BootstrapFetcher.d.ts +0 -280
  339. package/dist/sync/BootstrapFetcher.js +0 -962
  340. package/dist/sync/ConnectionManager.d.ts +0 -8
  341. package/dist/sync/ConnectionManager.js +0 -8
  342. package/dist/sync/OnDemandLoader.d.ts +0 -228
  343. package/dist/sync/OnDemandLoader.js +0 -742
  344. package/dist/sync/SubscriptionManager.d.ts +0 -159
  345. package/dist/sync/SubscriptionManager.js +0 -243
  346. package/dist/sync/SyncWebSocket.d.ts +0 -173
  347. package/dist/sync/SyncWebSocket.js +0 -438
  348. package/dist/sync/awaitClaimGrant.d.ts +0 -6
  349. package/dist/sync/awaitClaimGrant.js +0 -6
  350. package/dist/sync/bootstrapApply.d.ts +0 -70
  351. package/dist/sync/bootstrapApply.js +0 -73
  352. package/dist/sync/commitFrames.d.ts +0 -8
  353. package/dist/sync/commitFrames.js +0 -8
  354. package/dist/sync/contextPorts.d.ts +0 -18
  355. package/dist/sync/contextPorts.js +0 -31
  356. package/dist/sync/createClaimStream.d.ts +0 -7
  357. package/dist/sync/createClaimStream.js +0 -7
  358. package/dist/sync/createPresenceStream.d.ts +0 -69
  359. package/dist/sync/createPresenceStream.js +0 -200
  360. package/dist/sync/createSnapshot.d.ts +0 -29
  361. package/dist/sync/createSnapshot.js +0 -118
  362. package/dist/sync/credentialLifecycle.d.ts +0 -7
  363. package/dist/sync/credentialLifecycle.js +0 -7
  364. package/dist/sync/deltaPipeline.d.ts +0 -113
  365. package/dist/sync/deltaPipeline.js +0 -261
  366. package/dist/sync/groupChange.d.ts +0 -113
  367. package/dist/sync/groupChange.js +0 -242
  368. package/dist/sync/participants.d.ts +0 -115
  369. package/dist/sync/participants.js +0 -344
  370. package/dist/sync/persistedPrefix.d.ts +0 -12
  371. package/dist/sync/persistedPrefix.js +0 -22
  372. package/dist/sync/schemaDrift.d.ts +0 -55
  373. package/dist/sync/schemaDrift.js +0 -53
  374. package/dist/sync/schemas.d.ts +0 -70
  375. package/dist/sync/schemas.js +0 -94
  376. package/dist/sync/syncCursor.d.ts +0 -40
  377. package/dist/sync/syncCursor.js +0 -55
  378. package/dist/sync/syncPlan.d.ts +0 -54
  379. package/dist/sync/syncPlan.js +0 -50
  380. package/dist/sync/wsFrameHandlers.d.ts +0 -8
  381. package/dist/sync/wsFrameHandlers.js +0 -8
  382. package/dist/testing/fixtures/bootstrap.d.ts +0 -49
  383. package/dist/testing/fixtures/bootstrap.js +0 -59
  384. package/dist/testing/fixtures/deltas.d.ts +0 -83
  385. package/dist/testing/fixtures/deltas.js +0 -136
  386. package/dist/testing/fixtures/httpResponses.d.ts +0 -70
  387. package/dist/testing/fixtures/httpResponses.js +0 -90
  388. package/dist/testing/fixtures/models.d.ts +0 -83
  389. package/dist/testing/fixtures/models.js +0 -272
  390. package/dist/testing/helpers/reactWrapper.d.ts +0 -69
  391. package/dist/testing/helpers/reactWrapper.js +0 -67
  392. package/dist/testing/helpers/syncEngineHarness.d.ts +0 -54
  393. package/dist/testing/helpers/syncEngineHarness.js +0 -73
  394. package/dist/testing/helpers/wait.d.ts +0 -30
  395. package/dist/testing/helpers/wait.js +0 -49
  396. package/dist/testing/index.d.ts +0 -23
  397. package/dist/testing/index.js +0 -33
  398. package/dist/testing/mocks/FakeDatabase.d.ts +0 -18
  399. package/dist/testing/mocks/FakeDatabase.js +0 -10
  400. package/dist/testing/mocks/MockMutationExecutor.d.ts +0 -87
  401. package/dist/testing/mocks/MockMutationExecutor.js +0 -186
  402. package/dist/testing/mocks/MockNetworkMonitor.d.ts +0 -20
  403. package/dist/testing/mocks/MockNetworkMonitor.js +0 -46
  404. package/dist/testing/mocks/MockSyncContext.d.ts +0 -51
  405. package/dist/testing/mocks/MockSyncContext.js +0 -72
  406. package/dist/testing/mocks/MockSyncStore.d.ts +0 -88
  407. package/dist/testing/mocks/MockSyncStore.js +0 -171
  408. package/dist/testing/mocks/MockWebSocket.d.ts +0 -71
  409. package/dist/testing/mocks/MockWebSocket.js +0 -118
  410. package/dist/transaction/ablo.d.ts +0 -88
  411. package/dist/transaction/ablo.js +0 -33
  412. package/dist/transaction/auth/apiKey.d.ts +0 -152
  413. package/dist/transaction/auth/apiKey.js +0 -419
  414. package/dist/transaction/auth/bootstrapScope.d.ts +0 -15
  415. package/dist/transaction/auth/bootstrapScope.js +0 -1
  416. package/dist/transaction/auth/capability.d.ts +0 -177
  417. package/dist/transaction/auth/capability.js +0 -199
  418. package/dist/transaction/auth/credentialEndpoint.d.ts +0 -61
  419. package/dist/transaction/auth/credentialEndpoint.js +0 -86
  420. package/dist/transaction/auth/credentialPolicy.d.ts +0 -148
  421. package/dist/transaction/auth/credentialPolicy.js +0 -125
  422. package/dist/transaction/auth/credentialSource.d.ts +0 -30
  423. package/dist/transaction/auth/credentialSource.js +0 -55
  424. package/dist/transaction/auth/hostedEndpoints.d.ts +0 -21
  425. package/dist/transaction/auth/hostedEndpoints.js +0 -21
  426. package/dist/transaction/auth/identity.d.ts +0 -55
  427. package/dist/transaction/auth/identity.js +0 -210
  428. package/dist/transaction/auth/index.d.ts +0 -162
  429. package/dist/transaction/auth/index.js +0 -304
  430. package/dist/transaction/auth/schemas.d.ts +0 -59
  431. package/dist/transaction/auth/schemas.js +0 -85
  432. package/dist/transaction/auth/sessionMint.d.ts +0 -28
  433. package/dist/transaction/auth/sessionMint.js +0 -85
  434. package/dist/transaction/coordination/awaitClaimGrant.d.ts +0 -49
  435. package/dist/transaction/coordination/awaitClaimGrant.js +0 -112
  436. package/dist/transaction/coordination/claimHeartbeatLoop.d.ts +0 -50
  437. package/dist/transaction/coordination/claimHeartbeatLoop.js +0 -88
  438. package/dist/transaction/coordination/claimMeta.d.ts +0 -49
  439. package/dist/transaction/coordination/claimMeta.js +0 -52
  440. package/dist/transaction/coordination/createClaimStream.d.ts +0 -64
  441. package/dist/transaction/coordination/createClaimStream.js +0 -475
  442. package/dist/transaction/coordination/events.d.ts +0 -74
  443. package/dist/transaction/coordination/events.js +0 -7
  444. package/dist/transaction/coordination/index.d.ts +0 -19
  445. package/dist/transaction/coordination/index.js +0 -44
  446. package/dist/transaction/coordination/locator.d.ts +0 -83
  447. package/dist/transaction/coordination/locator.js +0 -82
  448. package/dist/transaction/coordination/schema.d.ts +0 -1473
  449. package/dist/transaction/coordination/schema.js +0 -1013
  450. package/dist/transaction/coordination/targetConflict.d.ts +0 -2
  451. package/dist/transaction/coordination/targetConflict.js +0 -103
  452. package/dist/transaction/coordination/trace.d.ts +0 -78
  453. package/dist/transaction/coordination/trace.js +0 -138
  454. package/dist/transaction/durableWrites.d.ts +0 -62
  455. package/dist/transaction/durableWrites.js +0 -71
  456. package/dist/transaction/environment.d.ts +0 -105
  457. package/dist/transaction/environment.js +0 -108
  458. package/dist/transaction/errorCodes.d.ts +0 -403
  459. package/dist/transaction/errorCodes.js +0 -480
  460. package/dist/transaction/errors.d.ts +0 -428
  461. package/dist/transaction/errors.js +0 -686
  462. package/dist/transaction/index.d.ts +0 -20
  463. package/dist/transaction/index.js +0 -20
  464. package/dist/transaction/keys/index.d.ts +0 -87
  465. package/dist/transaction/keys/index.js +0 -207
  466. package/dist/transaction/log/syncDeltaRow.d.ts +0 -158
  467. package/dist/transaction/log/syncDeltaRow.js +0 -95
  468. package/dist/transaction/logPosition.d.ts +0 -97
  469. package/dist/transaction/logPosition.js +0 -125
  470. package/dist/transaction/logger.d.ts +0 -16
  471. package/dist/transaction/logger.js +0 -7
  472. package/dist/transaction/observability.d.ts +0 -53
  473. package/dist/transaction/observability.js +0 -19
  474. package/dist/transaction/persistence.d.ts +0 -12
  475. package/dist/transaction/persistence.js +0 -11
  476. package/dist/transaction/plugin.d.ts +0 -192
  477. package/dist/transaction/plugin.js +0 -87
  478. package/dist/transaction/policy/types.d.ts +0 -217
  479. package/dist/transaction/policy/types.js +0 -126
  480. package/dist/transaction/resources/functionalUpdate.d.ts +0 -79
  481. package/dist/transaction/resources/functionalUpdate.js +0 -87
  482. package/dist/transaction/resources/httpResources.d.ts +0 -266
  483. package/dist/transaction/resources/httpResources.js +0 -7
  484. package/dist/transaction/resources/modelOperations.d.ts +0 -319
  485. package/dist/transaction/resources/modelOperations.js +0 -12
  486. package/dist/transaction/resources/mutationOptions.d.ts +0 -66
  487. package/dist/transaction/resources/mutationOptions.js +0 -9
  488. package/dist/transaction/resources/where.d.ts +0 -85
  489. package/dist/transaction/resources/where.js +0 -70
  490. package/dist/transaction/resources/writeOptionsSchema.d.ts +0 -47
  491. package/dist/transaction/resources/writeOptionsSchema.js +0 -73
  492. package/dist/transaction/schema/field.d.ts +0 -126
  493. package/dist/transaction/schema/field.js +0 -265
  494. package/dist/transaction/schema/loadStrategy.d.ts +0 -45
  495. package/dist/transaction/schema/loadStrategy.js +0 -46
  496. package/dist/transaction/schema/model.d.ts +0 -379
  497. package/dist/transaction/schema/model.js +0 -123
  498. package/dist/transaction/schema/openapi.d.ts +0 -57
  499. package/dist/transaction/schema/openapi.js +0 -340
  500. package/dist/transaction/schema/relation.d.ts +0 -199
  501. package/dist/transaction/schema/relation.js +0 -104
  502. package/dist/transaction/schema/residency.d.ts +0 -29
  503. package/dist/transaction/schema/residency.js +0 -25
  504. package/dist/transaction/schema/roles.d.ts +0 -249
  505. package/dist/transaction/schema/roles.js +0 -230
  506. package/dist/transaction/schema/schema.d.ts +0 -324
  507. package/dist/transaction/schema/schema.js +0 -305
  508. package/dist/transaction/schema/tenancy.d.ts +0 -139
  509. package/dist/transaction/schema/tenancy.js +0 -190
  510. package/dist/transaction/transactionLayer.d.ts +0 -82
  511. package/dist/transaction/transactionLayer.js +0 -24
  512. package/dist/transaction/transactions/settlement/commitEnvelope.d.ts +0 -143
  513. package/dist/transaction/transactions/settlement/commitEnvelope.js +0 -161
  514. package/dist/transaction/transactions/settlement/httpCommitEnvelope.d.ts +0 -53
  515. package/dist/transaction/transactions/settlement/httpCommitEnvelope.js +0 -207
  516. package/dist/transaction/transactions/settlement/idempotencyKey.d.ts +0 -10
  517. package/dist/transaction/transactions/settlement/idempotencyKey.js +0 -9
  518. package/dist/transaction/transactions/settlement/pendingWrite.d.ts +0 -112
  519. package/dist/transaction/transactions/settlement/pendingWrite.js +0 -20
  520. package/dist/transaction/transport/commitFrames.d.ts +0 -90
  521. package/dist/transaction/transport/commitFrames.js +0 -134
  522. package/dist/transaction/transport/connectionManager.d.ts +0 -215
  523. package/dist/transaction/transport/connectionManager.js +0 -673
  524. package/dist/transaction/transport/credentialLifecycle.d.ts +0 -177
  525. package/dist/transaction/transport/credentialLifecycle.js +0 -324
  526. package/dist/transaction/transport/heartbeat.d.ts +0 -65
  527. package/dist/transaction/transport/heartbeat.js +0 -93
  528. package/dist/transaction/transport/httpClient.d.ts +0 -123
  529. package/dist/transaction/transport/httpClient.js +0 -145
  530. package/dist/transaction/transport/httpOptions.d.ts +0 -33
  531. package/dist/transaction/transport/httpOptions.js +0 -12
  532. package/dist/transaction/transport/httpTransport.d.ts +0 -8
  533. package/dist/transaction/transport/httpTransport.js +0 -1276
  534. package/dist/transaction/transport/networkProbe.d.ts +0 -84
  535. package/dist/transaction/transport/networkProbe.js +0 -207
  536. package/dist/transaction/transport/wsFrameHandlers.d.ts +0 -128
  537. package/dist/transaction/transport/wsFrameHandlers.js +0 -429
  538. package/dist/transaction/transport/wsTransport.d.ts +0 -576
  539. package/dist/transaction/transport/wsTransport.js +0 -1017
  540. package/dist/transaction/types/assertExact.d.ts +0 -17
  541. package/dist/transaction/types/assertExact.js +0 -1
  542. package/dist/transaction/types/global.d.ts +0 -107
  543. package/dist/transaction/types/global.js +0 -40
  544. package/dist/transaction/types/index.d.ts +0 -205
  545. package/dist/transaction/types/index.js +0 -56
  546. package/dist/transaction/types/modelData.d.ts +0 -10
  547. package/dist/transaction/types/modelData.js +0 -9
  548. package/dist/transaction/types/participant.d.ts +0 -20
  549. package/dist/transaction/types/participant.js +0 -10
  550. package/dist/transaction/types/streams.d.ts +0 -540
  551. package/dist/transaction/types/streams.js +0 -11
  552. package/dist/transaction/utils/asyncIterator.d.ts +0 -34
  553. package/dist/transaction/utils/asyncIterator.js +0 -135
  554. package/dist/transaction/utils/duration.d.ts +0 -25
  555. package/dist/transaction/utils/duration.js +0 -45
  556. package/dist/transaction/utils/json.d.ts +0 -57
  557. package/dist/transaction/utils/json.js +0 -276
  558. package/dist/transaction/wire/accountResponses.d.ts +0 -351
  559. package/dist/transaction/wire/accountResponses.js +0 -255
  560. package/dist/transaction/wire/auth.d.ts +0 -49
  561. package/dist/transaction/wire/auth.js +0 -57
  562. package/dist/transaction/wire/bootstrapReason.d.ts +0 -9
  563. package/dist/transaction/wire/bootstrapReason.js +0 -8
  564. package/dist/transaction/wire/claimEvent.d.ts +0 -76
  565. package/dist/transaction/wire/claimEvent.js +0 -73
  566. package/dist/transaction/wire/claims.d.ts +0 -463
  567. package/dist/transaction/wire/claims.js +0 -229
  568. package/dist/transaction/wire/commit.d.ts +0 -603
  569. package/dist/transaction/wire/commit.js +0 -321
  570. package/dist/transaction/wire/delta.d.ts +0 -250
  571. package/dist/transaction/wire/delta.js +0 -147
  572. package/dist/transaction/wire/errorEnvelope.d.ts +0 -72
  573. package/dist/transaction/wire/errorEnvelope.js +0 -123
  574. package/dist/transaction/wire/feedCursor.d.ts +0 -60
  575. package/dist/transaction/wire/feedCursor.js +0 -82
  576. package/dist/transaction/wire/feedEvent.d.ts +0 -177
  577. package/dist/transaction/wire/feedEvent.js +0 -39
  578. package/dist/transaction/wire/frames.d.ts +0 -194
  579. package/dist/transaction/wire/frames.js +0 -50
  580. package/dist/transaction/wire/inboundFrames.d.ts +0 -552
  581. package/dist/transaction/wire/inboundFrames.js +0 -116
  582. package/dist/transaction/wire/index.d.ts +0 -50
  583. package/dist/transaction/wire/index.js +0 -74
  584. package/dist/transaction/wire/listEnvelope.d.ts +0 -37
  585. package/dist/transaction/wire/listEnvelope.js +0 -42
  586. package/dist/transaction/wire/modelResponses.d.ts +0 -85
  587. package/dist/transaction/wire/modelResponses.js +0 -43
  588. package/dist/transaction/wire/protocol.d.ts +0 -38
  589. package/dist/transaction/wire/protocol.js +0 -38
  590. package/dist/transaction/wire/protocolVersion.d.ts +0 -73
  591. package/dist/transaction/wire/protocolVersion.js +0 -83
  592. package/dist/transactions/mutations/MutationQueue.d.ts +0 -655
  593. package/dist/transactions/mutations/MutationQueue.js +0 -2797
  594. package/dist/transactions/mutations/MutationStore.d.ts +0 -20
  595. package/dist/transactions/mutations/MutationStore.js +0 -53
  596. package/dist/transactions/mutations/UnconfirmedWrites.d.ts +0 -82
  597. package/dist/transactions/mutations/UnconfirmedWrites.js +0 -104
  598. package/dist/transactions/mutations/coalesceRules.d.ts +0 -58
  599. package/dist/transactions/mutations/coalesceRules.js +0 -140
  600. package/dist/transactions/mutations/commitLatency.d.ts +0 -52
  601. package/dist/transactions/mutations/commitLatency.js +0 -130
  602. package/dist/transactions/mutations/commitOutboxStore.d.ts +0 -28
  603. package/dist/transactions/mutations/commitOutboxStore.js +0 -26
  604. package/dist/transactions/mutations/commitPayload.d.ts +0 -164
  605. package/dist/transactions/mutations/commitPayload.js +0 -152
  606. package/dist/transactions/mutations/deltaConfirmation.d.ts +0 -59
  607. package/dist/transactions/mutations/deltaConfirmation.js +0 -233
  608. package/dist/transactions/mutations/durableWriteStore.d.ts +0 -14
  609. package/dist/transactions/mutations/durableWriteStore.js +0 -12
  610. package/dist/transactions/mutations/optimisticApply.d.ts +0 -49
  611. package/dist/transactions/mutations/optimisticApply.js +0 -65
  612. package/dist/transactions/mutations/replayValidation.d.ts +0 -186
  613. package/dist/transactions/mutations/replayValidation.js +0 -163
  614. package/dist/utils/mobxSetup.d.ts +0 -53
  615. package/dist/utils/mobxSetup.js +0 -330
  616. package/dist/webhooks/events.d.ts +0 -43
  617. package/dist/webhooks/events.js +0 -42
  618. package/dist/webhooks/index.d.ts +0 -8
  619. package/dist/webhooks/index.js +0 -8
  620. package/dist/wire/index.d.ts +0 -1
  621. package/dist/wire/index.js +0 -8
  622. package/docs/interaction-model.md +0 -99
@@ -1,85 +0,0 @@
1
- /**
2
- * Mints a session token. This is the single implementation behind
3
- * `sessions.create`, shared by the WebSocket and HTTP clients so the two never
4
- * disagree on how a token is produced.
5
- *
6
- * Minting is a plain control-plane HTTP call — no socket, no synced data. A
7
- * backend holding a secret key (`sk_`) exchanges it for a short-lived, scoped
8
- * token whose kind depends on the session requested:
9
- *
10
- * `{ user }` → POST /auth/ephemeral-keys, returning an `ek_` key that carries
11
- * full end-user authority. This is the only route that mints a
12
- * user session; the capability route rejects a `user`
13
- * participant with `invalid_participant_kind`.
14
- * `{ agent }` → POST /auth/capability, returning an `rk_` key scoped to exactly
15
- * the operations named in `can`. For example
16
- * `can: { tasks: ['update'] }` becomes the wire allowlist entry
17
- * `tasks.update`, which the server matches against the model's
18
- * registered names.
19
- *
20
- * The caller supplies the already-resolved secret key and base URL in
21
- * {@link MintSessionContext}. Choosing which key to pass — the original secret
22
- * key, not a derived key that an earlier exchange may have produced — is the
23
- * caller's responsibility.
24
- */
25
- import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
26
- import { grantedOperations } from './capability.js';
27
- /**
28
- * Mints a session token from an already-resolved secret key and base URL.
29
- * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
30
- * and reshapes the response into an {@link AbloSession}.
31
- */
32
- export async function mintSession(params, ctx) {
33
- const { apiKey, baseUrl } = ctx;
34
- if (params.user) {
35
- const res = await mintUserSessionKey({
36
- apiKey,
37
- baseUrl,
38
- userId: params.user.id,
39
- ...(params.organizationId ? { organizationId: params.organizationId } : {}),
40
- ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
41
- ttlSeconds: params.ttlSeconds ?? 900,
42
- ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
43
- });
44
- return {
45
- object: 'session',
46
- id: res.id,
47
- token: res.token,
48
- expiresAt: res.expiresAt,
49
- organizationId: res.organizationId,
50
- // The ephemeral mint stores scope on the key row; reshape its flat
51
- // response into the session resource's scope block.
52
- scope: {
53
- organizationId: res.organizationId,
54
- syncGroups: res.syncGroups,
55
- operations: [],
56
- participantKind: 'user',
57
- participantId: res.participantId,
58
- },
59
- userMeta: params.userMeta ?? { id: res.participantId },
60
- };
61
- }
62
- // One translation from the declared grant to the wire allowlist, shared with
63
- // every other door that mints — see `auth/capability.ts`.
64
- const operations = grantedOperations(params.can, ctx.modelTypenames);
65
- const res = await exchangeApiKey({
66
- apiKey,
67
- baseUrl,
68
- participantKind: 'agent',
69
- participantId: params.agent.id,
70
- ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
71
- operations,
72
- ttlSeconds: params.ttlSeconds ?? 900,
73
- ...(params.userMeta ? { userMeta: params.userMeta } : {}),
74
- ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
75
- });
76
- return {
77
- object: 'session',
78
- id: res.capabilityId,
79
- token: res.token,
80
- expiresAt: res.expiresAt,
81
- organizationId: res.organizationId,
82
- scope: res.scope,
83
- userMeta: res.userMeta,
84
- };
85
- }
@@ -1,49 +0,0 @@
1
- /**
2
- * Waits for a queued claim to reach the head of the line — the client side of
3
- * the fair-queue handover. When a claim is contended, the server puts it in a
4
- * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
5
- * `claim_queued` frame over the WebSocket). The grant is delivered later, when
6
- * the claim reaches the head, as a `claim_granted` frame. This resolves once
7
- * that frame arrives for the given `claimId`, so the caller's `claim` promise
8
- * stays pending — event-driven, with no polling — until it is actually the
9
- * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
10
- * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
11
- *
12
- * It needs only a minimal `{ subscribe }` transport, so it can be tested
13
- * against a fake; the duplex `WsTransport` satisfies it.
14
- */
15
- import { type Logger } from '../logger.js';
16
- export interface GrantTransport {
17
- subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
18
- }
19
- export interface ClaimGrantInfo {
20
- /**
21
- * True when the grant arrived as `claim_granted` — the target was held when
22
- * the caller asked, and the caller waited in the FIFO line behind the holder.
23
- * False for the immediate `claim_acquired`, where the target was free.
24
- *
25
- * Callers read this to know the row may have changed while they queued. Claim
26
- * visibility is scoped to the entity, so a broad, organization-wide
27
- * subscription receives no presence or claim fan-out, and the local
28
- * coordination snapshot cannot be trusted to tell whether the caller waited.
29
- * The grant frame itself is the authoritative signal.
30
- */
31
- readonly waited: boolean;
32
- /**
33
- * The fencing token the server minted for this grant (Option B), read off the
34
- * grant frame — the authoritative source, since the token is server-stamped.
35
- * `undefined` when the server does not fence (no minter wired).
36
- */
37
- readonly fenceToken?: number;
38
- }
39
- export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
40
- timeoutMs?: number;
41
- /**
42
- * Backpressure: reject instead of waiting if, when we join the line, the
43
- * server reports `position >= maxQueueDepth` (i.e. that many claims are
44
- * already ahead of us). Omit to wait however deep the queue is.
45
- */
46
- maxQueueDepth?: number;
47
- /** Where grant transitions are logged. Defaults to silent. */
48
- logger?: Logger;
49
- }): Promise<ClaimGrantInfo>;
@@ -1,112 +0,0 @@
1
- /**
2
- * Waits for a queued claim to reach the head of the line — the client side of
3
- * the fair-queue handover. When a claim is contended, the server puts it in a
4
- * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
5
- * `claim_queued` frame over the WebSocket). The grant is delivered later, when
6
- * the claim reaches the head, as a `claim_granted` frame. This resolves once
7
- * that frame arrives for the given `claimId`, so the caller's `claim` promise
8
- * stays pending — event-driven, with no polling — until it is actually the
9
- * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
10
- * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
11
- *
12
- * It needs only a minimal `{ subscribe }` transport, so it can be tested
13
- * against a fake; the duplex `WsTransport` satisfies it.
14
- */
15
- import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
16
- import { modelTarget } from './locator.js';
17
- import { noopLogger } from '../logger.js';
18
- /** Read the server-stamped fencing token off a grant frame, if present. */
19
- function readFenceToken(p) {
20
- return typeof p.fenceToken === 'number' ? p.fenceToken : undefined;
21
- }
22
- export function awaitClaimGrant(transport, claimId, options) {
23
- const logger = options?.logger ?? noopLogger;
24
- return new Promise((resolve, reject) => {
25
- const unsubs = [];
26
- let timer;
27
- const settle = (fn) => {
28
- if (timer)
29
- clearTimeout(timer);
30
- for (const u of unsubs)
31
- u();
32
- fn();
33
- };
34
- // The target was free → `claim_acquired` (immediate); it was contended,
35
- // we waited in line, and reached the head → `claim_granted`. Either frame
36
- // means the lease is now ours; `waited` records which path it was.
37
- unsubs.push(transport.subscribe('claim_acquired', (p) => {
38
- if (p?.claimId === claimId) {
39
- logger.debug(`claim: acquired ${claimId} (target was free)`);
40
- const fenceToken = readFenceToken(p);
41
- settle(() => {
42
- resolve({ waited: false, ...(fenceToken !== undefined ? { fenceToken } : {}) });
43
- });
44
- }
45
- }));
46
- unsubs.push(transport.subscribe('claim_granted', (p) => {
47
- if (p?.claimId === claimId) {
48
- // Promoted to the head of the line — the creator's "it's the agent's
49
- // turn now" moment after waiting behind a holder.
50
- logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
51
- const fenceToken = readFenceToken(p);
52
- settle(() => {
53
- resolve({ waited: true, ...(fenceToken !== undefined ? { fenceToken } : {}) });
54
- });
55
- }
56
- }));
57
- if (options?.maxQueueDepth !== undefined) {
58
- const max = options.maxQueueDepth;
59
- unsubs.push(transport.subscribe('claim_queued', (p) => {
60
- if (p?.claimId !== claimId)
61
- return;
62
- const position = typeof p.position === 'number' ? p.position : 0;
63
- if (position >= max) {
64
- settle(() => {
65
- reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' }));
66
- });
67
- }
68
- }));
69
- }
70
- unsubs.push(transport.subscribe('claim_rejected', (p) => {
71
- const rejection = p;
72
- if (rejection.claimId !== claimId)
73
- return;
74
- const target = rejection.target
75
- ? claimTargetLabel({
76
- ...modelTarget(rejection.target),
77
- field: rejection.target.field,
78
- })
79
- : claimId;
80
- settle(() => {
81
- reject(new AbloClaimedError(formatClaimedErrorMessage({
82
- targetLabel: target,
83
- heldBy: rejection.heldBy,
84
- claim: rejection.heldByClaim,
85
- policyReason: rejection.policyReason,
86
- fallback: `Claim rejected for ${target}.`,
87
- }), {
88
- code: rejection.reason === 'conflict'
89
- ? 'claim_conflict'
90
- : 'claim_lease_unavailable',
91
- claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
92
- }));
93
- });
94
- }));
95
- unsubs.push(transport.subscribe('claim_lost', (p) => {
96
- if (p?.claimId === claimId) {
97
- settle(() => {
98
- reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
99
- code: 'claim_lost',
100
- }));
101
- });
102
- }
103
- }));
104
- if (options?.timeoutMs && options.timeoutMs > 0) {
105
- timer = setTimeout(() => {
106
- settle(() => {
107
- reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' }));
108
- });
109
- }, options.timeoutMs);
110
- }
111
- });
112
- }
@@ -1,50 +0,0 @@
1
- /**
2
- * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
3
- * implementation shared by both transports (the WebSocket claim stream and the
4
- * private HTTP transport), so the cadence and failure semantics cannot drift.
5
- *
6
- * A beat is the "still working" signal that keeps a lease alive for the
7
- * duration of real work. The loop's failure handling follows the lease-system
8
- * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
9
- * for a transient reason — the network blipped, the server was briefly
10
- * unavailable — is simply retried on the next tick, because the lease has
11
- * runway to spare by construction (the default cadence is a third of the TTL,
12
- * so two consecutive beats can fail before the lease is even at risk). Only a
13
- * definitive answer from the server — the lease lapsed and may have been
14
- * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
15
- * surfaces the loss, because for a caller with no push channel the failed beat
16
- * IS the loss notification.
17
- */
18
- import { AbloClaimedError } from '../errors.js';
19
- import type { ClaimHeartbeat, ClaimHeartbeatOptions, Duration } from '../types/streams.js';
20
- /**
21
- * Normalize the public `heartbeat(options?)` argument — a bare Duration is
22
- * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
23
- * shorthand cannot drift.
24
- */
25
- export declare function resolveHeartbeatOptions(input: Duration | ClaimHeartbeatOptions | undefined): ClaimHeartbeatOptions;
26
- /**
27
- * The beat cadence for a lease of `ttlMs`: an explicit duration when the
28
- * caller set one, otherwise a third of the TTL (floored at 1s) — the
29
- * DynamoDB-lock-client rule, leaving two missed beats of runway before the
30
- * lease is at risk while keeping crash recovery within one beat window.
31
- */
32
- export declare function heartbeatCadenceMs(ttlMs: number, heartbeat: true | Duration): number;
33
- export interface ClaimHeartbeatLoopOptions {
34
- /** Send one beat; resolves while the lease is still ours. */
35
- beat(): Promise<ClaimHeartbeat>;
36
- /** Cadence between beats. Callers default this to a third of the TTL. */
37
- intervalMs: number;
38
- /**
39
- * Called once when a beat comes back with a definitive loss — the lease
40
- * expired or was taken. The loop has already stopped by the time this runs.
41
- */
42
- onLost?(error: AbloClaimedError): void;
43
- }
44
- /**
45
- * Start beating. Returns a stop function; callers stop the loop when the
46
- * claim is released (all held-claim assembly sites tie this to `release`).
47
- * Beats never overlap: a tick that fires while the previous beat is still
48
- * in flight is skipped rather than stacked.
49
- */
50
- export declare function startClaimHeartbeatLoop(options: ClaimHeartbeatLoopOptions): () => void;
@@ -1,88 +0,0 @@
1
- /**
2
- * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
3
- * implementation shared by both transports (the WebSocket claim stream and the
4
- * private HTTP transport), so the cadence and failure semantics cannot drift.
5
- *
6
- * A beat is the "still working" signal that keeps a lease alive for the
7
- * duration of real work. The loop's failure handling follows the lease-system
8
- * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
9
- * for a transient reason — the network blipped, the server was briefly
10
- * unavailable — is simply retried on the next tick, because the lease has
11
- * runway to spare by construction (the default cadence is a third of the TTL,
12
- * so two consecutive beats can fail before the lease is even at risk). Only a
13
- * definitive answer from the server — the lease lapsed and may have been
14
- * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
15
- * surfaces the loss, because for a caller with no push channel the failed beat
16
- * IS the loss notification.
17
- */
18
- import { AbloClaimedError } from '../errors.js';
19
- import { toMs } from '../utils/duration.js';
20
- /**
21
- * Normalize the public `heartbeat(options?)` argument — a bare Duration is
22
- * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
23
- * shorthand cannot drift.
24
- */
25
- export function resolveHeartbeatOptions(input) {
26
- if (input === undefined)
27
- return {};
28
- if (typeof input === 'string' || typeof input === 'number') {
29
- return { ttl: input };
30
- }
31
- return input;
32
- }
33
- /**
34
- * The beat cadence for a lease of `ttlMs`: an explicit duration when the
35
- * caller set one, otherwise a third of the TTL (floored at 1s) — the
36
- * DynamoDB-lock-client rule, leaving two missed beats of runway before the
37
- * lease is at risk while keeping crash recovery within one beat window.
38
- */
39
- export function heartbeatCadenceMs(ttlMs, heartbeat) {
40
- if (heartbeat !== true)
41
- return toMs(heartbeat);
42
- return Math.max(Math.floor(ttlMs / 3), 1_000);
43
- }
44
- /**
45
- * Start beating. Returns a stop function; callers stop the loop when the
46
- * claim is released (all held-claim assembly sites tie this to `release`).
47
- * Beats never overlap: a tick that fires while the previous beat is still
48
- * in flight is skipped rather than stacked.
49
- */
50
- export function startClaimHeartbeatLoop(options) {
51
- let stopped = false;
52
- let inFlight = false;
53
- const stop = () => {
54
- if (stopped)
55
- return;
56
- stopped = true;
57
- clearInterval(timer);
58
- };
59
- const timer = setInterval(() => {
60
- if (stopped || inFlight)
61
- return;
62
- inFlight = true;
63
- options
64
- .beat()
65
- .catch((error) => {
66
- if (stopped)
67
- return;
68
- if (error instanceof AbloClaimedError) {
69
- stop();
70
- options.onLost?.(error);
71
- return;
72
- }
73
- // Transient (connection, brief server unavailability): the next tick
74
- // is the retry — the ttl/3 cadence leaves runway for missed beats.
75
- })
76
- .finally(() => {
77
- inFlight = false;
78
- });
79
- }, options.intervalMs);
80
- // The loop must never be what keeps a Node process alive — the held work
81
- // is. A worker that finishes without releasing exits anyway, and the lease
82
- // lapses on schedule. No-op in browsers (where setInterval returns a number
83
- // without `unref`), which is why the call is optional even though the Node
84
- // timer type always has it.
85
- // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
86
- timer.unref?.();
87
- return stop;
88
- }
@@ -1,49 +0,0 @@
1
- /**
2
- * A claim's application metadata, crossing between the wire and the shape the
3
- * program declared for it.
4
- *
5
- * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
6
- * parses it as `z.record(z.string(), z.unknown())` and always will, because a
7
- * newer peer must be able to send a field this build has never heard of and
8
- * still be understood. The read surface is the opposite: `Register`'s
9
- * `ClaimMeta` slot names the one shape this program's claims carry, so
10
- * `claim.state({ id })?.target.meta` reads without a guard.
11
- *
12
- * Those two facts meet here, and only here, in both directions. A decode calls
13
- * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
14
- * locator projection calls {@link wireMeta} on the way back out, where a
15
- * caller's declared value is put on the socket or in the HTTP body. Between
16
- * them they are the one place the SDK takes the caller's word for a shape it
17
- * did not check — written down once, with the reason, instead of being asserted
18
- * at each crossing.
19
- *
20
- * The two directions are not symmetric in cost. Losing the declared shape on
21
- * the way out is harmless, because the wire has always accepted any record;
22
- * gaining it on the way in is the promise the read surface makes, so
23
- * `declaredMeta` is the one to audit when a claim reads back a shape its holder
24
- * never wrote.
25
- */
26
- import type { ResolveClaimMeta } from '../types/global.js';
27
- /**
28
- * Read a parsed `meta` as the declared shape. Call it only where a decode hands
29
- * a wire value to a public claim, and only for a value already known present —
30
- * the absent case is an omitted member, not a declared-shaped `undefined`.
31
- *
32
- * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
33
- * pair because two claim surfaces already read a caller's `meta` back off the
34
- * options it passed in, and spell that local reader `claimMeta`.
35
- */
36
- export declare function declaredMeta(raw: unknown): ResolveClaimMeta;
37
- /**
38
- * Write a declared `meta` as the permissive record the wire carries. Every path
39
- * from a caller's target to a frame or request body goes through `subTarget`,
40
- * so this has exactly one caller — widening it is how the declared shape stops
41
- * being a compile error at the edge of the protocol instead of stopping there.
42
- *
43
- * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
44
- * program may register an `interface` for its claim metadata, and an interface
45
- * carries no implicit index signature, so a directly-typed parameter would make
46
- * the conversion itself unrepresentable at the one site that needs it. Widening
47
- * the input is what keeps the assertion single.
48
- */
49
- export declare function wireMeta(meta: unknown): Record<string, unknown>;
@@ -1,52 +0,0 @@
1
- /**
2
- * A claim's application metadata, crossing between the wire and the shape the
3
- * program declared for it.
4
- *
5
- * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
6
- * parses it as `z.record(z.string(), z.unknown())` and always will, because a
7
- * newer peer must be able to send a field this build has never heard of and
8
- * still be understood. The read surface is the opposite: `Register`'s
9
- * `ClaimMeta` slot names the one shape this program's claims carry, so
10
- * `claim.state({ id })?.target.meta` reads without a guard.
11
- *
12
- * Those two facts meet here, and only here, in both directions. A decode calls
13
- * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
14
- * locator projection calls {@link wireMeta} on the way back out, where a
15
- * caller's declared value is put on the socket or in the HTTP body. Between
16
- * them they are the one place the SDK takes the caller's word for a shape it
17
- * did not check — written down once, with the reason, instead of being asserted
18
- * at each crossing.
19
- *
20
- * The two directions are not symmetric in cost. Losing the declared shape on
21
- * the way out is harmless, because the wire has always accepted any record;
22
- * gaining it on the way in is the promise the read surface makes, so
23
- * `declaredMeta` is the one to audit when a claim reads back a shape its holder
24
- * never wrote.
25
- */
26
- /**
27
- * Read a parsed `meta` as the declared shape. Call it only where a decode hands
28
- * a wire value to a public claim, and only for a value already known present —
29
- * the absent case is an omitted member, not a declared-shaped `undefined`.
30
- *
31
- * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
32
- * pair because two claim surfaces already read a caller's `meta` back off the
33
- * options it passed in, and spell that local reader `claimMeta`.
34
- */
35
- export function declaredMeta(raw) {
36
- return raw;
37
- }
38
- /**
39
- * Write a declared `meta` as the permissive record the wire carries. Every path
40
- * from a caller's target to a frame or request body goes through `subTarget`,
41
- * so this has exactly one caller — widening it is how the declared shape stops
42
- * being a compile error at the edge of the protocol instead of stopping there.
43
- *
44
- * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
45
- * program may register an `interface` for its claim metadata, and an interface
46
- * carries no implicit index signature, so a directly-typed parameter would make
47
- * the conversion itself unrepresentable at the one site that needs it. Widening
48
- * the input is what keeps the assertion single.
49
- */
50
- export function wireMeta(meta) {
51
- return meta;
52
- }
@@ -1,64 +0,0 @@
1
- /**
2
- * Creates a {@link ClaimStream} over a live sync connection. A claim is a
3
- * short-lived, advisory lease a participant takes on an entity (or a field of
4
- * one) to signal "I'm working on this"; the stream lets you take claims, see
5
- * everyone else's, and watch the wait queue when a claim is contended.
6
- *
7
- * The stream is built directly on the sync WebSocket and shares that one
8
- * connection. It learns about other participants' claims from the same
9
- * `presence_update` frames the {@link createPresenceStream} presence stream
10
- * consumes — the server piggybacks each participant's `activeClaims` on every
11
- * presence frame — and sends its own claims as `claim_begin` and
12
- * `claim_abandon` frames.
13
- *
14
- * Wire frames:
15
- * • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
16
- * entityId, description, field?, estimatedMs? }`.
17
- * • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
18
- * entityId? }`.
19
- * • Inbound, via presence — `event.activeClaims`, each stamped with
20
- * `declaredAt` and `expiresAt`.
21
- * • Inbound `claim_rejected` — the server refused the claim, with conflict
22
- * metadata.
23
- */
24
- import type { WsTransport } from '../transport/wsTransport.js';
25
- import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
26
- import { type Logger } from '../logger.js';
27
- /**
28
- * The wire capability the claim stream actually uses: subscribe to typed
29
- * inbound frames, check liveness, and send outbound frames. The duplex
30
- * `WsTransport` satisfies it, so production wiring is unchanged — but depending on the port
31
- * rather than the whole socket class lets a test drive it with a plain object,
32
- * no cast. `Pick` carries the exact (generic, typed-payload) `subscribe`
33
- * signature, so every handler stays fully typed.
34
- */
35
- export type ClaimTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
36
- export interface ClaimStreamConfig {
37
- /** Identity used to filter our own active claims out of `others`. */
38
- participantId: string;
39
- /** Where the coordination trace is logged. Defaults to silent. */
40
- logger?: Logger;
41
- }
42
- export interface AttachableClaimStream extends ClaimStream {
43
- /**
44
- * Mints a lease directly: sends the `claim_begin` frame and returns a held
45
- * {@link Claim} that carries no row `data` (the resource layer reads the row
46
- * and stamps it). This is an internal entry point, not part of the public
47
- * {@link ClaimStream}; application code takes a claim through
48
- * `ablo.<model>.claim({ id })`, which is built on this.
49
- */
50
- claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
51
- attach(transport: ClaimTransport): void;
52
- /**
53
- * Seeds the participant identity once the host resolves it. The stream can
54
- * be built before identity is known — a hosted client learns who it is
55
- * from its credential's scope during connect — and until then the
56
- * construction-time id (possibly empty) would let the participant's own
57
- * claims into `others`. Idempotent; later frames filter on the new id.
58
- */
59
- setParticipant(participant: {
60
- id: string;
61
- }): void;
62
- dispose(): void;
63
- }
64
- export declare function createClaimStream(config: ClaimStreamConfig, transport?: ClaimTransport | null): AttachableClaimStream;