@openplanr/protocol 0.13.0 → 0.15.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 (34) hide show
  1. package/README.md +23 -0
  2. package/package.json +6 -2
  3. package/registries/commands.json +12 -12
  4. package/registries/roles.json +43 -133
  5. package/registries/skills.json +14 -14
  6. package/registries/task-kinds.json +2 -2
  7. package/schemas/v1.20.0/design-document.schema.json +379 -0
  8. package/schemas/v1.20.0/design-review-bundle.schema.json +692 -0
  9. package/schemas/v1.21.0/diagram-authoring-bundle.schema.json +1609 -0
  10. package/schemas/v1.21.0/diagram-edit-transaction.schema.json +4369 -0
  11. package/schemas/v1.21.0/diagram-review-bundle.schema.json +4047 -0
  12. package/schemas/v1.21.0/diagram-shape-definition.schema.json +457 -0
  13. package/schemas/v1.22.0/design-document.schema.json +506 -0
  14. package/schemas/v1.22.0/design-review-bundle.schema.json +822 -0
  15. package/schemas/v1.5.0/role-registry.schema.json +4 -1
  16. package/src/browser-contracts.d.mts +5 -1
  17. package/src/browser-contracts.mjs +27 -0
  18. package/src/contracts.mjs +39 -6
  19. package/src/design-contracts.d.mts +40 -2
  20. package/src/design-contracts.mjs +258 -17
  21. package/src/design-publication-contracts.mjs +3 -1
  22. package/src/diagram-authoring-contracts.d.mts +2 -0
  23. package/src/generated/canonical-registries.mjs +71 -161
  24. package/src/index.d.mts +7 -0
  25. package/src/index.mjs +7 -0
  26. package/src/json-schema.mjs +4 -0
  27. package/src/registries.mjs +20 -4
  28. package/src/review-experience-contracts.d.mts +2 -0
  29. package/src/review-experience-contracts.mjs +77 -5
  30. package/src/shape-library-contracts.d.mts +57 -0
  31. package/src/shape-library-contracts.mjs +266 -0
  32. package/src/studio-presentation-contracts.d.mts +50 -2
  33. package/src/studio-presentation-contracts.mjs +285 -4
  34. package/src/workspace-contracts.mjs +3 -3
@@ -6,6 +6,7 @@ import {
6
6
  copyImmutableDiagramData,
7
7
  DIAGRAM_AUTHORING_SCHEMAS,
8
8
  diagramAuthoringBundleDigest,
9
+ diagramPresentationDigest,
9
10
  sealImmutableDiagramData,
10
11
  validateDiagramAuthoringArtifact,
11
12
  } from './diagram-authoring-contracts.mjs';
@@ -15,6 +16,34 @@ import {
15
16
  DIAGRAM_REVIEW_BUNDLE_SCHEMA,
16
17
  } from './diagram-review-contracts.mjs';
17
18
  import { validateJson } from './json-schema.mjs';
19
+ import {
20
+ assertShapeLibrary,
21
+ assertShapeReference,
22
+ SHAPE_LIBRARY_SCHEMA,
23
+ SHAPE_REFERENCE_SCHEMA,
24
+ shapeReferenceKey,
25
+ } from './shape-library-contracts.mjs';
26
+
27
+ export function supportsDiagramShapeLibrary(value) {
28
+ return (
29
+ value !== null &&
30
+ typeof value === 'object' &&
31
+ Object.getOwnPropertyDescriptor(value, 'schemaVersion')?.value === '1.2.0'
32
+ );
33
+ }
34
+ export function supportsDiagramStudioPresentation(value) {
35
+ if (value === null || typeof value !== 'object') return false;
36
+ const version = Object.getOwnPropertyDescriptor(value, 'schemaVersion')?.value;
37
+ return version === '1.1.0' || version === '1.2.0';
38
+ }
39
+ export function diagramAuthoringVersionFields(value) {
40
+ return Object.hasOwn(value, 'shapeLibrary')
41
+ ? { schemaVersion: '1.2.0', protocolVersion: '1.21.0' }
42
+ : value.studioPresentation
43
+ ? { schemaVersion: '1.1.0', protocolVersion: '1.17.0' }
44
+ : { schemaVersion: '1.0.0', protocolVersion: '1.13.0' };
45
+ }
46
+
18
47
  export const DIAGRAM_PRESENTATION_SCHEMA = {
19
48
  $schema: 'https://json-schema.org/draft/2020-12/schema',
20
49
  $id: 'https://openplanr.dev/schemas/v1.17.0/diagram-presentation.schema.json',
@@ -72,6 +101,7 @@ export function assertDiagramReviewBundleV11(value) {
72
101
  }
73
102
  export function assertVersionedDiagramReviewBundle(value) {
74
103
  assertDiagramData(value);
104
+ if (value?.schemaVersion === '1.2.0') return assertDiagramReviewBundleV12(value);
75
105
  return value?.schemaVersion === '1.1.0'
76
106
  ? assertDiagramReviewBundleV11(value)
77
107
  : assertDiagramReviewBundle(value);
@@ -118,14 +148,21 @@ DIAGRAM_EDIT_TRANSACTION_V11_SCHEMA.properties.operations.items.oneOf.push({
118
148
  });
119
149
  export function legacyDiagramAuthoringProjection(value) {
120
150
  assertDiagramData(value);
121
- const { studioPresentation: _studio, ...legacy } = value;
151
+ if (supportsDiagramShapeLibrary(value)) assertShapeLibraryReferences(value);
152
+ const { studioPresentation: _studio, shapeLibrary: _library, ...legacy } = value;
122
153
  legacy.schemaVersion = '1.0.0';
123
154
  legacy.protocolVersion = '1.13.0';
155
+ if (supportsDiagramShapeLibrary(value)) {
156
+ legacy.presentation = structuredClone(value.presentation);
157
+ for (const placement of legacy.presentation.elements) delete placement.appearance.shapeRef;
158
+ legacy.presentation.presentationDigest = diagramPresentationDigest(legacy.presentation);
159
+ }
124
160
  legacy.bundleDigest = diagramAuthoringBundleDigest(legacy);
125
161
  return legacy;
126
162
  }
127
163
  export function assertVersionedDiagramAuthoringBundle(value) {
128
164
  assertDiagramData(value);
165
+ if (supportsDiagramShapeLibrary(value)) return assertDiagramAuthoringBundleV12(value);
129
166
  if (value?.schemaVersion !== '1.1.0') return assertDiagramAuthoringBundle(value);
130
167
  if (
131
168
  validateJson(value, DIAGRAM_AUTHORING_BUNDLE_V11_SCHEMA).length ||
@@ -139,6 +176,7 @@ export function assertVersionedDiagramAuthoringBundle(value) {
139
176
  export function assertVersionedDiagramEditTransaction(value, options = {}) {
140
177
  assertDiagramData(value);
141
178
  assertDiagramData(options);
179
+ if (supportsDiagramShapeLibrary(value)) return assertDiagramEditTransactionV12(value, options);
142
180
  if (value?.schemaVersion !== '1.1.0') return assertDiagramEditTransaction(value, options);
143
181
  if (validateJson(value, DIAGRAM_EDIT_TRANSACTION_V11_SCHEMA).length)
144
182
  throw new TypeError('Invalid diagram transaction 1.1.0.');
@@ -216,10 +254,10 @@ export function validateVersionedDiagramAuthoringArtifact(kind, value, options =
216
254
  return [{ path: '$', rule: 'diagram-authoring-contract', detail: error.message }];
217
255
  }
218
256
  if (kind === 'diagram-authoring-bundle') return validateVersionedDiagramAuthoringBundle(value);
219
- if (kind === 'diagram-edit-transaction' && value?.schemaVersion === '1.1.0')
257
+ if (kind === 'diagram-edit-transaction' && supportsDiagramStudioPresentation(value))
220
258
  return validateVersionedDiagramEditTransaction(value, options);
221
259
  const context = options.baseBundle ?? options.bundle;
222
- if (context?.schemaVersion !== '1.1.0')
260
+ if (!supportsDiagramStudioPresentation(context))
223
261
  return validateDiagramAuthoringArtifact(kind, value, options);
224
262
  const failures = validateVersionedDiagramAuthoringBundle(context);
225
263
  if (failures.length) return failures.map((entry) => ({ ...entry, path: '$options.bundle' }));
@@ -246,7 +284,10 @@ export function validateVersionedDiagramAuthoringArtifact(kind, value, options =
246
284
  Object.hasOwn(item, 'presentationDigest')
247
285
  ) {
248
286
  if (canonicalizeJson(item) === canonicalizeJson(fullSnapshot))
249
- item.bundleDigest = legacy.bundleDigest;
287
+ Object.assign(item, {
288
+ bundleDigest: legacy.bundleDigest,
289
+ presentationDigest: legacy.presentation.presentationDigest,
290
+ });
250
291
  else if (item.bundleDigest === legacy.bundleDigest) invalidBasis = true;
251
292
  }
252
293
  for (const child of Object.values(item)) project(child);
@@ -285,3 +326,243 @@ export function sealVersionedDiagramAuthoringSnapshot(value, previous = null) {
285
326
  assertVersionedDiagramAuthoringBundle(copy);
286
327
  return copy;
287
328
  }
329
+
330
+ function withShapeReferences(schema) {
331
+ const copy = structuredClone(schema);
332
+ function visit(value) {
333
+ if (!value || typeof value !== 'object') return;
334
+ if (value.properties?.shape && value.properties?.strokeWidth && value.properties?.fontSize)
335
+ value.properties.shapeRef = SHAPE_REFERENCE_SCHEMA;
336
+ for (const child of Object.values(value)) visit(child);
337
+ }
338
+ visit(copy);
339
+ return copy;
340
+ }
341
+ function versionSchema(schema, name) {
342
+ return {
343
+ ...schema,
344
+ $id: `https://openplanr.dev/schemas/v1.21.0/${name}.schema.json`,
345
+ 'x-openplanr-contract': { id: name, version: '1.21.0' },
346
+ };
347
+ }
348
+ export const DIAGRAM_AUTHORING_BUNDLE_V12_SCHEMA = versionSchema(
349
+ withShapeReferences(DIAGRAM_AUTHORING_BUNDLE_V11_SCHEMA),
350
+ 'diagram-authoring-bundle',
351
+ );
352
+ Object.assign(DIAGRAM_AUTHORING_BUNDLE_V12_SCHEMA.properties, {
353
+ schemaVersion: { const: '1.2.0' },
354
+ protocolVersion: { const: '1.21.0' },
355
+ shapeLibrary: SHAPE_LIBRARY_SCHEMA,
356
+ });
357
+ DIAGRAM_AUTHORING_BUNDLE_V12_SCHEMA.required = DIAGRAM_AUTHORING_BUNDLE_V12_SCHEMA.required
358
+ .filter((key) => key !== 'studioPresentation')
359
+ .concat('shapeLibrary');
360
+ export const DIAGRAM_EDIT_TRANSACTION_V12_SCHEMA = versionSchema(
361
+ withShapeReferences(DIAGRAM_EDIT_TRANSACTION_V11_SCHEMA),
362
+ 'diagram-edit-transaction',
363
+ );
364
+ Object.assign(DIAGRAM_EDIT_TRANSACTION_V12_SCHEMA.properties, {
365
+ schemaVersion: { const: '1.2.0' },
366
+ protocolVersion: { const: '1.21.0' },
367
+ });
368
+ DIAGRAM_EDIT_TRANSACTION_V12_SCHEMA.properties.operations.items.oneOf.push({
369
+ type: 'object',
370
+ additionalProperties: false,
371
+ required: ['type', 'before', 'after'],
372
+ properties: {
373
+ type: { const: 'set-shape-library' },
374
+ before: { anyOf: [SHAPE_LIBRARY_SCHEMA, { type: 'null' }] },
375
+ after: { anyOf: [SHAPE_LIBRARY_SCHEMA, { type: 'null' }] },
376
+ },
377
+ });
378
+ export const DIAGRAM_REVIEW_BUNDLE_V12_SCHEMA = versionSchema(
379
+ structuredClone(DIAGRAM_REVIEW_BUNDLE_SCHEMA),
380
+ 'diagram-review-bundle',
381
+ );
382
+ Object.assign(DIAGRAM_REVIEW_BUNDLE_V12_SCHEMA.properties, {
383
+ schemaVersion: { const: '1.2.0' },
384
+ presentation: DIAGRAM_PRESENTATION_SCHEMA,
385
+ authored: {
386
+ oneOf: [
387
+ DIAGRAM_AUTHORING_SCHEMAS['diagram-authoring-bundle'],
388
+ DIAGRAM_AUTHORING_BUNDLE_V11_SCHEMA,
389
+ DIAGRAM_AUTHORING_BUNDLE_V12_SCHEMA,
390
+ ],
391
+ },
392
+ });
393
+
394
+ function assertShapeLibraryReferences(value) {
395
+ assertShapeLibrary(value.shapeLibrary);
396
+ for (const entry of value.presentation.elements)
397
+ assertPlacementShape(entry, value.shapeLibrary, true);
398
+ }
399
+ function assertDiagramAuthoringBundleV12(value) {
400
+ if (validateJson(value, DIAGRAM_AUTHORING_BUNDLE_V12_SCHEMA).length)
401
+ throw new TypeError('Invalid diagram authoring bundle 1.2.0.');
402
+ if (
403
+ value.bundleDigest !== diagramAuthoringBundleDigest(value) ||
404
+ value.presentation.presentationDigest !== diagramPresentationDigest(value.presentation)
405
+ )
406
+ throw new TypeError('Diagram authoring bundle 1.2.0 content digest does not match.');
407
+ assertShapeLibraryReferences(value);
408
+ if (value.studioPresentation) assertDiagramPresentation(value.studioPresentation);
409
+ assertDiagramAuthoringBundle(legacyDiagramAuthoringProjection(value));
410
+ return value;
411
+ }
412
+ function assertDiagramReviewBundleV12(value) {
413
+ if (validateJson(value, DIAGRAM_REVIEW_BUNDLE_V12_SCHEMA).length)
414
+ throw new TypeError('Invalid diagram review bundle 1.2.0.');
415
+ const { presentation, ...legacy } = value;
416
+ if (presentation) assertDiagramPresentation(presentation);
417
+ if (value.authored) {
418
+ assertVersionedDiagramAuthoringBundle(value.authored);
419
+ if (
420
+ canonicalizeJson(value.authored.studioPresentation ?? null) !==
421
+ canonicalizeJson(presentation ?? null)
422
+ )
423
+ throw new TypeError('Review and authored presentations differ.');
424
+ legacy.authored = legacyDiagramAuthoringProjection(value.authored);
425
+ }
426
+ assertDiagramReviewBundle({ ...legacy, schemaVersion: '1.0.0' });
427
+ return value;
428
+ }
429
+ function assertLibraryOperation(operation) {
430
+ if (operation.before !== null) assertShapeLibrary(operation.before);
431
+ if (operation.after !== null) assertShapeLibrary(operation.after);
432
+ const previous = new Map(
433
+ (operation.before ?? []).map((entry) => [shapeReferenceKey(entry), entry.definitionDigest]),
434
+ );
435
+ for (const definition of operation.after ?? []) {
436
+ const digest = previous.get(shapeReferenceKey(definition));
437
+ if (digest && digest !== definition.definitionDigest)
438
+ throw new TypeError(
439
+ `Shape ${shapeReferenceKey(definition)}: immutable library definition changed.`,
440
+ );
441
+ }
442
+ }
443
+ function assertChangedValue(operation, current, label) {
444
+ if (
445
+ canonicalizeJson(operation.before) !== canonicalizeJson(current) ||
446
+ canonicalizeJson(operation.after) === canonicalizeJson(current)
447
+ )
448
+ throw new TypeError(`${label} operation before/after differs.`);
449
+ }
450
+ function assertPlacementShape(entry, library, validateGeometry = false) {
451
+ if (!entry.appearance.shapeRef) return;
452
+ const definition = assertShapeReference(entry.appearance.shapeRef, library);
453
+ if (!validateGeometry) return;
454
+ if (entry.route || !entry.bounds)
455
+ throw new TypeError(`Element ${entry.elementId}: connectors cannot reference library shapes.`);
456
+ if (
457
+ entry.bounds.width < definition.sizing.minWidth ||
458
+ entry.bounds.height < definition.sizing.minHeight
459
+ )
460
+ throw new TypeError(
461
+ `Element ${entry.elementId}: saved size is below shape minimum ${definition.sizing.minWidth} by ${definition.sizing.minHeight}.`,
462
+ );
463
+ }
464
+ function updateReferencedPlacements(operation, placements, library) {
465
+ if (operation.type === 'insert-elements' || operation.type === 'remove-elements') {
466
+ for (const entry of operation.presentation) {
467
+ assertPlacementShape(entry, library);
468
+ if (operation.type === 'insert-elements') placements.set(entry.elementId, entry);
469
+ else placements.delete(entry.elementId);
470
+ }
471
+ return;
472
+ }
473
+ if (!['set-geometry', 'set-appearance-locks'].includes(operation.type)) return;
474
+ for (const change of operation.changes) {
475
+ const appearance = operation.type === 'set-appearance-locks';
476
+ if (appearance) {
477
+ assertPlacementShape(change.before, library);
478
+ assertPlacementShape(change.after, library);
479
+ }
480
+ const previous = placements.get(change.elementId);
481
+ if (previous)
482
+ placements.set(change.elementId, {
483
+ ...previous,
484
+ ...(appearance ? { appearance: change.after.appearance } : change.after),
485
+ });
486
+ }
487
+ }
488
+
489
+ function stripShapeReferences(item) {
490
+ if (!item || typeof item !== 'object') return;
491
+ if (item.appearance) delete item.appearance.shapeRef;
492
+ for (const child of Object.values(item)) stripShapeReferences(child);
493
+ }
494
+ function projectLibraryOperations(operations, basis) {
495
+ let library = basis.shapeLibrary ?? null;
496
+ let studio = basis.studioPresentation ?? null;
497
+ const placements = new Map(basis.presentation.elements.map((entry) => [entry.elementId, entry]));
498
+ const ordinary = [];
499
+ for (const operation of operations) {
500
+ if (operation.type === 'set-shape-library') {
501
+ assertChangedValue(operation, library, 'Shape library');
502
+ library = operation.after;
503
+ } else if (operation.type === 'set-studio-presentation') {
504
+ assertChangedValue(operation, studio, 'Studio presentation');
505
+ studio = operation.after;
506
+ } else {
507
+ updateReferencedPlacements(operation, placements, library);
508
+ const projected = structuredClone(operation);
509
+ stripShapeReferences(projected);
510
+ ordinary.push(projected);
511
+ }
512
+ }
513
+ for (const placement of placements.values()) assertPlacementShape(placement, library, true);
514
+ return ordinary;
515
+ }
516
+ function assertDiagramEditTransactionV12(value, options) {
517
+ if (validateJson(value, DIAGRAM_EDIT_TRANSACTION_V12_SCHEMA).length)
518
+ throw new TypeError('Invalid diagram transaction 1.2.0.');
519
+ const basis = options.baseBundle ?? options.bundle;
520
+ if (
521
+ options.baseBundle &&
522
+ options.bundle &&
523
+ canonicalizeJson(options.baseBundle) !== canonicalizeJson(options.bundle)
524
+ )
525
+ throw new TypeError('Conflicting transaction bundle contexts.');
526
+ const seenDefinitions = new Map();
527
+ for (const operation of value.operations) {
528
+ if (operation.type !== 'set-shape-library') continue;
529
+ assertLibraryOperation(operation);
530
+ for (const definition of [...(operation.before ?? []), ...(operation.after ?? [])]) {
531
+ const key = shapeReferenceKey(definition);
532
+ const previous = seenDefinitions.get(key);
533
+ if (previous && previous !== definition.definitionDigest)
534
+ throw new TypeError(
535
+ `Shape ${key}: immutable library definition changed within transaction.`,
536
+ );
537
+ seenDefinitions.set(key, definition.definitionDigest);
538
+ }
539
+ }
540
+ if (!basis) return value;
541
+ assertVersionedDiagramAuthoringBundle(basis);
542
+ if (
543
+ value.diagramId !== basis.diagramId ||
544
+ value.base.bundleDigest !== basis.bundleDigest ||
545
+ value.base.semanticDigest !== basis.document.documentDigest ||
546
+ value.base.presentationDigest !== basis.presentation.presentationDigest
547
+ )
548
+ throw new TypeError('Shape library transaction basis differs.');
549
+ const ordinary = projectLibraryOperations(value.operations, basis);
550
+ if (ordinary.length) {
551
+ const legacy = legacyDiagramAuthoringProjection(basis);
552
+ assertDiagramEditTransaction(
553
+ {
554
+ ...value,
555
+ schemaVersion: '1.0.0',
556
+ protocolVersion: '1.13.0',
557
+ base: {
558
+ ...value.base,
559
+ bundleDigest: legacy.bundleDigest,
560
+ presentationDigest: legacy.presentation.presentationDigest,
561
+ },
562
+ operations: ordinary,
563
+ },
564
+ { baseBundle: legacy },
565
+ );
566
+ }
567
+ return value;
568
+ }
@@ -1,5 +1,5 @@
1
1
  // @ts-check
2
- import { DESIGN_DOCUMENT_SCHEMA } from './design-contracts.mjs';
2
+ import { DESIGN_DOCUMENT_V1_SCHEMA } from './design-contracts.mjs';
3
3
  import { validateJson } from './json-schema.mjs';
4
4
 
5
5
  /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_VERSION} */
@@ -98,7 +98,7 @@ export const DESIGN_WORKSPACE_SCHEMA = schema('design-review-workspace', {
98
98
  // design-system references are deliberately not part of a published workspace.
99
99
  const designProperties =
100
100
  /** @type {Record<string, { items: { properties: Record<string, unknown>; required: string[] } }>} */ (
101
- structuredClone(DESIGN_DOCUMENT_SCHEMA.properties)
101
+ structuredClone(DESIGN_DOCUMENT_V1_SCHEMA.properties)
102
102
  );
103
103
  for (const key of ['kind', 'schemaVersion', 'brief', 'assets', 'designSystem'])
104
104
  delete designProperties[key];
@@ -171,7 +171,7 @@ export const DESIGN_REVIEW_BUNDLE_SCHEMA = {
171
171
  },
172
172
  ['kind', 'schemaVersion', 'design', 'envelope', 'entries', 'revision'],
173
173
  ),
174
- $defs: structuredClone(DESIGN_DOCUMENT_SCHEMA.$defs),
174
+ $defs: structuredClone(DESIGN_DOCUMENT_V1_SCHEMA.$defs),
175
175
  };
176
176
 
177
177
  /** @returns {ReturnType<typeof import('./workspace-contracts.d.mts').assertWorkspaceContract>} */