@contentful/experience-design-system-types 2.42.1-dev-build-f69db6bf.0 → 2.43.0-alpha.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 (94) hide show
  1. package/README.md +15 -0
  2. package/dist/package.json +1 -1
  3. package/dist/src/agent-process-lifecycle.d.ts +26 -0
  4. package/dist/src/agent-process-lifecycle.js +171 -0
  5. package/dist/src/agent-prompt-artifact.d.ts +8 -0
  6. package/dist/src/agent-prompt-artifact.js +37 -0
  7. package/dist/src/agent-prompt-transport.d.ts +1 -0
  8. package/dist/src/agent-prompt-transport.js +4 -0
  9. package/dist/src/cdf/build.d.ts +9 -2
  10. package/dist/src/cdf/build.js +134 -17
  11. package/dist/src/cdf/finite-values.d.ts +8 -0
  12. package/dist/src/cdf/finite-values.js +21 -0
  13. package/dist/src/cdf/index.d.ts +2 -1
  14. package/dist/src/cdf/index.js +1 -0
  15. package/dist/src/cdf/property-validation.d.ts +16 -0
  16. package/dist/src/cdf/property-validation.js +211 -0
  17. package/dist/src/cdf/representation-validation.d.ts +6 -0
  18. package/dist/src/cdf/representation-validation.js +182 -0
  19. package/dist/src/cdf/schema.d.ts +778 -20
  20. package/dist/src/cdf/schema.js +362 -5
  21. package/dist/src/cdf/types.d.ts +57 -59
  22. package/dist/src/cdf/types.js +72 -15
  23. package/dist/src/cdf/validate.js +31 -1
  24. package/dist/src/cdf/vocabularies.d.ts +1 -1
  25. package/dist/src/cdf/vocabularies.js +9 -1
  26. package/dist/src/config/index.js +6 -3
  27. package/dist/src/exploration/constants.d.ts +10 -0
  28. package/dist/src/exploration/constants.js +18 -0
  29. package/dist/src/exploration/index.d.ts +3 -0
  30. package/dist/src/exploration/index.js +3 -0
  31. package/dist/src/exploration/schemas.d.ts +201 -0
  32. package/dist/src/exploration/schemas.js +126 -0
  33. package/dist/src/exploration/types.d.ts +393 -0
  34. package/dist/src/exploration/types.js +1 -0
  35. package/dist/src/handoff/index.d.ts +1 -1
  36. package/dist/src/index.d.ts +15 -1
  37. package/dist/src/index.js +12 -4
  38. package/dist/src/property-contract/analysis-representation-candidates.d.ts +19 -0
  39. package/dist/src/property-contract/analysis-representation-candidates.js +45 -0
  40. package/dist/src/property-contract/classification.d.ts +38 -0
  41. package/dist/src/property-contract/classification.js +84 -0
  42. package/dist/src/property-contract/compact-model-components.d.ts +16 -0
  43. package/dist/src/property-contract/compact-model-components.js +113 -0
  44. package/dist/src/property-contract/content-digest.d.ts +2 -0
  45. package/dist/src/property-contract/content-digest.js +69 -0
  46. package/dist/src/property-contract/decision-protocol.d.ts +45 -0
  47. package/dist/src/property-contract/decision-protocol.js +251 -0
  48. package/dist/src/property-contract/definition-import-rules.d.ts +10 -0
  49. package/dist/src/property-contract/definition-import-rules.js +105 -0
  50. package/dist/src/property-contract/definition-import.d.ts +13 -0
  51. package/dist/src/property-contract/definition-import.js +52 -0
  52. package/dist/src/property-contract/discriminated-union-source.d.ts +17 -0
  53. package/dist/src/property-contract/discriminated-union-source.js +180 -0
  54. package/dist/src/property-contract/import-prerequisites.d.ts +70 -0
  55. package/dist/src/property-contract/import-prerequisites.js +208 -0
  56. package/dist/src/property-contract/index.d.ts +18 -1
  57. package/dist/src/property-contract/index.js +18 -6
  58. package/dist/src/property-contract/logical-source-graph.d.ts +36 -0
  59. package/dist/src/property-contract/logical-source-graph.js +240 -0
  60. package/dist/src/property-contract/mapper-readiness.d.ts +6 -0
  61. package/dist/src/property-contract/mapper-readiness.js +34 -0
  62. package/dist/src/property-contract/model-exploration.d.ts +42 -0
  63. package/dist/src/property-contract/model-exploration.js +94 -0
  64. package/dist/src/property-contract/native-source-region.d.ts +5 -0
  65. package/dist/src/property-contract/native-source-region.js +125 -0
  66. package/dist/src/property-contract/null-handling.d.ts +10 -0
  67. package/dist/src/property-contract/null-handling.js +45 -0
  68. package/dist/src/property-contract/physical-property-import.d.ts +6 -0
  69. package/dist/src/property-contract/physical-property-import.js +55 -0
  70. package/dist/src/property-contract/property-decision.d.ts +14 -0
  71. package/dist/src/property-contract/property-decision.js +155 -0
  72. package/dist/src/property-contract/property-model.d.ts +197 -0
  73. package/dist/src/property-contract/property-model.js +833 -0
  74. package/dist/src/property-contract/representation-plan.d.ts +133 -0
  75. package/dist/src/property-contract/representation-plan.js +756 -0
  76. package/dist/src/property-contract/representation-proposal.d.ts +65 -0
  77. package/dist/src/property-contract/representation-proposal.js +204 -0
  78. package/dist/src/property-contract/resource-link-schema.d.ts +55 -0
  79. package/dist/src/property-contract/resource-link-schema.js +28 -0
  80. package/dist/src/property-contract/source-representation.d.ts +9 -0
  81. package/dist/src/property-contract/source-representation.js +79 -0
  82. package/dist/src/property-contract/target-definition.d.ts +17 -16
  83. package/dist/src/property-contract/target-definition.js +4 -26
  84. package/dist/src/schema-export.d.ts +30 -0
  85. package/dist/src/schema-export.js +285 -0
  86. package/dist/src/shared-source.d.ts +105 -0
  87. package/dist/src/shared-source.js +1 -0
  88. package/dist/src/source-input-association.d.ts +23 -0
  89. package/dist/src/source-input-association.js +52 -0
  90. package/dist/src/sources-api/preview/index.d.ts +37 -3
  91. package/dist/src/sources-api/preview/index.js +39 -1
  92. package/dist/src/sources-api/preview/schema.d.ts +2 -0
  93. package/dist/src/sources-api/preview/schema.js +74 -0
  94. package/package.json +1 -1
@@ -0,0 +1,833 @@
1
+ import { cdfToTarget } from '../cdf/property-validation.js';
2
+ import { childPath, cloneJson, freezeJson, jsonEqual, jsonValueIssue, own, } from './json-value.js';
3
+ import { TARGET_PROPERTY_TYPES, containsTargetDefinitionType, validateTargetDefinition, validateTargetValue, } from './target-definition.js';
4
+ import { finiteSourceValueDomain, isSourceBoundRepresentation } from './source-representation.js';
5
+ import { validateRepresentationProposal } from './representation-proposal.js';
6
+ import { discriminatedUnionTag } from './discriminated-union.js';
7
+ import { validateDiscriminatedUnionSourceDefinition } from './discriminated-union-source.js';
8
+ import { validateNullHandlingSource } from './null-handling.js';
9
+ const DEFAULT_TARGETS = [
10
+ 'String',
11
+ 'Number',
12
+ 'Boolean',
13
+ 'Array',
14
+ 'Record',
15
+ 'Integer',
16
+ 'DateTime',
17
+ 'Literal',
18
+ 'DiscriminatedUnion',
19
+ ];
20
+ export function createPropertyProfile(profile) {
21
+ if (!profile || typeof profile.id !== 'string' || !profile.id || profile.revision !== 2)
22
+ throw new Error('Profile requires identity and revision 2');
23
+ if (!Array.isArray(profile.mapperTypes) ||
24
+ !profile.mapperTypes.every((type) => typeof type === 'string') ||
25
+ !Array.isArray(profile.targetTypes) ||
26
+ !profile.targetTypes.every((type) => TARGET_PROPERTY_TYPES.includes(type)) ||
27
+ !Array.isArray(profile.defaultSourceTypes) ||
28
+ !Array.isArray(profile.defaultTargetTypes) ||
29
+ !Array.isArray(profile.requirements) ||
30
+ profile.requirements.some((requirement) => !requirement || typeof requirement.path !== 'string' || typeof requirement.capability !== 'string'))
31
+ throw new Error('Invalid mapper profile');
32
+ if (profile.defaultTargetTypes.some((type) => !DEFAULT_TARGETS.includes(type)))
33
+ throw new Error('Unsupported target default capability');
34
+ if (new Set(profile.mapperTypes).size !== profile.mapperTypes.length ||
35
+ profile.defaultSourceTypes.some((type) => !profile.mapperTypes.includes(type)) ||
36
+ profile.defaultTargetTypes.some((type) => !profile.targetTypes.includes(type)))
37
+ throw new Error('Inconsistent mapper capabilities');
38
+ return freezeJson(cloneJson(profile));
39
+ }
40
+ export const LOCAL_NATIVE_PROPERTY_PROFILE = createPropertyProfile({
41
+ id: 'local-native-cdf',
42
+ revision: 2,
43
+ mapperTypes: [
44
+ 'string',
45
+ 'number',
46
+ 'boolean',
47
+ 'array',
48
+ 'record',
49
+ 'richtext',
50
+ 'media',
51
+ 'link',
52
+ 'token',
53
+ 'Integer',
54
+ 'DateTime',
55
+ 'Literal',
56
+ 'RichText',
57
+ 'JSON',
58
+ 'ResourceLink',
59
+ 'DiscriminatedUnion',
60
+ ],
61
+ targetTypes: [...TARGET_PROPERTY_TYPES],
62
+ defaultSourceTypes: [
63
+ 'string',
64
+ 'number',
65
+ 'boolean',
66
+ 'array',
67
+ 'record',
68
+ 'richtext',
69
+ 'token',
70
+ 'Integer',
71
+ 'DateTime',
72
+ 'Literal',
73
+ 'DiscriminatedUnion',
74
+ ],
75
+ defaultTargetTypes: DEFAULT_TARGETS,
76
+ requirements: [],
77
+ });
78
+ function validSourceDeclaration(declaration) {
79
+ return Boolean(declaration &&
80
+ (declaration.fileId === null || typeof declaration.fileId === 'string') &&
81
+ (declaration.canonicalPath === null || typeof declaration.canonicalPath === 'string') &&
82
+ (declaration.textHash === null || typeof declaration.textHash === 'string') &&
83
+ ['verified', 'changed', 'unverified', 'unavailable'].includes(declaration.binding) &&
84
+ ['startLine', 'endLine', 'startOffset', 'endOffset'].every((key) => {
85
+ const value = declaration[key];
86
+ return (value === null ||
87
+ (key.endsWith('Offset') && value === undefined) ||
88
+ (typeof value === 'number' && Number.isSafeInteger(value) && value >= (key.endsWith('Offset') ? 0 : 1)));
89
+ }));
90
+ }
91
+ export function validateSourceGraph(graph) {
92
+ const unsafe = jsonValueIssue(graph);
93
+ if (unsafe)
94
+ return [{ path: `/source/graph${unsafe.path}`, message: unsafe.message }];
95
+ const issues = [];
96
+ const add = (path, message) => {
97
+ issues.push({ path: `/source/graph${path}`, message });
98
+ };
99
+ if (!graph ||
100
+ graph.schemaVersion !== 1 ||
101
+ !Array.isArray(graph.nodes) ||
102
+ !graph.limits ||
103
+ !Number.isInteger(graph.limits.maxNodes) ||
104
+ graph.limits.maxNodes < 1 ||
105
+ graph.limits.maxNodes > 512 ||
106
+ !Number.isInteger(graph.limits.maxDepth) ||
107
+ graph.limits.maxDepth < 1 ||
108
+ graph.limits.maxDepth > 16 ||
109
+ !Number.isInteger(graph.limits.maxFields) ||
110
+ graph.limits.maxFields < 1 ||
111
+ graph.limits.maxFields > 4096 ||
112
+ (graph.limits.maxEdges !== undefined &&
113
+ (!Number.isInteger(graph.limits.maxEdges) || graph.limits.maxEdges < 1 || graph.limits.maxEdges > 4096)) ||
114
+ !Number.isInteger(graph.omittedCount) ||
115
+ graph.omittedCount < 0 ||
116
+ !['complete-within-declared-bound', 'partial', 'unavailable'].includes(graph.coverage))
117
+ return [{ path: '/source/graph', message: 'Invalid graph envelope or bounds' }];
118
+ const ids = new Set(graph.nodes.map((node) => node?.id));
119
+ if (graph.nodes.length > graph.limits.maxNodes || ids.size !== graph.nodes.length || !ids.has(graph.rootId))
120
+ add('', 'Invalid graph identity or node bounds');
121
+ let fieldCount = 0;
122
+ let edgeCount = 0;
123
+ for (const [i, node] of graph.nodes.entries()) {
124
+ const path = `/nodes/${i}`;
125
+ if (!node ||
126
+ typeof node.id !== 'string' ||
127
+ !node.id ||
128
+ !Array.isArray(node.keyPath) ||
129
+ !node.keyPath.every((key) => typeof key === 'string') ||
130
+ ![
131
+ 'string',
132
+ 'number',
133
+ 'boolean',
134
+ 'null',
135
+ 'undefined',
136
+ 'never',
137
+ 'union',
138
+ 'intersection',
139
+ 'tuple',
140
+ 'array',
141
+ 'bigint',
142
+ 'symbol',
143
+ 'function',
144
+ 'record',
145
+ 'reference',
146
+ 'unknown',
147
+ ].includes(node.kind) ||
148
+ typeof node.typeText !== 'string' ||
149
+ typeof node.required !== 'boolean' ||
150
+ !['complete-within-declared-bound', 'partial', 'unavailable'].includes(node.coverage) ||
151
+ (node.reason !== null && typeof node.reason !== 'string')) {
152
+ add(path, 'Invalid source node');
153
+ continue;
154
+ }
155
+ if (!node.domain ||
156
+ !['closed', 'open', 'unknown'].includes(node.domain.openness) ||
157
+ !['compiler', 'unknown'].includes(node.domain.provenance) ||
158
+ !Array.isArray(node.domain.declaredValues) ||
159
+ (own(node.domain, 'unrepresentedValues') &&
160
+ (!Array.isArray(node.domain.unrepresentedValues) ||
161
+ !node.domain.unrepresentedValues.every((value) => value && typeof value.typeText === 'string' && typeof value.reason === 'string'))))
162
+ add(`${path}/domain`, 'Invalid independent domain evidence');
163
+ if (node.path !== undefined &&
164
+ (!Array.isArray(node.path) ||
165
+ node.path.length > graph.limits.maxNodes + 64 ||
166
+ node.path.some((part) => !part ||
167
+ !['field', 'item', 'tuple', 'union', 'intersection', 'index'].includes(part.kind) ||
168
+ (typeof part.key !== 'string' &&
169
+ (typeof part.key !== 'number' || !Number.isSafeInteger(part.key) || part.key < 0)))))
170
+ add(`${path}/path`, 'Invalid typed source path');
171
+ for (const key of ['readonly', 'nullable', 'undefinable'])
172
+ if (own(node, key) && typeof node[key] !== 'boolean')
173
+ add(`${path}/${key}`, 'Invalid source metadata');
174
+ if (node.compilerIdentity !== undefined &&
175
+ (!node.compilerIdentity ||
176
+ typeof node.compilerIdentity.typeId !== 'string' ||
177
+ !node.compilerIdentity.typeId ||
178
+ (node.compilerIdentity.declarationId !== undefined &&
179
+ (typeof node.compilerIdentity.declarationId !== 'string' || !node.compilerIdentity.declarationId))))
180
+ add(`${path}/compilerIdentity`, 'Invalid compiler identity');
181
+ if (node.alias !== undefined && (typeof node.alias !== 'string' || !node.alias))
182
+ add(`${path}/alias`, 'Invalid source alias');
183
+ for (const key of ['discriminatorKeys', 'callSignatures'])
184
+ if (node[key] !== undefined &&
185
+ (!Array.isArray(node[key]) ||
186
+ !node[key].every((value) => typeof value === 'string') ||
187
+ new Set(node[key]).size !== node[key].length))
188
+ add(`${path}/${key}`, 'Invalid source metadata list');
189
+ if (node.nullabilityProvenance !== undefined &&
190
+ !['compiler', 'syntax', 'compiler-erased', 'unknown'].includes(node.nullabilityProvenance))
191
+ add(path, 'Invalid nullability provenance');
192
+ if (node.nullability !== undefined) {
193
+ const metadata = node.nullability;
194
+ if (!metadata || !['enabled', 'disabled'].includes(metadata.compilerMode))
195
+ add(`${path}/nullability`, 'Invalid null checking mode');
196
+ for (const [kind, key] of [
197
+ ['null', 'nullable'],
198
+ ['undefined', 'undefinable'],
199
+ ]) {
200
+ const fact = metadata?.[kind];
201
+ if (!fact ||
202
+ !['present', 'absent', 'unknown'].includes(fact.state) ||
203
+ !['compiler', 'syntax', 'compiler-erased', 'unknown'].includes(fact.source) ||
204
+ (fact.state === 'present' && !['compiler', 'syntax'].includes(fact.source)) ||
205
+ (fact.state === 'absent' && (fact.source !== 'compiler' || metadata.compilerMode !== 'enabled')) ||
206
+ (fact.state === 'unknown' && !['compiler-erased', 'unknown'].includes(fact.source)) ||
207
+ (fact.state === 'unknown' ? own(node, key) : node[key] !== (fact.state === 'present')))
208
+ add(`${path}/nullability/${kind}`, 'Invalid nullability fact');
209
+ }
210
+ }
211
+ if (node.discriminator !== undefined &&
212
+ (!node.discriminator ||
213
+ !['compiler', 'unknown'].includes(node.discriminator.provenance) ||
214
+ typeof node.discriminator.complete !== 'boolean' ||
215
+ !Array.isArray(node.discriminator.keys) ||
216
+ !jsonEqual(node.discriminator.keys, node.discriminatorKeys)))
217
+ add(path, 'Invalid discriminator evidence');
218
+ if (node.kind === 'reference' &&
219
+ node.coverage === 'complete-within-declared-bound' &&
220
+ node.alternatives?.length !== 1)
221
+ add(path, 'Source reference requires one target');
222
+ if (node.kind === 'array' && node.coverage === 'complete-within-declared-bound' && node.items?.length !== 1)
223
+ add(path, 'Source array requires one item');
224
+ if (node.tupleElements !== undefined &&
225
+ (node.kind !== 'tuple' ||
226
+ !Array.isArray(node.tupleElements) ||
227
+ node.tupleElements.length !== node.items?.length ||
228
+ node.tupleElements.filter((item) => item?.rest).length > 1 ||
229
+ node.tupleElements.some((item, index) => !item ||
230
+ item.nodeId !== node.items?.[index] ||
231
+ (item.label !== null && typeof item.label !== 'string') ||
232
+ typeof item.optional !== 'boolean' ||
233
+ typeof item.rest !== 'boolean')))
234
+ add(`${path}/tupleElements`, 'Invalid source tuple metadata');
235
+ const refs = [];
236
+ for (const key of ['items', 'alternatives'])
237
+ if (own(node, key)) {
238
+ const list = node[key];
239
+ if (!Array.isArray(list) || !list.every((id) => typeof id === 'string'))
240
+ add(`${path}/${key}`, 'Invalid source references');
241
+ else
242
+ refs.push(...list);
243
+ }
244
+ if (own(node, 'fields')) {
245
+ if (!Array.isArray(node.fields))
246
+ add(`${path}/fields`, 'Invalid source fields');
247
+ else {
248
+ fieldCount += node.fields.length;
249
+ const keys = new Set();
250
+ for (const field of node.fields) {
251
+ if (!field ||
252
+ typeof field.key !== 'string' ||
253
+ typeof field.nodeId !== 'string' ||
254
+ typeof field.required !== 'boolean' ||
255
+ (field.readonly !== undefined && typeof field.readonly !== 'boolean') ||
256
+ (field.description !== undefined && typeof field.description !== 'string') ||
257
+ (field.declarations !== undefined &&
258
+ (!Array.isArray(field.declarations) ||
259
+ field.declarations.some((declaration) => !validSourceDeclaration(declaration)))) ||
260
+ keys.has(field.key))
261
+ add(`${path}/fields`, 'Invalid or duplicated own field');
262
+ else {
263
+ keys.add(field.key);
264
+ refs.push(field.nodeId);
265
+ }
266
+ }
267
+ }
268
+ }
269
+ if (own(node, 'indexSignatures')) {
270
+ if (!Array.isArray(node.indexSignatures))
271
+ add(`${path}/indexSignatures`, 'Invalid index evidence');
272
+ else
273
+ for (const index of node.indexSignatures) {
274
+ if (!index || typeof index.keyType !== 'string' || typeof index.valueNodeId !== 'string')
275
+ add(`${path}/indexSignatures`, 'Invalid index reference');
276
+ else
277
+ refs.push(index.valueNodeId);
278
+ }
279
+ }
280
+ edgeCount += refs.length;
281
+ for (const ref of refs)
282
+ if (!ids.has(ref))
283
+ add(path, 'Invalid source node reference');
284
+ }
285
+ if (issues.length)
286
+ return issues;
287
+ for (const [i, node] of graph.nodes.entries()) {
288
+ const path = `/nodes/${i}`;
289
+ for (const field of node.fields ?? []) {
290
+ const child = graph.nodes.find((item) => item.id === field.nodeId);
291
+ if (field.path !== undefined &&
292
+ !jsonEqual(field.path, [
293
+ ...(node.path ?? node.keyPath.map((key) => ({ kind: 'field', key }))),
294
+ { kind: 'field', key: field.key },
295
+ ]))
296
+ add(`${path}/fields`, 'Source occurrence path disagrees');
297
+ if (node.compilerIdentity && (!field.path || !field.declarations))
298
+ add(`${path}/fields`, 'Compiler field requires exact occurrence evidence');
299
+ if (child && !child.compilerIdentity && field.required !== child.required)
300
+ add(`${path}/fields`, 'Source edge requiredness disagrees');
301
+ if (child?.path &&
302
+ !child.compilerIdentity &&
303
+ node.path &&
304
+ !jsonEqual(child.path, [...node.path, { kind: 'field', key: field.key }]))
305
+ add(`${path}/fields`, 'Source field path disagrees');
306
+ }
307
+ if (node.discriminator?.provenance === 'compiler' && node.discriminator.keys.length) {
308
+ if (node.kind !== 'union' || !node.discriminator.complete)
309
+ add(path, 'Discriminator requires complete union');
310
+ for (const key of node.discriminator.keys) {
311
+ const values = [];
312
+ for (const alternative of node.alternatives ?? []) {
313
+ const member = graph.nodes.find((item) => item.id === alternative);
314
+ const edge = member?.fields?.find((field) => field.key === key);
315
+ const tag = edge && graph.nodes.find((item) => item.id === edge.nodeId);
316
+ if (!edge?.required ||
317
+ !tag ||
318
+ tag.domain.provenance !== 'compiler' ||
319
+ tag.domain.openness !== 'closed' ||
320
+ tag.domain.declaredValues.length !== 1 ||
321
+ values.some((value) => jsonEqual(value, tag.domain.declaredValues[0])))
322
+ add(path, 'Unproven unique required discriminator');
323
+ else
324
+ values.push(tag.domain.declaredValues[0]);
325
+ }
326
+ }
327
+ }
328
+ }
329
+ const reachable = new Set();
330
+ const pending = [graph.rootId];
331
+ while (pending.length) {
332
+ const id = pending.pop();
333
+ if (reachable.has(id))
334
+ continue;
335
+ reachable.add(id);
336
+ const node = graph.nodes.find((item) => item.id === id);
337
+ if (node)
338
+ pending.push(...(node.items ?? []), ...(node.alternatives ?? []), ...(node.fields?.map((field) => field.nodeId) ?? []), ...(node.indexSignatures?.map((index) => index.valueNodeId) ?? []));
339
+ }
340
+ if (reachable.size !== graph.nodes.length)
341
+ add('', 'Unreachable source nodes');
342
+ if (edgeCount > (graph.limits.maxEdges ?? 4096))
343
+ add('', 'Source edge census exceeds bounds');
344
+ if (graph.resources !== undefined &&
345
+ (!graph.resources || graph.resources.nodes !== graph.nodes.length || graph.resources.edges !== edgeCount))
346
+ add('/resources', 'Source resource counts disagree');
347
+ if (fieldCount > graph.limits.maxFields)
348
+ add('', 'Source field census exceeds bounds');
349
+ if (graph.coverage === 'complete-within-declared-bound' &&
350
+ (graph.omittedCount || graph.nodes.some((node) => node.coverage !== 'complete-within-declared-bound')))
351
+ add('', 'Complete coverage contradicts omitted or partial source evidence');
352
+ return issues;
353
+ }
354
+ /** Validate JSON defaults against source structure independently of target support. */
355
+ export function validateSourceValue(graph, value, path = '/defaultValue', nodeId = graph.rootId) {
356
+ const invalid = validateSourceGraph(graph);
357
+ if (invalid.length)
358
+ return invalid;
359
+ const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
360
+ const visit = (id, current, at, ancestors) => {
361
+ const node = nodes.get(id);
362
+ if (ancestors.get(id)?.has(current))
363
+ return [{ path: at, message: 'Nonconsuming recursive source' }];
364
+ const next = new Map(ancestors);
365
+ next.set(id, new Set([...(ancestors.get(id) ?? []), current]));
366
+ const issue = (message) => [{ path: at, message }];
367
+ if (node.kind === 'reference')
368
+ return node.alternatives?.length === 1
369
+ ? visit(node.alternatives[0], current, at, next)
370
+ : issue('Invalid source reference');
371
+ if (node.kind === 'union') {
372
+ const alternatives = (node.alternatives ?? []).map((ref) => visit(ref, current, at, next));
373
+ return alternatives.some((result) => !result.length)
374
+ ? []
375
+ : issue('Default matches no declared source alternative');
376
+ }
377
+ if (node.kind === 'intersection')
378
+ return (node.alternatives ?? []).flatMap((ref) => visit(ref, current, at, next));
379
+ if (['string', 'number', 'boolean'].includes(node.kind) && typeof current !== node.kind)
380
+ return issue('Default source kind mismatch');
381
+ if (node.kind === 'null' && current !== null)
382
+ return issue('Default source kind mismatch');
383
+ if (['undefined', 'never'].includes(node.kind))
384
+ return issue('Source does not admit this JSON value');
385
+ if (node.domain.provenance === 'compiler' &&
386
+ node.domain.openness === 'closed' &&
387
+ node.domain.declaredValues.length &&
388
+ !node.domain.declaredValues.some((entry) => jsonEqual(entry, current)))
389
+ return issue('Default outside proven source domain');
390
+ if (node.kind === 'array') {
391
+ if (!Array.isArray(current) || node.items?.length !== 1)
392
+ return issue('Default source array mismatch');
393
+ return current.flatMap((entry, index) => visit(node.items[0], entry, `${at}/${index}`, next));
394
+ }
395
+ if (node.kind === 'tuple') {
396
+ if (!Array.isArray(current))
397
+ return issue('Default source tuple mismatch');
398
+ const elements = node.tupleElements ?? (node.items ?? []).map((nodeId) => ({ nodeId, optional: false, rest: false }));
399
+ const rest = elements.findIndex((element) => element.rest);
400
+ if (rest < 0 && current.length > elements.length)
401
+ return issue('Default tuple has extra items');
402
+ const issues = [];
403
+ const trailing = rest < 0 ? 0 : elements.length - rest - 1;
404
+ if (rest >= 0 && current.length < rest + trailing)
405
+ return issue('Required source tuple item missing');
406
+ for (const [index, element] of elements.entries()) {
407
+ if (element.rest) {
408
+ for (let i = index; i < current.length - trailing; i++)
409
+ issues.push(...visit(element.nodeId, current[i], `${at}/${i}`, next));
410
+ continue;
411
+ }
412
+ const valueIndex = rest >= 0 && index > rest ? current.length - (elements.length - index) : index;
413
+ if (valueIndex >= current.length) {
414
+ if (!element.optional)
415
+ issues.push({ path: `${at}/${valueIndex}`, message: 'Required source tuple item missing' });
416
+ }
417
+ else
418
+ issues.push(...visit(element.nodeId, current[valueIndex], `${at}/${valueIndex}`, next));
419
+ }
420
+ return issues;
421
+ }
422
+ if (node.kind === 'record') {
423
+ if (!current || typeof current !== 'object' || Array.isArray(current))
424
+ return issue('Default source record mismatch');
425
+ const issues = [];
426
+ for (const field of node.fields ?? []) {
427
+ if (!own(current, field.key)) {
428
+ if (field.required)
429
+ issues.push({ path: childPath(at, field.key), message: 'Required source field missing' });
430
+ }
431
+ else
432
+ issues.push(...visit(field.nodeId, current[field.key], childPath(at, field.key), next));
433
+ }
434
+ for (const [key, entry] of Object.entries(current))
435
+ for (const signature of node.indexSignatures ?? [])
436
+ if (signature.keyType === 'string' || (signature.keyType === 'number' && String(Number(key)) === key))
437
+ issues.push(...visit(signature.valueNodeId, entry, childPath(at, key), next));
438
+ return issues;
439
+ }
440
+ if (!['string', 'number', 'boolean', 'null'].includes(node.kind))
441
+ return issue('Source kind is not proven JSON data');
442
+ return [];
443
+ };
444
+ if (!nodes.has(nodeId))
445
+ return [{ path, message: 'Source value owner is not in the complete graph' }];
446
+ return visit(nodeId, value, path, new Map());
447
+ }
448
+ /** Source domains remain independently proven; caller defaults and observations never close them. */
449
+ export function validateSourceDomain(graph, definition, nullHandling = []) {
450
+ const invalid = validateSourceGraph(graph);
451
+ if (nullHandling.length)
452
+ invalid.push(...validateNullHandlingSource(nullHandling, graph));
453
+ if (invalid.length)
454
+ return invalid;
455
+ if (containsTargetDefinitionType(definition, 'DiscriminatedUnion'))
456
+ return validateDiscriminatedUnionSourceDefinition(definition, graph);
457
+ const issues = [];
458
+ const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
459
+ const walk = (id, target, path, seen, domainOwner = true, required) => {
460
+ if (seen.has(id))
461
+ return;
462
+ const node = nodes.get(id);
463
+ if (!node)
464
+ return;
465
+ const next = new Set(seen);
466
+ next.add(id);
467
+ const expectedRequired = required ?? node.required;
468
+ const nullJudgment = nullHandling.find((judgment) => judgment.sourceNodeId === id);
469
+ const omitNull = node.kind === 'union' && nullJudgment?.handling === 'omit-equivalent' && !expectedRequired && !target.required;
470
+ const sourceValues = omitNull
471
+ ? node.domain.declaredValues.filter((value) => value !== null)
472
+ : node.domain.declaredValues;
473
+ if (domainOwner && target.values?.length) {
474
+ const complete = graph.coverage === 'complete-within-declared-bound' &&
475
+ graph.omittedCount === 0 &&
476
+ node.coverage === 'complete-within-declared-bound' &&
477
+ node.domain.provenance === 'compiler' &&
478
+ node.domain.openness === 'closed' &&
479
+ sourceValues.length > 0 &&
480
+ !node.domain.unrepresentedValues?.length;
481
+ if (!complete ||
482
+ sourceValues.some((value) => !target.values.some((allowed) => jsonEqual(allowed, value))) ||
483
+ target.values.some((allowed) => !sourceValues.some((value) => jsonEqual(allowed, value))))
484
+ issues.push({ path, message: 'Finite constraints require a complete matching compiler domain' });
485
+ }
486
+ if (domainOwner &&
487
+ ['String', 'Number', 'Boolean'].includes(target.type) &&
488
+ graph.coverage === 'complete-within-declared-bound' &&
489
+ graph.omittedCount === 0 &&
490
+ node.coverage === 'complete-within-declared-bound' &&
491
+ node.domain.provenance === 'compiler' &&
492
+ node.domain.openness === 'closed' &&
493
+ sourceValues.length &&
494
+ !node.domain.unrepresentedValues?.length &&
495
+ !(target.type === 'Boolean' &&
496
+ sourceValues.length === 2 &&
497
+ sourceValues.includes(true) &&
498
+ sourceValues.includes(false)) &&
499
+ (!target.values?.length ||
500
+ sourceValues.some((value) => !target.values.some((allowed) => jsonEqual(allowed, value))) ||
501
+ target.values.some((allowed) => !sourceValues.some((value) => jsonEqual(allowed, value)))))
502
+ issues.push({ path, message: 'Finite source domain is not enforced; source retained' });
503
+ if (target.type === 'Literal' || target.type === 'Integer' || target.type === 'DateTime') {
504
+ const values = finiteSourceValueDomain(graph, id);
505
+ if (!values?.length ||
506
+ values.some((value) => validateTargetValue(target, value).length) ||
507
+ (target.type === 'Literal' && (values.length !== 1 || !jsonEqual(values[0], target.value))))
508
+ issues.push({ path, message: `${target.type} requires a proven compatible source domain` });
509
+ if (target.required !== undefined && expectedRequired !== target.required)
510
+ issues.push({ path, message: 'Representation does not preserve source requiredness' });
511
+ if (values?.length &&
512
+ target.type !== 'Literal' &&
513
+ (!target.values?.length ||
514
+ values.some((value) => !target.values.some((allowed) => jsonEqual(allowed, value))) ||
515
+ target.values.some((allowed) => !values.some((value) => jsonEqual(allowed, value)))))
516
+ issues.push({ path, message: 'Finite source domain is not enforced; source retained' });
517
+ return;
518
+ }
519
+ if (node.kind === 'reference' || node.kind === 'union' || node.kind === 'intersection') {
520
+ const memberTarget = { ...target };
521
+ if (node.kind === 'union')
522
+ delete memberTarget.defaultValue;
523
+ for (const alternative of node.alternatives ?? []) {
524
+ const member = nodes.get(alternative);
525
+ if (member && !['undefined', 'never'].includes(member.kind) && !(omitNull && member.kind === 'null'))
526
+ walk(alternative, memberTarget, path, next, false, expectedRequired);
527
+ }
528
+ }
529
+ if (target.required !== undefined && expectedRequired !== target.required)
530
+ issues.push({ path, message: 'Representation does not preserve source requiredness' });
531
+ if ((node.kind === 'array' && target.type !== 'Array') || (node.kind === 'record' && target.type !== 'Record'))
532
+ issues.push({ path, message: 'Representation does not preserve source structure' });
533
+ if (['tuple', 'function', 'bigint', 'symbol', 'unknown'].includes(node.kind) ||
534
+ node.indexSignatures?.length ||
535
+ node.kind === 'reference')
536
+ issues.push({ path, message: 'Native source structure unavailable; source retained' });
537
+ if (['string', 'number', 'boolean', 'null'].includes(node.kind) &&
538
+ { string: 'String', number: 'Number', boolean: 'Boolean', null: 'JSON' }[node.kind] !== target.type)
539
+ issues.push({ path, message: 'Representation does not preserve source kind' });
540
+ if (node.domain.openness === 'open' && target.values?.length)
541
+ issues.push({ path, message: 'Representation narrows open source domain' });
542
+ if (node.domain.unrepresentedValues?.length)
543
+ issues.push({ path: `${path}/sourceDomain`, message: 'Source domain contains unrepresentable values' });
544
+ if (node.domain.provenance === 'compiler' && node.domain.openness === 'closed' && sourceValues.length) {
545
+ sourceValues.forEach((value, i) => issues.push(...validateTargetValue(target, value, `${path}/sourceDomain/${i}`)));
546
+ if (own(target, 'defaultValue') && !sourceValues.some((v) => jsonEqual(v, target.defaultValue)))
547
+ issues.push({ path: `${path}/defaultValue`, message: 'Default outside proven source domain' });
548
+ }
549
+ if (target.type === 'Record')
550
+ for (const field of node.fields ?? []) {
551
+ if (!own(target.fields, field.key)) {
552
+ issues.push({
553
+ path: childPath(childPath(path, 'fields'), field.key),
554
+ message: 'Source field missing from representation',
555
+ });
556
+ continue;
557
+ }
558
+ walk(field.nodeId, target.fields[field.key], childPath(childPath(path, 'fields'), field.key), next, true, field.required);
559
+ }
560
+ if (target.type === 'Array' && node.items?.length === 1)
561
+ walk(node.items[0], target.items, `${path}/items`, next);
562
+ };
563
+ walk(graph.rootId, definition, '', new Set());
564
+ if (own(definition, 'defaultValue'))
565
+ issues.push(...validateSourceValue(graph, definition.defaultValue));
566
+ const defaultDomain = (id, value, path, seen) => {
567
+ if (seen.has(id))
568
+ return;
569
+ const node = nodes.get(id);
570
+ if (!node)
571
+ return;
572
+ const next = new Set(seen);
573
+ next.add(id);
574
+ if (node.domain.provenance === 'compiler' &&
575
+ node.domain.openness === 'closed' &&
576
+ node.domain.declaredValues.length &&
577
+ !node.domain.declaredValues.some((allowed) => jsonEqual(allowed, value)))
578
+ issues.push({ path, message: 'Default outside proven source domain' });
579
+ if (node.kind === 'array' && Array.isArray(value) && node.items?.length === 1)
580
+ value.forEach((item, i) => defaultDomain(node.items[0], item, `${path}/${i}`, next));
581
+ if (value && typeof value === 'object' && !Array.isArray(value))
582
+ for (const field of node.fields ?? [])
583
+ if (own(value, field.key))
584
+ defaultDomain(field.nodeId, value[field.key], childPath(path, field.key), next);
585
+ };
586
+ if (own(definition, 'defaultValue'))
587
+ defaultDomain(graph.rootId, definition.defaultValue, '/defaultValue', new Set());
588
+ return issues;
589
+ }
590
+ export function projectProperty(model, profile, context) {
591
+ const snapshot = freezeJson(cloneJson(model));
592
+ const profileSnapshot = createPropertyProfile(profile);
593
+ const issues = validateSourceGraph(model.source.graph);
594
+ if (model.nullHandling !== undefined)
595
+ issues.push(...validateNullHandlingSource(model.nullHandling, model.source.graph));
596
+ if (issues.length)
597
+ return { model: snapshot, profile: profileSnapshot, outcome: 'unsupported', issues, requirements: [] };
598
+ const requirements = [];
599
+ let conditional = false;
600
+ let unsupported = issues.length > 0;
601
+ const require = (path, capability) => {
602
+ const key = `${path}:${capability}`;
603
+ const availability = own(context.capabilities, key) ? context.capabilities[key] : 'unknown';
604
+ if (!['enabled', 'unavailable', 'unknown'].includes(availability)) {
605
+ unsupported = true;
606
+ issues.push({ path, message: 'Invalid caller capability' });
607
+ return;
608
+ }
609
+ requirements.push({ path, capability, availability });
610
+ if (availability === 'unavailable')
611
+ unsupported = true;
612
+ if (availability === 'unknown')
613
+ conditional = true;
614
+ };
615
+ for (const requirement of profileSnapshot.requirements)
616
+ require(requirement.path, requirement.capability);
617
+ const representation = model.representation;
618
+ if (!representation)
619
+ return {
620
+ model: snapshot,
621
+ profile: profileSnapshot,
622
+ outcome: 'unsupported',
623
+ issues: [...issues, { path: '/representation', message: 'No representation decision' }],
624
+ requirements,
625
+ };
626
+ const target = cdfToTarget(cloneJson(representation));
627
+ const omitRootNull = !target.required &&
628
+ model.source.graph.nodes.find((node) => node.id === model.source.graph.rootId)?.required === false &&
629
+ model.nullHandling?.some((judgment) => judgment.sourceNodeId === model.source.graph.rootId && judgment.handling === 'omit-equivalent');
630
+ if (isSourceBoundRepresentation(target.type)) {
631
+ const proposal = model.representationProposal;
632
+ const validation = validateRepresentationProposal(proposal, model, () => ({
633
+ status: 'unknown',
634
+ requirements: [{ path: '', capability: 'deployed-mapper', availability: 'unknown' }],
635
+ }));
636
+ const compared = cloneJson(target);
637
+ if (proposal?.desiredDefinition.required === undefined)
638
+ delete compared.required;
639
+ if (!validation.valid || !proposal || !jsonEqual(proposal.desiredDefinition, compared)) {
640
+ unsupported = true;
641
+ issues.push(...validation.issues, {
642
+ path: '/representationProposal',
643
+ message: 'Source-bound proposal must match the complete desired definition',
644
+ });
645
+ }
646
+ else if (proposal.compatibility?.status !== 'judged-compatible') {
647
+ conditional = true;
648
+ issues.push({
649
+ path: '/representationProposal/compatibility',
650
+ message: 'Source compatibility remains unresolved',
651
+ });
652
+ }
653
+ const root = model.source.graph.nodes.find((node) => node.id === model.source.graph.rootId);
654
+ if (target.required !== undefined && target.required !== root?.required) {
655
+ unsupported = true;
656
+ issues.push({ path: '/required', message: 'Representation does not preserve source requiredness' });
657
+ }
658
+ }
659
+ const sourceDefault = model.source.default;
660
+ if (sourceDefault?.state === 'unsupported') {
661
+ issues.push({ path: '/source/default', message: 'Source default unresolved; source retained' });
662
+ if (model.defaultIntent.action === 'absent' || model.defaultAuthority === 'generation')
663
+ conditional = true;
664
+ }
665
+ if (model.defaultAuthority === 'generation' &&
666
+ sourceDefault?.state === 'value' &&
667
+ own(sourceDefault, 'value') &&
668
+ (model.defaultIntent.action === 'clear' ||
669
+ (model.defaultIntent.action === 'set' && !jsonEqual(model.defaultIntent.value, sourceDefault.value)))) {
670
+ unsupported = true;
671
+ issues.push({ path: '/defaultIntent', message: 'Generated default differs from original source default' });
672
+ }
673
+ if (model.defaultAuthority === 'review' && model.defaultIntent.action !== 'absent')
674
+ issues.push({
675
+ path: '/source/default',
676
+ message: 'Original source default retained independently of accepted review intent',
677
+ });
678
+ const visit = (d, t, path, position, literalUnderlying = false) => {
679
+ if (!profile.mapperTypes.includes(d.$type) || !profile.targetTypes.includes(t.type)) {
680
+ unsupported = true;
681
+ issues.push({ path, message: 'Mapper type unavailable' });
682
+ }
683
+ require(path, 'mapper');
684
+ if (path && isSourceBoundRepresentation(d.$type) && !literalUnderlying) {
685
+ unsupported = true;
686
+ issues.push({ path, message: 'Nested source-bound representation requires its own compatibility judgment' });
687
+ }
688
+ if (literalUnderlying && ['RichText', 'ResourceLink'].includes(d.$type)) {
689
+ unsupported = true;
690
+ issues.push({ path, message: 'Literal singleton does not prove source-bound underlying semantics' });
691
+ }
692
+ if ((d.$type === 'array' && position !== 'root') || (d.$type === 'record' && position === 'field')) {
693
+ unsupported = true;
694
+ issues.push({ path, message: 'Native position unavailable; source retained' });
695
+ }
696
+ if (d.$type === 'DiscriminatedUnion') {
697
+ if (model.category !== 'content') {
698
+ unsupported = true;
699
+ issues.push({ path, message: 'Discriminated unions require content category' });
700
+ }
701
+ if (d.discriminator?.includes('/')) {
702
+ unsupported = true;
703
+ issues.push({
704
+ path: `${path}/discriminator`,
705
+ message: 'Target cannot address a slash-containing discriminator key',
706
+ });
707
+ }
708
+ const tags = new Set();
709
+ for (const [index, member] of (d.members ?? []).entries()) {
710
+ const tag = discriminatedUnionTag(member, d.discriminator, 'cdf');
711
+ if (!tag)
712
+ continue;
713
+ const key = String(tag.value);
714
+ if (tags.has(key) || own(Object.prototype, key)) {
715
+ unsupported = true;
716
+ issues.push({
717
+ path: `${path}/members/${index}`,
718
+ message: 'Target cannot safely distinguish this typed discriminator tag',
719
+ });
720
+ }
721
+ tags.add(key);
722
+ visit(member, t.members[index], `${path}/members/${index}`, 'member', literalUnderlying);
723
+ }
724
+ }
725
+ if (d.$items)
726
+ visit(d.$items, t.items, `${path}/items`, 'item', literalUnderlying);
727
+ if (d.$fields)
728
+ for (const [key, field] of Object.entries(d.$fields))
729
+ visit(field, t.fields[key], childPath(childPath(path, 'fields'), key), 'field', literalUnderlying);
730
+ if (d.valueType)
731
+ visit(d.valueType, t.valueType, `${path}/valueType`, position, true);
732
+ };
733
+ visit(representation, target, '', 'root');
734
+ if (model.defaultIntent.action === 'clear')
735
+ delete target.defaultValue;
736
+ else if (model.defaultIntent.action === 'set')
737
+ target.defaultValue = cloneJson(model.defaultIntent.value);
738
+ else if (!own(target, 'defaultValue') &&
739
+ !(omitRootNull && model.source.default?.value === null) &&
740
+ model.source.default?.state === 'value' &&
741
+ own(model.source.default, 'value'))
742
+ target.defaultValue = cloneJson(model.source.default.value);
743
+ let lossy = false;
744
+ const defaults = (d, t, path) => {
745
+ if (own(t, 'defaultValue')) {
746
+ if (!profile.defaultSourceTypes.includes(d.$type) || !profile.defaultTargetTypes.includes(t.type)) {
747
+ delete t.defaultValue;
748
+ lossy = true;
749
+ issues.push({
750
+ path: `${path}/defaultValue`,
751
+ message: 'Source mapper and mapped target must both support default',
752
+ });
753
+ }
754
+ else
755
+ require(path, 'default');
756
+ }
757
+ if (d.$items)
758
+ defaults(d.$items, t.items, `${path}/items`);
759
+ if (d.valueType)
760
+ defaults(d.valueType, t.valueType, `${path}/valueType`);
761
+ if (d.members)
762
+ d.members.forEach((member, index) => defaults(member, t.members[index], `${path}/members/${index}`));
763
+ if (d.$fields)
764
+ for (const [key, field] of Object.entries(d.$fields))
765
+ defaults(field, t.fields[key], childPath(childPath(path, 'fields'), key));
766
+ };
767
+ defaults(representation, target, '');
768
+ const validation = validateTargetDefinition(target);
769
+ issues.push(...validation.issues);
770
+ if (validation.valid) {
771
+ const domainIssues = isSourceBoundRepresentation(target.type)
772
+ ? []
773
+ : validateSourceDomain(model.source.graph, target, model.nullHandling);
774
+ issues.push(...domainIssues);
775
+ if (domainIssues.length)
776
+ unsupported = true;
777
+ }
778
+ if (!validation.valid ||
779
+ issues.some((issue) => issue.message === 'Default outside proven source domain' ||
780
+ issue.message === 'Value outside declared domain' ||
781
+ issue.message === 'Source field missing from representation'))
782
+ unsupported = true;
783
+ if (model.source.graph.coverage !== 'complete-within-declared-bound')
784
+ conditional = true;
785
+ return {
786
+ model: snapshot,
787
+ profile: profileSnapshot,
788
+ outcome: unsupported ? 'unsupported' : conditional ? 'conditional' : lossy ? 'lossy' : 'supported',
789
+ ...(unsupported ? {} : { target }),
790
+ issues,
791
+ requirements,
792
+ };
793
+ }
794
+ /** Generic drafts preserve complete accounting; deployment and approval are caller responsibilities. */
795
+ export function deriveRepresentationAlternatives(model) {
796
+ const graph = model.source.graph;
797
+ const accounting = graph.nodes.map((node) => ({
798
+ nodeId: node.id,
799
+ keyPath: [...node.keyPath],
800
+ disposition: 'retained',
801
+ }));
802
+ const alternatives = [
803
+ {
804
+ sourceRevision: model.identity.sourceRevision,
805
+ sourceNodeIds: graph.nodes.map((n) => n.id),
806
+ kind: 'json-document',
807
+ definition: { type: 'JSON' },
808
+ accounting,
809
+ dependencies: [],
810
+ mapper: 'unknown',
811
+ cardinality: 'unknown',
812
+ approved: false,
813
+ },
814
+ ];
815
+ for (const node of graph.nodes)
816
+ if (node.kind === 'record' && node.fields?.length) {
817
+ const fields = Object.create(null);
818
+ for (const field of node.fields)
819
+ fields[field.key] = { type: 'JSON', required: field.required };
820
+ alternatives.push({
821
+ sourceRevision: model.identity.sourceRevision,
822
+ sourceNodeIds: [node.id],
823
+ kind: 'record-component',
824
+ definition: { type: 'Record', fields },
825
+ accounting,
826
+ dependencies: node.fields.map((field) => field.nodeId),
827
+ mapper: 'unknown',
828
+ cardinality: 'unknown',
829
+ approved: false,
830
+ });
831
+ }
832
+ return alternatives;
833
+ }