@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.
- package/lib/dashboard/closed-json-contract.mjs +99 -109
- package/lib/dashboard/operate-experience-audit-display-contract.d.mts +128 -153
- package/lib/dashboard/operate-experience-audit-display-contract.mjs +530 -585
- package/lib/dashboard/operate-experience-display-contract.d.mts +415 -437
- package/lib/dashboard/operate-experience-display-contract.mjs +768 -831
- package/lib/dashboard/operate-experience-surface-contract.d.mts +143 -148
- package/lib/dashboard/operate-experience-surface-contract.mjs +72 -73
- package/lib/dashboard/operate-review-contract.d.mts +7 -14
- package/lib/dashboard/operate-review-contract.mjs +46 -42
- package/lib/dashboard/operate-review-display-workspace-contract.d.mts +2 -5
- package/lib/dashboard/operate-review-display-workspace-contract.mjs +158 -104
- package/lib/dashboard/operate-review-payload-safety.mjs +4 -2
- package/lib/dashboard/operate-review-workspace-projection-v2.d.mts +47 -33
- package/lib/protocol/index.d.ts +2647 -543
- package/package.json +1 -1
- package/registries/commands.json +3 -3
- package/registries/skills.json +5 -5
- package/src/browser-contracts.d.mts +4 -1
- package/src/browser-contracts.mjs +16 -5
- package/src/canonical-json.d.mts +3 -1
- package/src/canonical-json.mjs +57 -20
- package/src/compat/live-evidence-v2.mjs +1604 -485
- package/src/compat/operate-experience-live-patch.mjs +67 -15
- package/src/compat/operating-planning-contracts.mjs +183 -51
- package/src/contracts.d.mts +54 -13
- package/src/contracts.mjs +625 -335
- package/src/design-contracts.mjs +58 -21
- package/src/design-handoff-contracts.d.mts +67 -11
- package/src/design-handoff-contracts.mjs +243 -98
- package/src/design-publication-contracts.mjs +98 -33
- package/src/diagram-authoring-contracts.d.mts +422 -78
- package/src/diagram-authoring-contracts.mjs +1697 -326
- package/src/diagram-contracts.d.mts +4 -1
- package/src/diagram-contracts.mjs +16 -4
- package/src/enterprise-contracts.d.mts +211 -46
- package/src/enterprise-contracts.mjs +727 -175
- package/src/errors.mjs +4 -0
- package/src/generated/canonical-registries.mjs +8 -8
- package/src/index.d.mts +8 -8
- package/src/index.mjs +36 -20
- package/src/json-schema.d.mts +21 -6
- package/src/json-schema.mjs +66 -18
- package/src/planning-contracts.d.mts +8 -2
- package/src/planning-contracts.mjs +33 -7
- package/src/registries.d.mts +11 -3
- package/src/registries.mjs +369 -87
- package/src/review-experience-contracts.d.mts +7 -2
- package/src/review-experience-contracts.mjs +198 -49
- package/src/semver.mjs +5 -1
- package/src/skill-source-contracts.d.mts +36 -16
- package/src/skill-source-contracts.mjs +25 -6
- package/src/task-contracts.d.mts +13 -3
- package/src/task-contracts.mjs +181 -40
- package/src/workspace-contracts.d.mts +38 -10
- 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 = {
|
|
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',
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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({
|
|
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
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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: {
|
|
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: {
|
|
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: {
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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))
|
|
218
|
-
|
|
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 (
|
|
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
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
&&
|
|
237
|
-
|
|
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 =
|
|
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)
|
|
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)
|
|
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))
|
|
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)
|
|
269
|
-
|
|
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)))
|
|
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(
|
|
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)
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
if (
|
|
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)))
|
|
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))
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
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(
|
|
327
|
-
|
|
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')
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
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
|
}
|