devcontour-harness 0.1.0-alpha.29 → 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 (65) hide show
  1. package/README.md +30 -2
  2. package/docs/architecture.md +64 -0
  3. package/docs/compatibility.md +15 -14
  4. package/docs/contracts.md +244 -26
  5. package/docs/release-notes/0.1.0-alpha.30.md +40 -0
  6. package/docs/review-probes.md +17 -17
  7. package/docs/upgrade.md +93 -0
  8. package/lib/agents/review-probe.d.ts +1 -0
  9. package/lib/agents/review-probe.js +20 -0
  10. package/lib/cli.js +57 -1
  11. package/lib/contracts/cli.d.ts +1150 -22
  12. package/lib/contracts/cli.js +129 -4
  13. package/lib/contracts/events.d.ts +642 -3
  14. package/lib/contracts/events.js +48 -0
  15. package/lib/contracts/index.d.ts +1 -0
  16. package/lib/contracts/index.js +1 -0
  17. package/lib/contracts/ports.d.ts +5 -1
  18. package/lib/contracts/published.d.ts +559 -2
  19. package/lib/contracts/published.js +2 -0
  20. package/lib/contracts/report.d.ts +1149 -0
  21. package/lib/contracts/report.js +401 -0
  22. package/lib/control/harness.d.ts +454 -1
  23. package/lib/control/harness.js +83 -1
  24. package/lib/control/report-file.d.ts +19 -0
  25. package/lib/control/report-file.js +85 -0
  26. package/lib/control/report.d.ts +9 -0
  27. package/lib/control/report.js +27 -0
  28. package/lib/engine/engine.d.ts +5 -1
  29. package/lib/engine/engine.js +49 -7
  30. package/lib/engine/runner.js +5 -2
  31. package/lib/environment/dependency-network.d.ts +42 -0
  32. package/lib/environment/dependency-network.js +413 -0
  33. package/lib/environment/lifecycle.d.ts +3 -1
  34. package/lib/environment/lifecycle.js +22 -4
  35. package/lib/environment/process.d.ts +5 -0
  36. package/lib/environment/process.js +38 -0
  37. package/lib/explain/state.d.ts +38 -0
  38. package/lib/explain/state.js +19 -11
  39. package/lib/index.d.ts +2 -0
  40. package/lib/index.js +2 -0
  41. package/lib/projections/attempt.d.ts +101 -0
  42. package/lib/projections/attempt.js +64 -0
  43. package/lib/projections/index.d.ts +2 -1
  44. package/lib/projections/index.js +2 -1
  45. package/lib/projections/stop.d.ts +19 -0
  46. package/lib/projections/stop.js +33 -27
  47. package/lib/report/compute.d.ts +72 -0
  48. package/lib/report/compute.js +1219 -0
  49. package/lib/report/document.d.ts +27 -0
  50. package/lib/report/document.js +206 -0
  51. package/lib/report/format.d.ts +23 -0
  52. package/lib/report/format.js +53 -0
  53. package/lib/report/html.d.ts +7 -0
  54. package/lib/report/html.js +109 -0
  55. package/lib/report/index.d.ts +4 -0
  56. package/lib/report/index.js +7 -0
  57. package/lib/report/markdown.d.ts +7 -0
  58. package/lib/report/markdown.js +112 -0
  59. package/lib/storage/sqlite.d.ts +19 -0
  60. package/lib/storage/sqlite.js +61 -6
  61. package/lib/verification/gates.d.ts +6 -0
  62. package/lib/verification/gates.js +15 -0
  63. package/package.json +5 -1
  64. package/schemas/run-event.schema.json +95 -0
  65. package/schemas/value-report.schema.json +2541 -0
@@ -2,17 +2,18 @@ import { z } from 'zod';
2
2
  import { API_VERSION, STATE_VERSION } from "./version.js";
3
3
  import { digestSchema, gitShaSchema, idSchema, isoTimeSchema, runtimeNameSchema, targetRefSchema, } from "./primitives.js";
4
4
  import { HarnessError, errorCodes } from "./errors.js";
5
- import { controlStateSchema, controllerLeaseSchema, workStatusSchema } from "./execution.js";
6
- import { runEventSchema } from "./events.js";
5
+ import { controlStateSchema, controllerLeaseSchema, failureKindSchema, pauseReasons, workStatusSchema, } from "./execution.js";
6
+ import { readRunEventSchema } from "./events.js";
7
7
  import { deliveryStateSchema, resultEnvelopeSchema } from "./result.js";
8
8
  import { reviewRecordSchema } from "./review.js";
9
9
  import { sourceRefSchema } from "./work.js";
10
10
  import { profilePinSchema, resolvedProfileSchema } from "./profiles.js";
11
11
  import { filePlanEntrySchema, projectManifestSchema } from "./project.js";
12
- import { stopDiagnosisSchema } from "./diagnosis.js";
12
+ import { diagnosisActions, diagnosisActors, diagnosisCauses, stopDiagnosisSchema, } from "./diagnosis.js";
13
13
  import { planCheckDataSchema, planRequestDataSchema } from "./planning.js";
14
14
  import { toolchainReportSchema } from "./toolchain.js";
15
15
  import { operationCatalogSchema } from "./catalog.js";
16
+ import { reportDataSchema } from "./report.js";
16
17
  const state = {
17
18
  name: '--state',
18
19
  value: 'dir',
@@ -171,6 +172,12 @@ export const cliCommands = {
171
172
  args: [
172
173
  state,
173
174
  { name: '--graph', value: 'id', required: false, description: 'Только этот граф' },
175
+ {
176
+ name: '--detail',
177
+ value: 'flag',
178
+ required: false,
179
+ description: 'Добавить detail: почему стоит выдача и активные попытки (стадия, владение, gates)',
180
+ },
174
181
  ],
175
182
  refusals: ['NOT_FOUND'],
176
183
  },
@@ -365,6 +372,51 @@ export const cliCommands = {
365
372
  ],
366
373
  refusals: ['NOT_FOUND'],
367
374
  },
375
+ report: {
376
+ description: 'Отчёт об эффекте по данным каталога состояния: принятые поручения, отказы проверок и ревью, автономность, скорость, расход, окружение, недели; только чтение, без вызовов моделей',
377
+ writes: false,
378
+ idempotency: 'Только чтение. Тот же каталог и те же параметры дают те же байты: момент отчёта по умолчанию — последняя метка времени в данных, а не часы',
379
+ args: [
380
+ state,
381
+ {
382
+ name: '--since',
383
+ value: 'text',
384
+ required: false,
385
+ description: 'Начало окна включительно: ISO-время с поясом, дата YYYY-MM-DD или Nd/Nw до --as-of',
386
+ },
387
+ {
388
+ name: '--until',
389
+ value: 'text',
390
+ required: false,
391
+ description: 'Конец окна не включительно: ISO-время с поясом или дата',
392
+ },
393
+ {
394
+ name: '--as-of',
395
+ value: 'text',
396
+ required: false,
397
+ description: 'Момент отчёта; по умолчанию — последняя метка времени в данных',
398
+ },
399
+ {
400
+ name: '--format',
401
+ value: 'text',
402
+ required: false,
403
+ description: 'json (по умолчанию, в конверте), md или html (текст в stdout без конверта; отказ — JSON-конверт)',
404
+ },
405
+ {
406
+ name: '--no-titles',
407
+ value: 'flag',
408
+ required: false,
409
+ description: 'Без заголовков поручений и метки проекта',
410
+ },
411
+ {
412
+ name: '--out',
413
+ value: 'path',
414
+ required: false,
415
+ description: 'Записать отчёт выбранного формата в файл (не символическую ссылку и не файл состояния); в stdout — конверт с путём и размером',
416
+ },
417
+ ],
418
+ refusals: ['NOT_FOUND', 'PATH_CONFLICT'],
419
+ },
368
420
  'plan-request': {
369
421
  description: 'Собрать read-only запрос планирования из постановки и фактов проекта (роли, gates, репозитории, контекст, ресурсы, контракты, требования) для ведущего агента; модель не вызывается, ничего не пишется',
370
422
  writes: false,
@@ -530,6 +582,66 @@ export const validateDataSchema = z.strictObject({
530
582
  contextDigest: digestSchema.optional(),
531
583
  orders: z.number().int().positive(),
532
584
  });
585
+ /** Активная попытка `status --detail` (`attemptView`). */
586
+ export const attemptViewSchema = z.strictObject({
587
+ runId: z.string().min(1).max(200),
588
+ workId: idSchema,
589
+ attempt: z.number().int().positive(),
590
+ status: z.string(),
591
+ phase: workStatusSchema,
592
+ runtime: z.string(),
593
+ model: z.string().optional(),
594
+ startedAt: isoTimeSchema,
595
+ elapsedMs: z.number().int().min(0),
596
+ /** Текущая стадия (последний незакрытый замер); нет — между стадиями. */
597
+ stage: z
598
+ .strictObject({
599
+ name: z.string().min(1),
600
+ family: z.string(),
601
+ startedAt: isoTimeSchema,
602
+ elapsedMs: z.number().int().min(0),
603
+ })
604
+ .optional(),
605
+ /** Последний heartbeat — `leaseUntil − leaseMs`; `stale` — срок истёк. */
606
+ lease: z.strictObject({
607
+ owner: z.string().min(1).max(300),
608
+ leaseUntil: z.number().int().min(0),
609
+ leaseMs: z.number().int().positive(),
610
+ /** Нет при сроке `0` (владение отозвано). */
611
+ sinceHeartbeatMs: z.number().int().min(0).optional(),
612
+ stale: z.boolean(),
613
+ }),
614
+ /** Обязательные gates текущей фазы на её текущем SHA: `passed + failed + remaining = required`. */
615
+ gates: z.strictObject({
616
+ phase: z.enum(['candidate', 'integration']),
617
+ required: z.number().int().min(0),
618
+ passed: z.number().int().min(0),
619
+ failed: z.number().int().min(0),
620
+ remaining: z.number().int().min(0),
621
+ }),
622
+ });
623
+ /**
624
+ * Почему выдача стоит (`status --detail`): причина паузы (`queueStop`), кто и
625
+ * что её снимает (`queuePause`, то же рассуждение, что у `explain`), классы
626
+ * отказа паузы runtime и последнее сообщение отказа этих классов.
627
+ */
628
+ export const queueViewSchema = z.strictObject({
629
+ paused: z.boolean(),
630
+ reason: z.enum(pauseReasons).optional(),
631
+ detail: z.string().optional(),
632
+ since: isoTimeSchema.optional(),
633
+ operation: z.string().optional(),
634
+ /**
635
+ * Пауза есть, но её снимет следующий run (очередь не запускали, штатная
636
+ * остановка, применимый запрос политики) — как в `explain`.
637
+ */
638
+ liftedByRun: z.literal(true).optional(),
639
+ failures: z.array(failureKindSchema).optional(),
640
+ code: z.enum(Object.keys(errorCodes)).optional(),
641
+ cause: z.enum(diagnosisCauses).optional(),
642
+ actor: z.enum(diagnosisActors).nullable().optional(),
643
+ action: z.enum(diagnosisActions).optional(),
644
+ });
533
645
  export const statusDataSchema = z.strictObject({
534
646
  stateVersion: z.literal(STATE_VERSION),
535
647
  control: controlStateSchema,
@@ -582,9 +694,21 @@ export const statusDataSchema = z.strictObject({
582
694
  })),
583
695
  })
584
696
  .optional(),
697
+ /**
698
+ * Только `status --detail`: время снимка, почему стоит выдача и активные
699
+ * попытки (стадия, длительность, владение, gates). Без флага поля нет.
700
+ */
701
+ detail: z
702
+ .strictObject({
703
+ at: isoTimeSchema,
704
+ queue: queueViewSchema,
705
+ attempts: z.array(attemptViewSchema),
706
+ })
707
+ .optional(),
585
708
  });
586
709
  export const eventsDataSchema = z.strictObject({
587
- events: z.array(runEventSchema),
710
+ /** Событие неизвестного этой версии типа — `{type: 'unknown', original}`. */
711
+ events: z.array(readRunEventSchema),
588
712
  /** Номер для следующего `--after`. */
589
713
  next: z.number().int().min(0),
590
714
  });
@@ -921,6 +1045,7 @@ export const cliDataSchemas = {
921
1045
  doctor: doctorDataSchema,
922
1046
  init: initDataSchema,
923
1047
  explain: explainDataSchema,
1048
+ report: reportDataSchema,
924
1049
  'plan-request': planRequestDataSchema,
925
1050
  'plan-check': planCheckDataSchema,
926
1051
  capabilities: operationCatalogSchema,