@openplanr/protocol 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/lib/dashboard/closed-json-contract.mjs +99 -109
  2. package/lib/dashboard/operate-experience-audit-display-contract.d.mts +128 -153
  3. package/lib/dashboard/operate-experience-audit-display-contract.mjs +530 -585
  4. package/lib/dashboard/operate-experience-display-contract.d.mts +415 -437
  5. package/lib/dashboard/operate-experience-display-contract.mjs +768 -831
  6. package/lib/dashboard/operate-experience-surface-contract.d.mts +143 -148
  7. package/lib/dashboard/operate-experience-surface-contract.mjs +72 -73
  8. package/lib/dashboard/operate-review-contract.d.mts +7 -14
  9. package/lib/dashboard/operate-review-contract.mjs +46 -42
  10. package/lib/dashboard/operate-review-display-workspace-contract.d.mts +2 -5
  11. package/lib/dashboard/operate-review-display-workspace-contract.mjs +158 -104
  12. package/lib/dashboard/operate-review-payload-safety.mjs +4 -2
  13. package/lib/dashboard/operate-review-workspace-projection-v2.d.mts +47 -33
  14. package/lib/protocol/index.d.ts +2647 -543
  15. package/package.json +1 -1
  16. package/registries/commands.json +7 -7
  17. package/registries/skills.json +6 -6
  18. package/src/browser-contracts.d.mts +4 -1
  19. package/src/browser-contracts.mjs +16 -5
  20. package/src/canonical-json.d.mts +3 -1
  21. package/src/canonical-json.mjs +57 -20
  22. package/src/compat/live-evidence-v2.mjs +1604 -485
  23. package/src/compat/operate-experience-live-patch.mjs +67 -15
  24. package/src/compat/operating-planning-contracts.mjs +183 -51
  25. package/src/contracts.d.mts +54 -13
  26. package/src/contracts.mjs +655 -345
  27. package/src/design-contracts.mjs +58 -21
  28. package/src/design-handoff-contracts.d.mts +67 -11
  29. package/src/design-handoff-contracts.mjs +243 -98
  30. package/src/design-publication-contracts.mjs +98 -33
  31. package/src/diagram-authoring-contracts.d.mts +422 -78
  32. package/src/diagram-authoring-contracts.mjs +1697 -326
  33. package/src/diagram-contracts.d.mts +4 -1
  34. package/src/diagram-contracts.mjs +16 -4
  35. package/src/enterprise-contracts.d.mts +211 -46
  36. package/src/enterprise-contracts.mjs +727 -175
  37. package/src/errors.mjs +4 -0
  38. package/src/generated/canonical-registries.mjs +13 -13
  39. package/src/index.d.mts +8 -8
  40. package/src/index.mjs +36 -20
  41. package/src/json-schema.d.mts +21 -6
  42. package/src/json-schema.mjs +66 -18
  43. package/src/planning-contracts.d.mts +8 -2
  44. package/src/planning-contracts.mjs +33 -7
  45. package/src/registries.d.mts +11 -3
  46. package/src/registries.mjs +369 -87
  47. package/src/review-experience-contracts.d.mts +7 -2
  48. package/src/review-experience-contracts.mjs +198 -49
  49. package/src/semver.mjs +5 -1
  50. package/src/skill-source-contracts.d.mts +36 -16
  51. package/src/skill-source-contracts.mjs +25 -6
  52. package/src/task-contracts.d.mts +13 -3
  53. package/src/task-contracts.mjs +181 -40
  54. package/src/workspace-contracts.d.mts +38 -10
  55. package/src/workspace-contracts.mjs +147 -33
@@ -1,62 +1,124 @@
1
- import { CANONICAL_REGISTRIES, resolveTaskKind } from './registries.mjs';
1
+ // @ts-check
2
2
  import { ProtocolError } from './errors.mjs';
3
+ import { CANONICAL_REGISTRIES, resolveTaskKind } from './registries.mjs';
3
4
 
5
+ /**
6
+ * @typedef {{ roles: Array<{ roleId: string; roleVersion: string }>; documentDigest: string }} RoleRegistry
7
+ * @typedef {{ bindings: Array<{ taskKind: string; roleId: string }>; documentDigest: string }} TaskKindRegistry
8
+ * @typedef {NonNullable<Parameters<typeof import('./task-contracts.d.mts').validateTaskOutputSemantics>[1]>} TaskOutputOptions
9
+ */
4
10
  const diagnostic = (code, path, message) => ({ code, path, message });
5
11
  const pathKey = ({ repositoryKey, path }) => `${repositoryKey}:${path}`;
6
12
 
7
- export function validateTaskManifestSemantics(value, {
8
- roles = CANONICAL_REGISTRIES['roles.json'],
9
- taskKinds = CANONICAL_REGISTRIES['task-kinds.json'],
10
- } = {}) {
13
+ /** @returns {ReturnType<typeof import('./task-contracts.d.mts').validateTaskManifestSemantics>} */
14
+ export function validateTaskManifestSemantics(
15
+ value,
16
+ {
17
+ roles = /** @type {RoleRegistry} */ (CANONICAL_REGISTRIES['roles.json']),
18
+ taskKinds = /** @type {TaskKindRegistry} */ (CANONICAL_REGISTRIES['task-kinds.json']),
19
+ } = {},
20
+ ) {
11
21
  const diagnostics = [];
12
22
  const binding = taskKinds.bindings.find(({ taskKind }) => taskKind === value?.routing?.taskKind);
13
23
  if (!binding || binding.roleId !== value?.routing?.roleId) {
14
- diagnostics.push(diagnostic('E_TASK_KIND_ROLE_MISMATCH', '$.routing', 'taskKind and roleId must match one canonical task-kind binding.'));
24
+ diagnostics.push(
25
+ diagnostic(
26
+ 'E_TASK_KIND_ROLE_MISMATCH',
27
+ '$.routing',
28
+ 'taskKind and roleId must match one canonical task-kind binding.',
29
+ ),
30
+ );
15
31
  }
16
- if (value?.routing?.taskKindRegistryDigest !== taskKinds.documentDigest
17
- || value?.routing?.roleRegistryDigest !== roles.documentDigest) {
18
- diagnostics.push(diagnostic('E_TASK_REGISTRY_BINDING_MISMATCH', '$.routing', 'routing must bind the exact canonical task-kind and role registry digests.'));
32
+ if (
33
+ value?.routing?.taskKindRegistryDigest !== taskKinds.documentDigest ||
34
+ value?.routing?.roleRegistryDigest !== roles.documentDigest
35
+ ) {
36
+ diagnostics.push(
37
+ diagnostic(
38
+ 'E_TASK_REGISTRY_BINDING_MISMATCH',
39
+ '$.routing',
40
+ 'routing must bind the exact canonical task-kind and role registry digests.',
41
+ ),
42
+ );
19
43
  }
20
44
  const role = roles.roles.find(({ roleId }) => roleId === value?.routing?.roleId);
21
45
  if (!role || role.roleVersion !== value?.routing?.roleVersion) {
22
- diagnostics.push(diagnostic('E_TASK_ROLE_VERSION_MISMATCH', '$.routing.roleVersion', 'role version is not present in the bound registry.'));
46
+ diagnostics.push(
47
+ diagnostic(
48
+ 'E_TASK_ROLE_VERSION_MISMATCH',
49
+ '$.routing.roleVersion',
50
+ 'role version is not present in the bound registry.',
51
+ ),
52
+ );
23
53
  }
24
54
  const scopeSets = new Map();
25
55
  for (const scope of ['create', 'modify', 'preserve']) {
26
56
  for (const entry of value?.scope?.[scope] ?? []) {
27
57
  const key = pathKey(entry);
28
58
  const previous = scopeSets.get(key);
29
- if (previous) diagnostics.push(diagnostic('E_TASK_SCOPE_OVERLAP', `$.scope.${scope}`, `${key} is already declared in ${previous}.`));
59
+ if (previous)
60
+ diagnostics.push(
61
+ diagnostic(
62
+ 'E_TASK_SCOPE_OVERLAP',
63
+ `$.scope.${scope}`,
64
+ `${key} is already declared in ${previous}.`,
65
+ ),
66
+ );
30
67
  scopeSets.set(key, scope);
31
68
  }
32
69
  }
33
- if (!value?.reviewBinding?.planDigest || !value?.reviewBinding?.planningReviewReceiptDigest || !value?.reviewBinding?.ownerDecisionDigest) {
34
- diagnostics.push(diagnostic('E_TASK_REVIEW_BINDING_REQUIRED', '$.reviewBinding', 'DEV task issuance requires plan, review-receipt, and owner-decision digests.'));
70
+ if (
71
+ !value?.reviewBinding?.planDigest ||
72
+ !value?.reviewBinding?.planningReviewReceiptDigest ||
73
+ !value?.reviewBinding?.ownerDecisionDigest
74
+ ) {
75
+ diagnostics.push(
76
+ diagnostic(
77
+ 'E_TASK_REVIEW_BINDING_REQUIRED',
78
+ '$.reviewBinding',
79
+ 'DEV task issuance requires plan, review-receipt, and owner-decision digests.',
80
+ ),
81
+ );
35
82
  }
36
83
  return diagnostics;
37
84
  }
38
85
 
86
+ /** @type {typeof import('./task-contracts.d.mts').assertTaskManifestSemantics} */
39
87
  export function assertTaskManifestSemantics(value, options) {
40
88
  const diagnostics = validateTaskManifestSemantics(value, options);
41
- if (diagnostics.length) throw new ProtocolError(diagnostics[0].code, diagnostics[0].message, '', { diagnostics });
89
+ if (diagnostics.length)
90
+ throw new ProtocolError(diagnostics[0].code, diagnostics[0].message, '', { diagnostics });
42
91
  return value;
43
92
  }
44
93
 
94
+ /** @returns {ReturnType<typeof import('./task-contracts.d.mts').validateTaskGraph>} */
45
95
  export function validateTaskGraph(values) {
46
96
  const diagnostics = [];
47
97
  const byId = new Map(values.map((value) => [value?.task?.taskId, value]));
48
- if (byId.size !== values.length || byId.has(undefined)) diagnostics.push(diagnostic('E_TASK_GRAPH_DUPLICATE', '$', 'Task graph IDs must be present and unique.'));
98
+ if (byId.size !== values.length || byId.has(undefined))
99
+ diagnostics.push(
100
+ diagnostic('E_TASK_GRAPH_DUPLICATE', '$', 'Task graph IDs must be present and unique.'),
101
+ );
49
102
  const visiting = new Set();
50
103
  const visited = new Set();
51
104
  const visit = (id) => {
52
105
  if (visiting.has(id)) {
53
- diagnostics.push(diagnostic('E_TASK_GRAPH_CYCLE', '$.dependencies', `Task dependency cycle includes ${id}.`));
106
+ diagnostics.push(
107
+ diagnostic('E_TASK_GRAPH_CYCLE', '$.dependencies', `Task dependency cycle includes ${id}.`),
108
+ );
54
109
  return;
55
110
  }
56
111
  if (visited.has(id)) return;
57
112
  visiting.add(id);
58
113
  for (const dependency of byId.get(id)?.dependencies ?? []) {
59
- if (!byId.has(dependency.taskId)) diagnostics.push(diagnostic('E_TASK_DEPENDENCY_MISSING', '$.dependencies', `Unknown dependency ${dependency.taskId}.`));
114
+ if (!byId.has(dependency.taskId))
115
+ diagnostics.push(
116
+ diagnostic(
117
+ 'E_TASK_DEPENDENCY_MISSING',
118
+ '$.dependencies',
119
+ `Unknown dependency ${dependency.taskId}.`,
120
+ ),
121
+ );
60
122
  else visit(dependency.taskId);
61
123
  }
62
124
  visiting.delete(id);
@@ -66,6 +128,7 @@ export function validateTaskGraph(values) {
66
128
  return diagnostics;
67
129
  }
68
130
 
131
+ /** @returns {ReturnType<typeof import('./task-contracts.d.mts').countR2Tasks>} */
69
132
  export function countR2Tasks(values) {
70
133
  return values.reduce((count, value) => {
71
134
  try {
@@ -76,55 +139,133 @@ export function countR2Tasks(values) {
76
139
  }, 0);
77
140
  }
78
141
 
79
- export function validateTaskOutputSemantics(value, { taskManifest } = {}) {
142
+ /** @returns {ReturnType<typeof import('./task-contracts.d.mts').validateTaskOutputSemantics>} */
143
+ export function validateTaskOutputSemantics(value, options = {}) {
144
+ const { taskManifest } = /** @type {TaskOutputOptions} */ (options);
80
145
  const diagnostics = [];
81
146
  if (taskManifest) {
82
- if (value?.taskBinding?.taskManifestId !== taskManifest.taskManifestId
83
- || value?.taskBinding?.taskManifestDigest !== taskManifest.documentDigest) {
84
- diagnostics.push(diagnostic('E_TASK_OUTPUT_BINDING_MISMATCH', '$.taskBinding', 'Task output must bind the exact issued task manifest.'));
147
+ if (
148
+ value?.taskBinding?.taskManifestId !== taskManifest.taskManifestId ||
149
+ value?.taskBinding?.taskManifestDigest !== taskManifest.documentDigest
150
+ ) {
151
+ diagnostics.push(
152
+ diagnostic(
153
+ 'E_TASK_OUTPUT_BINDING_MISMATCH',
154
+ '$.taskBinding',
155
+ 'Task output must bind the exact issued task manifest.',
156
+ ),
157
+ );
85
158
  }
86
- if (value?.roleBinding?.roleId !== taskManifest.routing.roleId
87
- || value?.roleBinding?.roleVersion !== taskManifest.routing.roleVersion
88
- || value?.roleBinding?.registryDigest !== taskManifest.routing.roleRegistryDigest) {
89
- diagnostics.push(diagnostic('E_TASK_OUTPUT_ROLE_MISMATCH', '$.roleBinding', 'Task output role binding must equal issued routing.'));
159
+ if (
160
+ value?.roleBinding?.roleId !== taskManifest.routing.roleId ||
161
+ value?.roleBinding?.roleVersion !== taskManifest.routing.roleVersion ||
162
+ value?.roleBinding?.registryDigest !== taskManifest.routing.roleRegistryDigest
163
+ ) {
164
+ diagnostics.push(
165
+ diagnostic(
166
+ 'E_TASK_OUTPUT_ROLE_MISMATCH',
167
+ '$.roleBinding',
168
+ 'Task output role binding must equal issued routing.',
169
+ ),
170
+ );
90
171
  }
91
- const allowed = new Set([...taskManifest.scope.create, ...taskManifest.scope.modify].map(pathKey));
172
+ const allowed = new Set(
173
+ [...taskManifest.scope.create, ...taskManifest.scope.modify].map(pathKey),
174
+ );
92
175
  const preserved = new Map(taskManifest.scope.preserve.map((entry) => [pathKey(entry), entry]));
93
176
  for (const change of value?.changes ?? []) {
94
177
  const key = pathKey(change);
95
- if (!allowed.has(key)) diagnostics.push(diagnostic('E_TASK_OUTPUT_SCOPE_ESCAPE', '$.changes', `${key} is outside Create/Modify.`));
96
- if (preserved.has(key)) diagnostics.push(diagnostic('E_TASK_OUTPUT_PRESERVE_CHANGED', '$.changes', `${key} intersects Preserve.`));
178
+ if (!allowed.has(key))
179
+ diagnostics.push(
180
+ diagnostic('E_TASK_OUTPUT_SCOPE_ESCAPE', '$.changes', `${key} is outside Create/Modify.`),
181
+ );
182
+ if (preserved.has(key))
183
+ diagnostics.push(
184
+ diagnostic('E_TASK_OUTPUT_PRESERVE_CHANGED', '$.changes', `${key} intersects Preserve.`),
185
+ );
97
186
  }
98
- const verification = new Map((value?.preserveVerification ?? []).map((entry) => [pathKey(entry), entry]));
99
- if (verification.size !== preserved.size || [...preserved.keys()].some((key) => !verification.has(key))) {
100
- diagnostics.push(diagnostic('E_TASK_OUTPUT_PRESERVE_COVERAGE', '$.preserveVerification', 'Preserve verification must bijectively cover the issued Preserve set.'));
187
+ const verification = new Map(
188
+ (value?.preserveVerification ?? []).map((entry) => [pathKey(entry), entry]),
189
+ );
190
+ if (
191
+ verification.size !== preserved.size ||
192
+ [...preserved.keys()].some((key) => !verification.has(key))
193
+ ) {
194
+ diagnostics.push(
195
+ diagnostic(
196
+ 'E_TASK_OUTPUT_PRESERVE_COVERAGE',
197
+ '$.preserveVerification',
198
+ 'Preserve verification must bijectively cover the issued Preserve set.',
199
+ ),
200
+ );
101
201
  }
102
202
  for (const [key, entry] of verification) {
103
- if (!preserved.has(key) || entry.beforeDigest !== entry.afterDigest || entry.unchanged !== true) {
104
- diagnostics.push(diagnostic('E_TASK_OUTPUT_PRESERVE_CHANGED', '$.preserveVerification', `${key} is not digest-equal.`));
203
+ if (
204
+ !preserved.has(key) ||
205
+ entry.beforeDigest !== entry.afterDigest ||
206
+ entry.unchanged !== true
207
+ ) {
208
+ diagnostics.push(
209
+ diagnostic(
210
+ 'E_TASK_OUTPUT_PRESERVE_CHANGED',
211
+ '$.preserveVerification',
212
+ `${key} is not digest-equal.`,
213
+ ),
214
+ );
105
215
  }
106
216
  }
107
217
  }
108
218
  if (value?.roleBinding?.roleId === 'planr-qa' && (value?.changes?.length ?? 0) > 0) {
109
- diagnostics.push(diagnostic('E_TASK_OUTPUT_QA_WRITE', '$.changes', 'QA is read-only and cannot report changed files.'));
219
+ diagnostics.push(
220
+ diagnostic(
221
+ 'E_TASK_OUTPUT_QA_WRITE',
222
+ '$.changes',
223
+ 'QA is read-only and cannot report changed files.',
224
+ ),
225
+ );
110
226
  }
111
227
  if ((value?.externalEffects?.length ?? 0) > 0) {
112
- diagnostics.push(diagnostic('E_TASK_OUTPUT_EXTERNAL_EFFECT', '$.externalEffects', 'Protocol 1.5 task outputs permit no external effects.'));
228
+ diagnostics.push(
229
+ diagnostic(
230
+ 'E_TASK_OUTPUT_EXTERNAL_EFFECT',
231
+ '$.externalEffects',
232
+ 'Protocol 1.5 task outputs permit no external effects.',
233
+ ),
234
+ );
113
235
  }
114
236
  const failedCommand = (value?.commandEvidence ?? []).some(({ status }) => status === 'failed');
115
- const failedAcceptance = (value?.acceptanceEvidence ?? []).some(({ result }) => result !== 'passed');
237
+ const failedAcceptance = (value?.acceptanceEvidence ?? []).some(
238
+ ({ result }) => result !== 'passed',
239
+ );
116
240
  const errorDiagnostic = (value?.diagnostics ?? []).some(({ severity }) => severity === 'error');
117
- if (value?.outcome === 'completed' && (value.errorHandoff !== null || failedCommand || failedAcceptance || errorDiagnostic)) {
118
- diagnostics.push(diagnostic('E_TASK_OUTPUT_COMPLETED_INVALID', '$.outcome', 'Completed output cannot retain failed evidence, error diagnostics, or an error handoff.'));
241
+ if (
242
+ value?.outcome === 'completed' &&
243
+ (value.errorHandoff !== null || failedCommand || failedAcceptance || errorDiagnostic)
244
+ ) {
245
+ diagnostics.push(
246
+ diagnostic(
247
+ 'E_TASK_OUTPUT_COMPLETED_INVALID',
248
+ '$.outcome',
249
+ 'Completed output cannot retain failed evidence, error diagnostics, or an error handoff.',
250
+ ),
251
+ );
119
252
  }
120
253
  if (value?.outcome === 'blocked' && (!value.errorHandoff || !errorDiagnostic)) {
121
- diagnostics.push(diagnostic('E_TASK_OUTPUT_BLOCKED_HANDOFF_REQUIRED', '$.errorHandoff', 'Blocked output requires an error diagnostic and bound error handoff.'));
254
+ diagnostics.push(
255
+ diagnostic(
256
+ 'E_TASK_OUTPUT_BLOCKED_HANDOFF_REQUIRED',
257
+ '$.errorHandoff',
258
+ 'Blocked output requires an error diagnostic and bound error handoff.',
259
+ ),
260
+ );
122
261
  }
123
262
  return diagnostics;
124
263
  }
125
264
 
265
+ /** @type {typeof import('./task-contracts.d.mts').assertTaskOutputSemantics} */
126
266
  export function assertTaskOutputSemantics(value, options) {
127
267
  const diagnostics = validateTaskOutputSemantics(value, options);
128
- if (diagnostics.length) throw new ProtocolError(diagnostics[0].code, diagnostics[0].message, '', { diagnostics });
268
+ if (diagnostics.length)
269
+ throw new ProtocolError(diagnostics[0].code, diagnostics[0].message, '', { diagnostics });
129
270
  return value;
130
271
  }
@@ -1,16 +1,39 @@
1
- export interface WorkspaceCiphertext { iv: string; ciphertext: string }
2
- export interface WorkspacePublicKey { kty: 'EC'; crv: 'P-256'; x: string; y: string; ext?: boolean; key_ops?: ['verify'] }
1
+ export interface WorkspaceCiphertext {
2
+ iv: string;
3
+ ciphertext: string;
4
+ }
5
+ export interface WorkspacePublicKey {
6
+ kty: 'EC';
7
+ crv: 'P-256';
8
+ x: string;
9
+ y: string;
10
+ ext?: boolean;
11
+ key_ops?: ['verify'];
12
+ }
3
13
  export interface WorkspaceRevision extends WorkspaceCiphertext {
4
- id: string; epoch: number; reviewOf: string; createdAt: string; signature: string;
14
+ id: string;
15
+ epoch: number;
16
+ reviewOf: string;
17
+ createdAt: string;
18
+ signature: string;
5
19
  }
6
20
  export interface WorkspaceEvent extends WorkspaceCiphertext {
7
- id: string; revisionId: string; reviewOf: string; epoch: number;
8
- publicKey: WorkspacePublicKey; signature: string;
21
+ id: string;
22
+ revisionId: string;
23
+ reviewOf: string;
24
+ epoch: number;
25
+ publicKey: WorkspacePublicKey;
26
+ signature: string;
9
27
  }
10
28
  export interface DesignReviewWorkspace {
11
- schemaVersion: '1.0.0'; id: string; version: number; epoch: number;
12
- currentRevision: string; commentsPaused: boolean;
13
- ownerPublicKey: WorkspacePublicKey; keyring: WorkspaceCiphertext;
29
+ schemaVersion: '1.0.0';
30
+ id: string;
31
+ version: number;
32
+ epoch: number;
33
+ currentRevision: string;
34
+ commentsPaused: boolean;
35
+ ownerPublicKey: WorkspacePublicKey;
36
+ keyring: WorkspaceCiphertext;
14
37
  }
15
38
  export declare const DESIGN_WORKSPACE_VERSION: '1.0.0';
16
39
  export declare const DESIGN_WORKSPACE_API: '/api/v1/design-workspaces';
@@ -22,5 +45,10 @@ export declare const DESIGN_WORKSPACE_CREATE_SCHEMA: Readonly<Record<string, unk
22
45
  export declare const DESIGN_WORKSPACE_REVISION_SCHEMA: Readonly<Record<string, unknown>>;
23
46
  export declare const DESIGN_WORKSPACE_EVENT_SCHEMA: Readonly<Record<string, unknown>>;
24
47
  export declare const DESIGN_REVIEW_BUNDLE_SCHEMA: Readonly<Record<string, unknown>>;
25
- export declare const DESIGN_WORKSPACE_SCHEMAS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
26
- export declare function assertWorkspaceContract<T>(value: T, contract: Readonly<Record<string, unknown>>): T;
48
+ export declare const DESIGN_WORKSPACE_SCHEMAS: Readonly<
49
+ Record<string, Readonly<Record<string, unknown>>>
50
+ >;
51
+ export declare function assertWorkspaceContract<T>(
52
+ value: T,
53
+ contract: Readonly<Record<string, unknown>>,
54
+ ): T;
@@ -1,79 +1,193 @@
1
- import { validateJson } from './json-schema.mjs';
1
+ // @ts-check
2
2
  import { DESIGN_DOCUMENT_SCHEMA } from './design-contracts.mjs';
3
+ import { validateJson } from './json-schema.mjs';
3
4
 
5
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_VERSION} */
4
6
  export const DESIGN_WORKSPACE_VERSION = '1.0.0';
7
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_API} */
5
8
  export const DESIGN_WORKSPACE_API = '/api/v1/design-workspaces';
9
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_MAX_BYTES} */
6
10
  export const DESIGN_WORKSPACE_MAX_BYTES = 5 * 1024 * 1024;
11
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_MAX_EVENT_BYTES} */
7
12
  export const DESIGN_WORKSPACE_MAX_EVENT_BYTES = 256 * 1024;
13
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_ID_PATTERN} */
8
14
  export const DESIGN_WORKSPACE_ID_PATTERN = '^[A-Za-z0-9_-]{22,64}$';
9
15
  const id = { type: 'string', pattern: DESIGN_WORKSPACE_ID_PATTERN };
10
16
  const digest = { type: 'string', pattern: '^[a-f0-9]{64}$' };
11
17
  const b64 = { type: 'string', pattern: '^[A-Za-z0-9_-]+$' };
12
18
  const epoch = { type: 'integer', minimum: 1, maximum: 2147483647 };
13
- const cipherProperties = { iv: { ...b64, minLength: 16, maxLength: 16 }, ciphertext: { ...b64, minLength: 22, maxLength: Math.ceil(DESIGN_WORKSPACE_MAX_BYTES * 4 / 3) } };
19
+ const cipherProperties = {
20
+ iv: { ...b64, minLength: 16, maxLength: 16 },
21
+ ciphertext: { ...b64, minLength: 22, maxLength: Math.ceil((DESIGN_WORKSPACE_MAX_BYTES * 4) / 3) },
22
+ };
14
23
  const signature = { ...b64, minLength: 86, maxLength: 86 };
15
24
  const publicKey = {
16
- type: 'object', additionalProperties: false, required: ['kty', 'crv', 'x', 'y'],
17
- properties: { kty: { const: 'EC' }, crv: { const: 'P-256' }, x: { ...b64, minLength: 43, maxLength: 43 }, y: { ...b64, minLength: 43, maxLength: 43 }, ext: { type: 'boolean' }, key_ops: { type: 'array', items: { const: 'verify' }, maxItems: 1 } },
25
+ type: 'object',
26
+ additionalProperties: false,
27
+ required: ['kty', 'crv', 'x', 'y'],
28
+ properties: {
29
+ kty: { const: 'EC' },
30
+ crv: { const: 'P-256' },
31
+ x: { ...b64, minLength: 43, maxLength: 43 },
32
+ y: { ...b64, minLength: 43, maxLength: 43 },
33
+ ext: { type: 'boolean' },
34
+ key_ops: { type: 'array', items: { const: 'verify' }, maxItems: 1 },
35
+ },
18
36
  };
19
37
  const schema = (name, properties, required = Object.keys(properties)) => ({
20
38
  $schema: 'https://json-schema.org/draft/2020-12/schema',
21
39
  $id: `https://openplanr.dev/schemas/v1.9.0/${name}.schema.json`,
22
40
  'x-openplanr-contract': { id: name, version: '1.9.0' },
23
- type: 'object', additionalProperties: false, properties, required,
41
+ type: 'object',
42
+ additionalProperties: false,
43
+ properties,
44
+ required,
24
45
  });
25
46
 
47
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_REVISION_SCHEMA} */
26
48
  export const DESIGN_WORKSPACE_REVISION_SCHEMA = schema('design-workspace-revision', {
27
- id, epoch, reviewOf: digest, createdAt: { type: 'string', format: 'date-time' }, ...cipherProperties, signature,
49
+ id,
50
+ epoch,
51
+ reviewOf: digest,
52
+ createdAt: { type: 'string', format: 'date-time' },
53
+ ...cipherProperties,
54
+ signature,
28
55
  });
56
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_EVENT_SCHEMA} */
29
57
  export const DESIGN_WORKSPACE_EVENT_SCHEMA = schema('design-workspace-event', {
30
- id, revisionId: id, reviewOf: digest, epoch, ...cipherProperties, publicKey, signature,
58
+ id,
59
+ revisionId: id,
60
+ reviewOf: digest,
61
+ epoch,
62
+ ...cipherProperties,
63
+ publicKey,
64
+ signature,
31
65
  });
32
- const sealed = { type: 'object', additionalProperties: false, required: ['iv', 'ciphertext'], properties: cipherProperties };
66
+ const sealed = {
67
+ type: 'object',
68
+ additionalProperties: false,
69
+ required: ['iv', 'ciphertext'],
70
+ properties: cipherProperties,
71
+ };
72
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_CREATE_SCHEMA} */
33
73
  export const DESIGN_WORKSPACE_CREATE_SCHEMA = schema('design-workspace-create', {
34
- schemaVersion: { const: DESIGN_WORKSPACE_VERSION }, id, ownerPublicKey: publicKey,
35
- ownerAuthHash: digest, reviewerAuthHash: digest, epoch: { const: 1 }, keyring: sealed,
36
- revision: DESIGN_WORKSPACE_REVISION_SCHEMA, operationId: id, signature,
74
+ schemaVersion: { const: DESIGN_WORKSPACE_VERSION },
75
+ id,
76
+ ownerPublicKey: publicKey,
77
+ ownerAuthHash: digest,
78
+ reviewerAuthHash: digest,
79
+ epoch: { const: 1 },
80
+ keyring: sealed,
81
+ revision: DESIGN_WORKSPACE_REVISION_SCHEMA,
82
+ operationId: id,
83
+ signature,
37
84
  });
85
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_SCHEMA} */
38
86
  export const DESIGN_WORKSPACE_SCHEMA = schema('design-review-workspace', {
39
- schemaVersion: { const: DESIGN_WORKSPACE_VERSION }, id, version: epoch, epoch,
40
- currentRevision: id, commentsPaused: { type: 'boolean' }, ownerPublicKey: publicKey, keyring: sealed,
87
+ schemaVersion: { const: DESIGN_WORKSPACE_VERSION },
88
+ id,
89
+ version: epoch,
90
+ epoch,
91
+ currentRevision: id,
92
+ commentsPaused: { type: 'boolean' },
93
+ ownerPublicKey: publicKey,
94
+ keyring: sealed,
41
95
  });
42
96
 
43
97
  // An explicit presentation-only model. Authored paths, source provenance, and
44
98
  // design-system references are deliberately not part of a published workspace.
45
- const designProperties = structuredClone(DESIGN_DOCUMENT_SCHEMA.properties);
46
- for (const key of ['kind', 'schemaVersion', 'brief', 'assets', 'designSystem']) delete designProperties[key];
99
+ const designProperties =
100
+ /** @type {Record<string, { items: { properties: Record<string, unknown>; required: string[] } }>} */ (
101
+ structuredClone(DESIGN_DOCUMENT_SCHEMA.properties)
102
+ );
103
+ for (const key of ['kind', 'schemaVersion', 'brief', 'assets', 'designSystem'])
104
+ delete designProperties[key];
47
105
  delete designProperties.screens.items.properties.source;
48
106
  designProperties.screens.items.required = ['id', 'title'];
49
107
  delete designProperties.variants.items.properties.sources;
50
- export const DESIGN_REVIEW_BUNDLE_SCHEMA = schema('design-review-bundle', {
51
- kind: { const: 'openplanr-design-review-bundle' }, schemaVersion: { const: DESIGN_WORKSPACE_VERSION },
52
- design: { type: 'object', additionalProperties: false, properties: designProperties, required: ['id', 'title', 'frames', 'screens', 'screenOrder', 'variants', 'selectedVariant', 'defaultView'] },
53
- envelope: { type: 'object', required: ['schemaVersion', 'artifacts', 'viewer'] },
54
- entries: { type: 'array', minItems: 1, maxItems: 256, items: { type: 'object', additionalProperties: false, required: ['artifactId', 'screenId', 'variantId', 'frameId'], properties: Object.fromEntries(['artifactId', 'screenId', 'variantId', 'frameId'].map((key) => [key, { type: 'string', minLength: 1, maxLength: 128 }])) } },
55
- state: {
56
- type: ['object', 'null'], additionalProperties: false,
57
- properties: {
58
- positions: {
59
- type: 'object', additionalProperties: {
60
- type: 'object', additionalProperties: false, required: ['x', 'y'],
61
- properties: { x: { type: 'number', minimum: -1e7, maximum: 1e7 }, y: { type: 'number', minimum: -1e7, maximum: 1e7 } },
108
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_REVIEW_BUNDLE_SCHEMA} */
109
+ export const DESIGN_REVIEW_BUNDLE_SCHEMA = {
110
+ ...schema(
111
+ 'design-review-bundle',
112
+ {
113
+ kind: { const: 'openplanr-design-review-bundle' },
114
+ schemaVersion: { const: DESIGN_WORKSPACE_VERSION },
115
+ design: {
116
+ type: 'object',
117
+ additionalProperties: false,
118
+ properties: designProperties,
119
+ required: [
120
+ 'id',
121
+ 'title',
122
+ 'frames',
123
+ 'screens',
124
+ 'screenOrder',
125
+ 'variants',
126
+ 'selectedVariant',
127
+ 'defaultView',
128
+ ],
129
+ },
130
+ envelope: { type: 'object', required: ['schemaVersion', 'artifacts', 'viewer'] },
131
+ entries: {
132
+ type: 'array',
133
+ minItems: 1,
134
+ maxItems: 256,
135
+ items: {
136
+ type: 'object',
137
+ additionalProperties: false,
138
+ required: ['artifactId', 'screenId', 'variantId', 'frameId'],
139
+ properties: Object.fromEntries(
140
+ ['artifactId', 'screenId', 'variantId', 'frameId'].map((key) => [
141
+ key,
142
+ { type: 'string', minLength: 1, maxLength: 128 },
143
+ ]),
144
+ ),
62
145
  },
63
146
  },
147
+ state: {
148
+ type: ['object', 'null'],
149
+ additionalProperties: false,
150
+ properties: {
151
+ positions: {
152
+ type: 'object',
153
+ additionalProperties: {
154
+ type: 'object',
155
+ additionalProperties: false,
156
+ required: ['x', 'y'],
157
+ properties: {
158
+ x: { type: 'number', minimum: -1e7, maximum: 1e7 },
159
+ y: { type: 'number', minimum: -1e7, maximum: 1e7 },
160
+ },
161
+ },
162
+ },
163
+ },
164
+ },
165
+ revision: { type: 'string', minLength: 1, maxLength: 128 },
166
+ verification: {
167
+ type: ['object', 'null'],
168
+ additionalProperties: false,
169
+ properties: { status: { enum: ['verified', 'unverified', 'failed', 'pending'] } },
170
+ },
64
171
  },
65
- },
66
- revision: { type: 'string', minLength: 1, maxLength: 128 },
67
- verification: { type: ['object', 'null'], additionalProperties: false, properties: { status: { enum: ['verified', 'unverified', 'failed', 'pending'] } } },
68
- }, ['kind', 'schemaVersion', 'design', 'envelope', 'entries', 'revision']);
69
- DESIGN_REVIEW_BUNDLE_SCHEMA.$defs = structuredClone(DESIGN_DOCUMENT_SCHEMA.$defs);
172
+ ['kind', 'schemaVersion', 'design', 'envelope', 'entries', 'revision'],
173
+ ),
174
+ $defs: structuredClone(DESIGN_DOCUMENT_SCHEMA.$defs),
175
+ };
70
176
 
177
+ /** @returns {ReturnType<typeof import('./workspace-contracts.d.mts').assertWorkspaceContract>} */
71
178
  export function assertWorkspaceContract(value, contract) {
72
179
  const errors = validateJson(value, contract);
73
- if (errors.length) throw new TypeError(`Invalid ${contract['x-openplanr-contract'].id}: ${errors.slice(0, 5).map(({ path, detail }) => `${path}: ${detail}`).join('; ')}`);
180
+ if (errors.length)
181
+ throw new TypeError(
182
+ `Invalid ${contract['x-openplanr-contract'].id}: ${errors
183
+ .slice(0, 5)
184
+ .map(({ path, detail }) => `${path}: ${detail}`)
185
+ .join('; ')}`,
186
+ );
74
187
  return value;
75
188
  }
76
189
 
190
+ /** @type {typeof import('./workspace-contracts.d.mts').DESIGN_WORKSPACE_SCHEMAS} */
77
191
  export const DESIGN_WORKSPACE_SCHEMAS = Object.freeze({
78
192
  'design-review-workspace': DESIGN_WORKSPACE_SCHEMA,
79
193
  'design-workspace-create': DESIGN_WORKSPACE_CREATE_SCHEMA,