@bjornpagen/bumbledb 1.3.0 → 2.0.0-rc.1

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 (290) hide show
  1. package/COOKBOOK.md +224 -95
  2. package/README.md +114 -45
  3. package/dist/alternatives.d.ts +5 -6
  4. package/dist/alternatives.d.ts.map +1 -1
  5. package/dist/alternatives.js +5 -6
  6. package/dist/alternatives.js.map +1 -1
  7. package/dist/bin.d.ts +3 -0
  8. package/dist/bin.d.ts.map +1 -0
  9. package/dist/bin.js +85 -0
  10. package/dist/bin.js.map +1 -0
  11. package/dist/capacity.d.ts +14 -17
  12. package/dist/capacity.d.ts.map +1 -1
  13. package/dist/capacity.js +7 -7
  14. package/dist/capacity.js.map +1 -1
  15. package/dist/changes.d.ts +32 -41
  16. package/dist/changes.d.ts.map +1 -1
  17. package/dist/changes.js +86 -110
  18. package/dist/changes.js.map +1 -1
  19. package/dist/closed.d.ts +2 -2
  20. package/dist/closed.d.ts.map +1 -1
  21. package/dist/closed.js +5 -5
  22. package/dist/closed.js.map +1 -1
  23. package/dist/codec.d.ts +20 -27
  24. package/dist/codec.d.ts.map +1 -1
  25. package/dist/codec.js +48 -22
  26. package/dist/codec.js.map +1 -1
  27. package/dist/compile.d.ts +26 -50
  28. package/dist/compile.d.ts.map +1 -1
  29. package/dist/compile.js +75 -64
  30. package/dist/compile.js.map +1 -1
  31. package/dist/database/database.d.ts +98 -0
  32. package/dist/database/database.d.ts.map +1 -0
  33. package/dist/database/database.js +249 -0
  34. package/dist/database/database.js.map +1 -0
  35. package/dist/database/driver.d.ts +40 -0
  36. package/dist/database/driver.d.ts.map +1 -0
  37. package/dist/database/driver.js +68 -0
  38. package/dist/database/driver.js.map +1 -0
  39. package/dist/database/fs.d.ts +12 -0
  40. package/dist/database/fs.d.ts.map +1 -0
  41. package/dist/database/fs.js +120 -0
  42. package/dist/database/fs.js.map +1 -0
  43. package/dist/database/generate.d.ts +26 -0
  44. package/dist/database/generate.d.ts.map +1 -0
  45. package/dist/database/generate.js +102 -0
  46. package/dist/database/generate.js.map +1 -0
  47. package/dist/database/hosted.d.ts +32 -0
  48. package/dist/database/hosted.d.ts.map +1 -0
  49. package/dist/database/hosted.js +44 -0
  50. package/dist/database/hosted.js.map +1 -0
  51. package/dist/database/io.d.ts +94 -0
  52. package/dist/database/io.d.ts.map +1 -0
  53. package/dist/database/io.js +35 -0
  54. package/dist/database/io.js.map +1 -0
  55. package/dist/database/mem.d.ts +26 -0
  56. package/dist/database/mem.d.ts.map +1 -0
  57. package/dist/database/mem.js +67 -0
  58. package/dist/database/mem.js.map +1 -0
  59. package/dist/database/migration.d.ts +55 -0
  60. package/dist/database/migration.d.ts.map +1 -0
  61. package/dist/database/migration.js +46 -0
  62. package/dist/database/migration.js.map +1 -0
  63. package/dist/database/s3.d.ts +36 -0
  64. package/dist/database/s3.d.ts.map +1 -0
  65. package/dist/database/s3.js +141 -0
  66. package/dist/database/s3.js.map +1 -0
  67. package/dist/db.d.ts +44 -128
  68. package/dist/db.d.ts.map +1 -1
  69. package/dist/db.js +163 -287
  70. package/dist/db.js.map +1 -1
  71. package/dist/engine.d.ts +7 -0
  72. package/dist/engine.d.ts.map +1 -0
  73. package/dist/engine.js +2 -0
  74. package/dist/engine.js.map +1 -0
  75. package/dist/errors.d.ts +152 -46
  76. package/dist/errors.d.ts.map +1 -1
  77. package/dist/errors.js +107 -19
  78. package/dist/errors.js.map +1 -1
  79. package/dist/face.d.ts +5 -5
  80. package/dist/face.d.ts.map +1 -1
  81. package/dist/face.js +6 -6
  82. package/dist/face.js.map +1 -1
  83. package/dist/fields.d.ts +4 -5
  84. package/dist/fields.d.ts.map +1 -1
  85. package/dist/fields.js +3 -3
  86. package/dist/fields.js.map +1 -1
  87. package/dist/index.d.ts +60 -58
  88. package/dist/index.d.ts.map +1 -1
  89. package/dist/index.js +27 -29
  90. package/dist/index.js.map +1 -1
  91. package/dist/judgment.d.ts +1 -1
  92. package/dist/judgment.js +1 -1
  93. package/dist/law.d.ts +16 -68
  94. package/dist/law.d.ts.map +1 -1
  95. package/dist/law.js +3 -3
  96. package/dist/law.js.map +1 -1
  97. package/dist/lower.d.ts +3 -3
  98. package/dist/lower.d.ts.map +1 -1
  99. package/dist/lower.js +35 -39
  100. package/dist/lower.js.map +1 -1
  101. package/dist/native/addon.d.ts +23 -0
  102. package/dist/native/addon.d.ts.map +1 -0
  103. package/dist/native/addon.js +15 -0
  104. package/dist/native/addon.js.map +1 -0
  105. package/dist/native/binding.d.ts +996 -0
  106. package/dist/native/json.d.ts +14 -0
  107. package/dist/native/json.d.ts.map +1 -0
  108. package/dist/native/json.js +73 -0
  109. package/dist/native/json.js.map +1 -0
  110. package/dist/native/load.d.ts +9 -0
  111. package/dist/native/load.d.ts.map +1 -0
  112. package/dist/native/load.js +30 -0
  113. package/dist/native/load.js.map +1 -0
  114. package/dist/native/op.d.ts +29 -0
  115. package/dist/native/op.d.ts.map +1 -0
  116. package/dist/native/op.js +50 -0
  117. package/dist/native/op.js.map +1 -0
  118. package/dist/query/atom.d.ts +13 -14
  119. package/dist/query/atom.d.ts.map +1 -1
  120. package/dist/query/atom.js +2 -2
  121. package/dist/query/atom.js.map +1 -1
  122. package/dist/query/compute.d.ts +7 -7
  123. package/dist/query/compute.d.ts.map +1 -1
  124. package/dist/query/compute.js +7 -16
  125. package/dist/query/compute.js.map +1 -1
  126. package/dist/query/find.d.ts +8 -8
  127. package/dist/query/find.d.ts.map +1 -1
  128. package/dist/query/find.js +1 -1
  129. package/dist/query/lower.d.ts +31 -17
  130. package/dist/query/lower.d.ts.map +1 -1
  131. package/dist/query/lower.js +260 -368
  132. package/dist/query/lower.js.map +1 -1
  133. package/dist/query/run.d.ts +5 -5
  134. package/dist/query/run.d.ts.map +1 -1
  135. package/dist/query/run.js +32 -15
  136. package/dist/query/run.js.map +1 -1
  137. package/dist/query/scope.d.ts +20 -28
  138. package/dist/query/scope.d.ts.map +1 -1
  139. package/dist/query/scope.js +13 -8
  140. package/dist/query/scope.js.map +1 -1
  141. package/dist/query/segments.d.ts +2 -2
  142. package/dist/query/segments.d.ts.map +1 -1
  143. package/dist/query/segments.js +3 -3
  144. package/dist/query/segments.js.map +1 -1
  145. package/dist/relation.d.ts +1 -1
  146. package/dist/relation.d.ts.map +1 -1
  147. package/dist/relation.js +4 -4
  148. package/dist/relation.js.map +1 -1
  149. package/dist/result.d.ts +15 -22
  150. package/dist/result.d.ts.map +1 -1
  151. package/dist/result.js +30 -39
  152. package/dist/result.js.map +1 -1
  153. package/dist/rows.d.ts +9 -33
  154. package/dist/rows.d.ts.map +1 -1
  155. package/dist/rows.js +8 -12
  156. package/dist/rows.js.map +1 -1
  157. package/dist/runtime.d.ts +17 -43
  158. package/dist/runtime.d.ts.map +1 -1
  159. package/dist/runtime.js +41 -241
  160. package/dist/runtime.js.map +1 -1
  161. package/dist/scalar.d.ts +36 -106
  162. package/dist/scalar.d.ts.map +1 -1
  163. package/dist/scalar.js +36 -185
  164. package/dist/scalar.js.map +1 -1
  165. package/dist/schema.d.ts +7 -18
  166. package/dist/schema.d.ts.map +1 -1
  167. package/dist/schema.js +18 -228
  168. package/dist/schema.js.map +1 -1
  169. package/dist/selection.d.ts +4 -4
  170. package/dist/selection.d.ts.map +1 -1
  171. package/dist/selection.js +5 -5
  172. package/dist/selection.js.map +1 -1
  173. package/dist/shape.d.ts +5 -5
  174. package/dist/shape.d.ts.map +1 -1
  175. package/dist/spec.d.ts +7 -79
  176. package/dist/spec.d.ts.map +1 -1
  177. package/dist/spec.js.map +1 -1
  178. package/dist/statements.d.ts +3 -3
  179. package/dist/statements.d.ts.map +1 -1
  180. package/dist/statements.js +10 -10
  181. package/dist/statements.js.map +1 -1
  182. package/dist/uuid.d.ts +1 -1
  183. package/dist/uuid.d.ts.map +1 -1
  184. package/dist/uuid.js +1 -1
  185. package/dist/uuid.js.map +1 -1
  186. package/dist/values.d.ts +2 -2
  187. package/dist/values.d.ts.map +1 -1
  188. package/dist/values.js +2 -2
  189. package/dist/values.js.map +1 -1
  190. package/package.json +18 -18
  191. package/src/alternatives.ts +7 -8
  192. package/src/bin.ts +82 -0
  193. package/src/capacity.ts +20 -23
  194. package/src/changes.ts +134 -197
  195. package/src/closed.ts +5 -5
  196. package/src/codec.ts +77 -51
  197. package/src/compile.ts +91 -113
  198. package/src/database/database.ts +413 -0
  199. package/src/database/driver.ts +134 -0
  200. package/src/database/fs.ts +119 -0
  201. package/src/database/generate.ts +116 -0
  202. package/src/database/hosted.ts +102 -0
  203. package/src/database/io.ts +134 -0
  204. package/src/database/mem.ts +113 -0
  205. package/src/database/migration.ts +107 -0
  206. package/src/database/s3.ts +231 -0
  207. package/src/db.ts +290 -547
  208. package/src/engine.ts +14 -0
  209. package/src/errors.ts +118 -39
  210. package/src/face.ts +9 -9
  211. package/src/fields.ts +6 -7
  212. package/src/index.ts +102 -109
  213. package/src/judgment.ts +1 -1
  214. package/src/law.ts +18 -70
  215. package/src/lower.ts +61 -72
  216. package/src/native/addon.ts +54 -0
  217. package/src/native/binding.d.ts +996 -0
  218. package/src/native/json.ts +100 -0
  219. package/src/native/load.ts +31 -0
  220. package/src/native/op.ts +73 -0
  221. package/src/query/atom.ts +15 -16
  222. package/src/query/compute.ts +13 -22
  223. package/src/query/find.ts +8 -8
  224. package/src/query/lower.ts +323 -414
  225. package/src/query/run.ts +42 -21
  226. package/src/query/scope.ts +37 -38
  227. package/src/query/segments.ts +4 -4
  228. package/src/relation.ts +4 -4
  229. package/src/result.ts +53 -80
  230. package/src/rows.ts +18 -46
  231. package/src/runtime.ts +50 -346
  232. package/src/scalar.ts +76 -336
  233. package/src/schema.ts +23 -284
  234. package/src/selection.ts +6 -6
  235. package/src/shape.ts +5 -5
  236. package/src/spec.ts +7 -85
  237. package/src/statements.ts +11 -11
  238. package/src/uuid.ts +1 -1
  239. package/src/values.ts +4 -4
  240. package/dist/close.d.ts +0 -24
  241. package/dist/close.d.ts.map +0 -1
  242. package/dist/close.js +0 -34
  243. package/dist/close.js.map +0 -1
  244. package/dist/db-native.d.ts +0 -196
  245. package/dist/db-native.d.ts.map +0 -1
  246. package/dist/db-native.js +0 -13
  247. package/dist/db-native.js.map +0 -1
  248. package/dist/internal/log.d.ts +0 -26
  249. package/dist/internal/log.d.ts.map +0 -1
  250. package/dist/internal/log.js +0 -12
  251. package/dist/internal/log.js.map +0 -1
  252. package/dist/migration.d.ts +0 -31
  253. package/dist/migration.d.ts.map +0 -1
  254. package/dist/migration.js +0 -47
  255. package/dist/migration.js.map +0 -1
  256. package/dist/native.d.ts +0 -562
  257. package/dist/native.d.ts.map +0 -1
  258. package/dist/native.js +0 -123
  259. package/dist/native.js.map +0 -1
  260. package/dist/query/description.d.ts +0 -41
  261. package/dist/query/description.d.ts.map +0 -1
  262. package/dist/query/description.js +0 -311
  263. package/dist/query/description.js.map +0 -1
  264. package/dist/query/parse-ir.d.ts +0 -10
  265. package/dist/query/parse-ir.d.ts.map +0 -1
  266. package/dist/query/parse-ir.js +0 -280
  267. package/dist/query/parse-ir.js.map +0 -1
  268. package/dist/runtime-codes.d.ts +0 -2
  269. package/dist/runtime-codes.d.ts.map +0 -1
  270. package/dist/runtime-codes.js +0 -18
  271. package/dist/runtime-codes.js.map +0 -1
  272. package/dist/runtime-errors.d.ts +0 -118
  273. package/dist/runtime-errors.d.ts.map +0 -1
  274. package/dist/runtime-errors.js +0 -98
  275. package/dist/runtime-errors.js.map +0 -1
  276. package/dist/runtime-native.d.ts +0 -141
  277. package/dist/runtime-native.d.ts.map +0 -1
  278. package/dist/runtime-native.js +0 -5
  279. package/dist/runtime-native.js.map +0 -1
  280. package/pack-provenance.json +0 -7
  281. package/src/close.ts +0 -53
  282. package/src/db-native.ts +0 -243
  283. package/src/internal/log.ts +0 -48
  284. package/src/migration.ts +0 -61
  285. package/src/native.ts +0 -736
  286. package/src/query/description.ts +0 -424
  287. package/src/query/parse-ir.ts +0 -291
  288. package/src/runtime-codes.ts +0 -17
  289. package/src/runtime-errors.ts +0 -109
  290. package/src/runtime-native.ts +0 -189
package/src/native.ts DELETED
@@ -1,736 +0,0 @@
1
- import { createRequire } from "node:module"
2
- import { Result } from "effect"
3
- import { NativeLoadError, NativeOperationError, NativeReportedError } from "#errors.ts"
4
- import type { SchemaSpec, ValueSpec, ValueTypeSpec } from "#spec.ts"
5
-
6
- /**
7
- * The opaque managed database capability. The native runtime registry —
8
- * not this wrapper — owns the LMDB environment, the kernel directory
9
- * lock and every session; a retained wrapper after a completed close is
10
- * inert. Minted only by the managed handshake
11
- * (`runtimeDirectoryDbOpen` → `runtimeDbTake` in #runtime-native.ts).
12
- */
13
- type DbHandle = { readonly __brand: "bumbledb.db" }
14
-
15
- /** Admitted owned instance attached through directory publish — not a JS builder. */
16
-
17
- /**
18
- * The sealed per-theory log schema (`crates/bumbledb-log` successor
19
- * lanes): the validated core schema plus its fingerprint, shared by the
20
- * command/decision grammar. Immutable plain data; no lifecycle verbs.
21
- */
22
- type LogSchemaHandle = { readonly __brand: "bumbledb.logSchema" }
23
-
24
- /** A discrete half-open interval `[start, end)` over u64/i64. */
25
- interface IntervalValue {
26
- readonly start: bigint
27
- readonly end: bigint
28
- }
29
-
30
- /**
31
- * A dense-line half-open interval with canonical binary64 endpoints:
32
- * NaN-free, strictly ordered; ±Infinity are unbounded endpoints.
33
- */
34
- interface F64IntervalValue {
35
- readonly start: number
36
- readonly end: number
37
- }
38
-
39
- /**
40
- * One marshalled cell. An application-owned Uuid crosses as its
41
- * canonical hyphenated UUID string; there is no fresh
42
- * range, reservation counter or issuance value anywhere on this wire.
43
- */
44
- type FactValue = boolean | bigint | number | string | Uint8Array | IntervalValue | F64IntervalValue
45
-
46
- type TaggedValue = ValueSpec
47
-
48
- type QueryParam = TaggedValue | { readonly kind: "set"; readonly values: readonly TaggedValue[] }
49
-
50
- type QueryIr =
51
- | {
52
- readonly kind: "cq"
53
- readonly interiors: readonly InteriorIr[]
54
- readonly head: readonly HeadTermIr[]
55
- readonly rules: readonly RuleIr[]
56
- }
57
- | {
58
- readonly kind: "reach"
59
- readonly interiors: readonly InteriorIr[]
60
- readonly rec: RecIr
61
- readonly head: readonly HeadTermIr[]
62
- readonly rules: readonly RuleIr[]
63
- }
64
-
65
- interface InteriorIr {
66
- readonly head: readonly HeadTermIr[]
67
- readonly rules: readonly RuleIr[]
68
- }
69
-
70
- interface RecIr {
71
- readonly head: readonly HeadTermIr[]
72
- readonly base: readonly RuleIr[]
73
- readonly rec: readonly RuleIr[]
74
- }
75
-
76
- type HeadTermIr =
77
- | { readonly kind: "var" }
78
- | { readonly kind: "compute" }
79
- | { readonly kind: "aggregate"; readonly op: HeadOpIr }
80
-
81
- type HeadOpIr = "sum" | "mean" | "min" | "max" | "count" | "pack"
82
-
83
- /**
84
- * The computed-find scalar expression (C05 `FindTerm::Compute(ScalarExpr)`):
85
- * exactly the frozen core roster, spelled as the migration plan JSON spells
86
- * the same expressions (one grammar, no second evaluator). `var` binds a
87
- * rule variable ordinal on this lane.
88
- */
89
- type NumericCastIr = "toF64" | "toF64Exact" | "toI64Exact" | "toU64Exact"
90
-
91
- type ScalarExprIr =
92
- | { readonly kind: "measure"; readonly expr: ScalarExprIr }
93
- | {
94
- readonly kind: "mulDiv"
95
- readonly a: ScalarExprIr
96
- readonly b: ScalarExprIr
97
- readonly divisor: ScalarExprIr
98
- readonly rounding: import("#scalar.ts").Rounding
99
- }
100
- | { readonly kind: "var"; readonly var: number }
101
- | { readonly kind: "literal"; readonly value: TaggedValue }
102
- | { readonly kind: "negate"; readonly expr: ScalarExprIr }
103
- | { readonly kind: "add"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
104
- | { readonly kind: "subtract"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
105
- | { readonly kind: "multiply"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
106
- | { readonly kind: "divide"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
107
- | { readonly kind: "cast"; readonly cast: NumericCastIr; readonly expr: ScalarExprIr }
108
- | { readonly kind: "isNaN"; readonly expr: ScalarExprIr }
109
- | { readonly kind: "isFinite"; readonly expr: ScalarExprIr }
110
-
111
- interface RuleIr {
112
- readonly finds: readonly FindTermIr[]
113
- readonly atoms: readonly AtomIr[]
114
- readonly negated: readonly AtomIr[]
115
- readonly conditions: readonly ConditionTreeIr[]
116
- }
117
-
118
- type FoldOpIr =
119
- | { readonly kind: "sum" }
120
- | { readonly kind: "mean" }
121
- | { readonly kind: "min" }
122
- | { readonly kind: "max" }
123
-
124
- type FindTermIr =
125
- | {
126
- readonly kind: "segments"
127
- readonly op: import("#query/segments.ts").SegmentOp
128
- readonly left: number
129
- readonly right: number
130
- }
131
- | { readonly kind: "var"; readonly var: number }
132
- | { readonly kind: "compute"; readonly expr: ScalarExprIr }
133
- | { readonly kind: "count" }
134
- | { readonly kind: "aggregate"; readonly op: FoldOpIr; readonly over: number }
135
- | { readonly kind: "pack"; readonly over: number }
136
-
137
- declare const parsedQueryBrand: unique symbol
138
-
139
- type ParsedQuery = QueryIr & { readonly [parsedQueryBrand]: true }
140
-
141
- type AggOpIr =
142
- | { readonly kind: "sum" }
143
- | { readonly kind: "mean" }
144
- | { readonly kind: "min" }
145
- | { readonly kind: "max" }
146
- | { readonly kind: "count" }
147
- | { readonly kind: "pack" }
148
-
149
- type AtomSourceIr =
150
- | { readonly kind: "edb"; readonly relation: number }
151
- | { readonly kind: "interior"; readonly interior: number }
152
-
153
- interface AtomIr {
154
- readonly source: AtomSourceIr
155
- readonly bindings: ReadonlyArray<readonly [number, TermIr]>
156
- }
157
-
158
- type TermIr =
159
- | { readonly kind: "var"; readonly var: number }
160
- | { readonly kind: "param"; readonly param: number }
161
- | { readonly kind: "paramSet"; readonly param: number }
162
- | { readonly kind: "literal"; readonly value: TaggedValue }
163
-
164
- type CmpOpIr =
165
- | { readonly kind: "eq" }
166
- | { readonly kind: "ne" }
167
- | { readonly kind: "lt" }
168
- | { readonly kind: "le" }
169
- | { readonly kind: "gt" }
170
- | { readonly kind: "ge" }
171
- | { readonly kind: "allen"; readonly mask: number }
172
- | { readonly kind: "pointIn" }
173
-
174
- interface ComparisonIr {
175
- readonly op: CmpOpIr
176
- readonly lhs: TermIr
177
- readonly rhs: TermIr
178
- }
179
-
180
- type ConditionTreeIr =
181
- | { readonly kind: "leaf"; readonly cmp: ComparisonIr }
182
- | { readonly kind: "and"; readonly children: readonly ConditionTreeIr[] }
183
- | { readonly kind: "or"; readonly children: readonly ConditionTreeIr[] }
184
-
185
- type StatementKindTag = "functionality" | "containment" | "capacity"
186
-
187
- // ---------------------------------------------------------------------------
188
- // Successor log grammar wire (C06 through the C09 bridge). The 0.x
189
- // braids/codec/manifest/sidecar lanes and their mint tables are deleted.
190
- // ---------------------------------------------------------------------------
191
-
192
- /**
193
- * A grammar lane's domain outcome: the payload, or a refusal row whose
194
- * `kind` is an identity string spelled exactly as `bumbledb-log`'s
195
- * identities emitter spells it (`logIdentities()` / log-identities.json).
196
- */
197
- type LogResult<T, K extends string> =
198
- | { readonly ok: true; readonly value: T }
199
- | { readonly ok: false; readonly kind: K; readonly message: string }
200
-
201
- /** `FrameError` kinds (the `frame` identity family). */
202
- type LogFrameKind =
203
- | "limitExceeded"
204
- | "lengthOverflow"
205
- | "allocation"
206
- | "truncated"
207
- | "family"
208
- | "layout"
209
- | "kind"
210
- | "tag"
211
- | "invalidEpoch"
212
- | "stateIdentityMismatch"
213
- | "emptyChangeSummary"
214
- | "emptyEvidence"
215
- | "invalidTerminalStamp"
216
- | "invalidPreconditionEvidence"
217
- | "invalidPolicy"
218
- | "invalidSequence"
219
- | "invalidCount"
220
- | "trailingBytes"
221
-
222
- /** Receipt-row kinds: the frame family plus the foreign-scope refusal. */
223
- type LogReceiptKind = LogFrameKind | "foreignRow"
224
-
225
- /** Command-lane kinds: frame family plus the two command-only arms. */
226
- type LogCommandKind = LogFrameKind | "core" | "schemaMismatch"
227
-
228
- /** Chain-step refusals from the decode-and-verify lane. */
229
- type LogChainKind = "wrongParent" | "wrongSequence"
230
-
231
- /** The complete database scope of every command/receipt/decision. */
232
- interface LogIdentity {
233
- /** Application-owned Uuid, canonical hyphenated UUID. */
234
- readonly databaseId: string
235
- readonly incarnationId: string
236
- /** The core schema fingerprint, 64 lowercase hex characters. */
237
- readonly schemaId: string
238
- }
239
-
240
- interface LogStateStamp {
241
- readonly incarnation: string
242
- readonly dataRevision: bigint
243
- }
244
-
245
- interface LogDecisionStamp {
246
- readonly seq: bigint
247
- readonly hash: Uint8Array
248
- }
249
-
250
- type LogCondition = { readonly kind: "unconditional" } | { readonly kind: "exactState"; readonly state: LogStateStamp }
251
-
252
- interface LogCommandId {
253
- readonly receiptEpoch: bigint
254
- readonly requestId: string
255
- }
256
-
257
- interface LogCommandMetadata {
258
- readonly identity: LogIdentity
259
- readonly id: LogCommandId
260
- readonly condition: LogCondition
261
- }
262
-
263
- interface LogCommandRef {
264
- readonly identity: LogIdentity
265
- readonly receiptEpoch: bigint
266
- readonly requestId: string
267
- readonly digest: Uint8Array
268
- }
269
-
270
- type LogOutcomeWire =
271
- | { readonly kind: "committed"; readonly added: bigint; readonly removed: bigint; readonly result?: Uint8Array }
272
- | { readonly kind: "noChange"; readonly result?: Uint8Array }
273
- | { readonly kind: "preconditionFailed"; readonly expected: LogStateStamp; readonly observed: LogStateStamp }
274
- | { readonly kind: "invariantRejected"; readonly evidence: Uint8Array }
275
-
276
- interface LogReceipt {
277
- readonly command: LogCommandRef
278
- readonly decisionAt: LogDecisionStamp
279
- readonly stateAt: LogStateStamp
280
- readonly outcome: LogOutcomeWire
281
- }
282
-
283
- interface LogLimits {
284
- readonly envelopeBytes: bigint
285
- readonly changeBytes: bigint
286
- readonly evidenceBytes: bigint
287
- readonly resultBytes: bigint
288
- }
289
-
290
- type LogAccess =
291
- | { readonly kind: "active" }
292
- | {
293
- readonly kind: "frozen"
294
- readonly operation: string
295
- readonly intent:
296
- | { readonly kind: "erasure" }
297
- | { readonly kind: "migration"; readonly planSetDigest: Uint8Array; readonly target: string }
298
- }
299
-
300
- type LogLifecycle =
301
- | {
302
- readonly kind: "live"
303
- readonly access: LogAccess
304
- readonly decision: LogDecisionStamp
305
- readonly state: LogStateStamp
306
- readonly receipts: { readonly openEpoch: bigint; readonly retiredThrough: bigint }
307
- }
308
- | {
309
- readonly kind: "deleted"
310
- readonly operation: string
311
- readonly reason:
312
- | { readonly kind: "erasure" }
313
- | {
314
- readonly kind: "migrationAborted"
315
- readonly sourceDatabase: string
316
- readonly sourceIncarnation: string
317
- readonly planSetDigest: Uint8Array
318
- }
319
- }
320
-
321
- type LogActivation =
322
- | { readonly kind: "notActivated" }
323
- | {
324
- readonly kind: "activated"
325
- readonly operation: string
326
- readonly targetGenesis: Uint8Array
327
- readonly cause:
328
- | { readonly kind: "create" }
329
- | { readonly kind: "restore" }
330
- | { readonly kind: "migration"; readonly planSetDigest: Uint8Array }
331
- }
332
-
333
- interface LogAuthority {
334
- readonly identity: LogIdentity
335
- readonly revision: bigint
336
- readonly lifecycle: LogLifecycle
337
- readonly activation: LogActivation
338
- }
339
-
340
- type LogGenesisProvenance =
341
- | { readonly kind: "create" }
342
- | { readonly kind: "restore"; readonly sourceEvidence: Uint8Array }
343
- | {
344
- readonly kind: "migration"
345
- readonly sourceDatabase: string
346
- readonly sourceIncarnation: string
347
- readonly planSetDigest: Uint8Array
348
- }
349
-
350
- interface LogGenesis {
351
- readonly identity: LogIdentity
352
- readonly initialApplicationDigest: Uint8Array
353
- readonly initialSystemDigest: Uint8Array
354
- readonly provenance: LogGenesisProvenance
355
- }
356
-
357
- interface ManifestField {
358
- readonly name: string
359
- readonly id: number
360
- readonly valueType: ValueTypeSpec
361
- /** The field's host newtype name off the declared spec; a closed relation's synthetic `id` slot carries the handle newtype. Absent on a bare column. */
362
- readonly newtype?: string
363
- }
364
-
365
- interface ManifestRow {
366
- readonly handle: string
367
- readonly id: bigint
368
- readonly values: ReadonlyArray<{ readonly name: string; readonly value: FactValue }>
369
- }
370
-
371
- interface ManifestRelation {
372
- readonly name: string
373
- readonly id: number
374
- readonly fields: readonly ManifestField[]
375
- readonly extension?: readonly ManifestRow[]
376
- }
377
-
378
- interface SealedSide {
379
- readonly relation: number
380
- readonly projection: readonly number[]
381
- readonly selection: ReadonlyArray<{ readonly field: number; readonly values: readonly FactValue[] }>
382
- }
383
-
384
- type SealedWeight =
385
- | { readonly kind: "unit" }
386
- | { readonly kind: "field"; readonly field: number }
387
- | { readonly kind: "duration"; readonly field: number }
388
-
389
- type SealedHi =
390
- | { readonly kind: "unbounded" }
391
- | { readonly kind: "lit"; readonly value: bigint }
392
- | { readonly kind: "targetField"; readonly field: number }
393
- | { readonly kind: "targetDuration"; readonly field: number }
394
-
395
- type SealedStatement =
396
- | {
397
- readonly id: number
398
- readonly kind: "functionality"
399
- readonly relation: number
400
- readonly projection: readonly number[]
401
- }
402
- | {
403
- readonly id: number
404
- readonly kind: "containment"
405
- readonly source: SealedSide
406
- readonly target: SealedSide
407
- }
408
- | {
409
- readonly id: number
410
- readonly kind: "capacity"
411
- readonly target: SealedSide
412
- readonly weight: SealedWeight
413
- readonly lo: bigint
414
- readonly hi: SealedHi
415
- readonly source: SealedSide
416
- }
417
-
418
- interface SealedDescriptor {
419
- readonly relations: readonly ManifestRelation[]
420
- readonly statements: readonly SealedStatement[]
421
- readonly fingerprint: string
422
- }
423
-
424
- interface ViolationFact {
425
- readonly relation: string
426
- readonly fields: ReadonlyArray<{ readonly name: string; readonly value: FactValue }>
427
- }
428
-
429
- type Violation =
430
- | {
431
- readonly statementId: number
432
- readonly kind: "functionality"
433
- readonly canonical: string
434
- readonly facts: readonly ViolationFact[]
435
- }
436
- | {
437
- readonly statementId: number
438
- readonly kind: "containment"
439
- readonly canonical: string
440
- readonly direction: "sourceUnsatisfied" | "targetRequired"
441
- readonly facts: readonly ViolationFact[]
442
- }
443
- | {
444
- readonly statementId: number
445
- readonly kind: "capacity"
446
- readonly canonical: string
447
- readonly measure: bigint
448
- readonly facts: readonly ViolationFact[]
449
- }
450
-
451
- // The managed create/open outcome is `ManagedDbOutcome` in
452
- // #runtime-native.ts (accepted | rejected | refused); reads, writes and
453
- // queries are worker-affine session verbs there too. The historical
454
- // raw-pointer `dbRead`/`dbWrite`/`tx*`/`instance*`/`prepared*` synchronous
455
- // surface — a JS callback inside a native transaction — is deleted,
456
- // as are the fresh/reserve issuance verbs (`WireFreshRange`).
457
-
458
- type ErrorFamilyKind =
459
- | "formatMismatch"
460
- | "schemaMismatch"
461
- | "alreadyInitialized"
462
- | "destinationExists"
463
- | "publishedButUnsynced"
464
- | "environmentLocked"
465
- | "io"
466
- | "lmdb"
467
- | "readersFull"
468
- | "schema"
469
- | "validation"
470
- | "factShape"
471
- | "closedRelationWrite"
472
- | "commitSync"
473
- | "transactionPoisoned"
474
- | "foreignPrepared"
475
- | "foreignWitness"
476
- | "param"
477
- | "capacityRayMeasure"
478
- | "overflow"
479
- | "scalar"
480
- | "resultBytesOverflow"
481
- | "corruption"
482
- | "store"
483
-
484
- type AdmissionTag = "accepted" | "rejected"
485
- type WriteTag = "accepted" | "rejected" | "abandoned" | "moved"
486
- type OpenKind = "schemaError" | "newtypeMismatch" | "fingerprintMismatch" | "destinationExists"
487
- type PrepareKind = "irError"
488
-
489
- interface Native {
490
- engineVersion(): string
491
-
492
- /** Small identity-sized inputs only; bulk hashing rides `runtimeHash`. */
493
- blake3Hash(data: Uint8Array): Uint8Array
494
-
495
- descriptor(spec: SchemaSpec): SealedDescriptor
496
-
497
- // --- successor log grammar (small frames; command/decision lanes are
498
- // executor verbs in #runtime-native.ts) ---
499
-
500
- logIdentities(): string
501
-
502
- logSchema(spec: SchemaSpec): LogSchemaHandle
503
-
504
- logSchemaFingerprint(schema: LogSchemaHandle): string
505
-
506
- logReceiptKey(id: LogCommandId): Uint8Array
507
-
508
- logReceiptEncode(receipt: LogReceipt, limits: LogLimits): LogResult<Uint8Array, LogReceiptKind>
509
-
510
- logReceiptDecode(
511
- expected: { readonly identity: LogIdentity; readonly receiptEpoch: bigint; readonly requestId: string },
512
- bytes: Uint8Array,
513
- limits: LogLimits
514
- ): LogResult<LogReceipt, LogReceiptKind>
515
-
516
- logReceiptDecodeAt(id: LogCommandId, bytes: Uint8Array, limits: LogLimits): LogResult<LogReceipt, LogReceiptKind>
517
-
518
- logControlEncode(authority: LogAuthority, cap: bigint): LogResult<Uint8Array, LogFrameKind>
519
-
520
- logControlDecode(bytes: Uint8Array, cap: bigint): LogResult<LogAuthority, LogFrameKind>
521
-
522
- logGenesisEncode(record: LogGenesis, cap: bigint): LogResult<Uint8Array, LogFrameKind>
523
-
524
- logGenesisDecode(bytes: Uint8Array, cap: bigint): LogResult<LogGenesis, LogFrameKind>
525
-
526
- logGenesisStamp(record: LogGenesis, cap: bigint): LogResult<LogDecisionStamp, LogFrameKind>
527
-
528
- logBlankDigests(): { readonly application: Uint8Array; readonly system: Uint8Array }
529
- }
530
-
531
- const SHIPPED_PLATFORMS = ["darwin-arm64", "linux-arm64", "linux-x64"] as const
532
-
533
- const requireNative = createRequire(import.meta.url)
534
-
535
- type NativeBinding = Native
536
-
537
- function ensureNativeBinding(): NativeBinding {
538
- const loaded = bindingCache
539
- if (loaded !== undefined) {
540
- return loaded
541
- }
542
- const next = loadNativeBinding(process.platform, process.arch)
543
- bindingCache = next
544
- return next
545
- }
546
-
547
- /** Lazy singleton: the addon loads on first native access, not module evaluation. */
548
- const native: NativeBinding = new Proxy({} as NativeBinding, {
549
- get(_target, property, receiver) {
550
- return Reflect.get(ensureNativeBinding(), property, receiver)
551
- },
552
- set(_target, property, value) {
553
- return Reflect.set(ensureNativeBinding(), property, value)
554
- }
555
- })
556
-
557
- let bindingCache: NativeBinding | undefined
558
-
559
- function nativeBindingIsLoaded(): boolean {
560
- return bindingCache !== undefined
561
- }
562
-
563
- function loadNativeBinding(platform: string, arch: string): NativeBinding {
564
- const platformPackage = `@bjornpagen/bumbledb-${platform}-${arch}`
565
-
566
- const present = Result.try(() => requireNative.resolve(`${platformPackage}/package.json`))
567
- if (Result.isFailure(present)) {
568
- throw new NativeLoadError({
569
- package: platformPackage,
570
- operation: "resolve",
571
- message: `no native binary for ${platform}-${arch}: @bjornpagen/bumbledb ships ${SHIPPED_PLATFORMS.join(", ")} only`,
572
- cause: present.failure
573
- })
574
- }
575
-
576
- const loaded = Result.try(() => requireNative(platformPackage))
577
- if (Result.isFailure(loaded)) {
578
- throw new NativeLoadError({
579
- package: platformPackage,
580
- operation: "load",
581
- message: `load the ${platformPackage} native binary (package present but unloadable)`,
582
- cause: loaded.failure
583
- })
584
- }
585
- return loaded.success
586
- }
587
-
588
- /**
589
- * @internal blake3 of the given bytes via the resident native binding —
590
- * the engine's own hash, lent to the replication driver
591
- * (`@bjornpagen/bumbledb-log`). Not SDK API; the export is deliberately
592
- * undocumented in the package surface. Small identity-sized inputs only.
593
- */
594
- function internalBlake3(data: Uint8Array): Uint8Array {
595
- return bridged("bumbledb blake3", function hashBytes() {
596
- return ensureNativeBinding().blake3Hash(data)
597
- })
598
- }
599
-
600
- /**
601
- * @internal the engine's own sealed descriptor as data — relation ids,
602
- * field ids and types in sealed order, closed rosters with resolved
603
- * axiom rows, materialized statements in engine order, and the real
604
- * fingerprint. Runs the pure seal path; no store opens. Not SDK API;
605
- * the export is deliberately undocumented in the package surface.
606
- */
607
- function internalDescriptor(spec: SchemaSpec): SealedDescriptor {
608
- return bridged("bumbledb descriptor", function sealSpec() {
609
- return ensureNativeBinding().descriptor(spec)
610
- })
611
- }
612
-
613
- /**
614
- * @internal the successor identity table emitted by the log core's one
615
- * speller (`bumbledb_log::identities::emit`). Not SDK API.
616
- */
617
- function internalLogIdentities(): string {
618
- return bridged("bumbledb-log identities", function emitIdentities() {
619
- return ensureNativeBinding().logIdentities()
620
- })
621
- }
622
-
623
- /**
624
- * @internal the sealed per-theory log schema off the same `SchemaSpec`
625
- * every other lane speaks — one validated core schema, lent to the
626
- * replication driver (`@bjornpagen/bumbledb-log`). Not SDK API.
627
- */
628
- function internalLogSchema(spec: SchemaSpec): LogSchemaHandle {
629
- return bridged("bumbledb-log schema", function sealSchema() {
630
- return ensureNativeBinding().logSchema(spec)
631
- })
632
- }
633
-
634
- function isEngineThrow(value: unknown): value is { kind: ErrorFamilyKind; message: string } {
635
- if (typeof value !== "object" || value === null) {
636
- return false
637
- }
638
- const rec = value as { kind?: unknown; message?: unknown }
639
- return typeof rec.kind === "string" && typeof rec.message === "string"
640
- }
641
-
642
- function errorFromThrow(caught: unknown): Error {
643
- if (caught instanceof Error) {
644
- return caught
645
- }
646
- if (isEngineThrow(caught)) {
647
- return new NativeReportedError({
648
- kind: caught.kind,
649
- message: `bumbledb ${caught.kind}: ${caught.message}`,
650
- cause: caught
651
- })
652
- }
653
- return new NativeReportedError({ kind: "Unknown", message: String(caught), cause: caught })
654
- }
655
-
656
- function bridged<T>(context: string, run: () => T): T {
657
- try {
658
- return run()
659
- } catch (caught) {
660
- if (caught instanceof Error) throw caught
661
- throw new NativeOperationError({ operation: context, cause: caught })
662
- }
663
- }
664
-
665
- export type {
666
- AdmissionTag,
667
- AggOpIr,
668
- AtomIr,
669
- AtomSourceIr,
670
- CmpOpIr,
671
- ComparisonIr,
672
- ConditionTreeIr,
673
- DbHandle,
674
- ErrorFamilyKind,
675
- F64IntervalValue,
676
- FactValue,
677
- FindTermIr,
678
- HeadOpIr,
679
- HeadTermIr,
680
- InteriorIr,
681
- IntervalValue,
682
- LogAccess,
683
- LogActivation,
684
- LogAuthority,
685
- LogChainKind,
686
- LogCommandId,
687
- LogCommandKind,
688
- LogCommandMetadata,
689
- LogCommandRef,
690
- LogCondition,
691
- LogDecisionStamp,
692
- LogFrameKind,
693
- LogGenesis,
694
- LogGenesisProvenance,
695
- LogIdentity,
696
- LogLifecycle,
697
- LogLimits,
698
- LogOutcomeWire,
699
- LogReceipt,
700
- LogReceiptKind,
701
- LogResult,
702
- LogSchemaHandle,
703
- LogStateStamp,
704
- NumericCastIr,
705
- OpenKind,
706
- ParsedQuery,
707
- PrepareKind,
708
- QueryIr,
709
- QueryParam,
710
- RecIr,
711
- RuleIr,
712
- ScalarExprIr,
713
- SealedDescriptor,
714
- SealedHi,
715
- SealedSide,
716
- SealedStatement,
717
- SealedWeight,
718
- StatementKindTag,
719
- TaggedValue,
720
- TermIr,
721
- Violation,
722
- ViolationFact,
723
- WriteTag
724
- }
725
- export {
726
- bridged,
727
- errorFromThrow,
728
- internalBlake3,
729
- internalDescriptor,
730
- internalLogIdentities,
731
- internalLogSchema,
732
- loadNativeBinding,
733
- native,
734
- nativeBindingIsLoaded,
735
- SHIPPED_PLATFORMS
736
- }