@api-client/core 0.19.1 → 0.19.2

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 (117) hide show
  1. package/build/src/mocking/ModelingMock.d.ts +2 -0
  2. package/build/src/mocking/ModelingMock.d.ts.map +1 -1
  3. package/build/src/mocking/ModelingMock.js +2 -0
  4. package/build/src/mocking/ModelingMock.js.map +1 -1
  5. package/build/src/mocking/lib/Ai.d.ts +11 -0
  6. package/build/src/mocking/lib/Ai.d.ts.map +1 -0
  7. package/build/src/mocking/lib/Ai.js +53 -0
  8. package/build/src/mocking/lib/Ai.js.map +1 -0
  9. package/build/src/modeling/ai/DataDomainDelta.d.ts +146 -0
  10. package/build/src/modeling/ai/DataDomainDelta.d.ts.map +1 -0
  11. package/build/src/modeling/ai/DataDomainDelta.js +729 -0
  12. package/build/src/modeling/ai/DataDomainDelta.js.map +1 -0
  13. package/build/src/modeling/ai/DomainSerialization.d.ts +20 -0
  14. package/build/src/modeling/ai/DomainSerialization.d.ts.map +1 -0
  15. package/build/src/modeling/ai/DomainSerialization.js +185 -0
  16. package/build/src/modeling/ai/DomainSerialization.js.map +1 -0
  17. package/build/src/modeling/ai/domain_response_schema.d.ts +806 -0
  18. package/build/src/modeling/ai/domain_response_schema.d.ts.map +1 -0
  19. package/build/src/modeling/ai/domain_response_schema.js +289 -0
  20. package/build/src/modeling/ai/domain_response_schema.js.map +1 -0
  21. package/build/src/modeling/ai/domain_tools.d.ts +68 -0
  22. package/build/src/modeling/ai/domain_tools.d.ts.map +1 -0
  23. package/build/src/modeling/ai/domain_tools.js +71 -0
  24. package/build/src/modeling/ai/domain_tools.js.map +1 -0
  25. package/build/src/modeling/ai/index.d.ts +10 -0
  26. package/build/src/modeling/ai/index.d.ts.map +1 -0
  27. package/build/src/modeling/ai/index.js +9 -0
  28. package/build/src/modeling/ai/index.js.map +1 -0
  29. package/build/src/modeling/ai/message_parser.d.ts +23 -0
  30. package/build/src/modeling/ai/message_parser.d.ts.map +1 -0
  31. package/build/src/modeling/ai/message_parser.js +93 -0
  32. package/build/src/modeling/ai/message_parser.js.map +1 -0
  33. package/build/src/modeling/ai/prompts/domain_system.d.ts +6 -0
  34. package/build/src/modeling/ai/prompts/domain_system.d.ts.map +1 -0
  35. package/build/src/modeling/ai/prompts/domain_system.js +80 -0
  36. package/build/src/modeling/ai/prompts/domain_system.js.map +1 -0
  37. package/build/src/modeling/ai/tools/DataDomain.tools.d.ts +25 -0
  38. package/build/src/modeling/ai/tools/DataDomain.tools.d.ts.map +1 -0
  39. package/build/src/modeling/ai/tools/DataDomain.tools.js +334 -0
  40. package/build/src/modeling/ai/tools/DataDomain.tools.js.map +1 -0
  41. package/build/src/modeling/ai/tools/Semantic.tools.d.ts +48 -0
  42. package/build/src/modeling/ai/tools/Semantic.tools.d.ts.map +1 -0
  43. package/build/src/modeling/ai/tools/Semantic.tools.js +36 -0
  44. package/build/src/modeling/ai/tools/Semantic.tools.js.map +1 -0
  45. package/build/src/modeling/ai/tools/config.d.ts +13 -0
  46. package/build/src/modeling/ai/tools/config.d.ts.map +1 -0
  47. package/build/src/modeling/ai/tools/config.js +2 -0
  48. package/build/src/modeling/ai/tools/config.js.map +1 -0
  49. package/build/src/modeling/ai/types.d.ts +302 -0
  50. package/build/src/modeling/ai/types.d.ts.map +1 -0
  51. package/build/src/modeling/ai/types.js +40 -0
  52. package/build/src/modeling/ai/types.js.map +1 -0
  53. package/build/src/models/AiMessage.d.ts +185 -0
  54. package/build/src/models/AiMessage.d.ts.map +1 -0
  55. package/build/src/models/AiMessage.js +203 -0
  56. package/build/src/models/AiMessage.js.map +1 -0
  57. package/build/src/models/AiSession.d.ts +80 -0
  58. package/build/src/models/AiSession.d.ts.map +1 -0
  59. package/build/src/models/AiSession.js +102 -0
  60. package/build/src/models/AiSession.js.map +1 -0
  61. package/build/src/models/kinds.d.ts +2 -0
  62. package/build/src/models/kinds.d.ts.map +1 -1
  63. package/build/src/models/kinds.js +2 -0
  64. package/build/src/models/kinds.js.map +1 -1
  65. package/build/src/sdk/AiSdk.d.ts +93 -0
  66. package/build/src/sdk/AiSdk.d.ts.map +1 -0
  67. package/build/src/sdk/AiSdk.js +348 -0
  68. package/build/src/sdk/AiSdk.js.map +1 -0
  69. package/build/src/sdk/RouteBuilder.d.ts +7 -0
  70. package/build/src/sdk/RouteBuilder.d.ts.map +1 -1
  71. package/build/src/sdk/RouteBuilder.js +18 -0
  72. package/build/src/sdk/RouteBuilder.js.map +1 -1
  73. package/build/src/sdk/Sdk.d.ts +2 -0
  74. package/build/src/sdk/Sdk.d.ts.map +1 -1
  75. package/build/src/sdk/Sdk.js +2 -0
  76. package/build/src/sdk/Sdk.js.map +1 -1
  77. package/build/src/sdk/SdkBase.d.ts +4 -0
  78. package/build/src/sdk/SdkBase.d.ts.map +1 -1
  79. package/build/src/sdk/SdkBase.js.map +1 -1
  80. package/build/src/sdk/SdkMock.d.ts +15 -0
  81. package/build/src/sdk/SdkMock.d.ts.map +1 -1
  82. package/build/src/sdk/SdkMock.js +118 -0
  83. package/build/src/sdk/SdkMock.js.map +1 -1
  84. package/build/tsconfig.tsbuildinfo +1 -1
  85. package/data/models/example-generator-api.json +22 -22
  86. package/package.json +3 -3
  87. package/src/mocking/ModelingMock.ts +2 -0
  88. package/src/mocking/lib/Ai.ts +71 -0
  89. package/src/modeling/ai/DataDomainDelta.ts +798 -0
  90. package/src/modeling/ai/DomainSerialization.ts +199 -0
  91. package/src/modeling/ai/domain_response_schema.ts +301 -0
  92. package/src/modeling/ai/domain_tools.ts +76 -0
  93. package/src/modeling/ai/message_parser.ts +101 -0
  94. package/src/modeling/ai/prompts/domain_system.ts +79 -0
  95. package/src/modeling/ai/readme.md +8 -0
  96. package/src/modeling/ai/tools/DataDomain.tools.ts +365 -0
  97. package/src/modeling/ai/tools/Semantic.tools.ts +38 -0
  98. package/src/modeling/ai/tools/config.ts +13 -0
  99. package/src/modeling/ai/tools/readme.md +3 -0
  100. package/src/modeling/ai/types.ts +306 -0
  101. package/src/models/AiMessage.ts +335 -0
  102. package/src/models/AiSession.ts +160 -0
  103. package/src/models/kinds.ts +2 -0
  104. package/src/sdk/AiSdk.ts +395 -0
  105. package/src/sdk/RouteBuilder.ts +27 -0
  106. package/src/sdk/Sdk.ts +3 -0
  107. package/src/sdk/SdkBase.ts +4 -0
  108. package/src/sdk/SdkMock.ts +185 -0
  109. package/tests/unit/mocking/current/Ai.spec.ts +109 -0
  110. package/tests/unit/modeling/ai/DataDomainDelta.spec.ts +419 -0
  111. package/tests/unit/modeling/ai/DomainAiTools.spec.ts +29 -0
  112. package/tests/unit/modeling/ai/DomainSerialization.spec.ts +143 -0
  113. package/tests/unit/modeling/ai/message_parser.spec.ts +157 -0
  114. package/tests/unit/modeling/ai/tools/DataDomain.tools.spec.ts +64 -0
  115. package/tests/unit/modeling/ai/tools/Semantic.tools.spec.ts +55 -0
  116. package/tests/unit/models/AiMessage.spec.ts +216 -0
  117. package/tests/unit/models/AiSession.spec.ts +147 -0
@@ -0,0 +1,729 @@
1
+ import { nanoid } from '@api-client/core/nanoid.js';
2
+ import { SemanticScope, DataSemantics } from '@api-client/core/modeling/Semantics.js';
3
+ import { DomainEntityKind, DomainPropertyKind, DomainAssociationKind } from '@api-client/core/models/kinds.js';
4
+ /**
5
+ * Normalizes the delta by removing duplicates. For example, when the model
6
+ * adds and entity more than once to the `modifiedEntities` array, This will merge all the changes into a single entity.
7
+ * @param delta The delta to normalize.
8
+ * @returns The normalized delta.
9
+ */
10
+ function mergeArrayByKey(items, mergeFn, keyProp = 'key') {
11
+ if (!items || items.length === 0)
12
+ return items;
13
+ const map = new Map();
14
+ const result = [];
15
+ for (const item of items) {
16
+ const k = item[keyProp];
17
+ if (!k) {
18
+ result.push({ ...item });
19
+ continue;
20
+ }
21
+ const existing = map.get(k);
22
+ if (existing) {
23
+ mergeFn(existing, item);
24
+ }
25
+ else {
26
+ const copy = { ...item };
27
+ map.set(k, copy);
28
+ result.push(copy);
29
+ }
30
+ }
31
+ return result;
32
+ }
33
+ /**
34
+ * A utility class responsible for applying AI-generated modifications (deltas)
35
+ * to an existing `DataDomain` model. It handles adding, modifying, and deleting
36
+ * entities, properties, associations, semantics, and models based on the
37
+ * prescribed changes.
38
+ *
39
+ * It also maintains a mapping of AI-generated provisional keys to the
40
+ * actual nanoid keys used within the data domain to ensure references remain intact.
41
+ */
42
+ export class DataDomainDelta {
43
+ /**
44
+ * The data domain to which the delta will be applied.
45
+ */
46
+ domain;
47
+ /**
48
+ * The map containing the mappings of AI generated keys to proper nanoids.
49
+ */
50
+ keyMap;
51
+ /**
52
+ * Initializes a new instance of the `DataDomainDelta` class.
53
+ *
54
+ * @param domain The target data domain where changes will be applied.
55
+ * @param keyMap An optional map tracking AI-generated provisional keys to actual domain nanoids.
56
+ */
57
+ constructor(domain, keyMap = new Map()) {
58
+ this.domain = domain;
59
+ this.keyMap = keyMap;
60
+ }
61
+ /**
62
+ * Applies the entire given delta structure to the data domain in a single pass.
63
+ * Operations include processing added/modified/deleted components across
64
+ * models, entities, properties, associations, and semantics.
65
+ *
66
+ * @param delta The AI-generated delta schema containing all requested changes.
67
+ */
68
+ apply(delta) {
69
+ if (delta.addedModels) {
70
+ for (const m of delta.addedModels) {
71
+ const existing = this.domain.findModel(this.keyMap.get(m.key) || m.key);
72
+ if (!existing) {
73
+ let newKey = this.keyMap.get(m.key);
74
+ if (!newKey) {
75
+ newKey = nanoid();
76
+ this.keyMap.set(m.key, newKey);
77
+ }
78
+ this.domain.addModel({ key: newKey, info: { name: m.name, description: m.description } });
79
+ }
80
+ }
81
+ }
82
+ if (delta.modifiedModels) {
83
+ for (const mod of delta.modifiedModels) {
84
+ const actualKey = this.keyMap.get(mod.key) || mod.key;
85
+ const model = this.domain.findModel(actualKey);
86
+ if (model) {
87
+ if (mod.name !== undefined)
88
+ model.info.name = mod.name;
89
+ if (mod.description !== undefined)
90
+ model.info.description = mod.description;
91
+ }
92
+ }
93
+ }
94
+ if (delta.addedEntities) {
95
+ for (const e of delta.addedEntities) {
96
+ this.handleAddEntity(this.domain, e);
97
+ }
98
+ }
99
+ if (delta.deletedEntityKeys) {
100
+ for (const key of delta.deletedEntityKeys) {
101
+ const actualKey = this.keyMap.get(key) || key;
102
+ this.domain.removeEntity(actualKey);
103
+ }
104
+ }
105
+ if (delta.modifiedEntities) {
106
+ for (const mod of delta.modifiedEntities) {
107
+ const actualEntityKey = this.keyMap.get(mod.key) || mod.key;
108
+ const entity = this.domain.findEntity(actualEntityKey);
109
+ if (!entity) {
110
+ continue;
111
+ }
112
+ if (mod.modelKey) {
113
+ const currentModel = entity.getParentInstance();
114
+ const actualModelKey = this.keyMap.get(mod.modelKey) || mod.modelKey;
115
+ if (currentModel.key !== actualModelKey && currentModel.info.name !== mod.modelKey) {
116
+ const newModel = this.getModel(this.domain, actualModelKey);
117
+ newModel.attachEntity(entity.key);
118
+ }
119
+ }
120
+ if (mod.name)
121
+ entity.info.name = mod.name;
122
+ if (mod.displayName)
123
+ entity.info.displayName = mod.displayName;
124
+ if (mod.description)
125
+ entity.info.description = mod.description;
126
+ this.applySemantics(entity, mod.addedSemantics, mod.modifiedSemantics, mod.deletedSemanticIds);
127
+ this.handlePropertyAdds(entity, mod.addedProperties);
128
+ this.handlePropertyDeletes(this.domain, mod.deletedPropertyKeys);
129
+ this.handlePropertyMods(this.domain, mod.modifiedProperties);
130
+ this.handleAssociationAdds(entity, mod.addedAssociations);
131
+ this.handleAssociationDeletes(this.domain, mod.deletedAssociationKeys);
132
+ this.handleAssociationMods(this.domain, mod.modifiedAssociations);
133
+ }
134
+ }
135
+ if (delta.deletedModelKeys) {
136
+ for (const key of delta.deletedModelKeys) {
137
+ const actualKey = this.keyMap.get(key) || key;
138
+ try {
139
+ this.domain.removeModel(actualKey);
140
+ }
141
+ catch {
142
+ // ignore
143
+ }
144
+ }
145
+ }
146
+ }
147
+ /**
148
+ * Internal handler to add a new entity to the data domain based on the provided schema.
149
+ * It also recursively handles adding the entity's semantics, properties, and associations.
150
+ *
151
+ * @param domain The data domain where the entity will reside.
152
+ * @param e The schema definition of the entity to be added.
153
+ */
154
+ handleAddEntity(domain, e) {
155
+ const targetModel = this.getModel(domain, e.modelKey || 'ai_generated');
156
+ const entityInput = { ...e };
157
+ delete entityInput.semantics;
158
+ let entityKey = this.keyMap.get(e.key);
159
+ if (!entityKey) {
160
+ entityKey = nanoid();
161
+ this.keyMap.set(e.key, entityKey);
162
+ }
163
+ const entityInfo = {
164
+ ...entityInput,
165
+ key: entityKey,
166
+ info: {
167
+ name: e.name,
168
+ displayName: e.displayName,
169
+ description: e.description,
170
+ },
171
+ };
172
+ const createdEntity = targetModel.addEntity(entityInfo);
173
+ this.applySemantics(createdEntity, e.semantics);
174
+ if (e.properties) {
175
+ for (const p of e.properties) {
176
+ this.handleAddProperty(createdEntity, p);
177
+ }
178
+ }
179
+ if (e.associations) {
180
+ for (const a of e.associations) {
181
+ this.handleAddAssociation(createdEntity, a);
182
+ }
183
+ }
184
+ }
185
+ /**
186
+ * Processes an array of newly added properties for a specific entity.
187
+ *
188
+ * @param entity The target domain entity to receive the new properties.
189
+ * @param adds The list of property definitions to add, if any.
190
+ */
191
+ handlePropertyAdds(entity, adds) {
192
+ if (!adds) {
193
+ return;
194
+ }
195
+ for (const p of adds) {
196
+ this.handleAddProperty(entity, p);
197
+ }
198
+ }
199
+ /**
200
+ * Internal handler to add a single property to an entity, generating keys
201
+ * and applying semantics as defined in the AI schema.
202
+ *
203
+ * @param entity The target domain entity.
204
+ * @param p The schema definition of the property to add.
205
+ */
206
+ handleAddProperty(entity, p) {
207
+ let propKey = p.key ? this.keyMap.get(p.key) : undefined;
208
+ if (!propKey) {
209
+ propKey = nanoid();
210
+ if (p.key) {
211
+ this.keyMap.set(p.key, propKey);
212
+ }
213
+ }
214
+ const prop = entity.addProperty({
215
+ key: propKey,
216
+ type: p.type,
217
+ info: {
218
+ name: p.name,
219
+ displayName: p.displayName,
220
+ description: p.description,
221
+ },
222
+ required: p.constraints?.required,
223
+ unique: p.constraints?.unique,
224
+ index: p.constraints?.index,
225
+ primary: p.constraints?.primary,
226
+ multiple: p.constraints?.multiple,
227
+ readOnly: p.constraints?.readOnly,
228
+ writeOnly: p.constraints?.writeOnly,
229
+ deprecated: p.deprecated,
230
+ schema: p.schema,
231
+ tags: p.tags,
232
+ });
233
+ this.applySemantics(prop, p.semantics);
234
+ }
235
+ /**
236
+ * Processes the deletion of properties by their keys from the given domain.
237
+ * Fails silently if a key is not found, maintaining fault tolerance.
238
+ *
239
+ * @param domain The target data domain.
240
+ * @param keys The array of property keys (AI-generated or actual) to remove.
241
+ */
242
+ handlePropertyDeletes(domain, keys) {
243
+ if (!keys) {
244
+ return;
245
+ }
246
+ for (const key of keys) {
247
+ const actualKey = this.keyMap.get(key) || key;
248
+ try {
249
+ domain.removeProperty(actualKey);
250
+ }
251
+ catch {
252
+ // we can ignore in case the model got the wrong key.
253
+ }
254
+ }
255
+ }
256
+ /**
257
+ * Processes modifications to existing properties within the domain, updating
258
+ * specific metadata, constraints, schema rules, and semantics based on the delta.
259
+ *
260
+ * @param domain The target data domain.
261
+ * @param mods The list of property modifications to apply.
262
+ */
263
+ handlePropertyMods(domain, mods) {
264
+ if (!mods) {
265
+ return;
266
+ }
267
+ for (const mod of mods) {
268
+ const actualKey = this.keyMap.get(mod.key) || mod.key;
269
+ const prop = domain.findProperty(actualKey);
270
+ if (!prop) {
271
+ continue;
272
+ }
273
+ if (mod.name) {
274
+ prop.info.name = mod.name;
275
+ }
276
+ if (mod.displayName) {
277
+ prop.info.displayName = mod.displayName;
278
+ }
279
+ if (mod.description) {
280
+ prop.info.description = mod.description;
281
+ }
282
+ if (mod.type) {
283
+ prop.type = mod.type;
284
+ }
285
+ if (mod.deprecated !== undefined) {
286
+ prop.deprecated = mod.deprecated;
287
+ }
288
+ if (mod.constraints) {
289
+ if (mod.constraints.required !== undefined) {
290
+ prop.required = mod.constraints.required;
291
+ }
292
+ if (mod.constraints.unique !== undefined) {
293
+ prop.unique = mod.constraints.unique;
294
+ }
295
+ if (mod.constraints.index !== undefined) {
296
+ prop.index = mod.constraints.index;
297
+ }
298
+ if (mod.constraints.primary !== undefined) {
299
+ prop.primary = mod.constraints.primary;
300
+ }
301
+ if (mod.constraints.multiple !== undefined) {
302
+ prop.multiple = mod.constraints.multiple;
303
+ }
304
+ if (mod.constraints.readOnly !== undefined) {
305
+ prop.readOnly = mod.constraints.readOnly;
306
+ }
307
+ if (mod.constraints.writeOnly !== undefined) {
308
+ prop.writeOnly = mod.constraints.writeOnly;
309
+ }
310
+ }
311
+ if (mod.schema) {
312
+ if (!prop.schema) {
313
+ prop.schema = {};
314
+ }
315
+ if (mod.schema.defaultValue) {
316
+ if (!prop.schema.defaultValue) {
317
+ prop.schema.defaultValue = {
318
+ value: '',
319
+ type: 'literal',
320
+ };
321
+ }
322
+ if (mod.schema.defaultValue.type) {
323
+ prop.schema.defaultValue.type = mod.schema.defaultValue.type;
324
+ }
325
+ if (mod.schema.defaultValue.value) {
326
+ prop.schema.defaultValue.value = mod.schema.defaultValue.value;
327
+ }
328
+ }
329
+ if (mod.schema.pattern !== undefined) {
330
+ prop.schema.pattern = mod.schema.pattern;
331
+ }
332
+ if (mod.schema.minimum !== undefined) {
333
+ prop.schema.minimum = mod.schema.minimum;
334
+ }
335
+ if (mod.schema.maximum !== undefined) {
336
+ prop.schema.maximum = mod.schema.maximum;
337
+ }
338
+ if (mod.schema.exclusiveMinimum !== undefined) {
339
+ prop.schema.exclusiveMinimum = mod.schema.exclusiveMinimum;
340
+ }
341
+ if (mod.schema.exclusiveMaximum !== undefined) {
342
+ prop.schema.exclusiveMaximum = mod.schema.exclusiveMaximum;
343
+ }
344
+ if (mod.schema.multipleOf !== undefined) {
345
+ prop.schema.multipleOf = mod.schema.multipleOf;
346
+ }
347
+ if (mod.schema.enum !== undefined) {
348
+ prop.schema.enum = [...mod.schema.enum];
349
+ }
350
+ if (mod.schema.examples !== undefined) {
351
+ prop.schema.examples = [...mod.schema.examples];
352
+ }
353
+ }
354
+ this.applySemantics(prop, mod.addedSemantics, mod.modifiedSemantics, mod.deletedSemanticIds);
355
+ }
356
+ }
357
+ /**
358
+ * Processes an array of newly added associations for a specific entity.
359
+ *
360
+ * @param entity The target domain entity referencing the newly created associations.
361
+ * @param adds An array of association definitions to add, if any.
362
+ */
363
+ handleAssociationAdds(entity, adds) {
364
+ if (!adds) {
365
+ return;
366
+ }
367
+ for (const a of adds) {
368
+ this.handleAddAssociation(entity, a);
369
+ }
370
+ }
371
+ /**
372
+ * Internal handler to append a single association to an entity, effectively creating
373
+ * a relationship to one or more targets. Attempts an optimized exact O(1) loopup
374
+ * before falling back to a full domain search.
375
+ *
376
+ * @param entity The source domain entity creating the association.
377
+ * @param a The defining schema for the new association.
378
+ */
379
+ handleAddAssociation(entity, a) {
380
+ let assocKey = this.keyMap.get(a.key);
381
+ if (!assocKey) {
382
+ assocKey = nanoid();
383
+ this.keyMap.set(a.key, assocKey);
384
+ }
385
+ const assoc = entity.addAssociation({
386
+ key: assocKey,
387
+ info: { name: a.name, displayName: a.displayName, description: a.description },
388
+ required: a.required,
389
+ multiple: a.multiple,
390
+ onDelete: a.onDelete,
391
+ schema: a.schema,
392
+ });
393
+ if (a.targets) {
394
+ for (const t of a.targets) {
395
+ const actualTargetKey = this.keyMap.get(t.key) || t.key;
396
+ // 1. Try exact match by key
397
+ const exactMatch = entity.domain.findEntity(actualTargetKey);
398
+ if (exactMatch) {
399
+ if (exactMatch.namespace !== entity.domain.key) {
400
+ assoc.addTarget(exactMatch.key, exactMatch.namespace);
401
+ }
402
+ else {
403
+ assoc.addTarget(exactMatch.key);
404
+ }
405
+ }
406
+ else {
407
+ // 2. Try name/display name search
408
+ const target = entity.domain.search({
409
+ query: actualTargetKey,
410
+ includeForeignDomains: true,
411
+ nodeTypes: [DomainEntityKind],
412
+ });
413
+ if (target.length > 0) {
414
+ const found = target[0];
415
+ if (found.isForeign) {
416
+ assoc.addTarget(found.key, found.node.namespace);
417
+ }
418
+ else {
419
+ assoc.addTarget(found.key);
420
+ }
421
+ }
422
+ else {
423
+ assoc.addTarget(actualTargetKey);
424
+ }
425
+ }
426
+ }
427
+ }
428
+ this.applySemantics(assoc, a.semantics);
429
+ }
430
+ /**
431
+ * Processes the deletion of associations by their keys from the given domain.
432
+ * Safely ignores errors if the specified association does not exist.
433
+ *
434
+ * @param domain The target data domain.
435
+ * @param keys An array of association keys to safely remove.
436
+ */
437
+ handleAssociationDeletes(domain, keys) {
438
+ if (!keys) {
439
+ return;
440
+ }
441
+ for (const key of keys) {
442
+ const actualKey = this.keyMap.get(key) || key;
443
+ try {
444
+ domain.removeAssociation(actualKey);
445
+ }
446
+ catch {
447
+ // we can ignore in case the model got the wrong key.
448
+ }
449
+ }
450
+ }
451
+ /**
452
+ * Processes modifications to existing associations within the domain.
453
+ * Updates attributes, semantics, and handles adding/replacing association targets.
454
+ *
455
+ * @param domain The target data domain containing the associations.
456
+ * @param mods An array of requested association modifications.
457
+ */
458
+ handleAssociationMods(domain, mods) {
459
+ if (!mods) {
460
+ return;
461
+ }
462
+ for (const mod of mods) {
463
+ const actualKey = this.keyMap.get(mod.key) || mod.key;
464
+ const assoc = domain.findAssociation(actualKey);
465
+ if (!assoc) {
466
+ continue;
467
+ }
468
+ if (mod.name) {
469
+ assoc.info.name = mod.name;
470
+ }
471
+ if (mod.displayName) {
472
+ assoc.info.displayName = mod.displayName;
473
+ }
474
+ if (mod.description) {
475
+ assoc.info.description = mod.description;
476
+ }
477
+ if (mod.required !== undefined) {
478
+ assoc.required = mod.required;
479
+ }
480
+ if (mod.onDelete !== undefined) {
481
+ assoc.onDelete = mod.onDelete;
482
+ }
483
+ if (mod.targets) {
484
+ // Clear existing targets before adding new ones
485
+ assoc.targets.splice(0, assoc.targets.length);
486
+ for (const t of mod.targets) {
487
+ const actualTargetKey = this.keyMap.get(t.key) || t.key;
488
+ // 1. Try exact match by key
489
+ const exactMatch = domain.findEntity(actualTargetKey);
490
+ if (exactMatch) {
491
+ if (exactMatch.namespace !== domain.key) {
492
+ assoc.addTarget(exactMatch.key, exactMatch.namespace);
493
+ }
494
+ else {
495
+ assoc.addTarget(exactMatch.key);
496
+ }
497
+ }
498
+ else {
499
+ // 2. Try name/display name search
500
+ const targetSearch = domain.search({
501
+ query: actualTargetKey,
502
+ includeForeignDomains: true,
503
+ nodeTypes: [DomainEntityKind],
504
+ });
505
+ if (targetSearch.length > 0) {
506
+ const found = targetSearch[0];
507
+ if (found.isForeign) {
508
+ assoc.addTarget(found.key, found.node.namespace);
509
+ }
510
+ else {
511
+ assoc.addTarget(found.key);
512
+ }
513
+ }
514
+ else {
515
+ assoc.addTarget(actualTargetKey);
516
+ }
517
+ }
518
+ }
519
+ }
520
+ this.applySemantics(assoc, mod.addedSemantics, mod.modifiedSemantics, mod.deletedSemanticIds);
521
+ }
522
+ }
523
+ /**
524
+ * Retrieves an existing `DomainModel` by its given key. If the model
525
+ * does not exist in the domain (e.g., AI generated a brand new model name natively),
526
+ * a newly instantiated one is created and registered within the domain automatically.
527
+ *
528
+ * @param domain The target data domain.
529
+ * @param modelKey The AI-suggested or actual nanoid key of the model.
530
+ * @returns The resolved or newly created `DomainModel`.
531
+ */
532
+ getModel(domain, modelKey) {
533
+ const mappedKey = this.keyMap.get(modelKey) || modelKey;
534
+ let m = domain.findModel(mappedKey);
535
+ if (!m) {
536
+ // AI generated a new model name (like "shipping"). Use it as the name, let core generate the nanoid key.
537
+ const newKey = this.keyMap.get(modelKey) || nanoid();
538
+ this.keyMap.set(modelKey, newKey);
539
+ m = domain.addModel({ key: newKey, info: { name: modelKey } });
540
+ }
541
+ return m;
542
+ }
543
+ /**
544
+ * Helper function to batch apply semantic patches (add, modify, delete)
545
+ * to a specific domain component (Entity, Property, or Association).
546
+ * Validates semantic scopes heavily before applying.
547
+ *
548
+ * @param target The domain element (Entity, Property, Association) to receive the semantics.
549
+ * @param added List of semantic blocks to newly append.
550
+ * @param modified List of existing semantics to override/update.
551
+ * @param deleted Array of semantic IDs indicating removals.
552
+ */
553
+ applySemantics(target, added, modified, deleted) {
554
+ // Determine the expected scope for the target
555
+ let expectedScope;
556
+ if (target.kind === DomainEntityKind) {
557
+ expectedScope = SemanticScope.Entity;
558
+ }
559
+ else if (target.kind === DomainPropertyKind) {
560
+ expectedScope = SemanticScope.Property;
561
+ }
562
+ else if (target.kind === DomainAssociationKind) {
563
+ expectedScope = SemanticScope.Association;
564
+ }
565
+ else {
566
+ throw new Error(`Unsupported target kind for semantics: ${target.kind}`);
567
+ }
568
+ const isValidSemantic = (id) => {
569
+ const semanticDef = DataSemantics[id];
570
+ if (!semanticDef) {
571
+ return false;
572
+ }
573
+ if (semanticDef.scope !== expectedScope) {
574
+ return false;
575
+ }
576
+ return true;
577
+ };
578
+ if (added) {
579
+ for (const s of added) {
580
+ const typeId = this.ensureSemanticId(s.id);
581
+ if (isValidSemantic(typeId)) {
582
+ target.addSemantic({ id: typeId, config: s.config });
583
+ }
584
+ }
585
+ }
586
+ if (modified) {
587
+ for (const s of modified) {
588
+ const typeId = this.ensureSemanticId(s.id);
589
+ if (isValidSemantic(typeId)) {
590
+ // Technically addSemantic overrides existing if they have the same ID
591
+ target.addSemantic({ id: typeId, config: s.config });
592
+ }
593
+ }
594
+ }
595
+ if (deleted) {
596
+ for (const id of deleted) {
597
+ const typeId = this.ensureSemanticId(id);
598
+ if (isValidSemantic(typeId)) {
599
+ target.removeSemantic(typeId);
600
+ }
601
+ }
602
+ }
603
+ }
604
+ /**
605
+ * Forces the given semantic ID to follow the structured format `Semantic#{id}`.
606
+ *
607
+ * @param id The raw semantic string given by the LLM/Delta payload.
608
+ * @returns The corrected semantic ID structured for internal parsing.
609
+ */
610
+ ensureSemanticId(id) {
611
+ let result = id;
612
+ if (!id.startsWith('Semantic#')) {
613
+ result = `Semantic#${id}`;
614
+ }
615
+ return result;
616
+ }
617
+ /**
618
+ * Normalizes the delta by removing duplicates. For example, when the model
619
+ * adds an entity more than once to the `modifiedEntities` array, this will merge all the changes
620
+ * into a single entity.
621
+ * @param delta The delta to normalize.
622
+ * @returns The normalized delta.
623
+ */
624
+ static normalize(delta) {
625
+ const result = { ...delta };
626
+ const mergeProperties = (a, b) => {
627
+ const aConstraints = a.constraints;
628
+ Object.assign(a, b);
629
+ if (aConstraints && b.constraints) {
630
+ a.constraints = { ...aConstraints, ...b.constraints };
631
+ }
632
+ };
633
+ const mergeAssociations = (a, b) => {
634
+ Object.assign(a, b);
635
+ };
636
+ const mergeSemantics = (a, b) => {
637
+ const aConfig = a.config;
638
+ Object.assign(a, b);
639
+ if (aConfig && b.config) {
640
+ a.config = { ...aConfig, ...b.config };
641
+ }
642
+ };
643
+ const mergeEntities = (a, b) => {
644
+ const aTags = a.tags;
645
+ const aProps = a.properties;
646
+ const aAssoc = a.associations;
647
+ const aSem = a.semantics;
648
+ Object.assign(a, b);
649
+ if (aTags && b.tags) {
650
+ a.tags = Array.from(new Set([...aTags, ...b.tags]));
651
+ }
652
+ if (aProps || b.properties) {
653
+ a.properties = mergeArrayByKey([...(aProps || []), ...(b.properties || [])], mergeProperties);
654
+ }
655
+ if (aAssoc || b.associations) {
656
+ a.associations = mergeArrayByKey([...(aAssoc || []), ...(b.associations || [])], mergeAssociations);
657
+ }
658
+ if (aSem || b.semantics) {
659
+ a.semantics = mergeArrayByKey([...(aSem || []), ...(b.semantics || [])], mergeSemantics, 'id');
660
+ }
661
+ };
662
+ const mergeEntityDeltas = (a, b) => {
663
+ const aTags = a.tags;
664
+ const aAddedProps = a.addedProperties;
665
+ const aModProps = a.modifiedProperties;
666
+ const aDelProps = a.deletedPropertyKeys;
667
+ const aAddedAssoc = a.addedAssociations;
668
+ const aModAssoc = a.modifiedAssociations;
669
+ const aDelAssoc = a.deletedAssociationKeys;
670
+ const aAddedSem = a.addedSemantics;
671
+ const aModSem = a.modifiedSemantics;
672
+ const aDelSem = a.deletedSemanticIds;
673
+ Object.assign(a, b);
674
+ if (aTags && b.tags) {
675
+ a.tags = Array.from(new Set([...aTags, ...b.tags]));
676
+ }
677
+ if (aAddedProps || b.addedProperties) {
678
+ a.addedProperties = mergeArrayByKey([...(aAddedProps || []), ...(b.addedProperties || [])], mergeProperties);
679
+ }
680
+ if (aModProps || b.modifiedProperties) {
681
+ a.modifiedProperties = mergeArrayByKey([...(aModProps || []), ...(b.modifiedProperties || [])], mergeProperties);
682
+ }
683
+ if (aDelProps && b.deletedPropertyKeys) {
684
+ a.deletedPropertyKeys = Array.from(new Set([...aDelProps, ...b.deletedPropertyKeys]));
685
+ }
686
+ if (aAddedAssoc || b.addedAssociations) {
687
+ a.addedAssociations = mergeArrayByKey([...(aAddedAssoc || []), ...(b.addedAssociations || [])], mergeAssociations);
688
+ }
689
+ if (aModAssoc || b.modifiedAssociations) {
690
+ a.modifiedAssociations = mergeArrayByKey([...(aModAssoc || []), ...(b.modifiedAssociations || [])], mergeAssociations);
691
+ }
692
+ if (aDelAssoc && b.deletedAssociationKeys) {
693
+ a.deletedAssociationKeys = Array.from(new Set([...aDelAssoc, ...b.deletedAssociationKeys]));
694
+ }
695
+ if (aAddedSem || b.addedSemantics) {
696
+ a.addedSemantics = mergeArrayByKey([...(aAddedSem || []), ...(b.addedSemantics || [])], mergeSemantics, 'id');
697
+ }
698
+ if (aModSem || b.modifiedSemantics) {
699
+ a.modifiedSemantics = mergeArrayByKey([...(aModSem || []), ...(b.modifiedSemantics || [])], mergeSemantics, 'id');
700
+ }
701
+ if (aDelSem && b.deletedSemanticIds) {
702
+ a.deletedSemanticIds = Array.from(new Set([...aDelSem, ...b.deletedSemanticIds]));
703
+ }
704
+ };
705
+ const mergeModels = (a, b) => {
706
+ Object.assign(a, b);
707
+ };
708
+ if (result.addedEntities) {
709
+ result.addedEntities = mergeArrayByKey(result.addedEntities, mergeEntities);
710
+ }
711
+ if (result.modifiedEntities) {
712
+ result.modifiedEntities = mergeArrayByKey(result.modifiedEntities, mergeEntityDeltas);
713
+ }
714
+ if (result.addedModels) {
715
+ result.addedModels = mergeArrayByKey(result.addedModels, mergeModels);
716
+ }
717
+ if (result.modifiedModels) {
718
+ result.modifiedModels = mergeArrayByKey(result.modifiedModels, mergeModels);
719
+ }
720
+ if (result.deletedModelKeys) {
721
+ result.deletedModelKeys = Array.from(new Set(result.deletedModelKeys));
722
+ }
723
+ if (result.deletedEntityKeys) {
724
+ result.deletedEntityKeys = Array.from(new Set(result.deletedEntityKeys));
725
+ }
726
+ return result;
727
+ }
728
+ }
729
+ //# sourceMappingURL=DataDomainDelta.js.map