@abloatai/ablo 0.34.1 → 0.35.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 (483) hide show
  1. package/AGENTS.md +2 -1
  2. package/CHANGELOG.md +674 -5
  3. package/README.md +39 -22
  4. package/dist/BaseSyncedStore.d.ts +152 -44
  5. package/dist/BaseSyncedStore.js +300 -184
  6. package/dist/Database.d.ts +9 -24
  7. package/dist/Database.js +37 -22
  8. package/dist/InstanceCache.d.ts +25 -4
  9. package/dist/InstanceCache.js +48 -15
  10. package/dist/LazyReferenceCollection.d.ts +3 -3
  11. package/dist/LazyReferenceCollection.js +4 -4
  12. package/dist/Model.d.ts +6 -6
  13. package/dist/Model.js +10 -10
  14. package/dist/ModelRegistry.d.ts +4 -4
  15. package/dist/ModelRegistry.js +3 -3
  16. package/dist/{SyncEngineContext.d.ts → RuntimeContext.d.ts} +20 -13
  17. package/dist/{SyncEngineContext.js → RuntimeContext.js} +11 -12
  18. package/dist/SyncClient.d.ts +42 -32
  19. package/dist/SyncClient.js +166 -110
  20. package/dist/ai-sdk/coordinatedTool.d.ts +2 -2
  21. package/dist/ai-sdk/coordinatedTool.js +1 -1
  22. package/dist/ai-sdk/coordinationContext.d.ts +2 -2
  23. package/dist/ai-sdk/coordinationContext.js +1 -1
  24. package/dist/ai-sdk/wrap.d.ts +3 -3
  25. package/dist/ai-sdk/wrap.js +2 -2
  26. package/dist/auth/index.d.ts +1 -156
  27. package/dist/auth/index.js +8 -301
  28. package/dist/cli.cjs +3344 -1073
  29. package/dist/client/Ablo.d.ts +42 -287
  30. package/dist/client/Ablo.js +118 -963
  31. package/dist/client/abloClient.d.ts +309 -0
  32. package/dist/client/abloClient.js +13 -0
  33. package/dist/client/clientPrelude.d.ts +52 -0
  34. package/dist/client/clientPrelude.js +60 -0
  35. package/dist/client/consoleLogger.d.ts +2 -2
  36. package/dist/client/coreClient.d.ts +60 -0
  37. package/dist/client/coreClient.js +118 -0
  38. package/dist/client/createInternalComponents.d.ts +4 -4
  39. package/dist/client/createInternalComponents.js +9 -8
  40. package/dist/client/createModelProxy.d.ts +78 -373
  41. package/dist/client/createModelProxy.js +114 -86
  42. package/dist/client/humans.d.ts +48 -0
  43. package/dist/client/humans.js +52 -0
  44. package/dist/client/modelRegistration.d.ts +1 -1
  45. package/dist/client/modelRegistration.js +9 -9
  46. package/dist/client/options.d.ts +73 -17
  47. package/dist/client/reactiveEngine.d.ts +48 -0
  48. package/dist/client/reactiveEngine.js +910 -0
  49. package/dist/client/resourceTypes.d.ts +9 -250
  50. package/dist/client/resourceTypes.js +8 -5
  51. package/dist/client/schemaConfig.d.ts +4 -4
  52. package/dist/client/schemaConfig.js +6 -2
  53. package/dist/client/validateAbloOptions.d.ts +3 -2
  54. package/dist/client/validateAbloOptions.js +1 -1
  55. package/dist/client/wsMutationExecutor.d.ts +3 -3
  56. package/dist/client/wsMutationExecutor.js +3 -3
  57. package/dist/context.d.ts +9 -9
  58. package/dist/context.js +10 -9
  59. package/dist/coordination/ClaimLog.d.ts +26 -0
  60. package/dist/coordination/ClaimLog.js +32 -0
  61. package/dist/coordination/index.d.ts +1 -15
  62. package/dist/coordination/index.js +8 -31
  63. package/dist/core/DatabaseManager.js +1 -1
  64. package/dist/core/QueryView.d.ts +1 -1
  65. package/dist/core/QueryView.js +1 -1
  66. package/dist/core/StoreManager.d.ts +4 -23
  67. package/dist/core/StoreManager.js +5 -55
  68. package/dist/core/index.d.ts +2 -2
  69. package/dist/core/index.js +2 -2
  70. package/dist/core/storeContract.d.ts +2 -2
  71. package/dist/docs/catalog.d.ts +72 -0
  72. package/dist/docs/catalog.js +227 -0
  73. package/dist/docs/index.d.ts +10 -0
  74. package/dist/docs/index.js +10 -0
  75. package/dist/environment.d.ts +1 -40
  76. package/dist/environment.js +8 -37
  77. package/dist/index.d.ts +40 -34
  78. package/dist/index.js +26 -20
  79. package/dist/interfaces/index.d.ts +44 -134
  80. package/dist/keys/index.d.ts +1 -77
  81. package/dist/keys/index.js +8 -190
  82. package/dist/mutators/{RecordingTransaction.d.ts → RecordingMutation.d.ts} +4 -4
  83. package/dist/mutators/{RecordingTransaction.js → RecordingMutation.js} +2 -2
  84. package/dist/mutators/Transaction.d.ts +1 -1
  85. package/dist/mutators/Transaction.js +1 -1
  86. package/dist/mutators/UndoManager.d.ts +6 -6
  87. package/dist/mutators/UndoManager.js +5 -5
  88. package/dist/mutators/defineMutators.d.ts +3 -3
  89. package/dist/mutators/defineMutators.js +1 -1
  90. package/dist/mutators/inverseOp.js +2 -2
  91. package/dist/mutators/mutateActions.d.ts +3 -3
  92. package/dist/mutators/mutateActions.js +1 -1
  93. package/dist/mutators/readerActions.d.ts +1 -1
  94. package/dist/mutators/undoApply.d.ts +1 -1
  95. package/dist/mutators/undoApply.js +1 -1
  96. package/dist/policy/index.d.ts +2 -2
  97. package/dist/policy/index.js +1 -1
  98. package/dist/query/client.d.ts +2 -2
  99. package/dist/query/client.js +4 -4
  100. package/dist/query/types.d.ts +6 -41
  101. package/dist/query/types.js +2 -2
  102. package/dist/react/AbloProvider.d.ts +6 -8
  103. package/dist/react/AbloProvider.js +5 -7
  104. package/dist/react/context.d.ts +1 -1
  105. package/dist/react/context.js +1 -1
  106. package/dist/react/index.d.ts +5 -5
  107. package/dist/react/index.js +3 -3
  108. package/dist/react/internalContext.d.ts +1 -1
  109. package/dist/react/useAblo.d.ts +3 -3
  110. package/dist/react/useAblo.js +1 -1
  111. package/dist/react/useCurrentUserId.js +1 -1
  112. package/dist/react/useErrorListener.js +1 -1
  113. package/dist/react/useMutationFailureListener.d.ts +2 -2
  114. package/dist/react/useMutationFailureListener.js +1 -1
  115. package/dist/react/useMutators.d.ts +3 -3
  116. package/dist/react/useMutators.js +3 -3
  117. package/dist/react/useUndoScope.d.ts +5 -5
  118. package/dist/react/useUndoScope.js +1 -1
  119. package/dist/schema/coordination.d.ts +69 -10
  120. package/dist/schema/coordination.js +86 -9
  121. package/dist/schema/ddl.js +2 -2
  122. package/dist/schema/diff.d.ts +1 -1
  123. package/dist/schema/generate.js +1 -1
  124. package/dist/schema/index.d.ts +10 -10
  125. package/dist/schema/index.js +18 -18
  126. package/dist/schema/queries.d.ts +27 -27
  127. package/dist/schema/queries.js +23 -23
  128. package/dist/schema/select.d.ts +3 -3
  129. package/dist/schema/select.js +3 -3
  130. package/dist/schema/serialize.d.ts +15 -6
  131. package/dist/schema/serialize.js +17 -3
  132. package/dist/schema/sugar.d.ts +6 -7
  133. package/dist/schema/sugar.js +9 -12
  134. package/dist/schema/syncDeltaRow.d.ts +4 -152
  135. package/dist/schema/syncDeltaRow.js +4 -105
  136. package/dist/server/adapter.d.ts +18 -1
  137. package/dist/server/commit.d.ts +10 -16
  138. package/dist/server/index.d.ts +1 -1
  139. package/dist/server/index.js +1 -1
  140. package/dist/server/readConfig.d.ts +1 -1
  141. package/dist/source/adapters/drizzle.d.ts +1 -1
  142. package/dist/source/adapters/drizzle.js +2 -2
  143. package/dist/source/adapters/kysely.d.ts +1 -1
  144. package/dist/source/adapters/kysely.js +1 -1
  145. package/dist/source/adapters/kyselyMutationCore.d.ts +1 -1
  146. package/dist/source/adapters/kyselyMutationCore.js +2 -2
  147. package/dist/source/adapters/memory.js +1 -1
  148. package/dist/source/adapters/prisma.d.ts +8 -3
  149. package/dist/source/adapters/prisma.js +1 -1
  150. package/dist/source/connector.js +1 -1
  151. package/dist/source/connectorProtocol.d.ts +2 -8
  152. package/dist/source/connectorProtocol.js +3 -2
  153. package/dist/source/contract.d.ts +29 -17
  154. package/dist/source/contract.js +27 -22
  155. package/dist/source/factory.d.ts +1 -1
  156. package/dist/source/footprint.d.ts +111 -0
  157. package/dist/source/footprint.js +0 -0
  158. package/dist/source/idempotency.js +2 -2
  159. package/dist/source/index.d.ts +1 -0
  160. package/dist/source/index.js +3 -0
  161. package/dist/source/next.d.ts +1 -1
  162. package/dist/source/signing.d.ts +9 -2
  163. package/dist/source/signing.js +4 -1
  164. package/dist/source/types.d.ts +6 -4
  165. package/dist/source/types.js +1 -1
  166. package/dist/stores/ObjectStore.d.ts +1 -1
  167. package/dist/stores/SyncActionStore.d.ts +1 -1
  168. package/dist/stores/SyncActionStore.js +2 -10
  169. package/dist/stores/syncAction.d.ts +26 -0
  170. package/dist/stores/syncAction.js +16 -0
  171. package/dist/surface.d.ts +3 -3
  172. package/dist/surface.js +6 -4
  173. package/dist/sync/BootstrapFetcher.d.ts +123 -6
  174. package/dist/sync/BootstrapFetcher.js +492 -66
  175. package/dist/sync/ConnectionManager.d.ts +6 -198
  176. package/dist/sync/ConnectionManager.js +6 -677
  177. package/dist/sync/OnDemandLoader.d.ts +2 -2
  178. package/dist/sync/OnDemandLoader.js +60 -21
  179. package/dist/sync/SubscriptionManager.d.ts +13 -2
  180. package/dist/sync/SubscriptionManager.js +23 -5
  181. package/dist/sync/SyncWebSocket.d.ts +27 -510
  182. package/dist/sync/SyncWebSocket.js +76 -954
  183. package/dist/sync/awaitClaimGrant.d.ts +4 -44
  184. package/dist/sync/awaitClaimGrant.js +4 -109
  185. package/dist/sync/commitFrames.d.ts +6 -40
  186. package/dist/sync/commitFrames.js +6 -97
  187. package/dist/sync/contextPorts.d.ts +18 -0
  188. package/dist/sync/contextPorts.js +31 -0
  189. package/dist/sync/createClaimStream.d.ts +5 -49
  190. package/dist/sync/createClaimStream.js +5 -469
  191. package/dist/sync/createPresenceStream.d.ts +26 -4
  192. package/dist/sync/createPresenceStream.js +28 -20
  193. package/dist/sync/createSnapshot.d.ts +2 -2
  194. package/dist/sync/createSnapshot.js +1 -1
  195. package/dist/sync/credentialLifecycle.d.ts +5 -173
  196. package/dist/sync/credentialLifecycle.js +5 -320
  197. package/dist/sync/deltaPipeline.d.ts +1 -1
  198. package/dist/sync/participants.d.ts +5 -4
  199. package/dist/sync/participants.js +29 -22
  200. package/dist/sync/schemaDrift.d.ts +55 -0
  201. package/dist/sync/schemaDrift.js +53 -0
  202. package/dist/sync/schemas.d.ts +21 -32
  203. package/dist/sync/schemas.js +26 -17
  204. package/dist/sync/syncPlan.d.ts +3 -3
  205. package/dist/sync/wsFrameHandlers.d.ts +6 -114
  206. package/dist/sync/wsFrameHandlers.js +6 -392
  207. package/dist/testing/fixtures/bootstrap.d.ts +1 -1
  208. package/dist/testing/fixtures/deltas.d.ts +1 -1
  209. package/dist/testing/fixtures/httpResponses.d.ts +70 -0
  210. package/dist/testing/fixtures/httpResponses.js +90 -0
  211. package/dist/testing/fixtures/models.js +1 -1
  212. package/dist/testing/helpers/wait.js +1 -1
  213. package/dist/testing/mocks/MockMutationExecutor.d.ts +2 -2
  214. package/dist/testing/mocks/MockMutationExecutor.js +8 -14
  215. package/dist/testing/mocks/MockSyncContext.d.ts +11 -11
  216. package/dist/testing/mocks/MockSyncContext.js +10 -9
  217. package/dist/testing/mocks/MockSyncStore.js +1 -1
  218. package/dist/testing/mocks/MockWebSocket.d.ts +2 -2
  219. package/dist/transaction/ablo.d.ts +88 -0
  220. package/dist/transaction/ablo.js +33 -0
  221. package/dist/{client/auth.d.ts → transaction/auth/apiKey.d.ts} +43 -8
  222. package/dist/{client/auth.js → transaction/auth/apiKey.js} +19 -0
  223. package/dist/transaction/auth/bootstrapScope.d.ts +15 -0
  224. package/dist/transaction/auth/bootstrapScope.js +1 -0
  225. package/dist/transaction/auth/capability.d.ts +177 -0
  226. package/dist/transaction/auth/capability.js +199 -0
  227. package/dist/{auth → transaction/auth}/credentialSource.d.ts +8 -1
  228. package/dist/{client → transaction/auth}/identity.d.ts +8 -7
  229. package/dist/{client → transaction/auth}/identity.js +1 -1
  230. package/dist/transaction/auth/index.d.ts +162 -0
  231. package/dist/transaction/auth/index.js +304 -0
  232. package/dist/{auth → transaction/auth}/schemas.d.ts +1 -1
  233. package/dist/{auth → transaction/auth}/schemas.js +13 -13
  234. package/dist/{client → transaction/auth}/sessionMint.d.ts +8 -8
  235. package/dist/{client → transaction/auth}/sessionMint.js +4 -7
  236. package/dist/transaction/coordination/awaitClaimGrant.d.ts +49 -0
  237. package/dist/transaction/coordination/awaitClaimGrant.js +112 -0
  238. package/dist/transaction/coordination/claimMeta.d.ts +49 -0
  239. package/dist/transaction/coordination/claimMeta.js +52 -0
  240. package/dist/transaction/coordination/createClaimStream.d.ts +64 -0
  241. package/dist/transaction/coordination/createClaimStream.js +475 -0
  242. package/dist/transaction/coordination/events.d.ts +74 -0
  243. package/dist/transaction/coordination/events.js +7 -0
  244. package/dist/transaction/coordination/index.d.ts +19 -0
  245. package/dist/transaction/coordination/index.js +44 -0
  246. package/dist/transaction/coordination/locator.d.ts +83 -0
  247. package/dist/transaction/coordination/locator.js +82 -0
  248. package/dist/transaction/coordination/schema.d.ts +1473 -0
  249. package/dist/{coordination → transaction/coordination}/schema.js +490 -55
  250. package/dist/transaction/coordination/targetConflict.d.ts +2 -0
  251. package/dist/transaction/coordination/targetConflict.js +103 -0
  252. package/dist/{coordination → transaction/coordination}/trace.d.ts +7 -18
  253. package/dist/{coordination → transaction/coordination}/trace.js +18 -25
  254. package/dist/transaction/durableWrites.d.ts +62 -0
  255. package/dist/{client → transaction}/durableWrites.js +28 -3
  256. package/dist/transaction/environment.d.ts +105 -0
  257. package/dist/transaction/environment.js +108 -0
  258. package/dist/{errorCodes.d.ts → transaction/errorCodes.d.ts} +11 -11
  259. package/dist/{errorCodes.js → transaction/errorCodes.js} +35 -12
  260. package/dist/{errors.d.ts → transaction/errors.d.ts} +37 -13
  261. package/dist/{errors.js → transaction/errors.js} +85 -16
  262. package/dist/transaction/index.d.ts +20 -0
  263. package/dist/transaction/index.js +20 -0
  264. package/dist/transaction/keys/index.d.ts +87 -0
  265. package/dist/transaction/keys/index.js +207 -0
  266. package/dist/transaction/log/syncDeltaRow.d.ts +158 -0
  267. package/dist/transaction/log/syncDeltaRow.js +95 -0
  268. package/dist/{sync/syncPosition.d.ts → transaction/logPosition.d.ts} +22 -8
  269. package/dist/{sync/syncPosition.js → transaction/logPosition.js} +15 -6
  270. package/dist/transaction/logger.d.ts +16 -0
  271. package/dist/transaction/logger.js +7 -0
  272. package/dist/transaction/observability.d.ts +53 -0
  273. package/dist/transaction/observability.js +19 -0
  274. package/dist/transaction/plugin.d.ts +192 -0
  275. package/dist/transaction/plugin.js +87 -0
  276. package/dist/{policy → transaction/policy}/types.d.ts +3 -3
  277. package/dist/{policy → transaction/policy}/types.js +2 -0
  278. package/dist/transaction/resources/httpResources.d.ts +266 -0
  279. package/dist/transaction/resources/httpResources.js +7 -0
  280. package/dist/transaction/resources/modelOperations.d.ts +319 -0
  281. package/dist/transaction/resources/modelOperations.js +12 -0
  282. package/dist/transaction/resources/mutationOptions.d.ts +66 -0
  283. package/dist/transaction/resources/mutationOptions.js +9 -0
  284. package/dist/transaction/resources/where.d.ts +85 -0
  285. package/dist/transaction/resources/where.js +70 -0
  286. package/dist/{client → transaction/resources}/writeOptionsSchema.d.ts +2 -6
  287. package/dist/{client → transaction/resources}/writeOptionsSchema.js +9 -5
  288. package/dist/{schema → transaction/schema}/field.d.ts +5 -5
  289. package/dist/{schema → transaction/schema}/field.js +5 -5
  290. package/dist/transaction/schema/loadStrategy.d.ts +45 -0
  291. package/dist/transaction/schema/loadStrategy.js +46 -0
  292. package/dist/{schema → transaction/schema}/model.d.ts +50 -35
  293. package/dist/{schema → transaction/schema}/model.js +30 -20
  294. package/dist/transaction/schema/openapi.d.ts +57 -0
  295. package/dist/transaction/schema/openapi.js +340 -0
  296. package/dist/{schema → transaction/schema}/relation.d.ts +14 -14
  297. package/dist/{schema → transaction/schema}/relation.js +7 -7
  298. package/dist/{schema → transaction/schema}/residency.d.ts +0 -9
  299. package/dist/{schema → transaction/schema}/residency.js +0 -5
  300. package/dist/{schema → transaction/schema}/roles.d.ts +5 -5
  301. package/dist/{schema → transaction/schema}/roles.js +5 -5
  302. package/dist/{schema → transaction/schema}/schema.d.ts +12 -10
  303. package/dist/{schema → transaction/schema}/schema.js +4 -3
  304. package/dist/{schema → transaction/schema}/tenancy.d.ts +1 -1
  305. package/dist/{schema → transaction/schema}/tenancy.js +7 -4
  306. package/dist/transaction/transactionLayer.d.ts +82 -0
  307. package/dist/transaction/transactionLayer.js +24 -0
  308. package/dist/{transactions → transaction/transactions/settlement}/commitEnvelope.d.ts +4 -5
  309. package/dist/{transactions → transaction/transactions/settlement}/commitEnvelope.js +9 -13
  310. package/dist/{transactions → transaction/transactions/settlement}/httpCommitEnvelope.d.ts +9 -2
  311. package/dist/{transactions → transaction/transactions/settlement}/httpCommitEnvelope.js +5 -9
  312. package/dist/{transactions/durableWriteStore.d.ts → transaction/transactions/settlement/pendingWrite.d.ts} +10 -36
  313. package/dist/transaction/transactions/settlement/pendingWrite.js +20 -0
  314. package/dist/transaction/transport/commitFrames.d.ts +90 -0
  315. package/dist/transaction/transport/commitFrames.js +134 -0
  316. package/dist/transaction/transport/connectionManager.d.ts +215 -0
  317. package/dist/transaction/transport/connectionManager.js +673 -0
  318. package/dist/transaction/transport/credentialLifecycle.d.ts +177 -0
  319. package/dist/transaction/transport/credentialLifecycle.js +324 -0
  320. package/dist/{sync → transaction/transport}/heartbeat.d.ts +3 -1
  321. package/dist/{sync → transaction/transport}/heartbeat.js +6 -4
  322. package/dist/{client → transaction/transport}/httpClient.d.ts +59 -16
  323. package/dist/{client → transaction/transport}/httpClient.js +5 -5
  324. package/dist/transaction/transport/httpOptions.d.ts +33 -0
  325. package/dist/transaction/transport/httpOptions.js +12 -0
  326. package/dist/{client → transaction/transport}/httpTransport.js +171 -85
  327. package/dist/{sync/NetworkProbe.d.ts → transaction/transport/networkProbe.d.ts} +7 -4
  328. package/dist/{sync/NetworkProbe.js → transaction/transport/networkProbe.js} +14 -13
  329. package/dist/transaction/transport/wsFrameHandlers.d.ts +128 -0
  330. package/dist/transaction/transport/wsFrameHandlers.js +429 -0
  331. package/dist/transaction/transport/wsTransport.d.ts +576 -0
  332. package/dist/transaction/transport/wsTransport.js +1017 -0
  333. package/dist/transaction/types/assertExact.d.ts +17 -0
  334. package/dist/transaction/types/assertExact.js +1 -0
  335. package/dist/{types → transaction/types}/global.d.ts +17 -2
  336. package/dist/{types → transaction/types}/global.js +2 -1
  337. package/dist/{types → transaction/types}/index.d.ts +14 -46
  338. package/dist/{types → transaction/types}/index.js +7 -16
  339. package/dist/{types → transaction/types}/streams.d.ts +63 -45
  340. package/dist/{utils → transaction/utils}/json.d.ts +18 -0
  341. package/dist/transaction/utils/json.js +276 -0
  342. package/dist/transaction/wire/accountResponses.d.ts +351 -0
  343. package/dist/transaction/wire/accountResponses.js +255 -0
  344. package/dist/transaction/wire/auth.d.ts +49 -0
  345. package/dist/transaction/wire/auth.js +57 -0
  346. package/dist/transaction/wire/claimEvent.d.ts +76 -0
  347. package/dist/transaction/wire/claimEvent.js +73 -0
  348. package/dist/transaction/wire/claims.d.ts +463 -0
  349. package/dist/transaction/wire/claims.js +229 -0
  350. package/dist/{wire → transaction/wire}/commit.d.ts +125 -193
  351. package/dist/{wire → transaction/wire}/commit.js +68 -47
  352. package/dist/{wire → transaction/wire}/delta.d.ts +66 -17
  353. package/dist/{wire → transaction/wire}/delta.js +37 -13
  354. package/dist/transaction/wire/errorEnvelope.d.ts +72 -0
  355. package/dist/{wire → transaction/wire}/errorEnvelope.js +36 -5
  356. package/dist/transaction/wire/feedCursor.d.ts +60 -0
  357. package/dist/transaction/wire/feedCursor.js +82 -0
  358. package/dist/transaction/wire/feedEvent.d.ts +177 -0
  359. package/dist/transaction/wire/feedEvent.js +39 -0
  360. package/dist/transaction/wire/frames.d.ts +194 -0
  361. package/dist/transaction/wire/frames.js +50 -0
  362. package/dist/transaction/wire/inboundFrames.d.ts +552 -0
  363. package/dist/transaction/wire/inboundFrames.js +116 -0
  364. package/dist/transaction/wire/index.d.ts +50 -0
  365. package/dist/transaction/wire/index.js +74 -0
  366. package/dist/{wire → transaction/wire}/listEnvelope.d.ts +13 -14
  367. package/dist/transaction/wire/listEnvelope.js +42 -0
  368. package/dist/transaction/wire/modelResponses.d.ts +85 -0
  369. package/dist/transaction/wire/modelResponses.js +43 -0
  370. package/dist/transactions/{TransactionQueue.d.ts → mutations/MutationQueue.d.ts} +79 -38
  371. package/dist/transactions/{TransactionQueue.js → mutations/MutationQueue.js} +110 -59
  372. package/dist/transactions/{TransactionStore.d.ts → mutations/MutationStore.d.ts} +8 -8
  373. package/dist/transactions/{TransactionStore.js → mutations/MutationStore.js} +2 -2
  374. package/dist/transactions/{coalesceRules.d.ts → mutations/coalesceRules.d.ts} +10 -10
  375. package/dist/transactions/{coalesceRules.js → mutations/coalesceRules.js} +1 -1
  376. package/dist/transactions/mutations/commitLatency.d.ts +52 -0
  377. package/dist/transactions/mutations/commitLatency.js +130 -0
  378. package/dist/transactions/{commitOutboxStore.d.ts → mutations/commitOutboxStore.d.ts} +1 -5
  379. package/dist/transactions/{commitOutboxStore.js → mutations/commitOutboxStore.js} +1 -1
  380. package/dist/transactions/{commitPayload.d.ts → mutations/commitPayload.d.ts} +16 -15
  381. package/dist/transactions/{commitPayload.js → mutations/commitPayload.js} +12 -12
  382. package/dist/transactions/{deltaConfirmation.d.ts → mutations/deltaConfirmation.d.ts} +11 -11
  383. package/dist/transactions/{deltaConfirmation.js → mutations/deltaConfirmation.js} +7 -7
  384. package/dist/transactions/mutations/durableWriteStore.d.ts +14 -0
  385. package/dist/transactions/mutations/durableWriteStore.js +12 -0
  386. package/dist/transactions/{optimisticApply.d.ts → mutations/optimisticApply.d.ts} +7 -7
  387. package/dist/transactions/{replayValidation.d.ts → mutations/replayValidation.d.ts} +3 -3
  388. package/dist/transactions/{replayValidation.js → mutations/replayValidation.js} +4 -3
  389. package/dist/utils/mobxSetup.d.ts +1 -1
  390. package/dist/utils/mobxSetup.js +5 -2
  391. package/dist/webhooks/events.d.ts +2 -2
  392. package/dist/wire/index.d.ts +1 -34
  393. package/dist/wire/index.js +8 -49
  394. package/docs/agent-messaging.md +3 -3
  395. package/docs/agents.md +19 -12
  396. package/docs/api-keys.md +8 -4
  397. package/docs/api.md +22 -18
  398. package/docs/audit.md +2 -0
  399. package/docs/cli.md +31 -3
  400. package/docs/client-behavior.md +8 -6
  401. package/docs/concurrency-convention.md +30 -24
  402. package/docs/coordination.md +48 -38
  403. package/docs/data-sources.md +3 -1
  404. package/docs/debugging.md +5 -3
  405. package/docs/deployment.md +267 -0
  406. package/docs/examples/agent-human.md +49 -42
  407. package/docs/examples/ai-sdk-tool.md +69 -44
  408. package/docs/examples/existing-python-backend.md +8 -6
  409. package/docs/examples/nextjs.md +129 -47
  410. package/docs/examples/scoped-agent.md +45 -44
  411. package/docs/examples/server-agent.md +46 -26
  412. package/docs/groups.md +32 -29
  413. package/docs/guarantees.md +4 -2
  414. package/docs/how-it-works.md +9 -7
  415. package/docs/idempotency.md +126 -0
  416. package/docs/identity.md +58 -54
  417. package/docs/index.md +172 -86
  418. package/docs/integration-guide.md +17 -16
  419. package/docs/interaction-model.md +6 -4
  420. package/docs/mcp.md +41 -16
  421. package/docs/migration.md +63 -5
  422. package/docs/operating-on-your-database.md +3 -1
  423. package/docs/projects.md +2 -0
  424. package/docs/quickstart.md +22 -5
  425. package/docs/react.md +12 -10
  426. package/docs/schema-contract.md +5 -3
  427. package/docs/session-settings.md +108 -0
  428. package/docs/sessions.md +3 -1
  429. package/docs/webhooks.md +3 -1
  430. package/llms.txt +47 -17
  431. package/package.json +10 -8
  432. package/dist/agent/Agent.d.ts +0 -366
  433. package/dist/agent/Agent.js +0 -514
  434. package/dist/agent/index.d.ts +0 -115
  435. package/dist/agent/index.js +0 -128
  436. package/dist/agent/session.d.ts +0 -93
  437. package/dist/agent/session.js +0 -149
  438. package/dist/agent/types.d.ts +0 -68
  439. package/dist/agent/types.js +0 -9
  440. package/dist/client/durableWrites.d.ts +0 -21
  441. package/dist/coordination/schema.d.ts +0 -722
  442. package/dist/schema/openapi.d.ts +0 -29
  443. package/dist/schema/openapi.js +0 -124
  444. package/dist/transactions/durableWriteStore.js +0 -30
  445. package/dist/utils/json.js +0 -88
  446. package/dist/wire/errorEnvelope.d.ts +0 -55
  447. package/dist/wire/frames.d.ts +0 -197
  448. package/dist/wire/frames.js +0 -49
  449. package/dist/wire/listEnvelope.js +0 -18
  450. /package/dist/{client → transaction/auth}/credentialEndpoint.d.ts +0 -0
  451. /package/dist/{client → transaction/auth}/credentialEndpoint.js +0 -0
  452. /package/dist/{auth → transaction/auth}/credentialPolicy.d.ts +0 -0
  453. /package/dist/{auth → transaction/auth}/credentialPolicy.js +0 -0
  454. /package/dist/{auth → transaction/auth}/credentialSource.js +0 -0
  455. /package/dist/{client → transaction/auth}/hostedEndpoints.d.ts +0 -0
  456. /package/dist/{client → transaction/auth}/hostedEndpoints.js +0 -0
  457. /package/dist/{client → transaction/coordination}/claimHeartbeatLoop.d.ts +0 -0
  458. /package/dist/{client → transaction/coordination}/claimHeartbeatLoop.js +0 -0
  459. /package/dist/{client → transaction}/persistence.d.ts +0 -0
  460. /package/dist/{client → transaction}/persistence.js +0 -0
  461. /package/dist/{client → transaction/resources}/functionalUpdate.d.ts +0 -0
  462. /package/dist/{client → transaction/resources}/functionalUpdate.js +0 -0
  463. /package/dist/{transactions → transaction/transactions/settlement}/idempotencyKey.d.ts +0 -0
  464. /package/dist/{transactions → transaction/transactions/settlement}/idempotencyKey.js +0 -0
  465. /package/dist/{client → transaction/transport}/httpTransport.d.ts +0 -0
  466. /package/dist/{types → transaction/types}/modelData.d.ts +0 -0
  467. /package/dist/{types → transaction/types}/modelData.js +0 -0
  468. /package/dist/{types → transaction/types}/participant.d.ts +0 -0
  469. /package/dist/{types → transaction/types}/participant.js +0 -0
  470. /package/dist/{types → transaction/types}/streams.js +0 -0
  471. /package/dist/{utils → transaction/utils}/asyncIterator.d.ts +0 -0
  472. /package/dist/{utils → transaction/utils}/asyncIterator.js +0 -0
  473. /package/dist/{utils → transaction/utils}/duration.d.ts +0 -0
  474. /package/dist/{utils → transaction/utils}/duration.js +0 -0
  475. /package/dist/{wire → transaction/wire}/bootstrapReason.d.ts +0 -0
  476. /package/dist/{wire → transaction/wire}/bootstrapReason.js +0 -0
  477. /package/dist/{wire → transaction/wire}/protocol.d.ts +0 -0
  478. /package/dist/{wire → transaction/wire}/protocol.js +0 -0
  479. /package/dist/{wire → transaction/wire}/protocolVersion.d.ts +0 -0
  480. /package/dist/{wire → transaction/wire}/protocolVersion.js +0 -0
  481. /package/dist/transactions/{UnconfirmedWrites.d.ts → mutations/UnconfirmedWrites.d.ts} +0 -0
  482. /package/dist/transactions/{UnconfirmedWrites.js → mutations/UnconfirmedWrites.js} +0 -0
  483. /package/dist/transactions/{optimisticApply.js → mutations/optimisticApply.js} +0 -0
package/dist/transaction/keys/index.js ADDED
@@ -0,0 +1,207 @@
1
+ /**
2
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
3
+ * place so every component that issues or checks a key agrees on the format.
4
+ *
5
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
6
+ * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
7
+ * so a browser bundle never pulls in `node:crypto`.
8
+ *
9
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
10
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
11
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
12
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
13
+ * mistyped or forged key locally, without a database round-trip. Older keys
14
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
15
+ * and parse here with `checksummed: false`.
16
+ */
17
+ import { createHash, randomBytes } from 'node:crypto';
18
+ import { z } from 'zod';
19
+ import { KEY_ENVIRONMENTS, KEY_PREFIX_ENVIRONMENTS, environmentFromKeyPrefix, environmentToKeyPrefix, } from '../environment.js';
20
+ // ── Vocabulary ──────────────────────────────────────────────────────────
21
+ // The four key kinds:
22
+ // secret (sk_) — backend and server-to-server use, including agents. Full
23
+ // authority; never expose one in a browser.
24
+ // restricted (rk_) — a scoped server key, such as an agent session token or a
25
+ // narrowed capability.
26
+ // ephemeral (ek_) — a short-lived, backend-minted session credential scoped to
27
+ // one user, safe to hand to that user's browser. Carries
28
+ // `participantKind: 'user'` and its baked-in sync groups.
29
+ // publishable (pk_) — a long-lived, browser-safe, organization-scoped read-only
30
+ // key. It is used directly as the bearer token — never
31
+ // exchanged, never expires, nothing to refresh. It grants
32
+ // read access to the organization's data and cannot write or
33
+ // reach any control-plane operation.
34
+ export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral', 'publishable'];
35
+ // A key's environment is the CREDENTIAL axis, not the plane axis: the format
36
+ // below spells it as one of two prefixes, so a plane name outside those two has
37
+ // no representation here and must not reach `generateApiKey`.
38
+ export const API_KEY_ENVS = KEY_ENVIRONMENTS;
39
+ const PREFIX_BY_KIND = {
40
+ secret: 'sk',
41
+ restricted: 'rk',
42
+ ephemeral: 'ek',
43
+ publishable: 'pk',
44
+ };
45
+ const KIND_BY_PREFIX = {
46
+ sk: 'secret',
47
+ rk: 'restricted',
48
+ ek: 'ephemeral',
49
+ pk: 'publishable',
50
+ };
51
+ const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
52
+ /** Random base62 chars before the checksum. */
53
+ const KEY_BODY_LEN = 30;
54
+ /** base62(CRC32): 62^6 (~5.7e10) > 2^32, so a CRC32 always fits in 6 chars. */
55
+ const CHECKSUM_LEN = 6;
56
+ /** A new checksummed body is exactly this long and pure base62. */
57
+ const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
58
+ /** `<sk|rk|ek|pk>_<live|test>_<body>`; the body charset covers base62 as well as the legacy base64url form. */
59
+ const KEY_RE = /^(sk|rk|ek|pk)_(live|test)_([0-9A-Za-z\-_]+)$/;
60
+ const BASE62_RE = /^[0-9A-Za-z]+$/;
61
+ // ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
62
+ const CRC32_TABLE = (() => {
63
+ const t = new Uint32Array(256);
64
+ for (let n = 0; n < 256; n++) {
65
+ let c = n;
66
+ for (let k = 0; k < 8; k++)
67
+ c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
68
+ t[n] = c >>> 0;
69
+ }
70
+ return t;
71
+ })();
72
+ function crc32(s) {
73
+ let c = 0xffffffff;
74
+ for (let i = 0; i < s.length; i++) {
75
+ // `& 0xff` bounds the index to the 256-entry table — the ?? 0 is unreachable.
76
+ c = ((CRC32_TABLE[(c ^ s.charCodeAt(i)) & 0xff] ?? 0) ^ (c >>> 8)) >>> 0;
77
+ }
78
+ return (c ^ 0xffffffff) >>> 0;
79
+ }
80
+ /** 6-char base62 encoding of the CRC32 of `payload`. */
81
+ function checksum6(payload) {
82
+ let n = crc32(payload);
83
+ let out = '';
84
+ for (let i = 0; i < CHECKSUM_LEN; i++) {
85
+ out = BASE62.charAt(n % 62) + out;
86
+ n = Math.floor(n / 62);
87
+ }
88
+ return out;
89
+ }
90
+ /** `len` cryptographically-random base62 chars (rejection-sampled, no bias). */
91
+ function randomBase62(len) {
92
+ let out = '';
93
+ while (out.length < len) {
94
+ for (const b of randomBytes(len * 2)) {
95
+ if (b < 248) {
96
+ out += BASE62.charAt(b % 62);
97
+ if (out.length === len)
98
+ break;
99
+ }
100
+ }
101
+ }
102
+ return out;
103
+ }
104
+ function bodyIsChecksummed(body) {
105
+ return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
106
+ }
107
+ /**
108
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
109
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
110
+ * rejected without any network call; an older key with no checksum parses with
111
+ * `checksummed: false` and is left for the server to validate by hash.
112
+ */
113
+ export const apiKeySchema = z.string().transform((raw, ctx) => {
114
+ const m = KEY_RE.exec(raw);
115
+ if (!m) {
116
+ ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
117
+ return z.NEVER;
118
+ }
119
+ const [, prefix, env, body] = m;
120
+ const kind = prefix === undefined ? undefined : KIND_BY_PREFIX[prefix];
121
+ // Unreachable on a KEY_RE match (all three groups are non-optional and the
122
+ // prefix alternation is exactly the KIND_BY_PREFIX key set) — narrows the
123
+ // regex-group lookups for the checks below.
124
+ if (kind === undefined || env === undefined || body === undefined) {
125
+ ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
126
+ return z.NEVER;
127
+ }
128
+ const checksummed = bodyIsChecksummed(body);
129
+ if (checksummed && checksum6(raw.slice(0, -CHECKSUM_LEN)) !== body.slice(KEY_BODY_LEN)) {
130
+ ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
131
+ return z.NEVER;
132
+ }
133
+ return {
134
+ raw,
135
+ kind,
136
+ env: environmentFromKeyPrefix(env),
137
+ body,
138
+ checksummed,
139
+ };
140
+ });
141
+ // ── Derived validators (thin wrappers over the same spec) ───────────────
142
+ /** Parse + fully validate (incl. checksum). Returns null when invalid. */
143
+ export function parseApiKey(raw) {
144
+ const r = apiKeySchema.safeParse(raw);
145
+ return r.success ? r.data : null;
146
+ }
147
+ /**
148
+ * Read the environment off a STORED display prefix (`keyPrefix`, the first 12
149
+ * chars — `rk_test_abcd`), rather than off a full plaintext key.
150
+ *
151
+ * A key row records its environment nowhere but its prefix, so this is how a
152
+ * server-side flow that only has the row — rotation, most importantly — recovers
153
+ * the credential's own mode. Returns null when the prefix is not a recognizable
154
+ * key spelling, so callers can fail closed rather than fall back to a default.
155
+ */
156
+ export function environmentFromStoredKeyPrefix(prefix) {
157
+ const spelling = /^(?:sk|rk|ek|pk)_([a-z]+)_/.exec(prefix)?.[1];
158
+ const env = KEY_PREFIX_ENVIRONMENTS.find((candidate) => candidate === spelling);
159
+ return env === undefined ? null : environmentFromKeyPrefix(env);
160
+ }
161
+ /** True when the key uses the new checksummed format (regardless of validity). */
162
+ export function isChecksummedKey(raw) {
163
+ const body = KEY_RE.exec(raw)?.[3];
164
+ return body !== undefined && bodyIsChecksummed(body);
165
+ }
166
+ /** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
167
+ export function keyChecksumMatches(raw) {
168
+ const body = KEY_RE.exec(raw)?.[3];
169
+ if (body === undefined || !bodyIsChecksummed(body))
170
+ return false;
171
+ return checksum6(raw.slice(0, -CHECKSUM_LEN)) === body.slice(KEY_BODY_LEN);
172
+ }
173
+ // ── Mint + hash (node:crypto) ───────────────────────────────────────────
174
+ /**
175
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
176
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
177
+ */
178
+ export function generateApiKey(env = 'production', kind = 'secret') {
179
+ const body = randomBase62(KEY_BODY_LEN);
180
+ const payload = `${PREFIX_BY_KIND[kind]}_${environmentToKeyPrefix(env)}_${body}`;
181
+ const plaintext = `${payload}${checksum6(payload)}`;
182
+ return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
183
+ }
184
+ /**
185
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
186
+ * minted and when one is looked up. A fast hash is the right choice here rather
187
+ * than a password hash like bcrypt: API keys are long random strings, so there is
188
+ * no dictionary of guesses to slow down.
189
+ */
190
+ export function hashApiKey(plaintext) {
191
+ return createHash('sha256').update(plaintext).digest('hex');
192
+ }
193
+ /** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
194
+ export const WEBHOOK_SECRET_PREFIX = 'whsec_';
195
+ /**
196
+ * Mints a webhook signing secret following the Standard Webhooks specification
197
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
198
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
199
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
200
+ * because signing a request with {@link signAbloSourceRequest} needs the live
201
+ * value. It is therefore kept in a secret store, returned to the customer once at
202
+ * creation, and never shown again.
203
+ */
204
+ export function generateWebhookSecret() {
205
+ const plaintext = `${WEBHOOK_SECRET_PREFIX}${randomBytes(32).toString('base64')}`;
206
+ return { plaintext, last4: plaintext.slice(-4) };
207
+ }
package/dist/transaction/log/syncDeltaRow.d.ts ADDED
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
3
+ * one committed change. The row is split into two slices by the concern each one
4
+ * serves:
5
+ *
6
+ * - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
7
+ * needs to reconstruct the change, plus the tenant key. This is a portable
8
+ * payload shape; it is not a statement that the row is physically stored in
9
+ * the customer's database.
10
+ * - {@link deltaAttributionSchema} — who made the change, and on whose authority.
11
+ *
12
+ * {@link syncDeltaRowSchema} composes both into the full stored row.
13
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
14
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
15
+ * Keeping those axes separate prevents a portable schema slice from being cited
16
+ * incorrectly as a physical-residency guarantee.
17
+ *
18
+ * This is the stored shape. The delta broadcast to clients is a narrower projection
19
+ * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
20
+ * the field names here mirror those on that wire delta.
21
+ */
22
+ import { z } from 'zod';
23
+ export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
24
+ export type { ParticipantKind, ConfirmationState } from '../wire/delta.js';
25
+ /** `backfill_provenance` */
26
+ export declare const backfillProvenanceSchema: z.ZodEnum<{
27
+ unknown: "unknown";
28
+ exact: "exact";
29
+ inferred: "inferred";
30
+ }>;
31
+ export type BackfillProvenance = z.infer<typeof backfillProvenanceSchema>;
32
+ /**
33
+ * Everything a client needs to materialize the change, plus the tenant key. This
34
+ * is the portable shape an authoritative WAL change or endpoint event carries.
35
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
36
+ * sync log; it is not written atomically with a direct application-row mutation.
37
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
38
+ * appended, so they are optional at the ingestion boundary.
39
+ */
40
+ export declare const syncDeltaCoreSchema: z.ZodObject<{
41
+ id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
42
+ actionType: z.ZodEnum<{
43
+ I: "I";
44
+ U: "U";
45
+ D: "D";
46
+ A: "A";
47
+ V: "V";
48
+ C: "C";
49
+ G: "G";
50
+ S: "S";
51
+ }>;
52
+ modelName: z.ZodString;
53
+ modelId: z.ZodString;
54
+ data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
55
+ previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
56
+ syncGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
57
+ organizationId: z.ZodNullable<z.ZodString>;
58
+ createdAt: z.ZodOptional<z.ZodString>;
59
+ transactionId: z.ZodNullable<z.ZodString>;
60
+ sourceChangeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
61
+ }, z.core.$strip>;
62
+ export type SyncDeltaCore = z.infer<typeof syncDeltaCoreSchema>;
63
+ export declare const deltaAttributionSchema: z.ZodObject<{
64
+ createdBy: z.ZodNullable<z.ZodString>;
65
+ actorId: z.ZodNullable<z.ZodString>;
66
+ actorKind: z.ZodNullable<z.ZodEnum<{
67
+ user: "user";
68
+ agent: "agent";
69
+ system: "system";
70
+ }>>;
71
+ onBehalfOfId: z.ZodNullable<z.ZodString>;
72
+ onBehalfOfKind: z.ZodNullable<z.ZodEnum<{
73
+ user: "user";
74
+ agent: "agent";
75
+ system: "system";
76
+ }>>;
77
+ capabilityId: z.ZodNullable<z.ZodString>;
78
+ delegationChainRootUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
79
+ confirmationState: z.ZodNullable<z.ZodEnum<{
80
+ auto: "auto";
81
+ previewed: "previewed";
82
+ approved: "approved";
83
+ required_human_approval: "required_human_approval";
84
+ auto_historical: "auto_historical";
85
+ }>>;
86
+ backfillProvenance: z.ZodNullable<z.ZodEnum<{
87
+ unknown: "unknown";
88
+ exact: "exact";
89
+ inferred: "inferred";
90
+ }>>;
91
+ }, z.core.$strip>;
92
+ export type DeltaAttribution = z.infer<typeof deltaAttributionSchema>;
93
+ /** The complete `sync_deltas` row: core and attribution combined. */
94
+ export declare const syncDeltaRowSchema: z.ZodObject<{
95
+ id: z.ZodOptional<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber]>>;
96
+ actionType: z.ZodEnum<{
97
+ I: "I";
98
+ U: "U";
99
+ D: "D";
100
+ A: "A";
101
+ V: "V";
102
+ C: "C";
103
+ G: "G";
104
+ S: "S";
105
+ }>;
106
+ modelName: z.ZodString;
107
+ modelId: z.ZodString;
108
+ data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
109
+ previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
110
+ syncGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
111
+ organizationId: z.ZodNullable<z.ZodString>;
112
+ createdAt: z.ZodOptional<z.ZodString>;
113
+ transactionId: z.ZodNullable<z.ZodString>;
114
+ sourceChangeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
115
+ createdBy: z.ZodNullable<z.ZodString>;
116
+ actorId: z.ZodNullable<z.ZodString>;
117
+ actorKind: z.ZodNullable<z.ZodEnum<{
118
+ user: "user";
119
+ agent: "agent";
120
+ system: "system";
121
+ }>>;
122
+ onBehalfOfId: z.ZodNullable<z.ZodString>;
123
+ onBehalfOfKind: z.ZodNullable<z.ZodEnum<{
124
+ user: "user";
125
+ agent: "agent";
126
+ system: "system";
127
+ }>>;
128
+ capabilityId: z.ZodNullable<z.ZodString>;
129
+ delegationChainRootUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
130
+ confirmationState: z.ZodNullable<z.ZodEnum<{
131
+ auto: "auto";
132
+ previewed: "previewed";
133
+ approved: "approved";
134
+ required_human_approval: "required_human_approval";
135
+ auto_historical: "auto_historical";
136
+ }>>;
137
+ backfillProvenance: z.ZodNullable<z.ZodEnum<{
138
+ unknown: "unknown";
139
+ exact: "exact";
140
+ inferred: "inferred";
141
+ }>>;
142
+ }, z.core.$strip>;
143
+ export type SyncDeltaRow = z.infer<typeof syncDeltaRowSchema>;
144
+ /** Which slices contain retained customer row data versus control metadata. */
145
+ export declare const DELTA_DATA_CLASSIFICATION: {
146
+ readonly core: "customer-data";
147
+ readonly attribution: "control-metadata";
148
+ };
149
+ /**
150
+ * Where the current runtime physically persists each slice. Both live in
151
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
152
+ * payloads (and optional previous payloads), so `control` here must not be read
153
+ * as "metadata only."
154
+ */
155
+ export declare const DELTA_PHYSICAL_STORAGE: {
156
+ readonly core: "control";
157
+ readonly attribution: "control";
158
+ };
package/dist/transaction/log/syncDeltaRow.js ADDED
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
3
+ * one committed change. The row is split into two slices by the concern each one
4
+ * serves:
5
+ *
6
+ * - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
7
+ * needs to reconstruct the change, plus the tenant key. This is a portable
8
+ * payload shape; it is not a statement that the row is physically stored in
9
+ * the customer's database.
10
+ * - {@link deltaAttributionSchema} — who made the change, and on whose authority.
11
+ *
12
+ * {@link syncDeltaRowSchema} composes both into the full stored row.
13
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
14
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
15
+ * Keeping those axes separate prevents a portable schema slice from being cited
16
+ * incorrectly as a physical-residency guarantee.
17
+ *
18
+ * This is the stored shape. The delta broadcast to clients is a narrower projection
19
+ * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
20
+ * the field names here mirror those on that wire delta.
21
+ */
22
+ import { z } from 'zod';
23
+ import { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, } from '../wire/delta.js';
24
+ // ── Enumerations that mirror the corresponding Postgres enum types ────────────
25
+ // `participant_kind` and `confirmation_state` are shared with the wire delta and
26
+ // live at the wire layer (see `../wire/delta.js`); they are re-exported here so
27
+ // code that imports them from `schema` keeps resolving.
28
+ export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
29
+ /** `backfill_provenance` */
30
+ export const backfillProvenanceSchema = z.enum(['exact', 'inferred', 'unknown']);
31
+ /** A delta payload: the full post-mutation row (or null for deletes). */
32
+ const deltaDataSchema = z.record(z.string(), z.unknown()).nullable();
33
+ // ── Core — the sync-protocol slice ────────────────────────────────────────────
34
+ /**
35
+ * Everything a client needs to materialize the change, plus the tenant key. This
36
+ * is the portable shape an authoritative WAL change or endpoint event carries.
37
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
38
+ * sync log; it is not written atomically with a direct application-row mutation.
39
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
40
+ * appended, so they are optional at the ingestion boundary.
41
+ */
42
+ export const syncDeltaCoreSchema = z.object({
43
+ /** Monotonically increasing sync id, assigned by the server when the delta is appended; absent on an outbox marker. */
44
+ id: z.union([z.bigint(), z.number()]).optional(),
45
+ /** The `action_type` column; its eight values are owned by the wire delta contract. */
46
+ actionType: syncDeltaActionSchema,
47
+ modelName: z.string().min(1),
48
+ modelId: z.string().min(1),
49
+ data: deltaDataSchema,
50
+ previousData: deltaDataSchema.optional(),
51
+ /** Routing keys that decide which subscribers receive this delta; computed by the server at append time. */
52
+ syncGroups: z.array(z.string()).optional(),
53
+ /** The committing organization id — the coarse-grained tenant-isolation boundary. */
54
+ organizationId: z.string().nullable(),
55
+ /** ISO 8601 timestamp, assigned by the server when the delta is appended. */
56
+ createdAt: z.string().optional(),
57
+ transactionId: z.string().nullable(),
58
+ /**
59
+ * Stable identity of the authoritative WAL row or endpoint event. It is
60
+ * nullable for hosted/legacy rows and is never exposed as the optimistic
61
+ * client transaction id.
62
+ */
63
+ sourceChangeId: z.string().min(1).nullable().optional(),
64
+ });
65
+ // ── Attribution — who made the change, and on whose authority ─────────────────
66
+ export const deltaAttributionSchema = z.object({
67
+ /** The acting participant, recorded as a single column for compatibility; the structured pair below is the richer form. */
68
+ createdBy: z.string().nullable(),
69
+ actorId: z.string().nullable(),
70
+ actorKind: participantKindSchema.nullable(),
71
+ onBehalfOfId: z.string().nullable(),
72
+ onBehalfOfKind: participantKindSchema.nullable(),
73
+ capabilityId: z.string().nullable(),
74
+ delegationChainRootUserId: z.string().nullable().optional(),
75
+ confirmationState: confirmationStateSchema.nullable(),
76
+ backfillProvenance: backfillProvenanceSchema.nullable(),
77
+ });
78
+ // ── Full stored row, classification, and physical storage ─────────────────────
79
+ /** The complete `sync_deltas` row: core and attribution combined. */
80
+ export const syncDeltaRowSchema = syncDeltaCoreSchema.extend(deltaAttributionSchema.shape);
81
+ /** Which slices contain retained customer row data versus control metadata. */
82
+ export const DELTA_DATA_CLASSIFICATION = {
83
+ core: 'customer-data',
84
+ attribution: 'control-metadata',
85
+ };
86
+ /**
87
+ * Where the current runtime physically persists each slice. Both live in
88
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
89
+ * payloads (and optional previous payloads), so `control` here must not be read
90
+ * as "metadata only."
91
+ */
92
+ export const DELTA_PHYSICAL_STORAGE = {
93
+ core: 'control',
94
+ attribution: 'control',
95
+ };
package/dist/{sync/syncPosition.d.ts → transaction/logPosition.d.ts} RENAMED
@@ -30,18 +30,18 @@
30
30
  * necessarily lands above our acknowledgement and still rejects as stale.
31
31
  *
32
32
  * The validation schema is the state shape: the class holds exactly one
33
- * {@link SyncPositionSnapshot} and merges monotonically into it, so snapshot
34
- * and restore share that shape and {@link parseSyncPosition} is the single gate
33
+ * {@link LogPositionSnapshot} and merges monotonically into it, so snapshot
34
+ * and restore share that shape and {@link parseLogPosition} is the single gate
35
35
  * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
36
36
  * being a known failure mode.
37
37
  */
38
38
  import { z } from 'zod';
39
- export declare const syncPositionSchema: z.ZodObject<{
39
+ export declare const logPositionSchema: z.ZodObject<{
40
40
  persisted: z.ZodNumber;
41
41
  applied: z.ZodNumber;
42
42
  acked: z.ZodNumber;
43
43
  }, z.core.$strip>;
44
- export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
44
+ export type LogPositionSnapshot = z.infer<typeof logPositionSchema>;
45
45
  /**
46
46
  * Only the `persisted` cursor is stored durably; `applied` and `acked` are
47
47
  * not. On resume the object pool is rebuilt from the persisted state, so the
@@ -54,15 +54,15 @@ export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
54
54
  * Validates an untrusted value, such as one loaded from disk, into a position
55
55
  * snapshot, or returns null when it does not match the schema.
56
56
  */
57
- export declare function parseSyncPosition(value: unknown): SyncPositionSnapshot | null;
57
+ export declare function parseLogPosition(value: unknown): LogPositionSnapshot | null;
58
58
  /**
59
59
  * The live sync position: one instance per client. Three producers each
60
60
  * advance their own cursor, and consumers read the result.
61
61
  */
62
- export declare class SyncPosition {
62
+ export declare class LogPosition {
63
63
  #private;
64
64
  /** Returns a copy of the current state in the schema's shape. */
65
- snapshot(): SyncPositionSnapshot;
65
+ snapshot(): LogPositionSnapshot;
66
66
  get persisted(): number;
67
67
  get applied(): number;
68
68
  get acked(): number;
@@ -79,5 +79,19 @@ export declare class SyncPosition {
79
79
  /** Records that the server acknowledged one of this client's commits at the given position. */
80
80
  noteAck(lastSyncId: number | undefined): void;
81
81
  /** Restores from an already-validated snapshot, for example on resume from disk. The merge is monotonic. */
82
- restore(snapshot: SyncPositionSnapshot): void;
82
+ restore(snapshot: LogPositionSnapshot): void;
83
83
  }
84
+ /** @deprecated Renamed to {@link logPositionSchema}. Removed in 0.36.0. */
85
+ export declare const syncPositionSchema: z.ZodObject<{
86
+ persisted: z.ZodNumber;
87
+ applied: z.ZodNumber;
88
+ acked: z.ZodNumber;
89
+ }, z.core.$strip>;
90
+ /** @deprecated Renamed to {@link LogPositionSnapshot}. Removed in 0.36.0. */
91
+ export type SyncPositionSnapshot = LogPositionSnapshot;
92
+ /** @deprecated Renamed to {@link parseLogPosition}. Removed in 0.36.0. */
93
+ export declare const parseSyncPosition: typeof parseLogPosition;
94
+ /** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
95
+ export declare const SyncPosition: typeof LogPosition;
96
+ /** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
97
+ export type SyncPosition = LogPosition;
package/dist/{sync/syncPosition.js → transaction/logPosition.js} RENAMED
@@ -30,13 +30,13 @@
30
30
  * necessarily lands above our acknowledgement and still rejects as stale.
31
31
  *
32
32
  * The validation schema is the state shape: the class holds exactly one
33
- * {@link SyncPositionSnapshot} and merges monotonically into it, so snapshot
34
- * and restore share that shape and {@link parseSyncPosition} is the single gate
33
+ * {@link LogPositionSnapshot} and merges monotonically into it, so snapshot
34
+ * and restore share that shape and {@link parseLogPosition} is the single gate
35
35
  * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
36
36
  * being a known failure mode.
37
37
  */
38
38
  import { z } from 'zod';
39
- export const syncPositionSchema = z.object({
39
+ export const logPositionSchema = z.object({
40
40
  /** The resume cursor; advances only after deltas persist to durable local storage. */
41
41
  persisted: z.number().int().nonnegative(),
42
42
  /** The in-memory cursor: the last delta applied to the object pool. */
@@ -56,8 +56,8 @@ export const syncPositionSchema = z.object({
56
56
  * Validates an untrusted value, such as one loaded from disk, into a position
57
57
  * snapshot, or returns null when it does not match the schema.
58
58
  */
59
- export function parseSyncPosition(value) {
60
- const result = syncPositionSchema.safeParse(value);
59
+ export function parseLogPosition(value) {
60
+ const result = logPositionSchema.safeParse(value);
61
61
  return result.success ? result.data : null;
62
62
  }
63
63
  const ZERO = { persisted: 0, applied: 0, acked: 0 };
@@ -73,7 +73,7 @@ function advance(state, next) {
73
73
  * The live sync position: one instance per client. Three producers each
74
74
  * advance their own cursor, and consumers read the result.
75
75
  */
76
- export class SyncPosition {
76
+ export class LogPosition {
77
77
  #state = ZERO;
78
78
  /** Returns a copy of the current state in the schema's shape. */
79
79
  snapshot() {
@@ -114,3 +114,12 @@ export class SyncPosition {
114
114
  this.#state = advance(this.#state, snapshot);
115
115
  }
116
116
  }
117
+ // ── Deprecated aliases (renamed from the sync/syncPosition module, 2026-07-17) ──
118
+ // The position is a participant's place in the transaction log; the old names
119
+ // said the consumer. Same class, same instanceof identity. Removed in 0.36.0.
120
+ /** @deprecated Renamed to {@link logPositionSchema}. Removed in 0.36.0. */
121
+ export const syncPositionSchema = logPositionSchema;
122
+ /** @deprecated Renamed to {@link parseLogPosition}. Removed in 0.36.0. */
123
+ export const parseSyncPosition = parseLogPosition;
124
+ /** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
125
+ export const SyncPosition = LogPosition;
package/dist/transaction/logger.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * The logging port the SDK writes through.
3
+ *
4
+ * A contract with no framework and no local state: credential exchange, commit,
5
+ * and claim all need to log with no UI and no offline store present, so the port
6
+ * belongs to the settlement core (ADR 0016). The consumer supplies the
7
+ * implementation; the SDK ships a no-op default.
8
+ */
9
+ export interface Logger {
10
+ debug(message: string, ...args: unknown[]): void;
11
+ info(message: string, ...args: unknown[]): void;
12
+ warn(message: string, ...args: unknown[]): void;
13
+ error(message: string, ...args: unknown[]): void;
14
+ }
15
+ /** The no-op default — what the core logs through when no logger is wired. */
16
+ export declare const noopLogger: Logger;
package/dist/transaction/logger.js ADDED
@@ -0,0 +1,7 @@
1
+ /** The no-op default — what the core logs through when no logger is wired. */
2
+ export const noopLogger = {
3
+ debug() { },
4
+ info() { },
5
+ warn() { },
6
+ error() { },
7
+ };
package/dist/transaction/observability.d.ts ADDED
@@ -0,0 +1,53 @@
1
+ /**
2
+ * The observability the settlement core reports on its own behalf.
3
+ *
4
+ * Coordination outcomes — a claim changing state, a stale-write collision that
5
+ * notified instead of aborting — happen with no UI and no local store anywhere,
6
+ * so the core must be able to report them without depending on the consumer's
7
+ * full provider (ADR 0016).
8
+ *
9
+ * This is deliberately the narrow set the core actually calls today. Widening it
10
+ * later is non-breaking; the reactive engine's `ObservabilityProvider` extends
11
+ * this interface, so a single implementation still satisfies both.
12
+ */
13
+ import type { ClaimEvent, ConflictEvent } from './coordination/events.js';
14
+ export interface CoordinationObservability {
15
+ /** Capture a claim state change (acquired / queued / granted / lost / rejected / expired). */
16
+ captureClaim(event: ClaimEvent): void;
17
+ /** Capture a notify-instead-of-abort stale-write collision. */
18
+ captureConflict(event: ConflictEvent): void;
19
+ }
20
+ /** Breadcrumb severity levels */
21
+ export type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
22
+ /** Breadcrumb categories for sync engine lifecycle events */
23
+ export type BreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.coordination' | 'sync.groups';
24
+ export interface WebSocketErrorDetails {
25
+ context: string;
26
+ error?: string;
27
+ code?: number;
28
+ reason?: string;
29
+ }
30
+ /**
31
+ * The observability the duplex transport reports on its own behalf: connection
32
+ * lifecycle breadcrumbs and socket errors. A server-side agent holding a socket
33
+ * for claim push has no store and no UI, so the transport must be able to
34
+ * report without the consumer's full provider — the same reasoning as
35
+ * {@link CoordinationObservability}, one layer down. The reactive engine's
36
+ * `ObservabilityProvider` extends this interface, so a single implementation
37
+ * satisfies both.
38
+ */
39
+ export interface TransportObservability {
40
+ /** Add a breadcrumb for sync lifecycle events */
41
+ breadcrumb(message: string, category: BreadcrumbCategory, level?: BreadcrumbLevel, data?: Record<string, string | number | boolean | undefined>): void;
42
+ /** Capture WebSocket error */
43
+ captureWebSocketError(details: WebSocketErrorDetails): void;
44
+ }
45
+ /**
46
+ * Everything the duplex transport reports: its own lifecycle
47
+ * ({@link TransportObservability}) plus the coordination outcomes that ride
48
+ * the socket ({@link CoordinationObservability} — claim pushes and notified
49
+ * collisions arrive as frames, so the transport is where they surface).
50
+ */
51
+ export type SocketObservability = TransportObservability & CoordinationObservability;
52
+ /** The no-op default — what the transport reports through when nothing is wired. */
53
+ export declare const noopSocketObservability: SocketObservability;