owenloop 0.5.9 → 0.5.11

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 (86) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1200 -166
  28. package/dist/src/defs.d.ts +41 -1
  29. package/dist/src/defs.js +461 -92
  30. package/dist/src/engine.d.ts +108 -22
  31. package/dist/src/engine.js +573 -85
  32. package/dist/src/factory.js +5 -3
  33. package/dist/src/hub.d.ts +77 -0
  34. package/dist/src/hub.js +162 -0
  35. package/dist/src/implements.d.ts +37 -0
  36. package/dist/src/implements.js +790 -0
  37. package/dist/src/index.d.ts +12 -10
  38. package/dist/src/index.js +7 -6
  39. package/dist/src/mcp/serve.js +254 -45
  40. package/dist/src/mcp/server.d.ts +10 -7
  41. package/dist/src/mcp/server.js +53 -8
  42. package/dist/src/model.d.ts +46 -10
  43. package/dist/src/model.js +224 -78
  44. package/dist/src/order-resolver.js +1 -0
  45. package/dist/src/store/def-source.d.ts +19 -0
  46. package/dist/src/store/def-source.js +87 -17
  47. package/dist/src/store/gc-recovery.d.ts +46 -0
  48. package/dist/src/store/gc-recovery.js +258 -0
  49. package/dist/src/store/gc.d.ts +94 -0
  50. package/dist/src/store/gc.js +563 -0
  51. package/dist/src/store/index.d.ts +3 -1
  52. package/dist/src/store/index.js +2 -0
  53. package/dist/src/store/install.d.ts +34 -5
  54. package/dist/src/store/install.js +73 -11
  55. package/dist/src/store/pre-commit-verifier.js +42 -2
  56. package/dist/src/store/snapshot-guard.d.ts +18 -0
  57. package/dist/src/store/snapshot-guard.js +94 -0
  58. package/dist/src/store.d.ts +66 -4
  59. package/dist/src/store.js +333 -12
  60. package/dist/src/types.d.ts +97 -17
  61. package/dist/src/types.js +4 -0
  62. package/dist/src/util.js +4 -1
  63. package/docs/authoring.md +214 -9
  64. package/docs/bundles.md +19 -0
  65. package/docs/cli.md +270 -30
  66. package/docs/crypto.md +13 -7
  67. package/docs/design.md +107 -46
  68. package/docs/evals/mcp-charter-baseline.json +428 -0
  69. package/docs/mcp-charter-eval.md +124 -0
  70. package/docs/shift-logs.md +18 -0
  71. package/docs/wire-contracts.md +28 -7
  72. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  73. package/examples/workflows/ship.yaml +28 -2
  74. package/package.json +2 -1
  75. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  76. package/plugins/claude-code/plugin/.mcp.json +1 -1
  77. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  78. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  79. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  80. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  81. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  82. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  83. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  84. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  85. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  86. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -0,0 +1,790 @@
1
+ const JSON_SCHEMA_TYPES = new Set(['null', 'boolean', 'object', 'array', 'number', 'string', 'integer']);
2
+ const ANNOTATION_KEYWORDS = new Set([
3
+ 'title',
4
+ 'description',
5
+ 'default',
6
+ 'examples',
7
+ '$comment',
8
+ '$id',
9
+ '$schema',
10
+ '$anchor',
11
+ '$dynamicAnchor',
12
+ ]);
13
+ /**
14
+ * This is a syntax/value allowlist, not a guarantee that every accepted
15
+ * composition can be structurally proved safe by schemaSubset.
16
+ */
17
+ const SUPPORTED_KEYWORDS = new Set([
18
+ 'type',
19
+ 'const',
20
+ 'enum',
21
+ 'minimum',
22
+ 'maximum',
23
+ 'exclusiveMinimum',
24
+ 'exclusiveMaximum',
25
+ 'minLength',
26
+ 'maxLength',
27
+ 'pattern',
28
+ 'format',
29
+ 'minItems',
30
+ 'maxItems',
31
+ 'uniqueItems',
32
+ 'items',
33
+ 'minProperties',
34
+ 'maxProperties',
35
+ 'properties',
36
+ 'required',
37
+ 'additionalProperties',
38
+ 'oneOf',
39
+ 'anyOf',
40
+ ]);
41
+ function isMap(value) {
42
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
43
+ }
44
+ function isJsonSchema(value) {
45
+ return typeof value === 'boolean' || isMap(value);
46
+ }
47
+ function joinPath(path, segment) {
48
+ return path === '' ? segment : path + '.' + segment;
49
+ }
50
+ function indexedPath(path, index) {
51
+ return path + '[' + index + ']';
52
+ }
53
+ function message(path, text) {
54
+ return { path, message: path + ': ' + text };
55
+ }
56
+ function schemaObject(value) {
57
+ return typeof value === 'boolean' ? undefined : value;
58
+ }
59
+ function schemaAt(value, fallbackPath, issues) {
60
+ if (!isJsonSchema(value)) {
61
+ issues.push(message(fallbackPath, 'expected a JSON Schema object or boolean'));
62
+ return undefined;
63
+ }
64
+ return value;
65
+ }
66
+ function propertyMap(value, path, issues) {
67
+ if (value === undefined)
68
+ return {};
69
+ if (!isMap(value)) {
70
+ issues.push(message(path, 'expected a map'));
71
+ return {};
72
+ }
73
+ return value;
74
+ }
75
+ function stringSet(value, path, issues) {
76
+ if (value === undefined)
77
+ return new Set();
78
+ if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
79
+ issues.push(message(path, 'expected an array of strings'));
80
+ return new Set();
81
+ }
82
+ return new Set(value);
83
+ }
84
+ function typeSet(value, path, issues) {
85
+ if (value === undefined)
86
+ return undefined;
87
+ if (typeof value === 'string' && JSON_SCHEMA_TYPES.has(value))
88
+ return new Set([value]);
89
+ if (Array.isArray(value)
90
+ && value.length > 0
91
+ && value.every((entry) => typeof entry === 'string' && JSON_SCHEMA_TYPES.has(entry))
92
+ && new Set(value).size === value.length)
93
+ return new Set(value);
94
+ issues.push(message(path, 'expected a string or an array of strings'));
95
+ return undefined;
96
+ }
97
+ function typeIsSubset(source, target) {
98
+ return source === target || (source === 'integer' && target === 'number');
99
+ }
100
+ function stableJson(value) {
101
+ if (Array.isArray(value))
102
+ return '[' + value.map(stableJson).join(',') + ']';
103
+ if (isMap(value)) {
104
+ return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + stableJson(value[key])).join(',') + '}';
105
+ }
106
+ return JSON.stringify(value);
107
+ }
108
+ function enumValues(value, path, issues) {
109
+ if (value === undefined)
110
+ return undefined;
111
+ if (!Array.isArray(value) || value.length === 0) {
112
+ issues.push(message(path, 'expected a non-empty array'));
113
+ return undefined;
114
+ }
115
+ return value;
116
+ }
117
+ function isJsonValue(value) {
118
+ if (value === null || typeof value === 'string' || typeof value === 'boolean')
119
+ return true;
120
+ if (typeof value === 'number')
121
+ return Number.isFinite(value);
122
+ if (Array.isArray(value))
123
+ return value.every(isJsonValue);
124
+ return isMap(value) && Object.values(value).every(isJsonValue);
125
+ }
126
+ function effectiveValues(schema, path, issues) {
127
+ const hasConst = Object.hasOwn(schema, 'const');
128
+ const enumValue = enumValues(schema.enum, joinPath(path, 'enum'), issues);
129
+ if (!hasConst && enumValue === undefined)
130
+ return undefined;
131
+ if (!hasConst)
132
+ return enumValue;
133
+ const constant = schema.const;
134
+ if (enumValue === undefined)
135
+ return [constant];
136
+ const constantKey = stableJson(constant);
137
+ return enumValue.some((value) => stableJson(value) === constantKey) ? [constant] : [];
138
+ }
139
+ function lowerBound(schema, path, issues) {
140
+ const minimum = schema.minimum;
141
+ const exclusive = schema.exclusiveMinimum;
142
+ if (minimum !== undefined && typeof minimum !== 'number') {
143
+ issues.push(message(joinPath(path, 'minimum'), 'expected a number'));
144
+ }
145
+ if (exclusive !== undefined && typeof exclusive !== 'number') {
146
+ issues.push(message(joinPath(path, 'exclusiveMinimum'), 'expected a number'));
147
+ }
148
+ const bounds = [];
149
+ if (typeof minimum === 'number')
150
+ bounds.push({ value: minimum, exclusive: false });
151
+ if (typeof exclusive === 'number')
152
+ bounds.push({ value: exclusive, exclusive: true });
153
+ return bounds.reduce((strictest, current) => {
154
+ if (strictest === undefined || current.value > strictest.value)
155
+ return current;
156
+ if (current.value === strictest.value && current.exclusive)
157
+ return current;
158
+ return strictest;
159
+ }, undefined);
160
+ }
161
+ function upperBound(schema, path, issues) {
162
+ const maximum = schema.maximum;
163
+ const exclusive = schema.exclusiveMaximum;
164
+ if (maximum !== undefined && typeof maximum !== 'number') {
165
+ issues.push(message(joinPath(path, 'maximum'), 'expected a number'));
166
+ }
167
+ if (exclusive !== undefined && typeof exclusive !== 'number') {
168
+ issues.push(message(joinPath(path, 'exclusiveMaximum'), 'expected a number'));
169
+ }
170
+ const bounds = [];
171
+ if (typeof maximum === 'number')
172
+ bounds.push({ value: maximum, exclusive: false });
173
+ if (typeof exclusive === 'number')
174
+ bounds.push({ value: exclusive, exclusive: true });
175
+ return bounds.reduce((strictest, current) => {
176
+ if (strictest === undefined || current.value < strictest.value)
177
+ return current;
178
+ if (current.value === strictest.value && current.exclusive)
179
+ return current;
180
+ return strictest;
181
+ }, undefined);
182
+ }
183
+ function sourceMeetsLower(source, target) {
184
+ if (target === undefined)
185
+ return true;
186
+ if (source === undefined)
187
+ return false;
188
+ return source.value > target.value || (source.value === target.value && (source.exclusive || !target.exclusive));
189
+ }
190
+ function sourceMeetsUpper(source, target) {
191
+ if (target === undefined)
192
+ return true;
193
+ if (source === undefined)
194
+ return false;
195
+ return source.value < target.value || (source.value === target.value && (source.exclusive || !target.exclusive));
196
+ }
197
+ function numberValue(value, path, issues) {
198
+ if (value === undefined)
199
+ return undefined;
200
+ if (typeof value === 'number')
201
+ return value;
202
+ issues.push(message(path, 'expected a number'));
203
+ return undefined;
204
+ }
205
+ function sourceAtLeast(source, target, keyword, path, issues) {
206
+ const targetValue = numberValue(target[keyword], joinPath(path, keyword), issues);
207
+ if (targetValue === undefined)
208
+ return;
209
+ const sourceValue = numberValue(source[keyword], joinPath(path, keyword), issues);
210
+ if (sourceValue === undefined || sourceValue < targetValue) {
211
+ issues.push(message(joinPath(path, keyword), `source minimum ${sourceValue ?? 'unbounded'} does not satisfy target minimum ${targetValue}`));
212
+ }
213
+ }
214
+ function sourceAtMost(source, target, keyword, path, issues) {
215
+ const targetValue = numberValue(target[keyword], joinPath(path, keyword), issues);
216
+ if (targetValue === undefined)
217
+ return;
218
+ const sourceValue = numberValue(source[keyword], joinPath(path, keyword), issues);
219
+ if (sourceValue === undefined || sourceValue > targetValue) {
220
+ issues.push(message(joinPath(path, keyword), `source maximum ${sourceValue ?? 'unbounded'} does not satisfy target maximum ${targetValue}`));
221
+ }
222
+ }
223
+ function validNumber(value) {
224
+ return typeof value === 'number' && Number.isFinite(value);
225
+ }
226
+ function validNonNegativeInteger(value) {
227
+ return validNumber(value) && Number.isInteger(value) && value >= 0;
228
+ }
229
+ /**
230
+ * Validate every supported keyword before subset comparison. buildDef accepts
231
+ * a gross JSON Schema shape, so this checker must fail closed on malformed
232
+ * supported values even when the opposite schema does not constrain them.
233
+ */
234
+ function validateSchema(schema, path, issues) {
235
+ const object = schemaObject(schema);
236
+ if (object === undefined)
237
+ return true;
238
+ let valid = true;
239
+ for (const key of Object.keys(object)) {
240
+ if (!SUPPORTED_KEYWORDS.has(key) && !ANNOTATION_KEYWORDS.has(key)) {
241
+ issues.push(message(joinPath(path, key), 'unsupported JSON Schema keyword'));
242
+ valid = false;
243
+ continue;
244
+ }
245
+ if (ANNOTATION_KEYWORDS.has(key))
246
+ continue;
247
+ const value = object[key];
248
+ const fieldPath = joinPath(path, key);
249
+ switch (key) {
250
+ case 'type':
251
+ if (typeSet(value, fieldPath, issues) === undefined)
252
+ valid = false;
253
+ break;
254
+ case 'const':
255
+ if (!isJsonValue(value)) {
256
+ issues.push(message(fieldPath, 'expected a JSON value'));
257
+ valid = false;
258
+ }
259
+ break;
260
+ case 'enum': {
261
+ const entries = enumValues(value, fieldPath, issues);
262
+ if (entries === undefined || entries.some((entry) => !isJsonValue(entry))) {
263
+ if (entries !== undefined && entries.some((entry) => !isJsonValue(entry))) {
264
+ issues.push(message(fieldPath, 'expected JSON values'));
265
+ }
266
+ valid = false;
267
+ }
268
+ else if (new Set(entries.map(stableJson)).size !== entries.length) {
269
+ issues.push(message(fieldPath, 'expected unique values'));
270
+ valid = false;
271
+ }
272
+ break;
273
+ }
274
+ case 'minimum':
275
+ case 'maximum':
276
+ case 'exclusiveMinimum':
277
+ case 'exclusiveMaximum':
278
+ if (!validNumber(value)) {
279
+ issues.push(message(fieldPath, 'expected a finite number'));
280
+ valid = false;
281
+ }
282
+ break;
283
+ case 'minLength':
284
+ case 'maxLength':
285
+ case 'minItems':
286
+ case 'maxItems':
287
+ case 'minProperties':
288
+ case 'maxProperties':
289
+ if (!validNonNegativeInteger(value)) {
290
+ issues.push(message(fieldPath, 'expected a non-negative integer'));
291
+ valid = false;
292
+ }
293
+ break;
294
+ case 'uniqueItems':
295
+ if (typeof value !== 'boolean') {
296
+ issues.push(message(fieldPath, 'expected a boolean'));
297
+ valid = false;
298
+ }
299
+ break;
300
+ case 'pattern':
301
+ if (typeof value !== 'string') {
302
+ issues.push(message(fieldPath, 'expected a string'));
303
+ valid = false;
304
+ }
305
+ else {
306
+ try {
307
+ new RegExp(value, 'u');
308
+ }
309
+ catch {
310
+ issues.push(message(fieldPath, 'expected a valid ECMA-262 Unicode regular expression'));
311
+ valid = false;
312
+ }
313
+ }
314
+ break;
315
+ case 'format':
316
+ if (typeof value !== 'string') {
317
+ issues.push(message(fieldPath, 'expected a string'));
318
+ valid = false;
319
+ }
320
+ break;
321
+ case 'oneOf':
322
+ case 'anyOf':
323
+ if (!Array.isArray(value) || value.length === 0) {
324
+ issues.push(message(fieldPath, 'expected a non-empty array'));
325
+ valid = false;
326
+ break;
327
+ }
328
+ for (const [index, entry] of value.entries()) {
329
+ const branchPath = indexedPath(fieldPath, index);
330
+ const branch = schemaAt(entry, branchPath, issues);
331
+ if (branch === undefined || !validateSchema(branch, branchPath, issues))
332
+ valid = false;
333
+ }
334
+ break;
335
+ case 'items': {
336
+ const child = schemaAt(value, fieldPath, issues);
337
+ if (child === undefined)
338
+ valid = false;
339
+ else if (!validateSchema(child, fieldPath, issues))
340
+ valid = false;
341
+ break;
342
+ }
343
+ case 'properties':
344
+ if (!isMap(value)) {
345
+ issues.push(message(fieldPath, 'expected a map'));
346
+ valid = false;
347
+ break;
348
+ }
349
+ for (const property of Object.keys(value)) {
350
+ const propertyPath = joinPath(fieldPath, property);
351
+ const child = schemaAt(value[property], propertyPath, issues);
352
+ if (child === undefined || !validateSchema(child, propertyPath, issues))
353
+ valid = false;
354
+ }
355
+ break;
356
+ case 'required':
357
+ if (!Array.isArray(value)
358
+ || value.some((entry) => typeof entry !== 'string')
359
+ || new Set(value).size !== value.length) {
360
+ issues.push(message(fieldPath, 'expected an array of unique strings'));
361
+ valid = false;
362
+ }
363
+ break;
364
+ case 'additionalProperties': {
365
+ const child = schemaAt(value, fieldPath, issues);
366
+ if (child === undefined)
367
+ valid = false;
368
+ else if (!validateSchema(child, fieldPath, issues))
369
+ valid = false;
370
+ break;
371
+ }
372
+ }
373
+ }
374
+ return valid;
375
+ }
376
+ function additionalSchema(schema, path, issues) {
377
+ const value = schema.additionalProperties;
378
+ if (value === undefined)
379
+ return true;
380
+ const parsed = schemaAt(value, joinPath(path, 'additionalProperties'), issues);
381
+ return parsed ?? true;
382
+ }
383
+ function isClosed(schema) {
384
+ return schema.additionalProperties === false;
385
+ }
386
+ const UNION_KEYWORDS = ['oneOf', 'anyOf'];
387
+ function unionBranches(schema, keyword) {
388
+ const value = schema[keyword];
389
+ if (!Array.isArray(value) || value.length === 0 || value.some((branch) => !isJsonSchema(branch)))
390
+ return undefined;
391
+ return value;
392
+ }
393
+ function unionBranchSets(schema) {
394
+ const sets = [];
395
+ for (const keyword of UNION_KEYWORDS) {
396
+ const branches = unionBranches(schema, keyword);
397
+ if (branches !== undefined)
398
+ sets.push({ keyword, branches });
399
+ }
400
+ return sets;
401
+ }
402
+ function withoutTopLevelUnions(schema) {
403
+ const { oneOf: _oneOf, anyOf: _anyOf, ...root } = schema;
404
+ return root;
405
+ }
406
+ function requiredNames(schema) {
407
+ const required = schema.required;
408
+ return Array.isArray(required) && required.every((name) => typeof name === 'string')
409
+ ? new Set(required)
410
+ : new Set();
411
+ }
412
+ function discriminatorValues(schema) {
413
+ const object = schemaObject(schema);
414
+ if (object === undefined)
415
+ return undefined;
416
+ return effectiveValues(object, 'discriminator', []);
417
+ }
418
+ function isExplicitObjectOnly(schema) {
419
+ const object = schemaObject(schema);
420
+ if (object === undefined)
421
+ return false;
422
+ const types = typeSet(object.type, 'target oneOf branch.type', []);
423
+ return types?.size === 1 && types.has('object');
424
+ }
425
+ function branchesAreDisjoint(source, target) {
426
+ const sourceObject = schemaObject(source);
427
+ const targetObject = schemaObject(target);
428
+ if (sourceObject === undefined || targetObject === undefined)
429
+ return false;
430
+ const sourceProperties = sourceObject.properties;
431
+ const targetProperties = targetObject.properties;
432
+ if (!isMap(sourceProperties) || !isMap(targetProperties))
433
+ return false;
434
+ const sourceRequired = requiredNames(sourceObject);
435
+ const targetRequired = requiredNames(targetObject);
436
+ for (const property of Object.keys(sourceProperties)) {
437
+ if (!sourceRequired.has(property) || !targetRequired.has(property) || !Object.hasOwn(targetProperties, property))
438
+ continue;
439
+ const sourceValues = discriminatorValues(sourceProperties[property]);
440
+ const targetValues = discriminatorValues(targetProperties[property]);
441
+ if (sourceValues === undefined || targetValues === undefined)
442
+ continue;
443
+ const targetValueKeys = new Set(targetValues.map(stableJson));
444
+ if (sourceValues.every((value) => !targetValueKeys.has(stableJson(value))))
445
+ return true;
446
+ }
447
+ return false;
448
+ }
449
+ function targetOneOfIsDisjoint(branches) {
450
+ if (branches.some((branch) => !isExplicitObjectOnly(branch)))
451
+ return false;
452
+ for (let left = 0; left < branches.length; left += 1) {
453
+ for (let right = left + 1; right < branches.length; right += 1) {
454
+ const leftBranch = branches[left];
455
+ const rightBranch = branches[right];
456
+ if (leftBranch === undefined || rightBranch === undefined || !branchesAreDisjoint(leftBranch, rightBranch))
457
+ return false;
458
+ }
459
+ }
460
+ return true;
461
+ }
462
+ function isSubsetOfOneBranch(source, targets, path, direction) {
463
+ return targets.some((target) => {
464
+ const probeIssues = [];
465
+ schemaSubset(source, target, path, direction, probeIssues);
466
+ return probeIssues.length === 0;
467
+ });
468
+ }
469
+ function compareUnionObligations(source, target, path, direction, issues) {
470
+ const sourceSets = unionBranchSets(source);
471
+ const targetSets = unionBranchSets(target);
472
+ if (sourceSets.length > 0 && isSubsetOfOneBranch(withoutTopLevelUnions(source), [target], path, direction)) {
473
+ return;
474
+ }
475
+ if (targetSets.length === 0) {
476
+ for (const sourceSet of sourceSets) {
477
+ for (const [index, branch] of sourceSet.branches.entries()) {
478
+ const branchPath = indexedPath(joinPath(path, sourceSet.keyword), index);
479
+ if (!isSubsetOfOneBranch(branch, [target], branchPath, direction)) {
480
+ issues.push(message(branchPath, 'source union branch is not a subset of the target schema'));
481
+ }
482
+ }
483
+ }
484
+ return;
485
+ }
486
+ const sourceCandidates = sourceSets.length === 0
487
+ ? [{ branches: [source], path }]
488
+ : sourceSets.map((set) => ({
489
+ branches: set.branches,
490
+ path: joinPath(path, set.keyword),
491
+ }));
492
+ for (const targetSet of targetSets) {
493
+ const targetPath = joinPath(path, targetSet.keyword);
494
+ if (targetSet.keyword === 'oneOf' && !targetOneOfIsDisjoint(targetSet.branches)) {
495
+ issues.push(message(targetPath, 'target oneOf branches are not proven pairwise disjoint by explicit object-only schemas with required const/enum discriminators'));
496
+ continue;
497
+ }
498
+ for (const sourceSet of sourceCandidates) {
499
+ for (const [index, branch] of sourceSet.branches.entries()) {
500
+ const branchPath = sourceSet.path === path ? targetPath : indexedPath(sourceSet.path, index);
501
+ if (!isSubsetOfOneBranch(branch, targetSet.branches, branchPath, direction)) {
502
+ const sourceDescription = sourceSet.path === path ? 'source schema' : 'source union branch';
503
+ issues.push(message(branchPath, `${sourceDescription} is not a subset of any target ${targetSet.keyword} branch`));
504
+ }
505
+ }
506
+ }
507
+ }
508
+ }
509
+ /**
510
+ * Checks whether every value admitted by source is admitted by target. Inputs
511
+ * call it as interface → implementation (contravariance); public outputs call
512
+ * it as implementation → interface (covariance).
513
+ */
514
+ function schemaSubset(source, target, path, direction, issues) {
515
+ if (source === false || target === true)
516
+ return;
517
+ if (source === true) {
518
+ issues.push(message(path, 'source schema accepts values the target schema does not prove it accepts'));
519
+ return;
520
+ }
521
+ if (target === false) {
522
+ issues.push(message(path, 'target schema rejects every value accepted by the source schema'));
523
+ return;
524
+ }
525
+ const sourceTypes = typeSet(source.type, joinPath(path, 'source.type'), issues);
526
+ const targetTypes = typeSet(target.type, joinPath(path, 'target.type'), issues);
527
+ if (targetTypes !== undefined) {
528
+ if (sourceTypes === undefined || [...sourceTypes].some((type) => ![...targetTypes].some((allowed) => typeIsSubset(type, allowed)))) {
529
+ issues.push(message(joinPath(path, 'type'), 'source types are not a subset of target types'));
530
+ }
531
+ }
532
+ const sourceValues = effectiveValues(source, joinPath(path, 'source'), issues);
533
+ const targetValues = effectiveValues(target, path, issues);
534
+ if (targetValues !== undefined) {
535
+ const targetSet = new Set(targetValues.map(stableJson));
536
+ if (sourceValues === undefined || sourceValues.some((value) => !targetSet.has(stableJson(value)))) {
537
+ issues.push(message(joinPath(path, 'enum'), 'source allowed values are not a subset of target allowed values'));
538
+ }
539
+ }
540
+ if (!sourceMeetsLower(lowerBound(source, path, issues), lowerBound(target, path, issues))) {
541
+ issues.push(message(path, 'source numeric lower bound does not satisfy target lower bound'));
542
+ }
543
+ if (!sourceMeetsUpper(upperBound(source, path, issues), upperBound(target, path, issues))) {
544
+ issues.push(message(path, 'source numeric upper bound does not satisfy target upper bound'));
545
+ }
546
+ sourceAtLeast(source, target, 'minLength', path, issues);
547
+ sourceAtMost(source, target, 'maxLength', path, issues);
548
+ sourceAtLeast(source, target, 'minItems', path, issues);
549
+ sourceAtMost(source, target, 'maxItems', path, issues);
550
+ if (target.uniqueItems === true && source.uniqueItems !== true) {
551
+ issues.push(message(joinPath(path, 'uniqueItems'), 'source schema permits duplicate array items that the target forbids'));
552
+ }
553
+ const outputProjection = direction === 'output' && isClosed(target) && isClosed(source);
554
+ if (!outputProjection) {
555
+ sourceAtLeast(source, target, 'minProperties', path, issues);
556
+ sourceAtMost(source, target, 'maxProperties', path, issues);
557
+ }
558
+ for (const keyword of ['pattern', 'format']) {
559
+ if (target[keyword] === undefined)
560
+ continue;
561
+ if (typeof target[keyword] !== 'string') {
562
+ issues.push(message(joinPath(path, keyword), 'expected a string'));
563
+ continue;
564
+ }
565
+ if (source[keyword] !== target[keyword]) {
566
+ issues.push(message(joinPath(path, keyword), 'target constraint is not proven by the source schema'));
567
+ }
568
+ }
569
+ if (target.items !== undefined) {
570
+ const sourceItems = schemaAt(source.items ?? true, joinPath(path, 'source.items'), issues);
571
+ const targetItems = schemaAt(target.items, joinPath(path, 'items'), issues);
572
+ if (sourceItems !== undefined && targetItems !== undefined) {
573
+ schemaSubset(sourceItems, targetItems, joinPath(path, 'items'), direction, issues);
574
+ }
575
+ }
576
+ compareUnionObligations(source, target, path, direction, issues);
577
+ compareObjects(source, target, path, direction, issues);
578
+ }
579
+ function compareObjects(source, target, path, direction, issues) {
580
+ const sourceProperties = propertyMap(source.properties, joinPath(path, 'source.properties'), issues);
581
+ const targetProperties = propertyMap(target.properties, joinPath(path, 'properties'), issues);
582
+ const sourceRequired = stringSet(source.required, joinPath(path, 'source.required'), issues);
583
+ const targetRequired = stringSet(target.required, joinPath(path, 'required'), issues);
584
+ const sourceAdditional = additionalSchema(source, path, issues);
585
+ const targetAdditional = additionalSchema(target, path, issues);
586
+ const outputProjection = direction === 'output' && isClosed(target) && isClosed(source);
587
+ if (outputProjection) {
588
+ const visibleProperties = Object.keys(sourceProperties).filter((property) => Object.hasOwn(targetProperties, property));
589
+ const implementationOnlyCount = Object.keys(sourceProperties).length - visibleProperties.length;
590
+ const visibleRequiredCount = visibleProperties.filter((property) => sourceRequired.has(property)).length;
591
+ const sourceMinimum = typeof source.minProperties === 'number' ? source.minProperties : 0;
592
+ const projectedMinimum = Math.max(visibleRequiredCount, sourceMinimum - implementationOnlyCount, 0);
593
+ const targetMinimum = typeof target.minProperties === 'number' ? target.minProperties : undefined;
594
+ if (targetMinimum !== undefined && projectedMinimum < targetMinimum) {
595
+ issues.push(message(joinPath(path, 'minProperties'), `projected source minimum ${projectedMinimum} does not satisfy target minimum ${targetMinimum}`));
596
+ }
597
+ const targetMaximum = typeof target.maxProperties === 'number' ? target.maxProperties : undefined;
598
+ const sourceMaximum = typeof source.maxProperties === 'number' ? source.maxProperties : Number.POSITIVE_INFINITY;
599
+ const projectedMaximum = Math.min(visibleProperties.length, sourceMaximum);
600
+ if (targetMaximum !== undefined && projectedMaximum > targetMaximum) {
601
+ issues.push(message(joinPath(path, 'maxProperties'), `projected source maximum ${projectedMaximum} does not satisfy target maximum ${targetMaximum}`));
602
+ }
603
+ }
604
+ for (const property of targetRequired) {
605
+ if (sourceRequired.has(property))
606
+ continue;
607
+ if (direction === 'input') {
608
+ issues.push(message(joinPath(path, 'required'), `implementation-only required property '${property}'`));
609
+ }
610
+ else {
611
+ issues.push(message(joinPath(path, 'required'), `implementation must require interface property '${property}'`));
612
+ }
613
+ }
614
+ for (const property of Object.keys(targetProperties)) {
615
+ const targetPropertyPath = joinPath(joinPath(path, 'properties'), property);
616
+ const targetProperty = schemaAt(targetProperties[property], targetPropertyPath, issues);
617
+ if (targetProperty === undefined)
618
+ continue;
619
+ const sourceProperty = sourceProperties[property];
620
+ if (sourceProperty !== undefined) {
621
+ const parsedSource = schemaAt(sourceProperty, targetPropertyPath, issues);
622
+ if (parsedSource !== undefined)
623
+ schemaSubset(parsedSource, targetProperty, targetPropertyPath, direction, issues);
624
+ continue;
625
+ }
626
+ if (direction === 'output') {
627
+ issues.push(message(targetPropertyPath, `implementation output is missing interface property '${property}'`));
628
+ continue;
629
+ }
630
+ if (sourceAdditional !== false) {
631
+ schemaSubset(sourceAdditional, targetProperty, targetPropertyPath, direction, issues);
632
+ }
633
+ }
634
+ for (const property of Object.keys(sourceProperties)) {
635
+ if (Object.hasOwn(targetProperties, property))
636
+ continue;
637
+ if (outputProjection)
638
+ continue;
639
+ const sourcePropertyPath = joinPath(joinPath(path, 'properties'), property);
640
+ const sourceProperty = schemaAt(sourceProperties[property], sourcePropertyPath, issues);
641
+ if (sourceProperty !== undefined)
642
+ schemaSubset(sourceProperty, targetAdditional, sourcePropertyPath, direction, issues);
643
+ }
644
+ if (direction === 'output' && isClosed(target) && !isClosed(source)) {
645
+ issues.push(message(joinPath(path, 'additionalProperties'), 'implementation has an unprovable open-property surface for a closed interface output'));
646
+ return;
647
+ }
648
+ if (!outputProjection) {
649
+ schemaSubset(sourceAdditional, targetAdditional, joinPath(path, 'additionalProperties'), direction, issues);
650
+ }
651
+ }
652
+ function artifacts(value, path, issues) {
653
+ if (!Array.isArray(value)) {
654
+ issues.push(message(path, 'expected an array'));
655
+ return [];
656
+ }
657
+ return value;
658
+ }
659
+ function publicOutput(def, name) {
660
+ if (!(def.outputs ?? []).includes(name))
661
+ return undefined;
662
+ for (const step of def.steps) {
663
+ const artifact = [...step.produces, ...(step.generates ?? [])].find((produce) => produce.stem === name);
664
+ if (artifact !== undefined)
665
+ return artifact.schema;
666
+ }
667
+ return undefined;
668
+ }
669
+ /**
670
+ * Validate a workflow against a supplied external interface signature without
671
+ * mutating either value. x.discovery.interface remains the definition's
672
+ * self-description and owns local schemaRef pointers; x.implements only names
673
+ * external contracts and carries no copied schemas or second pointer syntax.
674
+ *
675
+ * This is structural JSON Schema compatibility, not a general theorem prover.
676
+ * It supports booleans; type/const/enum; numeric, string, array, and object
677
+ * bounds; array items and uniqueItems; object properties, required, and
678
+ * additionalProperties; and oneOf/anyOf. Union sibling constraints are
679
+ * compared separately from branch coverage. Target oneOf branches are accepted
680
+ * only when non-boolean, object-only schemas with required const/enum
681
+ * discriminators prove every pair disjoint.
682
+ * The checker remains structural and incomplete: coverage requiring multiple
683
+ * target branches fails closed. allOf, if/then/else, not, $ref, prefixItems,
684
+ * and other validation keywords fail closed with a path-specific issue. For a
685
+ * closed interface output, the projection rule permits extra implementation
686
+ * properties only when that implementation is also closed.
687
+ */
688
+ export function checkInterfaceCompatibility(signature, def) {
689
+ const issues = [];
690
+ const inputs = artifacts(signature.inputs, 'inputs', issues);
691
+ const outputs = artifacts(signature.outputs, 'outputs', issues);
692
+ const interfaceInputNames = new Set();
693
+ for (const [index, artifact] of inputs.entries()) {
694
+ const path = `inputs[${index}]`;
695
+ if (!isMap(artifact) || typeof artifact.name !== 'string' || artifact.name.trim() === '') {
696
+ issues.push(message(joinPath(path, 'name'), 'expected a non-empty string'));
697
+ continue;
698
+ }
699
+ interfaceInputNames.add(artifact.name);
700
+ const interfaceSchema = schemaAt(artifact.schema, joinPath(path, 'schema'), issues);
701
+ const implementation = def.inputs.find((input) => input.name === artifact.name);
702
+ if (implementation === undefined) {
703
+ issues.push(message(joinPath(path, 'name'), `workflow does not declare interface input '${artifact.name}'`));
704
+ continue;
705
+ }
706
+ const implementationSchema = schemaAt(implementation.schema, `inputs.${artifact.name}.schema`, issues);
707
+ if (interfaceSchema === undefined || implementationSchema === undefined)
708
+ continue;
709
+ const validInterfaceSchema = validateSchema(interfaceSchema, joinPath(path, 'schema'), issues);
710
+ const validImplementationSchema = validateSchema(implementationSchema, `inputs.${artifact.name}.schema`, issues);
711
+ if (validInterfaceSchema && validImplementationSchema) {
712
+ schemaSubset(interfaceSchema, implementationSchema, `inputs.${artifact.name}.schema`, 'input', issues);
713
+ }
714
+ }
715
+ for (const input of def.inputs) {
716
+ if (!interfaceInputNames.has(input.name)) {
717
+ issues.push(message(`inputs.${input.name}`, `workflow declares additional input '${input.name}' not in the interface`));
718
+ }
719
+ }
720
+ for (const [index, artifact] of outputs.entries()) {
721
+ const path = `outputs[${index}]`;
722
+ if (!isMap(artifact) || typeof artifact.name !== 'string' || artifact.name.trim() === '') {
723
+ issues.push(message(joinPath(path, 'name'), 'expected a non-empty string'));
724
+ continue;
725
+ }
726
+ const interfaceSchema = schemaAt(artifact.schema, joinPath(path, 'schema'), issues);
727
+ const implementationSchema = publicOutput(def, artifact.name);
728
+ if (implementationSchema === undefined) {
729
+ issues.push(message(joinPath(path, 'name'), `workflow does not declare public output '${artifact.name}' with a schema`));
730
+ continue;
731
+ }
732
+ if (interfaceSchema === undefined)
733
+ continue;
734
+ const validInterfaceSchema = validateSchema(interfaceSchema, joinPath(path, 'schema'), issues);
735
+ const validImplementationSchema = validateSchema(implementationSchema, `outputs.${artifact.name}.schema`, issues);
736
+ if (validInterfaceSchema && validImplementationSchema) {
737
+ schemaSubset(implementationSchema, interfaceSchema, `outputs.${artifact.name}.schema`, 'output', issues);
738
+ }
739
+ }
740
+ return { compatible: issues.length === 0, issues };
741
+ }
742
+ /**
743
+ * Return advisory, field-qualified authoring issues for x.implements. The
744
+ * extension remains optional so old binaries keep loading existing definitions.
745
+ */
746
+ export function implementsIssues(def) {
747
+ const value = def.x?.implements;
748
+ if (value === undefined)
749
+ return [];
750
+ if (!Array.isArray(value) || value.length === 0)
751
+ return ['x.implements: expected a non-empty array'];
752
+ const issues = [];
753
+ const coordinates = new Map();
754
+ for (const [index, claim] of value.entries()) {
755
+ const path = `x.implements[${index}]`;
756
+ if (!isMap(claim)) {
757
+ issues.push(path + ': expected a map');
758
+ continue;
759
+ }
760
+ const present = new Set();
761
+ for (const key of Object.keys(claim)) {
762
+ if (key !== 'name' && key !== 'version') {
763
+ issues.push(path + '.' + key + ': unknown field');
764
+ continue;
765
+ }
766
+ present.add(key);
767
+ }
768
+ const name = claim.name;
769
+ const version = claim.version;
770
+ if (!present.has('name') || typeof name !== 'string' || name.trim() === '') {
771
+ issues.push(path + '.name: expected a non-empty string');
772
+ }
773
+ if (!present.has('version') || typeof version !== 'string' || version.trim() === '') {
774
+ issues.push(path + '.version: expected a non-empty string');
775
+ }
776
+ if (typeof name === 'string' && name.trim() !== '' && typeof version === 'string' && version.trim() !== '') {
777
+ const versions = coordinates.get(name);
778
+ if (versions?.has(version)) {
779
+ issues.push(path + ': duplicate interface claim ' + name + '@' + version);
780
+ }
781
+ else if (versions) {
782
+ versions.add(version);
783
+ }
784
+ else {
785
+ coordinates.set(name, new Set([version]));
786
+ }
787
+ }
788
+ }
789
+ return issues;
790
+ }