devcontour-harness 0.1.0-alpha.28 → 0.1.0-alpha.30

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 (75) hide show
  1. package/README.md +36 -2
  2. package/docs/architecture.md +80 -0
  3. package/docs/compatibility.md +15 -14
  4. package/docs/contracts.md +244 -26
  5. package/docs/release-notes/0.1.0-alpha.29.md +32 -0
  6. package/docs/release-notes/0.1.0-alpha.30.md +40 -0
  7. package/docs/review-probes.md +23 -20
  8. package/docs/toolchains.md +12 -1
  9. package/docs/upgrade.md +124 -0
  10. package/lib/agents/review-probe.d.ts +1 -0
  11. package/lib/agents/review-probe.js +38 -0
  12. package/lib/cli.js +57 -1
  13. package/lib/contracts/cli.d.ts +1150 -22
  14. package/lib/contracts/cli.js +129 -4
  15. package/lib/contracts/events.d.ts +642 -3
  16. package/lib/contracts/events.js +48 -0
  17. package/lib/contracts/index.d.ts +1 -0
  18. package/lib/contracts/index.js +1 -0
  19. package/lib/contracts/ports.d.ts +5 -1
  20. package/lib/contracts/published.d.ts +559 -2
  21. package/lib/contracts/published.js +2 -0
  22. package/lib/contracts/report.d.ts +1149 -0
  23. package/lib/contracts/report.js +401 -0
  24. package/lib/control/harness.d.ts +454 -1
  25. package/lib/control/harness.js +83 -1
  26. package/lib/control/report-file.d.ts +19 -0
  27. package/lib/control/report-file.js +85 -0
  28. package/lib/control/report.d.ts +9 -0
  29. package/lib/control/report.js +27 -0
  30. package/lib/engine/engine.d.ts +5 -1
  31. package/lib/engine/engine.js +49 -7
  32. package/lib/engine/runner.js +5 -2
  33. package/lib/environment/dependency-network.d.ts +42 -0
  34. package/lib/environment/dependency-network.js +413 -0
  35. package/lib/environment/isolation.d.ts +23 -1
  36. package/lib/environment/isolation.js +61 -2
  37. package/lib/environment/lifecycle.d.ts +3 -1
  38. package/lib/environment/lifecycle.js +22 -4
  39. package/lib/environment/os-tools.d.ts +3 -1
  40. package/lib/environment/os-tools.js +3 -1
  41. package/lib/environment/process.d.ts +11 -0
  42. package/lib/environment/process.js +42 -2
  43. package/lib/explain/state.d.ts +38 -0
  44. package/lib/explain/state.js +19 -11
  45. package/lib/index.d.ts +2 -0
  46. package/lib/index.js +2 -0
  47. package/lib/projections/attempt.d.ts +101 -0
  48. package/lib/projections/attempt.js +64 -0
  49. package/lib/projections/index.d.ts +2 -1
  50. package/lib/projections/index.js +2 -1
  51. package/lib/projections/stop.d.ts +19 -0
  52. package/lib/projections/stop.js +33 -27
  53. package/lib/report/compute.d.ts +72 -0
  54. package/lib/report/compute.js +1219 -0
  55. package/lib/report/document.d.ts +27 -0
  56. package/lib/report/document.js +206 -0
  57. package/lib/report/format.d.ts +23 -0
  58. package/lib/report/format.js +53 -0
  59. package/lib/report/html.d.ts +7 -0
  60. package/lib/report/html.js +109 -0
  61. package/lib/report/index.d.ts +4 -0
  62. package/lib/report/index.js +7 -0
  63. package/lib/report/markdown.d.ts +7 -0
  64. package/lib/report/markdown.js +112 -0
  65. package/lib/storage/sqlite.d.ts +19 -0
  66. package/lib/storage/sqlite.js +61 -6
  67. package/lib/verification/dependency-store.d.ts +13 -1
  68. package/lib/verification/dependency-store.js +99 -25
  69. package/lib/verification/file-digests.d.ts +33 -0
  70. package/lib/verification/file-digests.js +121 -0
  71. package/lib/verification/gates.d.ts +34 -4
  72. package/lib/verification/gates.js +113 -11
  73. package/package.json +5 -1
  74. package/schemas/run-event.schema.json +95 -0
  75. package/schemas/value-report.schema.json +2541 -0
@@ -0,0 +1,401 @@
1
+ import { z } from 'zod';
2
+ import { failureKindSchema, pauseReasons } from "./execution.js";
3
+ import { isoTimeSchema } from "./primitives.js";
4
+ /**
5
+ * Отчёт об эффекте harness (`harness report`, `valueReport`): что дали
6
+ * исполнение, проверки и ревью на данных самого проекта. Строится только из
7
+ * перечисленных полей состояния, записей учёта и ревью; prompt, вывод
8
+ * runtime, тексты находок и ошибок, fencing-токены сюда не попадают.
9
+ *
10
+ * Правила (`docs/contracts.md`, раздел «Отчёт»):
11
+ * - каждое число — наблюдение, а не вывод: «сэкономлено часов» нет;
12
+ * - неизвестное — не ноль: `bound` говорит, точное ли значение, нижняя или
13
+ * верхняя граница, или оно неизвестно (`value: null`);
14
+ * - малые выборки: процент — только при знаменателе от 20, медиана — от 5
15
+ * значений, меньше 3 принятых поручений — «недостаточно данных»;
16
+ * - списки ограничены (`REPORT_LIMITS`), усечение отмечено флагом.
17
+ *
18
+ * Литералы перечней повторяют `src/report/*` (модуль без zod для браузера);
19
+ * тест сверяет оба перечня поэлементно.
20
+ */
21
+ export const REPORT_VERSION = 1;
22
+ export const REPORT_LIMITS = {
23
+ /** Строки таблицы поручений. */
24
+ works: 50,
25
+ /** Ссылки на evidence отказов. */
26
+ evidence: 50,
27
+ /** Недели тренда; более ранние свёрнуты в одну строку. */
28
+ weeks: 12,
29
+ /** Строки gates, стадий, версий движка и прочих разбивок. */
30
+ rows: 50,
31
+ /** Предел сериализованного JSON отчёта, байт UTF-8. */
32
+ jsonBytes: 512 * 1024,
33
+ /** Предел HTML отчёта, байт UTF-8. */
34
+ htmlBytes: 1024 * 1024,
35
+ };
36
+ /** Корзины классов отказа попытки (`failureBucketOf`). */
37
+ export const failureBuckets = [
38
+ 'defect',
39
+ 'incomplete',
40
+ 'integration',
41
+ 'environment',
42
+ 'time-limit',
43
+ 'tool',
44
+ 'operator',
45
+ 'budget',
46
+ 'unknown',
47
+ 'unclassified',
48
+ ];
49
+ /** Точность значения: точное, нижняя или верхняя граница, неизвестно. */
50
+ export const reportBounds = ['exact', 'lower', 'upper', 'unknown'];
51
+ export const headlineIds = ['accepted', 'sent-back', 'lead-time', 'spend', 'environment'];
52
+ const count = z.number().int().min(0);
53
+ const ms = z.number().int().min(0);
54
+ const usd = z.number().min(0);
55
+ const week = z.string().regex(/^\d{4}-W\d{2}$/);
56
+ const label = z.string().min(1).max(200);
57
+ const sentence = z.string().max(600);
58
+ const rows = REPORT_LIMITS.rows;
59
+ /** Значение и его основание: `n` — знаменатель или размер выборки, `unknown` — неизмеренные входы. */
60
+ export const reportMeasureSchema = z.strictObject({
61
+ value: z.number().nullable(),
62
+ n: count,
63
+ unknown: count,
64
+ bound: z.enum(reportBounds),
65
+ });
66
+ /**
67
+ * Распределение: медиана и p75 — только при `n >= 5`, иначе `null`, а
68
+ * значения перечислены в `values` (по возрастанию).
69
+ */
70
+ export const reportDistSchema = z.strictObject({
71
+ n: count,
72
+ unknown: count,
73
+ median: z.number().min(0).nullable(),
74
+ p75: z.number().min(0).nullable(),
75
+ max: z.number().min(0).nullable(),
76
+ values: z.array(z.number().min(0)).max(4),
77
+ });
78
+ const headlineSchema = z.strictObject({
79
+ id: z.enum(headlineIds),
80
+ /** Значение для крупного шрифта: «19», «≥ $5.73», «3.2 h». */
81
+ value: z.string().min(1).max(60),
82
+ /** Одно предложение простым языком. */
83
+ text: sentence,
84
+ /** Знаменатель, окно и оговорка. */
85
+ basis: sentence,
86
+ measure: reportMeasureSchema,
87
+ });
88
+ const evidenceRefSchema = z.strictObject({
89
+ workId: label,
90
+ runId: label,
91
+ attempt: z.number().int().positive(),
92
+ kind: z.enum(['test', 'review', 'scope']),
93
+ phase: z.enum(['candidate', 'integration']).nullable(),
94
+ gate: label.nullable(),
95
+ at: isoTimeSchema,
96
+ /** Первые 12 символов SHA кандидата. */
97
+ sha: z.string().max(12).nullable(),
98
+ /** Журнал относительно каталога состояния; путь вне его — `…/<имя>`. */
99
+ log: z.string().max(300).nullable(),
100
+ /** Блокирующие находки отклонившего ревью. */
101
+ blocking: count.nullable(),
102
+ });
103
+ const countRow = (key) => z.strictObject({ key, count });
104
+ const weekRowSchema = z.strictObject({
105
+ kind: z.literal('week'),
106
+ week,
107
+ attempts: count,
108
+ accepted: count,
109
+ firstPass: count,
110
+ defects: count,
111
+ environment: count,
112
+ knownUsd: usd,
113
+ unknownCalls: count,
114
+ leadMedianMs: ms.nullable(),
115
+ engines: z.array(label).max(5),
116
+ /** Набор версий движка отличается от предыдущей активной недели. */
117
+ engineChanged: z.boolean(),
118
+ /** Версий движка в неделе больше 5: показаны первые. */
119
+ enginesTruncated: z.boolean(),
120
+ });
121
+ const weekGapSchema = z.strictObject({ kind: z.literal('gap'), from: week, to: week });
122
+ const weekEarlierSchema = z.strictObject({
123
+ kind: z.literal('earlier'),
124
+ from: week,
125
+ to: week,
126
+ weeks: count,
127
+ attempts: count,
128
+ accepted: count,
129
+ firstPass: count,
130
+ defects: count,
131
+ environment: count,
132
+ knownUsd: usd,
133
+ unknownCalls: count,
134
+ });
135
+ const workRowSchema = z.strictObject({
136
+ id: label,
137
+ /** Нет при `noTitles`. */
138
+ title: z.string().max(180).optional(),
139
+ outcome: z.enum(['accepted', 'failed', 'cancelled']),
140
+ finishedAt: isoTimeSchema.nullable(),
141
+ attempts: count,
142
+ /** Засчитанные попытки: без отказов окружения и прерываний штатной остановкой. */
143
+ counted: count,
144
+ leadMs: ms.nullable(),
145
+ knownUsd: usd,
146
+ unknownCalls: count,
147
+ costBound: z.enum(reportBounds),
148
+ rejections: z.array(countRow(z.enum(failureBuckets))).max(failureBuckets.length),
149
+ });
150
+ export const valueReportSchema = z.strictObject({
151
+ reportVersion: z.literal(REPORT_VERSION),
152
+ harnessVersion: z.string().min(1).max(100),
153
+ /** Метка проекта (имя каталога состояния); нет при `noTitles`. */
154
+ label: z.string().max(200).nullable(),
155
+ window: z.strictObject({
156
+ since: isoTimeSchema.nullable(),
157
+ until: isoTimeSchema.nullable(),
158
+ /** Момент отчёта: по умолчанию — последняя метка времени в данных, а не часы. */
159
+ asOf: isoTimeSchema,
160
+ }),
161
+ /** Принятых поручений в окне не меньше 3. */
162
+ enoughData: z.boolean(),
163
+ coverage: z.strictObject({
164
+ works: count,
165
+ attempts: count,
166
+ failed: count,
167
+ withFailureKind: count,
168
+ withTimings: count,
169
+ /** Попытки с полным учётом вызовов (`callsRecorded`). */
170
+ withCalls: count,
171
+ /**
172
+ * Поручения `done` без успешной попытки: время приёмки неизвестно, в
173
+ * принятые (в любом окне) не входят.
174
+ */
175
+ doneWithoutAttempt: count,
176
+ withWait: count,
177
+ withEngineVersion: count,
178
+ engines: z.array(label).max(20),
179
+ enginesTruncated: z.boolean(),
180
+ calls: count,
181
+ reviews: count,
182
+ events: count,
183
+ eventsFrom: isoTimeSchema.nullable(),
184
+ }),
185
+ summary: z.discriminatedUnion('status', [
186
+ z.strictObject({
187
+ status: z.literal('ok'),
188
+ headlines: z.array(headlineSchema).max(5),
189
+ }),
190
+ z.strictObject({
191
+ status: z.literal('not-enough-data'),
192
+ text: sentence,
193
+ accepted: count,
194
+ attempts: count,
195
+ failedAttempts: count,
196
+ works: count,
197
+ }),
198
+ ]),
199
+ defects: z.strictObject({
200
+ rejected: count,
201
+ byKind: z.strictObject({ gate: count, review: count, 'scope-violation': count }),
202
+ byPhase: z.strictObject({ candidate: count, integration: count, unknown: count }),
203
+ /**
204
+ * Возвращено до приёмки: `value` — с отказом `defect`; `unknown` — только
205
+ * с отказами без класса (`unknown`, `unclassified`) — `bound: lower`;
206
+ * без них, но с возвратами только gate подготовки — `bound: upper`.
207
+ */
208
+ sentBack: reportMeasureSchema,
209
+ /** Возвращённые только отказами gate подготовки (возможна сеть). */
210
+ sentBackSetupOnly: count,
211
+ /**
212
+ * Диапазон возвращённых: `min` — с отказом `defect` не только в gates
213
+ * подготовки; `max` — плюс только gates подготовки и только отказы без
214
+ * класса. Оба сомнения сразу — `sentBack.bound: unknown`, показывается
215
+ * диапазон.
216
+ */
217
+ sentBackRange: z.strictObject({ min: count, max: count }),
218
+ byGate: z
219
+ .array(z.strictObject({
220
+ gate: label,
221
+ phase: z.enum(['candidate', 'integration']),
222
+ failed: count,
223
+ /** Gate подготовки (установка зависимостей): его отказ часто вызван сетью. */
224
+ setup: z.boolean(),
225
+ }))
226
+ .max(rows),
227
+ byGateTruncated: z.boolean(),
228
+ reviews: z.strictObject({
229
+ rejected: count,
230
+ candidate: count,
231
+ integration: count,
232
+ blockingFindings: count,
233
+ withoutFindings: count,
234
+ }),
235
+ afterGreenGates: reportMeasureSchema,
236
+ integration: count,
237
+ planContract: z.strictObject({
238
+ rounds: count,
239
+ rejected: count,
240
+ plans: z.strictObject({ rounds: count, rejected: count }),
241
+ contracts: z.strictObject({ rounds: count, rejected: count }),
242
+ blockingClosed: count,
243
+ blockingOpen: count,
244
+ blockingWithdrawn: count,
245
+ }),
246
+ withdrawn: reportMeasureSchema,
247
+ items: z.array(evidenceRefSchema).max(REPORT_LIMITS.evidence),
248
+ itemsTotal: count,
249
+ itemsTruncated: z.boolean(),
250
+ }),
251
+ autonomy: z.strictObject({
252
+ withAction: reportMeasureSchema,
253
+ withoutAction: reportMeasureSchema,
254
+ /** `null` — действие этого вида не записывается. */
255
+ actions: z.strictObject({
256
+ /** Решения recovery с источником `operator`: единственное действие с записанным актёром. */
257
+ operatorDecisions: count,
258
+ /** Удержания и отмены попыток: актёр не записан, к действиям человека не относятся. */
259
+ holds: count,
260
+ cancelledAttempts: count,
261
+ retries: count.nullable(),
262
+ resets: count.nullable(),
263
+ baseMoves: count.nullable(),
264
+ }),
265
+ approvals: z.strictObject({
266
+ operator: count,
267
+ agent: count,
268
+ /**
269
+ * `events` — события `graph.approved`; `state` — согласования графов в
270
+ * состоянии (графы без событий); `mixed` — оба; `none` — записей нет
271
+ * (число неизвестно, а не ноль).
272
+ */
273
+ source: z.enum(['events', 'state', 'mixed', 'none']),
274
+ }),
275
+ pauses: z
276
+ .array(z.strictObject({
277
+ reason: z.enum(pauseReasons),
278
+ count,
279
+ pausedMs: ms,
280
+ /** Пауз без последующего resume: их время считано до `asOf`. */
281
+ open: count,
282
+ failures: z.array(failureKindSchema).max(20),
283
+ }))
284
+ .max(pauseReasons.length),
285
+ escalations: count,
286
+ }),
287
+ speed: z.strictObject({
288
+ leadTime: reportDistSchema,
289
+ /** Начало взято из `WorkState.approvedAt`: у первой попытки нет `wait.approvedAt`. */
290
+ leadTimeFallback: count,
291
+ dependencyWait: reportDistSchema,
292
+ queueWait: reportDistSchema,
293
+ stages: z
294
+ .array(z.strictObject({
295
+ family: label,
296
+ spans: count,
297
+ totalMs: ms,
298
+ medianMs: ms.nullable(),
299
+ acceptedMs: ms,
300
+ rejectedMs: ms,
301
+ incomplete: count,
302
+ }))
303
+ .max(rows),
304
+ stagesTruncated: z.boolean(),
305
+ firstPass: reportMeasureSchema,
306
+ firstPassRaw: reportMeasureSchema,
307
+ finished: z.strictObject({ accepted: count, failed: count, cancelled: count }),
308
+ attemptsPerAccepted: z.strictObject({
309
+ n: count,
310
+ buckets: z.strictObject({ '1': count, '2': count, '3': count, '4-6': count, '7+': count }),
311
+ median: z.number().min(0).nullable(),
312
+ mean: z.number().min(0).nullable(),
313
+ }),
314
+ attemptsOnOther: count,
315
+ machineTime: reportDistSchema,
316
+ }),
317
+ cost: z.strictObject({
318
+ calls: count,
319
+ knownCalls: count,
320
+ knownUsd: usd,
321
+ reportedUsd: usd,
322
+ estimatedUsd: usd,
323
+ unknown: z.strictObject({
324
+ total: count,
325
+ noPrice: count,
326
+ incomplete: count,
327
+ active: count,
328
+ abandoned: count,
329
+ byRuntime: z.array(z.strictObject({ runtime: label, calls: count })).max(20),
330
+ }),
331
+ /** Попытки без единой записи вызова и без полного учёта: расход неизвестен. */
332
+ attemptsWithoutCalls: count,
333
+ /** Попытки с записями вызовов, но без полного учёта: расход — нижняя граница. */
334
+ attemptsPartialCalls: count,
335
+ perAccepted: reportMeasureSchema,
336
+ perAttempt: reportDistSchema,
337
+ rejected: z.strictObject({
338
+ /** `lower` — у части попыток учёт неполон. */
339
+ bound: z.enum(reportBounds),
340
+ usd,
341
+ totalUsd: usd,
342
+ attempts: count,
343
+ byBucket: z.array(z.strictObject({ bucket: z.enum(failureBuckets), usd })).max(10),
344
+ }),
345
+ byStage: z
346
+ .array(z.strictObject({ stage: label, calls: count, knownUsd: usd, unknownCalls: count }))
347
+ .max(rows),
348
+ tokens: z.strictObject({
349
+ input: count,
350
+ output: count,
351
+ cacheRead: count,
352
+ cacheWrite: count,
353
+ incompleteCalls: count,
354
+ }),
355
+ }),
356
+ environment: z.strictObject({
357
+ failed: count,
358
+ classified: count,
359
+ interrupted: count,
360
+ buckets: z.array(z.strictObject({ bucket: z.enum(failureBuckets), count })).length(10),
361
+ /** Отказы окружения среди классифицированных; `lower`, если есть отказы gate подготовки. */
362
+ share: reportMeasureSchema,
363
+ /** Отказы `defect` только в gates подготовки: возможно, тоже окружение (сеть, реестр). */
364
+ setupCheckFailures: count,
365
+ timeLimit: count,
366
+ /** Подпричина отказа окружения ещё не записывается. */
367
+ causes: z.null(),
368
+ neutral: z.strictObject({
369
+ costBound: z.enum(reportBounds),
370
+ attempts: count,
371
+ blocked: count,
372
+ machineMs: ms,
373
+ knownUsd: usd,
374
+ runtimePauses: count,
375
+ }),
376
+ rechecks: z.strictObject({ flaky: count, confirmed: count }),
377
+ }),
378
+ weeks: z.strictObject({
379
+ rows: z.array(z.union([weekRowSchema, weekGapSchema])).max(2 * REPORT_LIMITS.weeks),
380
+ earlier: weekEarlierSchema.nullable(),
381
+ active: count,
382
+ }),
383
+ works: z.strictObject({
384
+ rows: z.array(workRowSchema).max(REPORT_LIMITS.works),
385
+ total: count,
386
+ truncated: z.boolean(),
387
+ }),
388
+ limitations: z
389
+ .array(z.strictObject({ id: z.string().min(1).max(60), text: sentence }))
390
+ .min(1)
391
+ .max(30),
392
+ });
393
+ /** `harness report --out`: отчёт записан в файл, в ответе — куда и сколько. */
394
+ export const reportFileSchema = z.strictObject({
395
+ out: z.string().min(1),
396
+ format: z.enum(['json', 'md', 'html']),
397
+ bytes: count,
398
+ asOf: isoTimeSchema,
399
+ });
400
+ /** Данные `harness report`: отчёт или запись о файле (`--out`). */
401
+ export const reportDataSchema = z.union([valueReportSchema, reportFileSchema]);