ai-database 2.1.3 → 2.3.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 (260) hide show
  1. package/CHANGELOG.md +35 -1
  2. package/README.md +880 -669
  3. package/dist/actions.d.ts +2 -2
  4. package/dist/actions.d.ts.map +1 -1
  5. package/dist/actions.js +1 -1
  6. package/dist/actions.js.map +1 -1
  7. package/dist/ai-promise-db.d.ts +49 -23
  8. package/dist/ai-promise-db.d.ts.map +1 -1
  9. package/dist/ai-promise-db.js +91 -63
  10. package/dist/ai-promise-db.js.map +1 -1
  11. package/dist/authorization.d.ts.map +1 -1
  12. package/dist/authorization.js +38 -30
  13. package/dist/authorization.js.map +1 -1
  14. package/dist/cascade-orchestrator.d.ts +404 -0
  15. package/dist/cascade-orchestrator.d.ts.map +1 -0
  16. package/dist/cascade-orchestrator.js +828 -0
  17. package/dist/cascade-orchestrator.js.map +1 -0
  18. package/dist/cascade-write-strategy.d.ts +584 -0
  19. package/dist/cascade-write-strategy.d.ts.map +1 -0
  20. package/dist/cascade-write-strategy.js +590 -0
  21. package/dist/cascade-write-strategy.js.map +1 -0
  22. package/dist/ch-adapter.d.ts +358 -0
  23. package/dist/ch-adapter.d.ts.map +1 -0
  24. package/dist/ch-adapter.js +929 -0
  25. package/dist/ch-adapter.js.map +1 -0
  26. package/dist/client/index.d.ts +42 -0
  27. package/dist/client/index.d.ts.map +1 -0
  28. package/dist/client/index.js +43 -0
  29. package/dist/client/index.js.map +1 -0
  30. package/dist/client.d.ts +266 -0
  31. package/dist/client.d.ts.map +1 -0
  32. package/dist/client.js +81 -0
  33. package/dist/client.js.map +1 -0
  34. package/dist/constants.d.ts +64 -1
  35. package/dist/constants.d.ts.map +1 -1
  36. package/dist/constants.js +52 -2
  37. package/dist/constants.js.map +1 -1
  38. package/dist/dataloader.d.ts +99 -0
  39. package/dist/dataloader.d.ts.map +1 -0
  40. package/dist/dataloader.js +225 -0
  41. package/dist/dataloader.js.map +1 -0
  42. package/dist/db-provider-port.d.ts +501 -0
  43. package/dist/db-provider-port.d.ts.map +1 -0
  44. package/dist/db-provider-port.js +113 -0
  45. package/dist/db-provider-port.js.map +1 -0
  46. package/dist/digital-objects-provider.d.ts +49 -0
  47. package/dist/digital-objects-provider.d.ts.map +1 -0
  48. package/dist/digital-objects-provider.js +55 -0
  49. package/dist/digital-objects-provider.js.map +1 -0
  50. package/dist/do-sqlite-adapter.d.ts +402 -0
  51. package/dist/do-sqlite-adapter.d.ts.map +1 -0
  52. package/dist/do-sqlite-adapter.js +745 -0
  53. package/dist/do-sqlite-adapter.js.map +1 -0
  54. package/dist/docs-rels/custom-types.d.ts +134 -0
  55. package/dist/docs-rels/custom-types.d.ts.map +1 -0
  56. package/dist/docs-rels/custom-types.js +70 -0
  57. package/dist/docs-rels/custom-types.js.map +1 -0
  58. package/dist/docs-rels/index.d.ts +16 -0
  59. package/dist/docs-rels/index.d.ts.map +1 -0
  60. package/dist/docs-rels/index.js +16 -0
  61. package/dist/docs-rels/index.js.map +1 -0
  62. package/dist/docs-rels/migrations/index.d.ts +30 -0
  63. package/dist/docs-rels/migrations/index.d.ts.map +1 -0
  64. package/dist/docs-rels/migrations/index.js +128 -0
  65. package/dist/docs-rels/migrations/index.js.map +1 -0
  66. package/dist/docs-rels/schema.d.ts +2961 -0
  67. package/dist/docs-rels/schema.d.ts.map +1 -0
  68. package/dist/docs-rels/schema.js +244 -0
  69. package/dist/docs-rels/schema.js.map +1 -0
  70. package/dist/durable-clickhouse.d.ts.map +1 -1
  71. package/dist/durable-clickhouse.js +16 -13
  72. package/dist/durable-clickhouse.js.map +1 -1
  73. package/dist/durable-promise.d.ts.map +1 -1
  74. package/dist/durable-promise.js +34 -15
  75. package/dist/durable-promise.js.map +1 -1
  76. package/dist/errors.d.ts +127 -0
  77. package/dist/errors.d.ts.map +1 -0
  78. package/dist/errors.js +210 -0
  79. package/dist/errors.js.map +1 -0
  80. package/dist/eventbridge.d.ts +117 -0
  81. package/dist/eventbridge.d.ts.map +1 -0
  82. package/dist/eventbridge.js +238 -0
  83. package/dist/eventbridge.js.map +1 -0
  84. package/dist/events.d.ts +2 -2
  85. package/dist/events.d.ts.map +1 -1
  86. package/dist/events.js +1 -1
  87. package/dist/events.js.map +1 -1
  88. package/dist/execution-queue.d.ts.map +1 -1
  89. package/dist/execution-queue.js +4 -5
  90. package/dist/execution-queue.js.map +1 -1
  91. package/dist/index.d.ts +35 -8
  92. package/dist/index.d.ts.map +1 -1
  93. package/dist/index.js +106 -6
  94. package/dist/index.js.map +1 -1
  95. package/dist/linguistic.d.ts +3 -108
  96. package/dist/linguistic.d.ts.map +1 -1
  97. package/dist/linguistic.js +3 -372
  98. package/dist/linguistic.js.map +1 -1
  99. package/dist/logger.d.ts +132 -0
  100. package/dist/logger.d.ts.map +1 -0
  101. package/dist/logger.js +137 -0
  102. package/dist/logger.js.map +1 -0
  103. package/dist/memory-provider.d.ts +128 -0
  104. package/dist/memory-provider.d.ts.map +1 -1
  105. package/dist/memory-provider.js +592 -257
  106. package/dist/memory-provider.js.map +1 -1
  107. package/dist/pg-adapter.d.ts +424 -0
  108. package/dist/pg-adapter.d.ts.map +1 -0
  109. package/dist/pg-adapter.js +921 -0
  110. package/dist/pg-adapter.js.map +1 -0
  111. package/dist/pipelines-iceberg-emitter.d.ts +327 -0
  112. package/dist/pipelines-iceberg-emitter.d.ts.map +1 -0
  113. package/dist/pipelines-iceberg-emitter.js +351 -0
  114. package/dist/pipelines-iceberg-emitter.js.map +1 -0
  115. package/dist/provider-capabilities.d.ts +146 -0
  116. package/dist/provider-capabilities.d.ts.map +1 -0
  117. package/dist/provider-capabilities.js +214 -0
  118. package/dist/provider-capabilities.js.map +1 -0
  119. package/dist/rdb-provider-adapter.d.ts +195 -0
  120. package/dist/rdb-provider-adapter.d.ts.map +1 -0
  121. package/dist/rdb-provider-adapter.js +291 -0
  122. package/dist/rdb-provider-adapter.js.map +1 -0
  123. package/dist/schema/cascade.d.ts +48 -17
  124. package/dist/schema/cascade.d.ts.map +1 -1
  125. package/dist/schema/cascade.js +477 -278
  126. package/dist/schema/cascade.js.map +1 -1
  127. package/dist/schema/definition-caches.d.ts +24 -0
  128. package/dist/schema/definition-caches.d.ts.map +1 -0
  129. package/dist/schema/definition-caches.js +26 -0
  130. package/dist/schema/definition-caches.js.map +1 -0
  131. package/dist/schema/dependency-graph.d.ts +21 -109
  132. package/dist/schema/dependency-graph.d.ts.map +1 -1
  133. package/dist/schema/dependency-graph.js +25 -333
  134. package/dist/schema/dependency-graph.js.map +1 -1
  135. package/dist/schema/diff.d.ts +103 -0
  136. package/dist/schema/diff.d.ts.map +1 -0
  137. package/dist/schema/diff.js +329 -0
  138. package/dist/schema/diff.js.map +1 -0
  139. package/dist/schema/entity-operations.d.ts +99 -0
  140. package/dist/schema/entity-operations.d.ts.map +1 -0
  141. package/dist/schema/entity-operations.js +818 -0
  142. package/dist/schema/entity-operations.js.map +1 -0
  143. package/dist/schema/index.d.ts +28 -34
  144. package/dist/schema/index.d.ts.map +1 -1
  145. package/dist/schema/index.js +454 -521
  146. package/dist/schema/index.js.map +1 -1
  147. package/dist/schema/migration.d.ts +205 -0
  148. package/dist/schema/migration.d.ts.map +1 -0
  149. package/dist/schema/migration.js +327 -0
  150. package/dist/schema/migration.js.map +1 -0
  151. package/dist/schema/nl-query-generator.d.ts +68 -0
  152. package/dist/schema/nl-query-generator.d.ts.map +1 -0
  153. package/dist/schema/nl-query-generator.js +362 -0
  154. package/dist/schema/nl-query-generator.js.map +1 -0
  155. package/dist/schema/nl-query.d.ts +65 -0
  156. package/dist/schema/nl-query.d.ts.map +1 -0
  157. package/dist/schema/nl-query.js +178 -0
  158. package/dist/schema/nl-query.js.map +1 -0
  159. package/dist/schema/parse.d.ts.map +1 -1
  160. package/dist/schema/parse.js +144 -89
  161. package/dist/schema/parse.js.map +1 -1
  162. package/dist/schema/provider.d.ts +37 -0
  163. package/dist/schema/provider.d.ts.map +1 -1
  164. package/dist/schema/provider.js +15 -7
  165. package/dist/schema/provider.js.map +1 -1
  166. package/dist/schema/resolve.d.ts +46 -5
  167. package/dist/schema/resolve.d.ts.map +1 -1
  168. package/dist/schema/resolve.js +237 -95
  169. package/dist/schema/resolve.js.map +1 -1
  170. package/dist/schema/search-utils.d.ts +76 -0
  171. package/dist/schema/search-utils.d.ts.map +1 -0
  172. package/dist/schema/search-utils.js +86 -0
  173. package/dist/schema/search-utils.js.map +1 -0
  174. package/dist/schema/seed.d.ts +53 -0
  175. package/dist/schema/seed.d.ts.map +1 -0
  176. package/dist/schema/seed.js +94 -0
  177. package/dist/schema/seed.js.map +1 -0
  178. package/dist/schema/semantic.d.ts +10 -0
  179. package/dist/schema/semantic.d.ts.map +1 -1
  180. package/dist/schema/semantic.js +192 -86
  181. package/dist/schema/semantic.js.map +1 -1
  182. package/dist/schema/sub-apis.d.ts +52 -0
  183. package/dist/schema/sub-apis.d.ts.map +1 -0
  184. package/dist/schema/sub-apis.js +216 -0
  185. package/dist/schema/sub-apis.js.map +1 -0
  186. package/dist/schema/system-entities.d.ts +42 -0
  187. package/dist/schema/system-entities.d.ts.map +1 -0
  188. package/dist/schema/system-entities.js +101 -0
  189. package/dist/schema/system-entities.js.map +1 -0
  190. package/dist/schema/types.d.ts +91 -9
  191. package/dist/schema/types.d.ts.map +1 -1
  192. package/dist/schema/union-fallback.d.ts.map +1 -1
  193. package/dist/schema/union-fallback.js +21 -15
  194. package/dist/schema/union-fallback.js.map +1 -1
  195. package/dist/schema/value-generators/ai.d.ts +54 -0
  196. package/dist/schema/value-generators/ai.d.ts.map +1 -0
  197. package/dist/schema/value-generators/ai.js +136 -0
  198. package/dist/schema/value-generators/ai.js.map +1 -0
  199. package/dist/schema/value-generators/index.d.ts +126 -0
  200. package/dist/schema/value-generators/index.d.ts.map +1 -0
  201. package/dist/schema/value-generators/index.js +219 -0
  202. package/dist/schema/value-generators/index.js.map +1 -0
  203. package/dist/schema/value-generators/placeholder.d.ts +52 -0
  204. package/dist/schema/value-generators/placeholder.d.ts.map +1 -0
  205. package/dist/schema/value-generators/placeholder.js +328 -0
  206. package/dist/schema/value-generators/placeholder.js.map +1 -0
  207. package/dist/schema/value-generators/types.d.ts +116 -0
  208. package/dist/schema/value-generators/types.d.ts.map +1 -0
  209. package/dist/schema/value-generators/types.js +11 -0
  210. package/dist/schema/value-generators/types.js.map +1 -0
  211. package/dist/schema/version.d.ts +111 -0
  212. package/dist/schema/version.d.ts.map +1 -0
  213. package/dist/schema/version.js +190 -0
  214. package/dist/schema/version.js.map +1 -0
  215. package/dist/schema.d.ts +1095 -24
  216. package/dist/schema.d.ts.map +1 -1
  217. package/dist/schema.js +2852 -40
  218. package/dist/schema.js.map +1 -1
  219. package/dist/semantic-vectors.d.ts +39 -0
  220. package/dist/semantic-vectors.d.ts.map +1 -0
  221. package/dist/semantic-vectors.js +334 -0
  222. package/dist/semantic-vectors.js.map +1 -0
  223. package/dist/semantic.d.ts +29 -1
  224. package/dist/semantic.d.ts.map +1 -1
  225. package/dist/semantic.js +26 -16
  226. package/dist/semantic.js.map +1 -1
  227. package/dist/telemetry.d.ts +128 -0
  228. package/dist/telemetry.d.ts.map +1 -0
  229. package/dist/telemetry.js +305 -0
  230. package/dist/telemetry.js.map +1 -0
  231. package/dist/tests.d.ts.map +1 -1
  232. package/dist/tests.js +30 -22
  233. package/dist/tests.js.map +1 -1
  234. package/dist/type-guards.d.ts +50 -5
  235. package/dist/type-guards.d.ts.map +1 -1
  236. package/dist/type-guards.js +87 -16
  237. package/dist/type-guards.js.map +1 -1
  238. package/dist/types.d.ts +33 -245
  239. package/dist/types.d.ts.map +1 -1
  240. package/dist/types.js +62 -72
  241. package/dist/types.js.map +1 -1
  242. package/dist/validation.d.ts +2 -5
  243. package/dist/validation.d.ts.map +1 -1
  244. package/dist/validation.js +65 -93
  245. package/dist/validation.js.map +1 -1
  246. package/dist/worker/db-provider.d.ts +168 -0
  247. package/dist/worker/db-provider.d.ts.map +1 -0
  248. package/dist/worker/db-provider.js +277 -0
  249. package/dist/worker/db-provider.js.map +1 -0
  250. package/dist/worker/index.d.ts +35 -0
  251. package/dist/worker/index.d.ts.map +1 -0
  252. package/dist/worker/index.js +37 -0
  253. package/dist/worker/index.js.map +1 -0
  254. package/dist/worker.d.ts +779 -0
  255. package/dist/worker.d.ts.map +1 -0
  256. package/dist/worker.js +2786 -0
  257. package/dist/worker.js.map +1 -0
  258. package/package.json +46 -16
  259. package/src/docs-rels/migrations/0001-init.sql +125 -0
  260. package/LICENSE +0 -21
@@ -0,0 +1,404 @@
1
+ /**
2
+ * Cascade Orchestrator — the moat work
3
+ *
4
+ * This module is the canonical, real cascade-generation engine for
5
+ * `ai-database`. It replaces the placeholder generator (`schema/cascade.ts`'s
6
+ * `PlaceholderValueGenerator`) for the SVO-shaped cascade surface and absorbs
7
+ * the algorithmic patterns proven by the
8
+ * `2026-05-06-cascade-via-ai-database-poc` (sibling-parallel `[->Type]`
9
+ * expansion, pre-derived child ids for backref correctness, rubric-style
10
+ * `$validate` with four verdict policies, embed-on-write) — but rebuilt on
11
+ * the canonical SVO foundation:
12
+ *
13
+ * - LLM calls go through `generate()` from `ai-functions` (auto-routed via
14
+ * `ai-providers`), wrapped with the per-model `ModelPolicy` from
15
+ * `language-models` (`RetryPolicy.forModel` + `FallbackChain.forModel`)
16
+ * so retry/circuit-breaker/fallback behaviour is consistent with the rest
17
+ * of the platform.
18
+ * - Generated entities are recorded as **Things** via the canonical
19
+ * `DBProvider` surface; relations are recorded as **Actions** with proper
20
+ * Frame role assignments (`subject`, `object`, plus optional Frame-role
21
+ * slots) per the `digital-objects` SVO ontology.
22
+ * - Verbs auto-register via `provider.defineVerb(...)` on first use when
23
+ * the adapter exposes the Verb registry surface.
24
+ * - Sharded writes flow through {@link CascadeWriteStrategy} so per-cascade
25
+ * DO isolation (Stack B) and partitioned-by-tenant Postgres (Stack A) get
26
+ * the right shape without leaking the choice into orchestrator code.
27
+ * - Read-back-during-traversal goes through {@link CascadeWriteStrategy.readShardLocal}
28
+ * so cascade reads land on the same shard that received the write.
29
+ *
30
+ * ## What's deliberately NOT in this module
31
+ *
32
+ * - **Pipelines → Iceberg dual-write.** That's bead `aip-0ypt`; the
33
+ * orchestrator surfaces an `analyticalEmitter` on the underlying
34
+ * {@link CascadeWriteStrategy} which `aip-0ypt` will wire later.
35
+ * - **CLI / Worker entrypoint.** The library function {@link generateCascade}
36
+ * is the surface; deployment shapes live downstream.
37
+ * - **Observability beyond debug logging.** Telemetry / tracing is its own
38
+ * bead.
39
+ * - **The schema-DSL cascade engine** (`schema/cascade.ts`). That module
40
+ * drives generation from the parsed `[->Type]` / `<-Type` schema syntax;
41
+ * this orchestrator drives generation from a {@link CascadeSpec} at the
42
+ * SVO level. Both can coexist; this is the canonical moat path.
43
+ *
44
+ * @see {@link ../docs/adr/0003-storage-strategy-pg-clickhouse-default.md}
45
+ * @see {@link ../docs/reviews/2026-05-05-cascade-poc-evaluation.md}
46
+ * @see {@link ../docs/plans/2026-05-05-cascade-storage-execution-implementation.md}
47
+ * @packageDocumentation
48
+ */
49
+ import type { DBProvider } from './schema/provider.js';
50
+ import type { DBProviderPort, SVOAction } from './db-provider-port.js';
51
+ import { hasActionRecording } from './db-provider-port.js';
52
+ import { CascadeWriteStrategy, type AnalyticalEmitter, type CascadeShardingStrategy } from './cascade-write-strategy.js';
53
+ /**
54
+ * Validation rubric / policy.
55
+ *
56
+ * Mirrors the POC's rubric+policy gating — every generated entity may be
57
+ * gated by an LLM-as-judge that scores against criteria. Four verdict
58
+ * policies cover the realistic gating cases:
59
+ *
60
+ * - `'all-pass'` — every criterion's score must reach `threshold` (or 1 if
61
+ * omitted). Strict default.
62
+ * - `'all-load-bearing-pass'` — only criteria flagged `loadBearing: true`
63
+ * must pass; advisory criteria are scored but don't gate.
64
+ * - `'mean-ge-threshold'` — average of all scores must be >= `threshold`.
65
+ * - `'weighted-ge-threshold'` — weighted mean using each criterion's
66
+ * `weight` (default 1) must be >= `threshold`.
67
+ *
68
+ * Verdict actions:
69
+ * - `accept` — write the entity.
70
+ * - `reject` — discard the entity (do not write, return as rejected).
71
+ * - `regenerate` — re-run the LLM with feedback, up to
72
+ * {@link CascadeOptions.maxRegenerationAttempts}.
73
+ * - `escalate` — bubble up to the caller as a typed error
74
+ * (`CascadeValidationEscalation`); cascade halts unless the caller
75
+ * catches it.
76
+ */
77
+ export interface ValidationRubric {
78
+ /** Rubric criteria. Each criterion gets one LLM score per validation call. */
79
+ criteria: ReadonlyArray<{
80
+ /** Short name (e.g., `'specificity'`, `'plausibility'`). */
81
+ name: string;
82
+ /** Description shown to the LLM judge. */
83
+ description: string;
84
+ /** When `true`, this criterion gates `'all-load-bearing-pass'` policy. */
85
+ loadBearing?: boolean;
86
+ /** Weight for `'weighted-ge-threshold'` policy. Default 1. */
87
+ weight?: number;
88
+ }>;
89
+ /** How the rubric scores collapse to a verdict. */
90
+ policy: 'all-pass' | 'all-load-bearing-pass' | 'mean-ge-threshold' | 'weighted-ge-threshold';
91
+ /**
92
+ * Score threshold used by `mean-ge-threshold` and
93
+ * `weighted-ge-threshold`. Each criterion is scored 0-1; the policy
94
+ * compares the (weighted) mean. Default 0.7.
95
+ */
96
+ threshold?: number;
97
+ /**
98
+ * What to do when the rubric verdict is "fail":
99
+ * - `'reject'` (default) — discard the entity.
100
+ * - `'regenerate'` — re-prompt with feedback up to the orchestrator's
101
+ * {@link CascadeOptions.maxRegenerationAttempts}.
102
+ * - `'escalate'` — throw {@link CascadeValidationEscalation}.
103
+ */
104
+ onFail?: 'reject' | 'regenerate' | 'escalate';
105
+ }
106
+ /**
107
+ * Spec for a single child relationship in a cascade.
108
+ *
109
+ * Children are array-shaped (sibling-parallel fan-out) — the POC's `[->Type]`
110
+ * pattern. A `count` directs the LLM to produce exactly N siblings (or a
111
+ * range when `[count.min, count.max]`). The `verb` names the relation that
112
+ * connects child→parent (e.g., `'placedBy'` for Order → Customer).
113
+ *
114
+ * `roles` may carry additional Frame role assignments beyond
115
+ * subject/object — e.g., a `recipient` for `'sent'`. Values may be:
116
+ *
117
+ * - A literal string (Thing id) — used verbatim.
118
+ * - The token `'$parent'` — substituted with the parent Thing id.
119
+ * - The token `'$root'` — substituted with the cascade root Thing id.
120
+ */
121
+ export interface ChildSpec {
122
+ /** Child noun (e.g., `'Order'`). Must be defined in the schema or be a free-form noun the adapter accepts. */
123
+ noun: string;
124
+ /**
125
+ * Number of sibling children, or a `[min, max]` range. The orchestrator
126
+ * passes the count to the LLM; the LLM is expected to honour it (the POC
127
+ * found `min/2..max+2` works in practice for naming-style cascades).
128
+ */
129
+ count: number | readonly [number, number];
130
+ /**
131
+ * Verb connecting child → parent (the Action recorded after each child
132
+ * is created). Subject is the child; object is the parent.
133
+ */
134
+ verb: string;
135
+ /**
136
+ * Frame-role assignments beyond subject/object. Special tokens:
137
+ * `'$parent'` resolves to the parent Thing id, `'$root'` to the root.
138
+ */
139
+ roles?: Partial<Record<Exclude<import('./db-provider-port.js').FrameRole, 'subject' | 'object'>, string>>;
140
+ /** Per-sibling generation hints (e.g., `'a B2B SaaS customer'`). */
141
+ hints?: Record<string, unknown>;
142
+ /** Optional validation rubric for each generated sibling. */
143
+ validate?: ValidationRubric;
144
+ /** Grandchildren — recursive cascade descent. */
145
+ children?: ReadonlyArray<ChildSpec>;
146
+ }
147
+ /**
148
+ * Top-level cascade spec.
149
+ *
150
+ * The orchestrator generates one root Thing of {@link rootNoun}, optionally
151
+ * validates it, then descends into {@link children} (sibling-parallel per
152
+ * level, sequential between levels so parent ids exist when children
153
+ * reference them).
154
+ */
155
+ export interface CascadeSpec {
156
+ rootNoun: string;
157
+ /** Generation hints for the root entity. */
158
+ rootHints?: Record<string, unknown>;
159
+ /** Optional validation rubric for the root. */
160
+ validate?: ValidationRubric;
161
+ /** Direct children of the root. Recursive. */
162
+ children?: ReadonlyArray<ChildSpec>;
163
+ }
164
+ /**
165
+ * Options for {@link generateCascade}.
166
+ */
167
+ export interface GenerateCascadeOptions extends CascadeSpec {
168
+ /** Adapter to write through. Required. */
169
+ adapter: DBProvider | DBProviderPort;
170
+ /**
171
+ * Model alias or full id (e.g., `'sonnet'`, `'anthropic/claude-sonnet-4.5'`).
172
+ * Resolved via `language-models`'s `policyFor()` for retry / fallback.
173
+ * Default: `'sonnet'`.
174
+ */
175
+ model?: string;
176
+ /**
177
+ * Optional separate model for validation (LLM-as-judge). Defaults to
178
+ * {@link model}. Useful when callers want a cheaper judge than generator
179
+ * (e.g., haiku for validation, sonnet for generation).
180
+ */
181
+ validationModel?: string;
182
+ /**
183
+ * Maximum cascade depth (root + descendants). Hard cap to prevent
184
+ * runaway recursion. Default 5.
185
+ */
186
+ maxDepth?: number;
187
+ /** Max regeneration attempts per entity when a rubric verdict is `'regenerate'`. Default 2. */
188
+ maxRegenerationAttempts?: number;
189
+ /**
190
+ * Optional embedder. If provided, every generated Thing's preferred
191
+ * text fields (per {@link buildEmbedText}) are embedded and the vector
192
+ * stored under `$embedding` on the Thing data. Cascade waits for embed
193
+ * before write so reads-back-during-traversal include the embedding.
194
+ */
195
+ embedder?: (text: string) => Promise<number[]>;
196
+ /**
197
+ * Override the LLM call. Default: `generate.generateObject` from
198
+ * `ai-functions`. Tests pass a mock that returns deterministic objects.
199
+ */
200
+ generator?: CascadeGenerator;
201
+ /**
202
+ * Override the validator LLM call. Default: same as {@link generator}.
203
+ * Tests pass a mock that returns deterministic verdicts.
204
+ */
205
+ validator?: CascadeValidator;
206
+ /**
207
+ * Sharding strategy for the underlying {@link CascadeWriteStrategy}.
208
+ * Default: derived from the adapter's declared `ShardingModel`.
209
+ */
210
+ sharding?: CascadeShardingStrategy | 'per-cascade' | 'partitioned-by-tenant' | 'unsharded';
211
+ /**
212
+ * Stable cascade id. The same id MUST produce the same shape (idempotency).
213
+ * If omitted the orchestrator derives one by content-hashing the spec +
214
+ * rootHints. Re-running with the same id re-uses content-hashed entity
215
+ * ids and lets `ON CONFLICT DO NOTHING` short-circuit duplicate writes.
216
+ */
217
+ cascadeId?: string;
218
+ /** Tenant id (required for `'partitioned-by-tenant'` sharding). */
219
+ tenantId?: string;
220
+ /**
221
+ * Subject ThingRef for every Action recorded (the Worker / Agent that
222
+ * initiated the cascade). When omitted, Actions carry only `subject` =
223
+ * the parent Thing id (typical for cascade-emitted relations).
224
+ */
225
+ initiator?: string;
226
+ /**
227
+ * Optional analytical fan-out hook (passed through to
228
+ * {@link CascadeWriteStrategy}). Stack B's dual-write path
229
+ * (DO SQLite local → Pipelines → Iceberg → ClickHouse) wires here in
230
+ * `aip-0ypt`.
231
+ */
232
+ analyticalEmitter?: AnalyticalEmitter;
233
+ /**
234
+ * Pre-built strategy. When provided, the orchestrator uses it verbatim
235
+ * (and ignores `sharding` / `analyticalEmitter`). Useful when the caller
236
+ * already configured the strategy with custom wiring.
237
+ */
238
+ strategy?: CascadeWriteStrategy;
239
+ /**
240
+ * Optional debug logger. Default: no-op.
241
+ */
242
+ debug?: (message: string, data?: Record<string, unknown>) => void;
243
+ }
244
+ /**
245
+ * The function the orchestrator calls to produce one entity payload.
246
+ *
247
+ * Returns a flat record of fields. The orchestrator handles id derivation,
248
+ * embedding, validation, and write — the generator is purely "make stuff up
249
+ * for this noun".
250
+ *
251
+ * The default implementation calls `generateObject` from `ai-functions`
252
+ * with a schema constructed from the spec's hints. Mocks bypass that
253
+ * machinery for deterministic testing.
254
+ */
255
+ export type CascadeGenerator = (input: {
256
+ noun: string;
257
+ hints: Record<string, unknown>;
258
+ parentNoun?: string;
259
+ parentData?: Record<string, unknown>;
260
+ rootNoun: string;
261
+ rootData?: Record<string, unknown>;
262
+ cascadeId: string;
263
+ /** Path from root, e.g., `['Customer', 'Order:0', 'OrderItem:1']`. Useful for context. */
264
+ path: ReadonlyArray<string>;
265
+ /** Sibling index within the parent's child array (0-based). */
266
+ siblingIndex?: number;
267
+ /** Total siblings being generated for this child spec. */
268
+ siblingCount?: number;
269
+ /** Feedback from a prior failed validation, if regenerating. */
270
+ feedback?: string;
271
+ /** Model alias to use. */
272
+ model: string;
273
+ }) => Promise<Record<string, unknown>>;
274
+ /**
275
+ * The function the orchestrator calls to score an entity against a rubric.
276
+ *
277
+ * Returns one score per criterion, in the same order. Scores are 0..1.
278
+ */
279
+ export type CascadeValidator = (input: {
280
+ noun: string;
281
+ data: Record<string, unknown>;
282
+ rubric: ValidationRubric;
283
+ model: string;
284
+ parentData?: Record<string, unknown>;
285
+ }) => Promise<{
286
+ scores: Record<string, number>;
287
+ feedback?: string;
288
+ }>;
289
+ /**
290
+ * Result of {@link generateCascade}.
291
+ */
292
+ export interface CascadeResult {
293
+ /** Stable cascade id (echoed back; derived if not supplied). */
294
+ cascadeId: string;
295
+ /** Root Thing produced. Includes `$id`, `$type`, and the data fields. */
296
+ root: GeneratedEntity;
297
+ /** All generated Things keyed by id. */
298
+ thingsById: Map<string, GeneratedEntity>;
299
+ /** All generated Actions in write order. */
300
+ actions: ReadonlyArray<GeneratedAction>;
301
+ /** Entities the validator rejected (NOT written). */
302
+ rejected: ReadonlyArray<RejectedEntity>;
303
+ /** Stats for callers / observability. */
304
+ stats: {
305
+ generated: number;
306
+ written: number;
307
+ actionsRecorded: number;
308
+ rejectedCount: number;
309
+ regenerationAttempts: number;
310
+ embedded: number;
311
+ durationMs: number;
312
+ };
313
+ }
314
+ /**
315
+ * A successfully-written generated entity.
316
+ */
317
+ export interface GeneratedEntity {
318
+ $id: string;
319
+ $type: string;
320
+ data: Record<string, unknown>;
321
+ /** Path from root (e.g., `['Customer', 'Order:0']`). */
322
+ path: ReadonlyArray<string>;
323
+ /** Parent Thing id, if any. */
324
+ parentId?: string;
325
+ /** Score map from the validation rubric, if validation ran. */
326
+ validationScores?: Record<string, number>;
327
+ }
328
+ /**
329
+ * A recorded Action.
330
+ */
331
+ export interface GeneratedAction {
332
+ verb: string;
333
+ subject?: string;
334
+ object?: string;
335
+ roles?: Record<string, string>;
336
+ data?: Record<string, unknown>;
337
+ }
338
+ /**
339
+ * An entity rejected by the validator. Not written to storage.
340
+ */
341
+ export interface RejectedEntity {
342
+ noun: string;
343
+ data: Record<string, unknown>;
344
+ scores: Record<string, number>;
345
+ feedback?: string;
346
+ path: ReadonlyArray<string>;
347
+ parentId?: string;
348
+ }
349
+ /**
350
+ * Thrown when a rubric verdict is `'escalate'` — the caller must catch
351
+ * this and decide whether to fail the cascade or recover.
352
+ */
353
+ export declare class CascadeValidationEscalation extends Error {
354
+ readonly noun: string;
355
+ readonly data: Record<string, unknown>;
356
+ readonly scores: Record<string, number>;
357
+ readonly path: ReadonlyArray<string>;
358
+ constructor(input: {
359
+ noun: string;
360
+ data: Record<string, unknown>;
361
+ scores: Record<string, number>;
362
+ path: ReadonlyArray<string>;
363
+ feedback?: string;
364
+ });
365
+ }
366
+ /**
367
+ * Run a cascade generation against an adapter.
368
+ *
369
+ * @example
370
+ * ```ts
371
+ * import { generateCascade, createMemoryProvider } from 'ai-database'
372
+ *
373
+ * const result = await generateCascade({
374
+ * adapter: createMemoryProvider(),
375
+ * rootNoun: 'Customer',
376
+ * rootHints: { industry: 'B2B SaaS', size: 'enterprise' },
377
+ * children: [
378
+ * {
379
+ * noun: 'Order',
380
+ * count: 5,
381
+ * verb: 'placedBy',
382
+ * hints: { stage: 'closed-won' },
383
+ * children: [
384
+ * { noun: 'OrderItem', count: [2, 5], verb: 'partOf' },
385
+ * ],
386
+ * },
387
+ * ],
388
+ * model: 'sonnet',
389
+ * })
390
+ *
391
+ * console.log(result.root.$id) // root Customer id
392
+ * console.log(result.stats.written) // 1 + 5 + (2..5)*5
393
+ * ```
394
+ */
395
+ export declare function generateCascade(options: GenerateCascadeOptions): Promise<CascadeResult>;
396
+ /**
397
+ * Build the embedding text from a Thing's data, preferring human-readable
398
+ * fields per the POC's `embedTextFor`. Falls back to JSON if no preferred
399
+ * fields exist.
400
+ */
401
+ export declare function buildEmbedText(data: Record<string, unknown>): string;
402
+ export type { SVOAction };
403
+ export { hasActionRecording };
404
+ //# sourceMappingURL=cascade-orchestrator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cascade-orchestrator.d.ts","sourceRoot":"","sources":["../src/cascade-orchestrator.ts"],"names":[],"mappings":"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"}