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
@@ -7,6 +7,8 @@ const sha = gitShaSchema;
7
7
  const text = z.string().max(4000);
8
8
  const runtime = runtimeNameSchema;
9
9
  const phase = z.enum(['candidate', 'integration']);
10
+ /** Предел имени стадии в событии `attempt.stage`. */
11
+ export const STAGE_NAME_LIMIT = 300;
10
12
  const delivery = {
11
13
  sink: idSchema,
12
14
  key: z.string().min(1).max(300),
@@ -71,6 +73,23 @@ export const eventPayloads = {
71
73
  sameVendor: z.boolean(),
72
74
  blocking: z.number().int().min(0),
73
75
  }),
76
+ /**
77
+ * Граница стадии попытки (замер `AttemptState.timings`): одно `started` и
78
+ * не больше одного `finished` на стадию, в той же транзакции под fencing,
79
+ * что и замер. Стадия попытки, утратившей владение или упавшей, остаётся
80
+ * открытой: её конец — событие конца попытки. `at` и `durationMs` — по
81
+ * часам движка, те же, что в замере.
82
+ */
83
+ 'attempt.stage': z.strictObject({
84
+ timingId: z.string().min(1).max(200),
85
+ stage: z.string().min(1).max(STAGE_NAME_LIMIT),
86
+ phase: z.enum(['started', 'finished']),
87
+ at: isoTimeSchema,
88
+ /** Только у `finished`. */
89
+ durationMs: z.number().int().min(0).optional(),
90
+ /** Только у `finished`. */
91
+ outcome: z.enum(['passed', 'failed']).optional(),
92
+ }),
74
93
  'attempt.failed': z.strictObject({
75
94
  failureKind: failureKindSchema,
76
95
  message: text,
@@ -181,6 +200,35 @@ const envelopeSchema = z.strictObject(envelope);
181
200
  const variants = Object.keys(eventPayloads).map((type) => envelopeSchema.extend({ type: z.literal(type), payload: eventPayloads[type] }));
182
201
  /** Событие: общий конверт и нагрузка своего типа (дискриминатор `type`). */
183
202
  export const runEventSchema = z.discriminatedUnion('type', variants);
203
+ /**
204
+ * Событие типа, которого эта версия не знает (его записала более новая
205
+ * версия): при чтении журнала оно не обрывает список, а возвращается
206
+ * непрозрачным — конверт, `type: 'unknown'` и исходный тип в `original`;
207
+ * нагрузка не возвращается. Записать такое событие нельзя: писатель строгий
208
+ * (`runEventSchema`). Известный тип с нарушенной нагрузкой — по-прежнему отказ.
209
+ */
210
+ export const unknownRunEventSchema = envelopeSchema.extend({
211
+ type: z.literal('unknown'),
212
+ original: z.string().min(1).max(200),
213
+ });
214
+ /** Схема прочитанного события (`events`): `runEventSchema` и `unknownRunEventSchema`. */
215
+ export const readRunEventSchema = z.discriminatedUnion('type', [
216
+ ...variants,
217
+ unknownRunEventSchema,
218
+ ]);
219
+ /**
220
+ * Разобрать сохранённое событие терпимо к неизвестному типу: тип, которого
221
+ * нет в `eventPayloads`, становится `UnknownRunEvent` (конверт проверяется
222
+ * строго); известный тип разбирается строгой схемой, и её отказ — ошибка.
223
+ */
224
+ export function readRunEvent(raw) {
225
+ const type = raw?.type;
226
+ if (typeof type === 'string' && !Object.hasOwn(eventPayloads, type)) {
227
+ const env = z.object(envelope).parse(raw);
228
+ return unknownRunEventSchema.parse({ ...env, type: 'unknown', original: type.slice(0, 200) });
229
+ }
230
+ return runEventSchema.parse(raw);
231
+ }
184
232
  /**
185
233
  * Типы транзакций исполнения. Это сохранённые строки: DevContour пишет их
186
234
  * в журнал аудита как тип события и разбирает (`scheduler.error` — причина
@@ -20,3 +20,4 @@ export * from './project.ts';
20
20
  export * from './diagnosis.ts';
21
21
  export * from './planning.ts';
22
22
  export * from './catalog.ts';
23
+ export * from './report.ts';
@@ -20,3 +20,4 @@ export * from "./project.js";
20
20
  export * from "./diagnosis.js";
21
21
  export * from "./planning.js";
22
22
  export * from "./catalog.js";
23
+ export * from "./report.js";
@@ -84,7 +84,11 @@ export interface ExecutionStore {
84
84
  readonly stateVersion: number;
85
85
  transact<T>(kind: TransactionKind, fn: (tx: ExecutionTransaction) => NotPromise<T>): T;
86
86
  read<T>(fn: (view: ExecutionView) => NotPromise<T>): T;
87
- /** События строго после `after`, по возрастанию `seq`. */
87
+ /**
88
+ * События строго после `after`, по возрастанию `seq`. Тип, которого эта
89
+ * версия не знает, возвращается `UnknownRunEvent` (`readRunEvent`), а не
90
+ * обрывает список.
91
+ */
88
92
  events(after?: number, limit?: number): RunEvent[];
89
93
  close(): void;
90
94
  }