@openplanr/protocol 0.5.0 → 0.6.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.
@@ -4,6 +4,7 @@ import {
4
4
  PROTOCOL_V18_CONTRACT_FILES,
5
5
  } from './skill-source-contracts.mjs';
6
6
  import { DESIGN_HANDOFF_CONTRACT_FILES } from './design-handoff-contracts.mjs';
7
+ import { DIAGRAM_AUTHORING_CONTRACT_FILES } from './diagram-authoring-contracts.mjs';
7
8
 
8
9
  export const PROTOCOL_V15_CONTRACTS = Object.freeze({
9
10
  'command-catalog': 'command-catalog.schema.json',
@@ -28,17 +29,22 @@ export const PROTOCOL_V111_CONTRACTS = Object.freeze({
28
29
  ...DESIGN_HANDOFF_CONTRACT_FILES,
29
30
  });
30
31
 
32
+ export const PROTOCOL_V113_CONTRACTS = DIAGRAM_AUTHORING_CONTRACT_FILES;
33
+
31
34
  const PROTOCOL_CONTRACTS_BY_VERSION = Object.freeze({
32
35
  '1.5.0': PROTOCOL_V15_CONTRACTS,
33
36
  '1.6.0': PROTOCOL_V16_CONTRACTS,
34
37
  '1.7.0': PROTOCOL_V17_CONTRACTS,
35
38
  '1.8.0': PROTOCOL_V18_CONTRACTS,
36
39
  '1.11.0': PROTOCOL_V111_CONTRACTS,
40
+ '1.13.0': PROTOCOL_V113_CONTRACTS,
37
41
  });
38
42
 
39
43
  /** Resolve a packaged schema asset without a source checkout or Node-only API. */
40
44
  export function protocolAssetUrl(kind, { protocolVersion = '1.5.0' } = {}) {
41
- const filename = PROTOCOL_CONTRACTS_BY_VERSION[protocolVersion]?.[kind];
45
+ const contracts = Object.hasOwn(PROTOCOL_CONTRACTS_BY_VERSION, protocolVersion)
46
+ ? PROTOCOL_CONTRACTS_BY_VERSION[protocolVersion] : null;
47
+ const filename = contracts && Object.hasOwn(contracts, kind) ? contracts[kind] : null;
42
48
  if (!filename) {
43
49
  throw new RangeError(`Unknown browser-safe Protocol contract: ${kind}@${protocolVersion}`);
44
50
  }
package/src/contracts.mjs CHANGED
@@ -12,6 +12,7 @@ import {
12
12
  PROTOCOL_V18_CONTRACT_FILES,
13
13
  } from './skill-source-contracts.mjs';
14
14
  import { DESIGN_HANDOFF_CONTRACT_FILES } from './design-handoff-contracts.mjs';
15
+ import { DIAGRAM_AUTHORING_CONTRACT_FILES, validateDiagramAuthoringArtifact } from './diagram-authoring-contracts.mjs';
15
16
 
16
17
  const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
17
18
 
@@ -156,6 +157,11 @@ const foundationPaths = {
156
157
  'diagram-type-registry': { '1.6.0': v16Schema('diagram-type-registry') },
157
158
  };
158
159
 
160
+ // Authoring successors are additive; preserve every legacy diagram registration.
161
+ for (const [kind, filename] of Object.entries(DIAGRAM_AUTHORING_CONTRACT_FILES)) {
162
+ foundationPaths[kind] = { ...foundationPaths[kind], '1.13.0': `schemas/v1.13.0/${filename}` };
163
+ }
164
+
159
165
  function compiledOperatePaths() {
160
166
  const catalog = OPERATE_CONTRACT_CATALOG_V2;
161
167
  if (
@@ -891,7 +897,25 @@ function guidedQuestionnaireCompatibilityErrors(value) {
891
897
  }
892
898
 
893
899
  export function validateProtocolArtifact(kind, value, { protocolVersion } = {}) {
894
- const version = inferredVersion(kind, value, protocolVersion);
900
+ const authoringKind = Object.hasOwn(DIAGRAM_AUTHORING_CONTRACT_FILES, kind);
901
+ let versionInput = value;
902
+ if (authoringKind && (!protocolVersion || protocolVersion === '1.13.0')) {
903
+ // Choose the additive validator without executing an envelope accessor.
904
+ // Its safety preflight owns the resulting located diagnostic.
905
+ let descriptor;
906
+ try {
907
+ descriptor = value !== null && typeof value === 'object'
908
+ ? Object.getOwnPropertyDescriptor(value, 'protocolVersion') : undefined;
909
+ } catch {
910
+ return validateDiagramAuthoringArtifact(kind, value);
911
+ }
912
+ if (descriptor && !Object.hasOwn(descriptor, 'value')) return validateDiagramAuthoringArtifact(kind, value);
913
+ versionInput = { protocolVersion: descriptor?.value };
914
+ }
915
+ const version = inferredVersion(kind, versionInput, protocolVersion);
916
+ if (version === '1.13.0' && authoringKind) {
917
+ return validateDiagramAuthoringArtifact(kind, value);
918
+ }
895
919
  const resolved = resolveProtocolSchema(kind, { protocolVersion: version });
896
920
  const errors = validateResolvedArtifact(value, resolved);
897
921
  if (kind === 'guided-questionnaire' && version === '1.2.0') {
@@ -0,0 +1,112 @@
1
+ export type DiagramAuthoringDigest = `sha256:${string}`;
2
+ export type DiagramAuthoringProfile = 'flowchart' | 'process' | 'swimlane' | 'architecture';
3
+ export type DiagramAuthoringNodeKind = 'process' | 'start' | 'end' | 'decision' | 'data-store' | 'component';
4
+ export type DiagramAuthoringRelationKind = 'association' | 'dependency' | 'flow' | 'message' | 'transition';
5
+ export type DiagramAuthoringContractKind = 'diagram-document' | 'diagram-presentation' | 'diagram-authoring-bundle' | 'diagram-edit-transaction' | 'diagram-source-map' | 'diagram-fidelity-report' | 'diagram-manifest' | 'diagram-change-proposal' | 'diagram-publication-state' | 'diagram-authoring-capabilities';
6
+ export type DiagramEditOperationClass = 'insert-elements' | 'update-semantics' | 'remove-elements' | 'set-membership-order' | 'set-geometry' | 'set-appearance-locks';
7
+ export type DiagramAuthoringSchema = Readonly<Record<string, unknown>>;
8
+ export interface DiagramAuthoringValidationError { path: string; rule: string; detail: string }
9
+ export interface DiagramAuthoringEnvelope<K extends string> { kind: K; schemaVersion: '1.0.0'; protocolVersion: '1.13.0' }
10
+ export interface DiagramAuthoringNode { id: string; label: string; kind: DiagramAuthoringNodeKind; description: string | null }
11
+ export interface DiagramAuthoringRelation { id: string; from: string; to: string; kind: DiagramAuthoringRelationKind; direction: 'forward' | 'both' | 'none'; label: string | null; weight: number | null }
12
+ export interface DiagramAuthoringContainer { id: string; label: string; members: string[] }
13
+ export interface DiagramAuthoringAnnotation { id: string; text: string; targetId: string | null }
14
+ export interface DiagramAuthoringAccessibility { title: string; description: string; readingOrder: string[] }
15
+ export interface DiagramAuthoringDocument extends DiagramAuthoringEnvelope<'planr-diagram'> {
16
+ diagramId: string; title: string; summary: string; audience: 'engineer' | 'executive' | 'mixed';
17
+ grammar: { id: DiagramAuthoringProfile; version: '1.0.0' };
18
+ nodes: DiagramAuthoringNode[]; relations: DiagramAuthoringRelation[]; groups: DiagramAuthoringContainer[]; lanes: DiagramAuthoringContainer[];
19
+ events: never[]; series: never[]; axes: never[]; sets: never[];
20
+ annotations: DiagramAuthoringAnnotation[]; emphasis: Array<{ targetId: string; level: 'primary' | 'secondary' | 'muted' }>;
21
+ laneOrder: string[]; accessibility: DiagramAuthoringAccessibility; documentDigest: DiagramAuthoringDigest;
22
+ }
23
+ export interface DiagramBounds { x: number; y: number; width: number; height: number }
24
+ export interface DiagramBoundaryAttachment { side: 'top' | 'right' | 'bottom' | 'left'; offset: number }
25
+ export interface DiagramRoute { mode: 'automatic' | 'manual'; strategy: 'straight' | 'orthogonal'; from: DiagramBoundaryAttachment; to: DiagramBoundaryAttachment; points: Array<{ x: number; y: number }> }
26
+ export interface DiagramAppearance {
27
+ shape: 'rectangle' | 'rounded-rectangle' | 'ellipse' | 'diamond' | 'cylinder' | 'text' | 'container' | 'connector';
28
+ fill: 'surface' | 'accent' | 'success' | 'warning' | 'danger' | 'transparent';
29
+ stroke: 'default' | 'accent' | 'muted' | 'danger' | 'none'; strokeWidth: number;
30
+ strokeStyle: 'solid' | 'dashed' | 'dotted'; fontSize: number; textAlign: 'left' | 'center' | 'right';
31
+ }
32
+ export interface DiagramGeometryLocks { position: boolean; size: boolean; route: boolean }
33
+ export interface DiagramGeometry { bounds: DiagramBounds | null; route: DiagramRoute | null; label: { x: number; y: number; width: number } | null; zIndex: number }
34
+ export interface DiagramPlacement extends DiagramGeometry { elementId: string; appearance: DiagramAppearance; locks: DiagramGeometryLocks }
35
+ export interface DiagramPresentation extends DiagramAuthoringEnvelope<'diagram-presentation'> {
36
+ diagramId: string; semanticDigest: DiagramAuthoringDigest; coordinateSystem: 'global-canvas';
37
+ layout: { direction: 'top-down' | 'left-right' | 'right-left' | 'bottom-up'; detailTier: 'simplified' | 'balanced' | 'faithful' };
38
+ theme: { themeId: 'paper' | 'slate' | 'midnight'; mode: 'light' | 'dark' | 'auto' };
39
+ elements: DiagramPlacement[]; presentationDigest: DiagramAuthoringDigest;
40
+ }
41
+ export interface DiagramAuthoringSnapshot { bundleDigest: DiagramAuthoringDigest; semanticDigest: DiagramAuthoringDigest; presentationDigest: DiagramAuthoringDigest }
42
+ export interface DiagramSourceMap extends DiagramAuthoringEnvelope<'diagram-source-map'> {
43
+ diagramId: string; semanticDigest: DiagramAuthoringDigest; sourceDigest: DiagramAuthoringDigest; sourceByteLength: number; encoding: 'utf-8';
44
+ parser: { id: string; version: string }; certificationVersion: 'flowchart-copy-v1';
45
+ entries: Array<{ sourceId: string | null; elementIds: string[]; range: { startByte: number; endByte: number } | null; construct: string; confidence: 'exact' | 'ambiguous'; losses: string[] }>;
46
+ }
47
+ export interface DiagramAuthoringBundle extends DiagramAuthoringEnvelope<'diagram-authoring-bundle'> {
48
+ diagramId: string; document: DiagramAuthoringDocument; presentation: DiagramPresentation;
49
+ originalSource: { format: 'mermaid'; text: string; sourceDigest: DiagramAuthoringDigest } | null;
50
+ sourceMap: DiagramSourceMap | null; bundleDigest: DiagramAuthoringDigest;
51
+ }
52
+ export type DiagramSemanticEntry =
53
+ | { collection: 'nodes'; value: DiagramAuthoringNode }
54
+ | { collection: 'relations'; value: DiagramAuthoringRelation }
55
+ | { collection: 'groups' | 'lanes'; value: DiagramAuthoringContainer }
56
+ | { collection: 'annotations'; value: DiagramAuthoringAnnotation };
57
+ export interface DiagramMembershipState { groups: Array<{ id: string; members: string[] }>; lanes: Array<{ id: string; members: string[] }>; laneOrder: string[] }
58
+ export type DiagramSemanticUpdate =
59
+ | { type: 'update-semantics'; collection: 'nodes'; elementId: string; before: Omit<DiagramAuthoringNode, 'id'>; after: Omit<DiagramAuthoringNode, 'id'> }
60
+ | { type: 'update-semantics'; collection: 'relations'; elementId: string; before: Omit<DiagramAuthoringRelation, 'id'>; after: Omit<DiagramAuthoringRelation, 'id'> }
61
+ | { type: 'update-semantics'; collection: 'groups' | 'lanes'; elementId: string; before: { label: string }; after: { label: string } }
62
+ | { type: 'update-semantics'; collection: 'annotations'; elementId: string; before: Omit<DiagramAuthoringAnnotation, 'id'>; after: Omit<DiagramAuthoringAnnotation, 'id'> }
63
+ | { type: 'update-semantics'; collection: 'emphasis'; elementId: string; before: 'primary' | 'secondary' | 'muted' | null; after: 'primary' | 'secondary' | 'muted' | null; index?: number }
64
+ | { type: 'update-semantics'; collection: 'document'; before: Pick<DiagramAuthoringDocument, 'title' | 'summary' | 'audience' | 'accessibility'>; after: Pick<DiagramAuthoringDocument, 'title' | 'summary' | 'audience' | 'accessibility'> }
65
+ | { type: 'update-semantics'; collection: 'source-map'; before: DiagramSourceMap | null; after: DiagramSourceMap | null };
66
+ export type DiagramEditOperation =
67
+ | { type: 'insert-elements'; elements: DiagramSemanticEntry[]; presentation: DiagramPlacement[]; positions?: Array<{ elementId: string; semanticIndex: number; presentationIndex: number }> }
68
+ | { type: 'remove-elements'; elements: DiagramSemanticEntry[]; presentation: DiagramPlacement[] }
69
+ | DiagramSemanticUpdate
70
+ | { type: 'set-membership-order'; before: DiagramMembershipState; after: DiagramMembershipState }
71
+ | { type: 'set-geometry'; changes: Array<{ elementId: string; before: DiagramGeometry; after: DiagramGeometry }> }
72
+ | { type: 'set-appearance-locks'; changes: Array<{ elementId: string; before: { appearance: DiagramAppearance; locks: DiagramGeometryLocks }; after: { appearance: DiagramAppearance; locks: DiagramGeometryLocks } }> };
73
+ export interface DiagramEditTransaction extends DiagramAuthoringEnvelope<'diagram-edit-transaction'> { transactionId: string; diagramId: string; base: DiagramAuthoringSnapshot; operations: DiagramEditOperation[]; undoOf: string | null }
74
+ export interface DiagramChangeProposal extends DiagramAuthoringEnvelope<'diagram-change-proposal'> { proposalId: string; diagramId: string; base: DiagramAuthoringSnapshot; transaction: DiagramEditTransaction; summary: string; author: { kind: 'human' | 'agent'; id: string }; status: 'proposed' | 'accepted' | 'rejected' | 'stale' }
75
+ export interface DiagramPublicationState extends DiagramAuthoringEnvelope<'diagram-publication-state'> { diagramId: string; draft: DiagramAuthoringSnapshot | null; published: DiagramAuthoringSnapshot | null; audience: 'private' | 'company' | 'public'; capabilitySemantics: 'descriptive-only-requires-host-authorization' }
76
+ export type DiagramFidelity = 'lossless' | 'partial' | 'unsupported';
77
+ export interface DiagramFidelityReport extends DiagramAuthoringEnvelope<'diagram-fidelity-report'> { diagramId: string; basis: DiagramAuthoringSnapshot; sourceDigest: DiagramAuthoringDigest | null; sourceFormat: 'mermaid' | 'planr-diagram-bundle'; targetFormat: 'mermaid' | 'planr-diagram-bundle' | 'svg' | 'html' | 'png'; semantic: DiagramFidelity; presentation: DiagramFidelity; sourceText: DiagramFidelity; losses: Array<{ dimension: 'semantic' | 'presentation' | 'sourceText'; code: string; elementIds: string[]; message: string }> }
78
+ export interface DiagramAuthoringManifest extends DiagramAuthoringEnvelope<'diagram-manifest'> { diagramId: string; basis: DiagramAuthoringSnapshot; bundle: { path: string; transportDigest: DiagramAuthoringDigest }; renderer: { id: string; version: string }; theme?: { id: string; version: string }; outputs: Array<{ path: string; mediaType: 'image/svg+xml' | 'text/html' | 'image/png'; transportDigest: DiagramAuthoringDigest; fidelity: DiagramFidelityReport }> }
79
+ export interface DiagramMermaidConstructCapability { readonly construct: string; readonly import: DiagramFidelity; readonly export: DiagramFidelity; readonly semanticRoundTrip: DiagramFidelity; readonly mapping: string }
80
+ export interface DiagramAuthoringCapability {
81
+ readonly grammarId: DiagramAuthoringProfile; readonly authoring: true;
82
+ readonly primitives: readonly ('node' | 'relation' | 'group' | 'lane' | 'annotation' | 'emphasis')[];
83
+ readonly nodeKinds: readonly DiagramAuthoringNodeKind[]; readonly relationKinds: readonly DiagramAuthoringRelationKind[];
84
+ readonly operations: readonly DiagramEditOperationClass[];
85
+ readonly mermaid: { readonly mode: 'copy'; readonly certificationVersion: 'flowchart-copy-v1'; readonly constructs: readonly DiagramMermaidConstructCapability[]; readonly linkedSource: false };
86
+ }
87
+ export interface DiagramAuthoringCapabilities extends DiagramAuthoringEnvelope<'diagram-authoring-capabilities'> { readonly version: '1.0.0'; readonly liveCollaboration: false; readonly profiles: readonly DiagramAuthoringCapability[]; readonly unsupportedGrammars: readonly string[] }
88
+ export interface DiagramAuthoringValidationOptions { document?: DiagramAuthoringDocument; bundle?: DiagramAuthoringBundle; baseBundle?: DiagramAuthoringBundle; sourceText?: string }
89
+ export interface DiagramLegacyInspection { valid: boolean; errors: DiagramAuthoringValidationError[]; diagramId: string | null; grammarId: string | null; authoringAvailable: boolean; requiresDerivedPresentation: boolean; unsupportedNodeKinds: string[]; adoption: 'explicit-save-required'; sourceModified: false }
90
+ export declare const DIAGRAM_AUTHORING_PROTOCOL_VERSION: '1.13.0';
91
+ export declare const DIAGRAM_AUTHORING_CONTRACT_VERSION: '1.0.0';
92
+ export declare const DIAGRAM_EDIT_OPERATION_CLASSES: readonly DiagramEditOperationClass[];
93
+ export declare const DIAGRAM_AUTHORING_LIMITS: Readonly<{ depth: 48; values: 500000; textCodeUnits: 8388608; sourceBytes: 1048576; elements: 10000; operations: 256; coordinate: 1000000 }>;
94
+ export declare const DIAGRAM_AUTHORING_SCHEMAS: Readonly<Record<DiagramAuthoringContractKind, DiagramAuthoringSchema>>;
95
+ export declare const DIAGRAM_AUTHORING_CONTRACT_FILES: Readonly<Record<DiagramAuthoringContractKind, string>>;
96
+ export declare const DIAGRAM_AUTHORING_CAPABILITIES: Readonly<DiagramAuthoringCapabilities>;
97
+ export declare function getDiagramAuthoringCapability(grammarId: string): DiagramAuthoringCapability | null;
98
+ export declare function diagramDocumentDigest(value: Omit<DiagramAuthoringDocument, 'documentDigest'> | DiagramAuthoringDocument | Record<string, unknown>): DiagramAuthoringDigest;
99
+ export declare function diagramPresentationDigest(value: Omit<DiagramPresentation, 'presentationDigest'> | DiagramPresentation): DiagramAuthoringDigest;
100
+ export declare function diagramAuthoringBundleDigest(value: Omit<DiagramAuthoringBundle, 'bundleDigest'> | DiagramAuthoringBundle): DiagramAuthoringDigest;
101
+ export declare function validateDiagramAuthoringArtifact(kind: string, value: unknown, options?: DiagramAuthoringValidationOptions): DiagramAuthoringValidationError[];
102
+ export declare function assertDiagramAuthoringArtifact<T>(kind: DiagramAuthoringContractKind, value: T, options?: DiagramAuthoringValidationOptions): T;
103
+ export declare function validateDiagramDocument(value: unknown, options?: DiagramAuthoringValidationOptions): DiagramAuthoringValidationError[];
104
+ export declare function assertDiagramDocument<T extends DiagramAuthoringDocument>(value: T, options?: DiagramAuthoringValidationOptions): T;
105
+ export declare function validateDiagramPresentation(value: unknown, options?: DiagramAuthoringValidationOptions): DiagramAuthoringValidationError[];
106
+ export declare function assertDiagramPresentation<T extends DiagramPresentation>(value: T, options?: DiagramAuthoringValidationOptions): T;
107
+ export declare function validateDiagramAuthoringBundle(value: unknown, options?: DiagramAuthoringValidationOptions): DiagramAuthoringValidationError[];
108
+ export declare function assertDiagramAuthoringBundle<T extends DiagramAuthoringBundle>(value: T, options?: DiagramAuthoringValidationOptions): T;
109
+ export declare function validateDiagramEditTransaction(value: unknown, options?: DiagramAuthoringValidationOptions): DiagramAuthoringValidationError[];
110
+ export declare function assertDiagramEditTransaction<T extends DiagramEditTransaction>(value: T, options?: DiagramAuthoringValidationOptions): T;
111
+ export declare function summarizeDiagramAuthoringContent(bundle: DiagramAuthoringBundle): { elementCount: number; hasVisibleContent: boolean };
112
+ export declare function inspectLegacyDiagramDocument(value: unknown): DiagramLegacyInspection;