@openplanr/protocol 0.6.1 → 0.7.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.
- package/README.md +10 -0
- 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 +777 -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/artifact-theme.json +64 -0
- package/registries/commands.json +40 -40
- package/registries/skills.json +5 -5
- package/schemas/v1.14.0/artifact-theme.schema.json +316 -0
- package/src/browser-contracts.d.mts +4 -1
- package/src/browser-contracts.mjs +16 -5
- package/src/canonical-json.d.mts +6 -1
- package/src/canonical-json.mjs +100 -22
- package/src/compat/live-evidence-v2.mjs +1611 -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 +635 -343
- package/src/design-contracts.mjs +58 -21
- package/src/design-handoff-contracts.d.mts +67 -11
- package/src/design-handoff-contracts.mjs +236 -119
- package/src/design-publication-contracts.mjs +98 -33
- package/src/diagram-authoring-contracts.d.mts +422 -78
- package/src/diagram-authoring-contracts.mjs +1715 -335
- 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 +738 -184
- package/src/errors.mjs +4 -0
- package/src/generated/canonical-registries.mjs +45 -45
- 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
|
-
|
|
1
|
+
// @ts-check
|
|
2
|
+
import { assertPlainData, canonicalizeJson, deepFreeze, 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,81 +240,93 @@ 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,
|
|
202
272
|
'design-planning-lineage': DESIGN_PLANNING_LINEAGE_SCHEMA,
|
|
203
273
|
});
|
|
204
274
|
|
|
205
|
-
function deepFreeze(value) {
|
|
206
|
-
if (value && typeof value === 'object' && !Object.isFrozen(value)) {
|
|
207
|
-
for (const nested of Object.values(value)) deepFreeze(nested);
|
|
208
|
-
Object.freeze(value);
|
|
209
|
-
}
|
|
210
|
-
return value;
|
|
211
|
-
}
|
|
212
|
-
|
|
213
|
-
function assertPlainData(value, depth = 0, seen = new Set()) {
|
|
214
|
-
if (depth > 64) throw new TypeError('Design handoff data exceeds the maximum nesting depth.');
|
|
215
|
-
if (value === null || ['string', 'boolean'].includes(typeof value)) return;
|
|
216
|
-
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.');
|
|
219
|
-
seen.add(value);
|
|
220
|
-
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.');
|
|
222
|
-
assertPlainData(descriptor.value, depth + 1, seen);
|
|
223
|
-
}
|
|
224
|
-
seen.delete(value);
|
|
225
|
-
}
|
|
226
|
-
|
|
227
275
|
function distinct(items, select, label) {
|
|
228
276
|
const values = items.map(select);
|
|
229
277
|
if (new Set(values).size !== values.length) throw new TypeError(`Duplicate ${label}.`);
|
|
230
278
|
}
|
|
231
279
|
|
|
280
|
+
/** @type {typeof import('./design-handoff-contracts.d.mts').isDesignHandoffRelativePath} */
|
|
232
281
|
export function isDesignHandoffRelativePath(value) {
|
|
233
|
-
return
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
&&
|
|
237
|
-
|
|
282
|
+
return (
|
|
283
|
+
typeof value === 'string' &&
|
|
284
|
+
value.length > 0 &&
|
|
285
|
+
value.length <= 4096 &&
|
|
286
|
+
!/^(?:[A-Za-z]:|\/|[A-Za-z][A-Za-z0-9+.-]*:)|[\\?#%\u0000-\u001f\u007f]/u.test(value) &&
|
|
287
|
+
value
|
|
288
|
+
.split('/')
|
|
289
|
+
.every(
|
|
290
|
+
(part) =>
|
|
291
|
+
part &&
|
|
292
|
+
part !== '.' &&
|
|
293
|
+
part !== '..' &&
|
|
294
|
+
!['__proto__', 'prototype', 'constructor'].includes(part),
|
|
295
|
+
)
|
|
296
|
+
);
|
|
238
297
|
}
|
|
239
298
|
|
|
299
|
+
/** @returns {ReturnType<typeof import('./design-handoff-contracts.d.mts').assertDesignHandoffContract>} */
|
|
240
300
|
export function assertDesignHandoffContract(value, schemaOrName) {
|
|
241
|
-
const schema =
|
|
301
|
+
const schema =
|
|
302
|
+
typeof schemaOrName === 'string' ? DESIGN_HANDOFF_SCHEMAS[schemaOrName] : schemaOrName;
|
|
242
303
|
if (!schema) throw new TypeError('Unknown design handoff contract.');
|
|
243
|
-
assertPlainData(value);
|
|
304
|
+
assertPlainData(value, 'Design handoff data');
|
|
244
305
|
canonicalizeJson(value);
|
|
245
306
|
const errors = validateJson(value, schema);
|
|
246
|
-
if (errors.length)
|
|
307
|
+
if (errors.length)
|
|
308
|
+
throw new TypeError(
|
|
309
|
+
`Invalid ${schema['x-openplanr-contract']?.id ?? 'design handoff data'}: ${errors
|
|
310
|
+
.slice(0, 5)
|
|
311
|
+
.map((error) => `${error.path} (${error.rule})`)
|
|
312
|
+
.join('; ')}`,
|
|
313
|
+
);
|
|
247
314
|
return value;
|
|
248
315
|
}
|
|
249
316
|
|
|
250
317
|
function assertEvidenceReferences(evidence) {
|
|
251
|
-
distinct(evidence, item => item.id, 'evidence reference identity');
|
|
252
|
-
for (const item of evidence)
|
|
318
|
+
distinct(evidence, (item) => item.id, 'evidence reference identity');
|
|
319
|
+
for (const item of evidence)
|
|
320
|
+
if (!isDesignHandoffRelativePath(item.path))
|
|
321
|
+
throw new TypeError('Design handoff evidence requires a repository-relative logical path.');
|
|
253
322
|
}
|
|
254
323
|
|
|
255
324
|
function assertProductCopy(value) {
|
|
256
|
-
if (/\b(?:hash|digest|checksum|sha[- ]?256|canonical(?:ize|ization)?)\b/iu.test(value))
|
|
325
|
+
if (/\b(?:hash|digest|checksum|sha[- ]?256|canonical(?:ize|ization)?)\b/iu.test(value))
|
|
326
|
+
throw new TypeError('Design readiness guidance must use product language.');
|
|
257
327
|
}
|
|
258
328
|
|
|
329
|
+
/** @returns {ReturnType<typeof import('./design-handoff-contracts.d.mts').assertDesignHandoffReadiness>} */
|
|
259
330
|
export function assertDesignHandoffReadiness(value) {
|
|
260
331
|
assertDesignHandoffContract(value, DESIGN_HANDOFF_READINESS_SCHEMA);
|
|
261
332
|
if (value.kind.endsWith('-absence')) {
|
|
@@ -263,30 +334,45 @@ export function assertDesignHandoffReadiness(value) {
|
|
|
263
334
|
return value;
|
|
264
335
|
}
|
|
265
336
|
assertEvidenceReferences(value.evidence);
|
|
266
|
-
distinct(value.checks, item => item.id, 'readiness check identity');
|
|
337
|
+
distinct(value.checks, (item) => item.id, 'readiness check identity');
|
|
267
338
|
const expected = DESIGN_HANDOFF_CHECK_IDS.join('\n');
|
|
268
|
-
if (value.checks.map(item => item.id).join('\n') !== expected)
|
|
269
|
-
|
|
339
|
+
if (value.checks.map((item) => item.id).join('\n') !== expected)
|
|
340
|
+
throw new TypeError('Design readiness must contain every stable check in canonical order.');
|
|
341
|
+
const evidenceIds = new Set(value.evidence.map((item) => item.id));
|
|
270
342
|
for (const check of value.checks) {
|
|
271
|
-
distinct(check.evidenceRefs, item => item, 'readiness evidence reference');
|
|
272
|
-
if (check.evidenceRefs.some(reference => !evidenceIds.has(reference)))
|
|
343
|
+
distinct(check.evidenceRefs, (item) => item, 'readiness evidence reference');
|
|
344
|
+
if (check.evidenceRefs.some((reference) => !evidenceIds.has(reference)))
|
|
345
|
+
throw new TypeError('Design readiness references missing evidence.');
|
|
273
346
|
assertProductCopy(`${check.message} ${check.recoveryAction?.label ?? ''}`);
|
|
274
347
|
}
|
|
275
348
|
const priority = { pass: 0, attention: 1, blocked: 2, stale: 3 };
|
|
276
|
-
const worst = value.checks.reduce(
|
|
349
|
+
const worst = value.checks.reduce(
|
|
350
|
+
(current, check) => (priority[check.status] > priority[current] ? check.status : current),
|
|
351
|
+
'pass',
|
|
352
|
+
);
|
|
277
353
|
const expectedStatus = worst === 'pass' ? 'ready' : worst;
|
|
278
|
-
if (value.status !== expectedStatus)
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
if (
|
|
354
|
+
if (value.status !== expectedStatus)
|
|
355
|
+
throw new TypeError('Design readiness summary does not match its checks.');
|
|
356
|
+
const blockingIds = value.checks
|
|
357
|
+
.filter((check) => ['blocked', 'stale'].includes(check.status))
|
|
358
|
+
.map((check) => check.id);
|
|
359
|
+
if (value.blockers.join('\n') !== blockingIds.join('\n'))
|
|
360
|
+
throw new TypeError('Design readiness blockers do not match its blocking checks.');
|
|
361
|
+
const actionable = value.checks.filter((check) => check.status !== 'pass');
|
|
362
|
+
if (
|
|
363
|
+
value.nextActions.length !== actionable.length ||
|
|
364
|
+
value.nextActions.some((actionValue, index) => {
|
|
365
|
+
const recoveryAction = actionable[index].recoveryAction;
|
|
366
|
+
return actionValue.id !== recoveryAction?.id || actionValue.label !== recoveryAction?.label;
|
|
367
|
+
})
|
|
368
|
+
)
|
|
369
|
+
throw new TypeError('Design readiness next actions do not match its checks.');
|
|
370
|
+
if (value.continuation.available !== ['ready', 'attention'].includes(value.status))
|
|
371
|
+
throw new TypeError('Design readiness continuation availability does not match its status.');
|
|
287
372
|
return value;
|
|
288
373
|
}
|
|
289
374
|
|
|
375
|
+
/** @type {typeof import('./design-handoff-contracts.d.mts').designImplementationHandoffDigest} */
|
|
290
376
|
export function designImplementationHandoffDigest(value) {
|
|
291
377
|
const projection = {
|
|
292
378
|
kind: value.kind,
|
|
@@ -303,36 +389,67 @@ export function designImplementationHandoffDigest(value) {
|
|
|
303
389
|
return `sha256:${sha256Hex(canonicalizeJson(projection))}`;
|
|
304
390
|
}
|
|
305
391
|
|
|
392
|
+
/** @type {typeof import('./design-handoff-contracts.d.mts').assertDesignImplementationHandoff} */
|
|
306
393
|
export function assertDesignImplementationHandoff(value) {
|
|
307
394
|
assertDesignHandoffContract(value, DESIGN_IMPLEMENTATION_HANDOFF_SCHEMA);
|
|
308
395
|
assertEvidenceReferences(value.sources);
|
|
309
|
-
distinct(value.requirements, item => item.id, 'implementation requirement identity');
|
|
310
|
-
const sourceIds = new Set(value.sources.map(item => item.id));
|
|
396
|
+
distinct(value.requirements, (item) => item.id, 'implementation requirement identity');
|
|
397
|
+
const sourceIds = new Set(value.sources.map((item) => item.id));
|
|
311
398
|
for (const item of value.requirements) {
|
|
312
|
-
distinct(item.sourceRefs, reference => reference, 'requirement source reference');
|
|
313
|
-
if (item.sourceRefs.some(reference => !sourceIds.has(reference)))
|
|
399
|
+
distinct(item.sourceRefs, (reference) => reference, 'requirement source reference');
|
|
400
|
+
if (item.sourceRefs.some((reference) => !sourceIds.has(reference)))
|
|
401
|
+
throw new TypeError('Implementation requirement references missing evidence.');
|
|
314
402
|
}
|
|
315
|
-
if (value.contentDigest !== designImplementationHandoffDigest(value))
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
403
|
+
if (value.contentDigest !== designImplementationHandoffDigest(value))
|
|
404
|
+
throw new TypeError(
|
|
405
|
+
'Implementation handoff content does not match its recorded integrity value.',
|
|
406
|
+
);
|
|
407
|
+
if (
|
|
408
|
+
value.approval?.contentDigest !== undefined &&
|
|
409
|
+
value.approval.contentDigest !== value.contentDigest
|
|
410
|
+
)
|
|
411
|
+
throw new TypeError('Implementation handoff approval does not match its content.');
|
|
412
|
+
if (value.status !== 'draft' && value.basis.readiness.status !== 'ready')
|
|
413
|
+
throw new TypeError(
|
|
414
|
+
'Only a ready implementation handoff can be approved or retained as approved history.',
|
|
415
|
+
);
|
|
416
|
+
if (
|
|
417
|
+
value.supersededBy &&
|
|
418
|
+
value.supersededBy.id === value.id &&
|
|
419
|
+
value.supersededBy.version <= value.version
|
|
420
|
+
)
|
|
421
|
+
throw new TypeError('A superseding handoff must identify a newer package version.');
|
|
319
422
|
return value;
|
|
320
423
|
}
|
|
321
424
|
|
|
425
|
+
/** @type {typeof import('./design-handoff-contracts.d.mts').assertDesignPlanningLineage} */
|
|
322
426
|
export function assertDesignPlanningLineage(value, handoff) {
|
|
323
427
|
assertDesignHandoffContract(value, DESIGN_PLANNING_LINEAGE_SCHEMA);
|
|
324
|
-
distinct(value.mappings, item => item.requirementId, 'lineage requirement identity');
|
|
428
|
+
distinct(value.mappings, (item) => item.requirementId, 'lineage requirement identity');
|
|
325
429
|
for (const mapping of value.mappings) {
|
|
326
|
-
distinct(
|
|
327
|
-
|
|
430
|
+
distinct(
|
|
431
|
+
mapping.acceptanceRefs,
|
|
432
|
+
(item) => `${item.storyId}:${item.acceptanceId}`,
|
|
433
|
+
'lineage acceptance identity',
|
|
434
|
+
);
|
|
435
|
+
distinct(mapping.taskIds, (item) => item, 'lineage task identity');
|
|
328
436
|
}
|
|
329
437
|
if (handoff) {
|
|
330
438
|
assertDesignImplementationHandoff(handoff);
|
|
331
|
-
if (handoff.status !== 'approved')
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
439
|
+
if (handoff.status !== 'approved')
|
|
440
|
+
throw new TypeError('Planning lineage requires an approved handoff.');
|
|
441
|
+
if (
|
|
442
|
+
value.handoff.id !== handoff.id ||
|
|
443
|
+
value.handoff.version !== handoff.version ||
|
|
444
|
+
value.handoff.contentDigest !== handoff.contentDigest
|
|
445
|
+
)
|
|
446
|
+
throw new TypeError('Planning lineage identifies a different handoff package.');
|
|
447
|
+
const expected = handoff.requirements.map((item) => item.id).sort();
|
|
448
|
+
const actual = value.mappings.map((item) => item.requirementId).sort();
|
|
449
|
+
if (actual.join('\n') !== expected.join('\n'))
|
|
450
|
+
throw new TypeError(
|
|
451
|
+
'Planning lineage must map every implementation requirement exactly once.',
|
|
452
|
+
);
|
|
336
453
|
}
|
|
337
454
|
return value;
|
|
338
455
|
}
|