@openplanr/protocol 0.6.1 → 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 +3 -3
  17. package/registries/skills.json +5 -5
  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 +625 -335
  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 +8 -8
  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,10 +1,15 @@
1
+ // @ts-check
1
2
  import { canonicalizeJson, sha256Hex } from './canonical-json.mjs';
2
3
  import { validateJson } from './json-schema.mjs';
3
4
 
5
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_PROTOCOL_VERSION} */
4
6
  export const DESIGN_HANDOFF_PROTOCOL_VERSION = '1.11.0';
7
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_CONTRACT_VERSION} */
5
8
  export const DESIGN_HANDOFF_CONTRACT_VERSION = '1.0.0';
9
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_AUTHORITY} */
6
10
  export const DESIGN_HANDOFF_AUTHORITY = 'prepare-plan';
7
11
 
12
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_CHECK_IDS} */
8
13
  export const DESIGN_HANDOFF_CHECK_IDS = Object.freeze([
9
14
  'current-revision',
10
15
  'selected-direction',
@@ -16,6 +21,7 @@ export const DESIGN_HANDOFF_CHECK_IDS = Object.freeze([
16
21
  'approved-review-handoff',
17
22
  ]);
18
23
 
24
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_SOURCE_KINDS} */
19
25
  export const DESIGN_HANDOFF_SOURCE_KINDS = Object.freeze([
20
26
  'design-revision',
21
27
  'selected-direction',
@@ -35,6 +41,7 @@ export const DESIGN_HANDOFF_SOURCE_KINDS = Object.freeze([
35
41
  'element-anchor',
36
42
  ]);
37
43
 
44
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_REQUIREMENT_KINDS} */
38
45
  export const DESIGN_HANDOFF_REQUIREMENT_KINDS = Object.freeze([
39
46
  'behavior',
40
47
  'visual-state',
@@ -45,6 +52,7 @@ export const DESIGN_HANDOFF_REQUIREMENT_KINDS = Object.freeze([
45
52
  'verification-intent',
46
53
  ]);
47
54
 
55
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_CONTRACT_FILES} */
48
56
  export const DESIGN_HANDOFF_CONTRACT_FILES = Object.freeze({
49
57
  'design-handoff-readiness': 'design-handoff-readiness.schema.json',
50
58
  'design-implementation-handoff': 'design-implementation-handoff.schema.json',
@@ -53,13 +61,21 @@ export const DESIGN_HANDOFF_CONTRACT_FILES = Object.freeze({
53
61
 
54
62
  const text = { type: 'string', minLength: 1, maxLength: 16384 };
55
63
  const title = { ...text, maxLength: 240 };
56
- const id = { type: 'string', minLength: 1, maxLength: 160, pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]*$' };
64
+ const id = {
65
+ type: 'string',
66
+ minLength: 1,
67
+ maxLength: 160,
68
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]*$',
69
+ };
57
70
  const digest = { type: 'string', pattern: '^sha256:[a-f0-9]{64}$' };
58
71
  const relativePath = { type: 'string', minLength: 1, maxLength: 4096 };
59
72
  const timestamp = { type: 'string', format: 'date-time' };
60
73
  const list = (items, maxItems = 1000) => ({ type: 'array', items, maxItems });
61
74
  const closed = (properties, required = Object.keys(properties)) => ({
62
- type: 'object', additionalProperties: false, properties, required,
75
+ type: 'object',
76
+ additionalProperties: false,
77
+ properties,
78
+ required,
63
79
  });
64
80
  const contract = (name, body) => ({
65
81
  $schema: 'https://json-schema.org/draft/2020-12/schema',
@@ -77,22 +93,28 @@ const anchor = {
77
93
  closed({ reviewId: id, pinId: id }),
78
94
  ],
79
95
  };
80
- const evidenceReference = closed({
81
- id,
82
- kind: { enum: DESIGN_HANDOFF_SOURCE_KINDS },
83
- path: relativePath,
84
- revision: digest,
85
- digest,
86
- anchor,
87
- }, ['id', 'kind', 'path']);
96
+ const evidenceReference = closed(
97
+ {
98
+ id,
99
+ kind: { enum: DESIGN_HANDOFF_SOURCE_KINDS },
100
+ path: relativePath,
101
+ revision: digest,
102
+ digest,
103
+ anchor,
104
+ },
105
+ ['id', 'kind', 'path'],
106
+ );
88
107
 
89
- const readinessCheck = closed({
90
- id: { enum: DESIGN_HANDOFF_CHECK_IDS },
91
- status: { enum: ['pass', 'attention', 'blocked', 'stale'] },
92
- message: title,
93
- evidenceRefs: list(id, 64),
94
- recoveryAction: action,
95
- }, ['id', 'status', 'message', 'evidenceRefs']);
108
+ const readinessCheck = closed(
109
+ {
110
+ id: { enum: DESIGN_HANDOFF_CHECK_IDS },
111
+ status: { enum: ['pass', 'attention', 'blocked', 'stale'] },
112
+ message: title,
113
+ evidenceRefs: list(id, 64),
114
+ recoveryAction: action,
115
+ },
116
+ ['id', 'status', 'message', 'evidenceRefs'],
117
+ );
96
118
 
97
119
  const readinessRecord = closed({
98
120
  kind: { const: 'openplanr-design-handoff-readiness' },
@@ -103,7 +125,10 @@ const readinessRecord = closed({
103
125
  sourceRevision: { anyOf: [digest, { type: 'null' }] },
104
126
  selectedVariant: { anyOf: [id, { type: 'null' }] },
105
127
  status: { enum: ['ready', 'attention', 'blocked', 'stale'] },
106
- continuation: closed({ action: { const: DESIGN_HANDOFF_AUTHORITY }, available: { type: 'boolean' } }),
128
+ continuation: closed({
129
+ action: { const: DESIGN_HANDOFF_AUTHORITY },
130
+ available: { type: 'boolean' },
131
+ }),
107
132
  checks: list(readinessCheck, DESIGN_HANDOFF_CHECK_IDS.length),
108
133
  evidence: list(evidenceReference, 10000),
109
134
  blockers: list({ enum: DESIGN_HANDOFF_CHECK_IDS }, DESIGN_HANDOFF_CHECK_IDS.length),
@@ -119,6 +144,7 @@ const readinessAbsence = closed({
119
144
  nextAction: action,
120
145
  });
121
146
 
147
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_READINESS_SCHEMA} */
122
148
  export const DESIGN_HANDOFF_READINESS_SCHEMA = contract('design-handoff-readiness', {
123
149
  oneOf: [readinessRecord, readinessAbsence],
124
150
  });
@@ -131,34 +157,58 @@ const requirement = closed({
131
157
  verification: { ...list(text, 256), minItems: 1 },
132
158
  });
133
159
 
134
- const implementationHandoff = closed({
135
- kind: { const: 'openplanr-design-implementation-handoff' },
136
- schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
137
- id,
138
- version: { type: 'integer', minimum: 1 },
139
- status: { enum: ['draft', 'approved', 'superseded', 'revoked'] },
140
- authority: { const: DESIGN_HANDOFF_AUTHORITY },
141
- title,
142
- basis: closed({
143
- designId: id,
144
- sourceRevision: digest,
145
- selectedVariant: id,
146
- readiness: closed({ status: { enum: ['ready', 'attention', 'blocked', 'stale'] }, digest }),
147
- reviewHandoff: closed({ version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
148
- }),
149
- sources: list(evidenceReference, 10000),
150
- requirements: { ...list(requirement, 10000), minItems: 1 },
151
- contentDigest: digest,
152
- markdown: { type: 'string', maxLength: 2097152 },
153
- approval: closed({ actorId: id, approvedAt: timestamp, contentDigest: digest, authority: { const: DESIGN_HANDOFF_AUTHORITY } }),
154
- supersededBy: closed({ id, version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
155
- revocation: closed({ actorId: id, revokedAt: timestamp, reason: text }),
156
- }, ['kind', 'schemaVersion', 'id', 'version', 'status', 'authority', 'title', 'basis', 'sources', 'requirements', 'contentDigest', 'markdown']);
160
+ const implementationHandoff = closed(
161
+ {
162
+ kind: { const: 'openplanr-design-implementation-handoff' },
163
+ schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
164
+ id,
165
+ version: { type: 'integer', minimum: 1 },
166
+ status: { enum: ['draft', 'approved', 'superseded', 'revoked'] },
167
+ authority: { const: DESIGN_HANDOFF_AUTHORITY },
168
+ title,
169
+ basis: closed({
170
+ designId: id,
171
+ sourceRevision: digest,
172
+ selectedVariant: id,
173
+ readiness: closed({ status: { enum: ['ready', 'attention', 'blocked', 'stale'] }, digest }),
174
+ reviewHandoff: closed({ version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
175
+ }),
176
+ sources: list(evidenceReference, 10000),
177
+ requirements: { ...list(requirement, 10000), minItems: 1 },
178
+ contentDigest: digest,
179
+ markdown: { type: 'string', maxLength: 2097152 },
180
+ approval: closed({
181
+ actorId: id,
182
+ approvedAt: timestamp,
183
+ contentDigest: digest,
184
+ authority: { const: DESIGN_HANDOFF_AUTHORITY },
185
+ }),
186
+ supersededBy: closed({ id, version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
187
+ revocation: closed({ actorId: id, revokedAt: timestamp, reason: text }),
188
+ },
189
+ [
190
+ 'kind',
191
+ 'schemaVersion',
192
+ 'id',
193
+ 'version',
194
+ 'status',
195
+ 'authority',
196
+ 'title',
197
+ 'basis',
198
+ 'sources',
199
+ 'requirements',
200
+ 'contentDigest',
201
+ 'markdown',
202
+ ],
203
+ );
157
204
 
158
205
  implementationHandoff.allOf = [
159
206
  {
160
207
  if: { properties: { status: { const: 'approved' } }, required: ['status'] },
161
- then: { required: ['approval'], not: { anyOf: [{ required: ['supersededBy'] }, { required: ['revocation'] }] } },
208
+ then: {
209
+ required: ['approval'],
210
+ not: { anyOf: [{ required: ['supersededBy'] }, { required: ['revocation'] }] },
211
+ },
162
212
  },
163
213
  {
164
214
  if: { properties: { status: { const: 'superseded' } }, required: ['status'] },
@@ -170,10 +220,19 @@ implementationHandoff.allOf = [
170
220
  },
171
221
  {
172
222
  if: { properties: { status: { const: 'draft' } }, required: ['status'] },
173
- then: { not: { anyOf: [{ required: ['approval'] }, { required: ['supersededBy'] }, { required: ['revocation'] }] } },
223
+ then: {
224
+ not: {
225
+ anyOf: [
226
+ { required: ['approval'] },
227
+ { required: ['supersededBy'] },
228
+ { required: ['revocation'] },
229
+ ],
230
+ },
231
+ },
174
232
  },
175
233
  ];
176
234
 
235
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA} */
177
236
  export const DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA = contract(
178
237
  'design-implementation-handoff',
179
238
  implementationHandoff,
@@ -181,21 +240,32 @@ export const DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA = contract(
181
240
 
182
241
  const lineageMapping = closed({
183
242
  requirementId: { type: 'string', pattern: '^REQ-[0-9]{3,}$' },
184
- acceptanceRefs: { ...list(closed({
185
- storyId: { type: 'string', pattern: '^US-[0-9]{3,}$' },
186
- acceptanceId: { type: 'string', pattern: '^AC-[0-9]{3,}$' },
187
- }), 256), minItems: 1 },
243
+ acceptanceRefs: {
244
+ ...list(
245
+ closed({
246
+ storyId: { type: 'string', pattern: '^US-[0-9]{3,}$' },
247
+ acceptanceId: { type: 'string', pattern: '^AC-[0-9]{3,}$' },
248
+ }),
249
+ 256,
250
+ ),
251
+ minItems: 1,
252
+ },
188
253
  taskIds: { ...list({ type: 'string', pattern: '^T-[0-9]{3,}$' }, 256), minItems: 1 },
189
254
  });
190
255
 
191
- export const DESIGN_PLANNING_LINEAGE_SCHEMA = contract('design-planning-lineage', closed({
192
- kind: { const: 'openplanr-design-planning-lineage' },
193
- schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
194
- handoff: closed({ id, version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
195
- specId: { type: 'string', pattern: '^SPEC-[0-9]{3,}$' },
196
- mappings: { ...list(lineageMapping, 10000), minItems: 1 },
197
- }));
256
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_PLANNING_LINEAGE_SCHEMA} */
257
+ export const DESIGN_PLANNING_LINEAGE_SCHEMA = contract(
258
+ 'design-planning-lineage',
259
+ closed({
260
+ kind: { const: 'openplanr-design-planning-lineage' },
261
+ schemaVersion: { const: DESIGN_HANDOFF_CONTRACT_VERSION },
262
+ handoff: closed({ id, version: { type: 'integer', minimum: 1 }, contentDigest: digest }),
263
+ specId: { type: 'string', pattern: '^SPEC-[0-9]{3,}$' },
264
+ mappings: { ...list(lineageMapping, 10000), minItems: 1 },
265
+ }),
266
+ );
198
267
 
268
+ /** @type {typeof import('./design-handoff-contracts.d.mts').DESIGN_HANDOFF_SCHEMAS} */
199
269
  export const DESIGN_HANDOFF_SCHEMAS = deepFreeze({
200
270
  'design-handoff-readiness': DESIGN_HANDOFF_READINESS_SCHEMA,
201
271
  'design-implementation-handoff': DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA,
@@ -214,11 +284,17 @@ function assertPlainData(value, depth = 0, seen = new Set()) {
214
284
  if (depth > 64) throw new TypeError('Design handoff data exceeds the maximum nesting depth.');
215
285
  if (value === null || ['string', 'boolean'].includes(typeof value)) return;
216
286
  if (typeof value === 'number' && Number.isFinite(value)) return;
217
- if (typeof value !== 'object' || seen.has(value)) throw new TypeError('Design handoff data must be finite, acyclic JSON.');
218
- if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError('Design handoff data must contain only plain JSON objects.');
287
+ if (typeof value !== 'object' || seen.has(value))
288
+ throw new TypeError('Design handoff data must be finite, acyclic JSON.');
289
+ if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
290
+ throw new TypeError('Design handoff data must contain only plain JSON objects.');
219
291
  seen.add(value);
220
292
  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
221
- if (['__proto__', 'prototype', 'constructor'].includes(key) || !Object.hasOwn(descriptor, 'value')) throw new TypeError('Design handoff data contains a forbidden property.');
293
+ if (
294
+ ['__proto__', 'prototype', 'constructor'].includes(key) ||
295
+ !Object.hasOwn(descriptor, 'value')
296
+ )
297
+ throw new TypeError('Design handoff data contains a forbidden property.');
222
298
  assertPlainData(descriptor.value, depth + 1, seen);
223
299
  }
224
300
  seen.delete(value);
@@ -229,33 +305,56 @@ function distinct(items, select, label) {
229
305
  if (new Set(values).size !== values.length) throw new TypeError(`Duplicate ${label}.`);
230
306
  }
231
307
 
308
+ /** @type {typeof import('./design-handoff-contracts.d.mts').isDesignHandoffRelativePath} */
232
309
  export function isDesignHandoffRelativePath(value) {
233
- return typeof value === 'string'
234
- && value.length > 0
235
- && value.length <= 4096
236
- && !/^(?:[A-Za-z]:|\/|[A-Za-z][A-Za-z0-9+.-]*:)|[\\?#%\u0000-\u001f\u007f]/u.test(value)
237
- && value.split('/').every(part => part && part !== '.' && part !== '..' && !['__proto__', 'prototype', 'constructor'].includes(part));
310
+ return (
311
+ typeof value === 'string' &&
312
+ value.length > 0 &&
313
+ value.length <= 4096 &&
314
+ !/^(?:[A-Za-z]:|\/|[A-Za-z][A-Za-z0-9+.-]*:)|[\\?#%\u0000-\u001f\u007f]/u.test(value) &&
315
+ value
316
+ .split('/')
317
+ .every(
318
+ (part) =>
319
+ part &&
320
+ part !== '.' &&
321
+ part !== '..' &&
322
+ !['__proto__', 'prototype', 'constructor'].includes(part),
323
+ )
324
+ );
238
325
  }
239
326
 
327
+ /** @returns {ReturnType<typeof import('./design-handoff-contracts.d.mts').assertDesignHandoffContract>} */
240
328
  export function assertDesignHandoffContract(value, schemaOrName) {
241
- const schema = typeof schemaOrName === 'string' ? DESIGN_HANDOFF_SCHEMAS[schemaOrName] : schemaOrName;
329
+ const schema =
330
+ typeof schemaOrName === 'string' ? DESIGN_HANDOFF_SCHEMAS[schemaOrName] : schemaOrName;
242
331
  if (!schema) throw new TypeError('Unknown design handoff contract.');
243
332
  assertPlainData(value);
244
333
  canonicalizeJson(value);
245
334
  const errors = validateJson(value, schema);
246
- if (errors.length) throw new TypeError(`Invalid ${schema['x-openplanr-contract']?.id ?? 'design handoff data'}: ${errors.slice(0, 5).map(error => `${error.path} (${error.rule})`).join('; ')}`);
335
+ if (errors.length)
336
+ throw new TypeError(
337
+ `Invalid ${schema['x-openplanr-contract']?.id ?? 'design handoff data'}: ${errors
338
+ .slice(0, 5)
339
+ .map((error) => `${error.path} (${error.rule})`)
340
+ .join('; ')}`,
341
+ );
247
342
  return value;
248
343
  }
249
344
 
250
345
  function assertEvidenceReferences(evidence) {
251
- distinct(evidence, item => item.id, 'evidence reference identity');
252
- for (const item of evidence) if (!isDesignHandoffRelativePath(item.path)) throw new TypeError('Design handoff evidence requires a repository-relative logical path.');
346
+ distinct(evidence, (item) => item.id, 'evidence reference identity');
347
+ for (const item of evidence)
348
+ if (!isDesignHandoffRelativePath(item.path))
349
+ throw new TypeError('Design handoff evidence requires a repository-relative logical path.');
253
350
  }
254
351
 
255
352
  function assertProductCopy(value) {
256
- if (/\b(?:hash|digest|checksum|sha[- ]?256|canonical(?:ize|ization)?)\b/iu.test(value)) throw new TypeError('Design readiness guidance must use product language.');
353
+ if (/\b(?:hash|digest|checksum|sha[- ]?256|canonical(?:ize|ization)?)\b/iu.test(value))
354
+ throw new TypeError('Design readiness guidance must use product language.');
257
355
  }
258
356
 
357
+ /** @returns {ReturnType<typeof import('./design-handoff-contracts.d.mts').assertDesignHandoffReadiness>} */
259
358
  export function assertDesignHandoffReadiness(value) {
260
359
  assertDesignHandoffContract(value, DESIGN_HANDOFF_READINESS_SCHEMA);
261
360
  if (value.kind.endsWith('-absence')) {
@@ -263,30 +362,45 @@ export function assertDesignHandoffReadiness(value) {
263
362
  return value;
264
363
  }
265
364
  assertEvidenceReferences(value.evidence);
266
- distinct(value.checks, item => item.id, 'readiness check identity');
365
+ distinct(value.checks, (item) => item.id, 'readiness check identity');
267
366
  const expected = DESIGN_HANDOFF_CHECK_IDS.join('\n');
268
- if (value.checks.map(item => item.id).join('\n') !== expected) throw new TypeError('Design readiness must contain every stable check in canonical order.');
269
- const evidenceIds = new Set(value.evidence.map(item => item.id));
367
+ if (value.checks.map((item) => item.id).join('\n') !== expected)
368
+ throw new TypeError('Design readiness must contain every stable check in canonical order.');
369
+ const evidenceIds = new Set(value.evidence.map((item) => item.id));
270
370
  for (const check of value.checks) {
271
- distinct(check.evidenceRefs, item => item, 'readiness evidence reference');
272
- if (check.evidenceRefs.some(reference => !evidenceIds.has(reference))) throw new TypeError('Design readiness references missing evidence.');
371
+ distinct(check.evidenceRefs, (item) => item, 'readiness evidence reference');
372
+ if (check.evidenceRefs.some((reference) => !evidenceIds.has(reference)))
373
+ throw new TypeError('Design readiness references missing evidence.');
273
374
  assertProductCopy(`${check.message} ${check.recoveryAction?.label ?? ''}`);
274
375
  }
275
376
  const priority = { pass: 0, attention: 1, blocked: 2, stale: 3 };
276
- const worst = value.checks.reduce((current, check) => priority[check.status] > priority[current] ? check.status : current, 'pass');
377
+ const worst = value.checks.reduce(
378
+ (current, check) => (priority[check.status] > priority[current] ? check.status : current),
379
+ 'pass',
380
+ );
277
381
  const expectedStatus = worst === 'pass' ? 'ready' : worst;
278
- if (value.status !== expectedStatus) throw new TypeError('Design readiness summary does not match its checks.');
279
- const blockingIds = value.checks.filter(check => ['blocked', 'stale'].includes(check.status)).map(check => check.id);
280
- if (value.blockers.join('\n') !== blockingIds.join('\n')) throw new TypeError('Design readiness blockers do not match its blocking checks.');
281
- const actionable = value.checks.filter(check => check.status !== 'pass');
282
- if (value.nextActions.length !== actionable.length || value.nextActions.some((actionValue, index) => {
283
- const recoveryAction = actionable[index].recoveryAction;
284
- return actionValue.id !== recoveryAction?.id || actionValue.label !== recoveryAction?.label;
285
- })) throw new TypeError('Design readiness next actions do not match its checks.');
286
- if (value.continuation.available !== ['ready', 'attention'].includes(value.status)) throw new TypeError('Design readiness continuation availability does not match its status.');
382
+ if (value.status !== expectedStatus)
383
+ throw new TypeError('Design readiness summary does not match its checks.');
384
+ const blockingIds = value.checks
385
+ .filter((check) => ['blocked', 'stale'].includes(check.status))
386
+ .map((check) => check.id);
387
+ if (value.blockers.join('\n') !== blockingIds.join('\n'))
388
+ throw new TypeError('Design readiness blockers do not match its blocking checks.');
389
+ const actionable = value.checks.filter((check) => check.status !== 'pass');
390
+ if (
391
+ value.nextActions.length !== actionable.length ||
392
+ value.nextActions.some((actionValue, index) => {
393
+ const recoveryAction = actionable[index].recoveryAction;
394
+ return actionValue.id !== recoveryAction?.id || actionValue.label !== recoveryAction?.label;
395
+ })
396
+ )
397
+ throw new TypeError('Design readiness next actions do not match its checks.');
398
+ if (value.continuation.available !== ['ready', 'attention'].includes(value.status))
399
+ throw new TypeError('Design readiness continuation availability does not match its status.');
287
400
  return value;
288
401
  }
289
402
 
403
+ /** @type {typeof import('./design-handoff-contracts.d.mts').designImplementationHandoffDigest} */
290
404
  export function designImplementationHandoffDigest(value) {
291
405
  const projection = {
292
406
  kind: value.kind,
@@ -303,36 +417,67 @@ export function designImplementationHandoffDigest(value) {
303
417
  return `sha256:${sha256Hex(canonicalizeJson(projection))}`;
304
418
  }
305
419
 
420
+ /** @type {typeof import('./design-handoff-contracts.d.mts').assertDesignImplementationHandoff} */
306
421
  export function assertDesignImplementationHandoff(value) {
307
422
  assertDesignHandoffContract(value, DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA);
308
423
  assertEvidenceReferences(value.sources);
309
- distinct(value.requirements, item => item.id, 'implementation requirement identity');
310
- const sourceIds = new Set(value.sources.map(item => item.id));
424
+ distinct(value.requirements, (item) => item.id, 'implementation requirement identity');
425
+ const sourceIds = new Set(value.sources.map((item) => item.id));
311
426
  for (const item of value.requirements) {
312
- distinct(item.sourceRefs, reference => reference, 'requirement source reference');
313
- if (item.sourceRefs.some(reference => !sourceIds.has(reference))) throw new TypeError('Implementation requirement references missing evidence.');
427
+ distinct(item.sourceRefs, (reference) => reference, 'requirement source reference');
428
+ if (item.sourceRefs.some((reference) => !sourceIds.has(reference)))
429
+ throw new TypeError('Implementation requirement references missing evidence.');
314
430
  }
315
- if (value.contentDigest !== designImplementationHandoffDigest(value)) throw new TypeError('Implementation handoff content does not match its recorded integrity value.');
316
- if (value.approval?.contentDigest !== undefined && value.approval.contentDigest !== value.contentDigest) throw new TypeError('Implementation handoff approval does not match its content.');
317
- if (value.status !== 'draft' && value.basis.readiness.status !== 'ready') throw new TypeError('Only a ready implementation handoff can be approved or retained as approved history.');
318
- if (value.supersededBy && value.supersededBy.id === value.id && value.supersededBy.version <= value.version) throw new TypeError('A superseding handoff must identify a newer package version.');
431
+ if (value.contentDigest !== designImplementationHandoffDigest(value))
432
+ throw new TypeError(
433
+ 'Implementation handoff content does not match its recorded integrity value.',
434
+ );
435
+ if (
436
+ value.approval?.contentDigest !== undefined &&
437
+ value.approval.contentDigest !== value.contentDigest
438
+ )
439
+ throw new TypeError('Implementation handoff approval does not match its content.');
440
+ if (value.status !== 'draft' && value.basis.readiness.status !== 'ready')
441
+ throw new TypeError(
442
+ 'Only a ready implementation handoff can be approved or retained as approved history.',
443
+ );
444
+ if (
445
+ value.supersededBy &&
446
+ value.supersededBy.id === value.id &&
447
+ value.supersededBy.version <= value.version
448
+ )
449
+ throw new TypeError('A superseding handoff must identify a newer package version.');
319
450
  return value;
320
451
  }
321
452
 
453
+ /** @type {typeof import('./design-handoff-contracts.d.mts').assertDesignPlanningLineage} */
322
454
  export function assertDesignPlanningLineage(value, handoff) {
323
455
  assertDesignHandoffContract(value, DESIGN_PLANNING_LINEAGE_SCHEMA);
324
- distinct(value.mappings, item => item.requirementId, 'lineage requirement identity');
456
+ distinct(value.mappings, (item) => item.requirementId, 'lineage requirement identity');
325
457
  for (const mapping of value.mappings) {
326
- distinct(mapping.acceptanceRefs, item => `${item.storyId}:${item.acceptanceId}`, 'lineage acceptance identity');
327
- distinct(mapping.taskIds, item => item, 'lineage task identity');
458
+ distinct(
459
+ mapping.acceptanceRefs,
460
+ (item) => `${item.storyId}:${item.acceptanceId}`,
461
+ 'lineage acceptance identity',
462
+ );
463
+ distinct(mapping.taskIds, (item) => item, 'lineage task identity');
328
464
  }
329
465
  if (handoff) {
330
466
  assertDesignImplementationHandoff(handoff);
331
- if (handoff.status !== 'approved') throw new TypeError('Planning lineage requires an approved handoff.');
332
- if (value.handoff.id !== handoff.id || value.handoff.version !== handoff.version || value.handoff.contentDigest !== handoff.contentDigest) throw new TypeError('Planning lineage identifies a different handoff package.');
333
- const expected = handoff.requirements.map(item => item.id).sort();
334
- const actual = value.mappings.map(item => item.requirementId).sort();
335
- if (actual.join('\n') !== expected.join('\n')) throw new TypeError('Planning lineage must map every implementation requirement exactly once.');
467
+ if (handoff.status !== 'approved')
468
+ throw new TypeError('Planning lineage requires an approved handoff.');
469
+ if (
470
+ value.handoff.id !== handoff.id ||
471
+ value.handoff.version !== handoff.version ||
472
+ value.handoff.contentDigest !== handoff.contentDigest
473
+ )
474
+ throw new TypeError('Planning lineage identifies a different handoff package.');
475
+ const expected = handoff.requirements.map((item) => item.id).sort();
476
+ const actual = value.mappings.map((item) => item.requirementId).sort();
477
+ if (actual.join('\n') !== expected.join('\n'))
478
+ throw new TypeError(
479
+ 'Planning lineage must map every implementation requirement exactly once.',
480
+ );
336
481
  }
337
482
  return value;
338
483
  }