devcontour-harness 0.1.0-alpha.31 → 0.1.0-alpha.34

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 (55) hide show
  1. package/README.md +22 -3
  2. package/docs/architecture.md +12 -0
  3. package/docs/compatibility.md +21 -18
  4. package/docs/contracts.md +135 -13
  5. package/docs/release-notes/0.1.0-alpha.32.md +33 -0
  6. package/docs/release-notes/0.1.0-alpha.33.md +29 -0
  7. package/docs/release-notes/0.1.0-alpha.34.md +32 -0
  8. package/docs/upgrade.md +137 -0
  9. package/lib/cli.js +2 -2
  10. package/lib/contracts/cli.d.ts +295 -5
  11. package/lib/contracts/events.d.ts +350 -4
  12. package/lib/contracts/events.js +63 -2
  13. package/lib/contracts/failure.d.ts +6 -1
  14. package/lib/contracts/failure.js +5 -1
  15. package/lib/contracts/handoff.d.ts +8 -0
  16. package/lib/contracts/handoff.js +17 -3
  17. package/lib/contracts/published.d.ts +177 -3
  18. package/lib/contracts/report.d.ts +116 -2
  19. package/lib/contracts/report.js +61 -3
  20. package/lib/control/base-move.d.ts +7 -2
  21. package/lib/control/base-move.js +14 -1
  22. package/lib/control/harness.d.ts +44 -8
  23. package/lib/control/harness.js +8 -96
  24. package/lib/control/status.d.ts +235 -0
  25. package/lib/control/status.js +101 -0
  26. package/lib/engine/budget.d.ts +78 -0
  27. package/lib/engine/budget.js +13 -2
  28. package/lib/engine/classify.d.ts +14 -1
  29. package/lib/engine/classify.js +34 -0
  30. package/lib/engine/engine.d.ts +17 -5
  31. package/lib/engine/engine.js +75 -5
  32. package/lib/engine/runner.js +4 -5
  33. package/lib/environment/isolation.d.ts +67 -3
  34. package/lib/environment/isolation.js +148 -5
  35. package/lib/environment/lifecycle.js +1 -1
  36. package/lib/explain/state.d.ts +25 -4
  37. package/lib/explain/state.js +29 -0
  38. package/lib/handoff/index.d.ts +1 -1
  39. package/lib/handoff/markdown.js +4 -2
  40. package/lib/handoff/pack.d.ts +38 -8
  41. package/lib/handoff/pack.js +57 -18
  42. package/lib/index.d.ts +18 -3
  43. package/lib/index.js +18 -2
  44. package/lib/integrations/connector/testing.js +1 -1
  45. package/lib/projections/next.d.ts +3 -1
  46. package/lib/projections/next.js +4 -1
  47. package/lib/projections/stop.d.ts +11 -0
  48. package/lib/projections/stop.js +44 -15
  49. package/lib/report/compute.js +228 -21
  50. package/lib/report/document.js +31 -7
  51. package/lib/verification/gates.js +20 -4
  52. package/package.json +1 -1
  53. package/schemas/handoff-pack.schema.json +6 -0
  54. package/schemas/run-event.schema.json +319 -0
  55. package/schemas/value-report.schema.json +235 -3
@@ -1,4 +1,37 @@
1
1
  import { z } from 'zod';
2
+ /**
3
+ * Причина отказа окружения (`attempt.diagnosed`): ставится в точке
4
+ * обнаружения (песочница gate, сеть установки зависимостей, провайдер,
5
+ * транспорт), а не разбором текста потом. `none` — отказ не окружения
6
+ * (код, ревью, область); `other` — отказ окружения без известной причины.
7
+ */
8
+ export declare const environmentCauses: readonly ["sandbox-launch", "sandbox-network", "sandbox-filesystem", "sandbox-policy", "dependency-network", "provider-auth", "provider-limit", "transport", "preflight", "lease-expired", "stalled", "shutdown", "other", "none"];
9
+ export declare const environmentCauseSchema: z.ZodEnum<{
10
+ preflight: "preflight";
11
+ transport: "transport";
12
+ none: "none";
13
+ other: "other";
14
+ "provider-auth": "provider-auth";
15
+ stalled: "stalled";
16
+ shutdown: "shutdown";
17
+ "sandbox-launch": "sandbox-launch";
18
+ "sandbox-network": "sandbox-network";
19
+ "sandbox-filesystem": "sandbox-filesystem";
20
+ "sandbox-policy": "sandbox-policy";
21
+ "dependency-network": "dependency-network";
22
+ "provider-limit": "provider-limit";
23
+ "lease-expired": "lease-expired";
24
+ }>;
25
+ export type EnvironmentCause = (typeof environmentCauses)[number];
26
+ /** Кто повторил поручение (`work.retried`): `host` — хост не назвал актёра. */
27
+ export declare const retryActors: readonly ["operator", "recovery", "host"];
28
+ export type RetryActor = (typeof retryActors)[number];
29
+ /** Кто отменил поручение (`work.cancelled`): `graph` — новая редакция графа его убрала. */
30
+ export declare const cancelActors: readonly ["operator", "host", "graph"];
31
+ export type CancelActor = (typeof cancelActors)[number];
32
+ /** Кто сдвинул ref базы (`base.moved`): `host` — хост не назвал актёра. */
33
+ export declare const baseMoveActors: readonly ["operator", "controller", "host"];
34
+ export type BaseMoveActor = (typeof baseMoveActors)[number];
2
35
  /** Предел имени стадии в событии `attempt.stage`. */
3
36
  export declare const STAGE_NAME_LIMIT = 300;
4
37
  /**
@@ -192,6 +225,48 @@ export declare const eventPayloads: {
192
225
  message: z.ZodString;
193
226
  blocked: z.ZodBoolean;
194
227
  }, z.core.$strict>;
228
+ /**
229
+ * Причина отказа попытки: пишется в той же транзакции, что `attempt.failed`
230
+ * (и `attempt.expired`, причина `lease-expired`). `counted` — отказ
231
+ * засчитан в предел попыток поручения. Текста отказа здесь нет.
232
+ */
233
+ readonly 'attempt.diagnosed': z.ZodObject<{
234
+ failureKind: z.ZodEnum<{
235
+ gate: "gate";
236
+ unknown: "unknown";
237
+ review: "review";
238
+ cancelled: "cancelled";
239
+ environment: "environment";
240
+ timeout: "timeout";
241
+ "provider-auth": "provider-auth";
242
+ stalled: "stalled";
243
+ "stale-base": "stale-base";
244
+ "empty-result": "empty-result";
245
+ unfinished: "unfinished";
246
+ "scope-violation": "scope-violation";
247
+ "review-protocol": "review-protocol";
248
+ merge: "merge";
249
+ budget: "budget";
250
+ "needs-lead": "needs-lead";
251
+ }>;
252
+ cause: z.ZodEnum<{
253
+ preflight: "preflight";
254
+ transport: "transport";
255
+ none: "none";
256
+ other: "other";
257
+ "provider-auth": "provider-auth";
258
+ stalled: "stalled";
259
+ shutdown: "shutdown";
260
+ "sandbox-launch": "sandbox-launch";
261
+ "sandbox-network": "sandbox-network";
262
+ "sandbox-filesystem": "sandbox-filesystem";
263
+ "sandbox-policy": "sandbox-policy";
264
+ "dependency-network": "dependency-network";
265
+ "provider-limit": "provider-limit";
266
+ "lease-expired": "lease-expired";
267
+ }>;
268
+ counted: z.ZodBoolean;
269
+ }, z.core.$strict>;
195
270
  readonly 'attempt.expired': z.ZodObject<{
196
271
  leaseUntil: z.ZodNumber;
197
272
  }, z.core.$strict>;
@@ -207,6 +282,34 @@ export declare const eventPayloads: {
207
282
  resultSha: z.ZodString;
208
283
  integrationSha: z.ZodString;
209
284
  }, z.core.$strict>;
285
+ /**
286
+ * Поручение возвращено в очередь повтором (`engine.retry`). `reset` —
287
+ * сброс исчерпанного предела; `spent` — засчитанных попыток до сброса
288
+ * (сброс обнуляет счётчик). Причины сброса нет: только её длина.
289
+ */
290
+ readonly 'work.retried': z.ZodObject<{
291
+ by: z.ZodEnum<{
292
+ operator: "operator";
293
+ recovery: "recovery";
294
+ host: "host";
295
+ }>;
296
+ reset: z.ZodBoolean;
297
+ spent: z.ZodOptional<z.ZodNumber>;
298
+ reasonLength: z.ZodOptional<z.ZodNumber>;
299
+ }, z.core.$strict>;
300
+ /**
301
+ * Поручение отменено (`engine.cancel` или новая редакция графа).
302
+ * `hadAttempt` — отменена и активная попытка (её `attempt.cancelled` — в
303
+ * той же транзакции).
304
+ */
305
+ readonly 'work.cancelled': z.ZodObject<{
306
+ by: z.ZodEnum<{
307
+ operator: "operator";
308
+ graph: "graph";
309
+ host: "host";
310
+ }>;
311
+ hadAttempt: z.ZodBoolean;
312
+ }, z.core.$strict>;
210
313
  readonly 'work.blocked': z.ZodObject<{
211
314
  code: z.ZodString;
212
315
  message: z.ZodString;
@@ -250,6 +353,17 @@ export declare const eventPayloads: {
250
353
  readonly 'controller.acquired': z.ZodObject<{
251
354
  owner: z.ZodString;
252
355
  }, z.core.$strict>;
356
+ /**
357
+ * Ref базы сдвинут (`fencedRefMove`) — в той же транзакции, что проверка
358
+ * владения и `git update-ref`. Одно событие на репозиторий.
359
+ */
360
+ readonly 'base.moved': z.ZodObject<{
361
+ by: z.ZodEnum<{
362
+ operator: "operator";
363
+ controller: "controller";
364
+ host: "host";
365
+ }>;
366
+ }, z.core.$strict>;
253
367
  readonly 'controller.released': z.ZodObject<{
254
368
  owner: z.ZodString;
255
369
  }, z.core.$strict>;
@@ -436,7 +550,7 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
436
550
  workId: z.ZodOptional<z.ZodString>;
437
551
  runId: z.ZodOptional<z.ZodString>;
438
552
  attempt: z.ZodOptional<z.ZodNumber>;
439
- type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
553
+ type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.diagnosed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.retried" | "work.cancelled" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "base.moved" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
440
554
  payload: z.ZodObject<{
441
555
  digest: z.ZodString;
442
556
  orders: z.ZodNumber;
@@ -598,6 +712,42 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
598
712
  }>;
599
713
  message: z.ZodString;
600
714
  blocked: z.ZodBoolean;
715
+ }, z.core.$strict> | z.ZodObject<{
716
+ failureKind: z.ZodEnum<{
717
+ gate: "gate";
718
+ unknown: "unknown";
719
+ review: "review";
720
+ cancelled: "cancelled";
721
+ environment: "environment";
722
+ timeout: "timeout";
723
+ "provider-auth": "provider-auth";
724
+ stalled: "stalled";
725
+ "stale-base": "stale-base";
726
+ "empty-result": "empty-result";
727
+ unfinished: "unfinished";
728
+ "scope-violation": "scope-violation";
729
+ "review-protocol": "review-protocol";
730
+ merge: "merge";
731
+ budget: "budget";
732
+ "needs-lead": "needs-lead";
733
+ }>;
734
+ cause: z.ZodEnum<{
735
+ preflight: "preflight";
736
+ transport: "transport";
737
+ none: "none";
738
+ other: "other";
739
+ "provider-auth": "provider-auth";
740
+ stalled: "stalled";
741
+ shutdown: "shutdown";
742
+ "sandbox-launch": "sandbox-launch";
743
+ "sandbox-network": "sandbox-network";
744
+ "sandbox-filesystem": "sandbox-filesystem";
745
+ "sandbox-policy": "sandbox-policy";
746
+ "dependency-network": "dependency-network";
747
+ "provider-limit": "provider-limit";
748
+ "lease-expired": "lease-expired";
749
+ }>;
750
+ counted: z.ZodBoolean;
601
751
  }, z.core.$strict> | z.ZodObject<{
602
752
  leaseUntil: z.ZodNumber;
603
753
  }, z.core.$strict> | z.ZodObject<{
@@ -609,6 +759,22 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
609
759
  }, z.core.$strict> | z.ZodObject<{
610
760
  resultSha: z.ZodString;
611
761
  integrationSha: z.ZodString;
762
+ }, z.core.$strict> | z.ZodObject<{
763
+ by: z.ZodEnum<{
764
+ operator: "operator";
765
+ recovery: "recovery";
766
+ host: "host";
767
+ }>;
768
+ reset: z.ZodBoolean;
769
+ spent: z.ZodOptional<z.ZodNumber>;
770
+ reasonLength: z.ZodOptional<z.ZodNumber>;
771
+ }, z.core.$strict> | z.ZodObject<{
772
+ by: z.ZodEnum<{
773
+ operator: "operator";
774
+ graph: "graph";
775
+ host: "host";
776
+ }>;
777
+ hadAttempt: z.ZodBoolean;
612
778
  }, z.core.$strict> | z.ZodObject<{
613
779
  code: z.ZodString;
614
780
  message: z.ZodString;
@@ -648,6 +814,12 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
648
814
  }>;
649
815
  }, z.core.$strict> | z.ZodObject<{
650
816
  owner: z.ZodString;
817
+ }, z.core.$strict> | z.ZodObject<{
818
+ by: z.ZodEnum<{
819
+ operator: "operator";
820
+ controller: "controller";
821
+ host: "host";
822
+ }>;
651
823
  }, z.core.$strict> | z.ZodObject<{
652
824
  owner: z.ZodString;
653
825
  }, z.core.$strict> | z.ZodObject<{
@@ -790,7 +962,7 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
790
962
  workId: z.ZodOptional<z.ZodString>;
791
963
  runId: z.ZodOptional<z.ZodString>;
792
964
  attempt: z.ZodOptional<z.ZodNumber>;
793
- type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
965
+ type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.diagnosed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.retried" | "work.cancelled" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "base.moved" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
794
966
  payload: z.ZodObject<{
795
967
  digest: z.ZodString;
796
968
  orders: z.ZodNumber;
@@ -952,6 +1124,42 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
952
1124
  }>;
953
1125
  message: z.ZodString;
954
1126
  blocked: z.ZodBoolean;
1127
+ }, z.core.$strict> | z.ZodObject<{
1128
+ failureKind: z.ZodEnum<{
1129
+ gate: "gate";
1130
+ unknown: "unknown";
1131
+ review: "review";
1132
+ cancelled: "cancelled";
1133
+ environment: "environment";
1134
+ timeout: "timeout";
1135
+ "provider-auth": "provider-auth";
1136
+ stalled: "stalled";
1137
+ "stale-base": "stale-base";
1138
+ "empty-result": "empty-result";
1139
+ unfinished: "unfinished";
1140
+ "scope-violation": "scope-violation";
1141
+ "review-protocol": "review-protocol";
1142
+ merge: "merge";
1143
+ budget: "budget";
1144
+ "needs-lead": "needs-lead";
1145
+ }>;
1146
+ cause: z.ZodEnum<{
1147
+ preflight: "preflight";
1148
+ transport: "transport";
1149
+ none: "none";
1150
+ other: "other";
1151
+ "provider-auth": "provider-auth";
1152
+ stalled: "stalled";
1153
+ shutdown: "shutdown";
1154
+ "sandbox-launch": "sandbox-launch";
1155
+ "sandbox-network": "sandbox-network";
1156
+ "sandbox-filesystem": "sandbox-filesystem";
1157
+ "sandbox-policy": "sandbox-policy";
1158
+ "dependency-network": "dependency-network";
1159
+ "provider-limit": "provider-limit";
1160
+ "lease-expired": "lease-expired";
1161
+ }>;
1162
+ counted: z.ZodBoolean;
955
1163
  }, z.core.$strict> | z.ZodObject<{
956
1164
  leaseUntil: z.ZodNumber;
957
1165
  }, z.core.$strict> | z.ZodObject<{
@@ -963,6 +1171,22 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
963
1171
  }, z.core.$strict> | z.ZodObject<{
964
1172
  resultSha: z.ZodString;
965
1173
  integrationSha: z.ZodString;
1174
+ }, z.core.$strict> | z.ZodObject<{
1175
+ by: z.ZodEnum<{
1176
+ operator: "operator";
1177
+ recovery: "recovery";
1178
+ host: "host";
1179
+ }>;
1180
+ reset: z.ZodBoolean;
1181
+ spent: z.ZodOptional<z.ZodNumber>;
1182
+ reasonLength: z.ZodOptional<z.ZodNumber>;
1183
+ }, z.core.$strict> | z.ZodObject<{
1184
+ by: z.ZodEnum<{
1185
+ operator: "operator";
1186
+ graph: "graph";
1187
+ host: "host";
1188
+ }>;
1189
+ hadAttempt: z.ZodBoolean;
966
1190
  }, z.core.$strict> | z.ZodObject<{
967
1191
  code: z.ZodString;
968
1192
  message: z.ZodString;
@@ -1002,6 +1226,12 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1002
1226
  }>;
1003
1227
  }, z.core.$strict> | z.ZodObject<{
1004
1228
  owner: z.ZodString;
1229
+ }, z.core.$strict> | z.ZodObject<{
1230
+ by: z.ZodEnum<{
1231
+ operator: "operator";
1232
+ controller: "controller";
1233
+ host: "host";
1234
+ }>;
1005
1235
  }, z.core.$strict> | z.ZodObject<{
1006
1236
  owner: z.ZodString;
1007
1237
  }, z.core.$strict> | z.ZodObject<{
@@ -1174,7 +1404,7 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1174
1404
  workId: z.ZodOptional<z.ZodString>;
1175
1405
  runId: z.ZodOptional<z.ZodString>;
1176
1406
  attempt: z.ZodOptional<z.ZodNumber>;
1177
- type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
1407
+ type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.diagnosed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.retried" | "work.cancelled" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "base.moved" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
1178
1408
  payload: z.ZodObject<{
1179
1409
  digest: z.ZodString;
1180
1410
  orders: z.ZodNumber;
@@ -1336,6 +1566,42 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1336
1566
  }>;
1337
1567
  message: z.ZodString;
1338
1568
  blocked: z.ZodBoolean;
1569
+ }, z.core.$strict> | z.ZodObject<{
1570
+ failureKind: z.ZodEnum<{
1571
+ gate: "gate";
1572
+ unknown: "unknown";
1573
+ review: "review";
1574
+ cancelled: "cancelled";
1575
+ environment: "environment";
1576
+ timeout: "timeout";
1577
+ "provider-auth": "provider-auth";
1578
+ stalled: "stalled";
1579
+ "stale-base": "stale-base";
1580
+ "empty-result": "empty-result";
1581
+ unfinished: "unfinished";
1582
+ "scope-violation": "scope-violation";
1583
+ "review-protocol": "review-protocol";
1584
+ merge: "merge";
1585
+ budget: "budget";
1586
+ "needs-lead": "needs-lead";
1587
+ }>;
1588
+ cause: z.ZodEnum<{
1589
+ preflight: "preflight";
1590
+ transport: "transport";
1591
+ none: "none";
1592
+ other: "other";
1593
+ "provider-auth": "provider-auth";
1594
+ stalled: "stalled";
1595
+ shutdown: "shutdown";
1596
+ "sandbox-launch": "sandbox-launch";
1597
+ "sandbox-network": "sandbox-network";
1598
+ "sandbox-filesystem": "sandbox-filesystem";
1599
+ "sandbox-policy": "sandbox-policy";
1600
+ "dependency-network": "dependency-network";
1601
+ "provider-limit": "provider-limit";
1602
+ "lease-expired": "lease-expired";
1603
+ }>;
1604
+ counted: z.ZodBoolean;
1339
1605
  }, z.core.$strict> | z.ZodObject<{
1340
1606
  leaseUntil: z.ZodNumber;
1341
1607
  }, z.core.$strict> | z.ZodObject<{
@@ -1347,6 +1613,22 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1347
1613
  }, z.core.$strict> | z.ZodObject<{
1348
1614
  resultSha: z.ZodString;
1349
1615
  integrationSha: z.ZodString;
1616
+ }, z.core.$strict> | z.ZodObject<{
1617
+ by: z.ZodEnum<{
1618
+ operator: "operator";
1619
+ recovery: "recovery";
1620
+ host: "host";
1621
+ }>;
1622
+ reset: z.ZodBoolean;
1623
+ spent: z.ZodOptional<z.ZodNumber>;
1624
+ reasonLength: z.ZodOptional<z.ZodNumber>;
1625
+ }, z.core.$strict> | z.ZodObject<{
1626
+ by: z.ZodEnum<{
1627
+ operator: "operator";
1628
+ graph: "graph";
1629
+ host: "host";
1630
+ }>;
1631
+ hadAttempt: z.ZodBoolean;
1350
1632
  }, z.core.$strict> | z.ZodObject<{
1351
1633
  code: z.ZodString;
1352
1634
  message: z.ZodString;
@@ -1386,6 +1668,12 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1386
1668
  }>;
1387
1669
  }, z.core.$strict> | z.ZodObject<{
1388
1670
  owner: z.ZodString;
1671
+ }, z.core.$strict> | z.ZodObject<{
1672
+ by: z.ZodEnum<{
1673
+ operator: "operator";
1674
+ controller: "controller";
1675
+ host: "host";
1676
+ }>;
1389
1677
  }, z.core.$strict> | z.ZodObject<{
1390
1678
  owner: z.ZodString;
1391
1679
  }, z.core.$strict> | z.ZodObject<{
@@ -1528,7 +1816,7 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1528
1816
  workId: z.ZodOptional<z.ZodString>;
1529
1817
  runId: z.ZodOptional<z.ZodString>;
1530
1818
  attempt: z.ZodOptional<z.ZodNumber>;
1531
- type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
1819
+ type: z.ZodLiteral<"graph.registered" | "graph.reviewed" | "graph.approved" | "work.ready" | "work.held" | "attempt.claimed" | "attempt.phase" | "attempt.gate" | "attempt.review" | "attempt.stage" | "attempt.liveness" | "attempt.failed" | "attempt.diagnosed" | "attempt.expired" | "attempt.cancelled" | "attempt.recovered" | "work.accepted" | "work.retried" | "work.cancelled" | "work.blocked" | "control.paused" | "control.resumed" | "controller.acquired" | "base.moved" | "controller.released" | "budget.blocked" | "corpus.adopted" | "work.recovery" | "joint.started" | "joint.liveness" | "joint.finished" | "policy.applied" | "policy.reconfigure" | "delivery.pending" | "delivery.delivered" | "delivery.failed" | "delivery.conflict" | "delivery.uncertain">;
1532
1820
  payload: z.ZodObject<{
1533
1821
  digest: z.ZodString;
1534
1822
  orders: z.ZodNumber;
@@ -1690,6 +1978,42 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1690
1978
  }>;
1691
1979
  message: z.ZodString;
1692
1980
  blocked: z.ZodBoolean;
1981
+ }, z.core.$strict> | z.ZodObject<{
1982
+ failureKind: z.ZodEnum<{
1983
+ gate: "gate";
1984
+ unknown: "unknown";
1985
+ review: "review";
1986
+ cancelled: "cancelled";
1987
+ environment: "environment";
1988
+ timeout: "timeout";
1989
+ "provider-auth": "provider-auth";
1990
+ stalled: "stalled";
1991
+ "stale-base": "stale-base";
1992
+ "empty-result": "empty-result";
1993
+ unfinished: "unfinished";
1994
+ "scope-violation": "scope-violation";
1995
+ "review-protocol": "review-protocol";
1996
+ merge: "merge";
1997
+ budget: "budget";
1998
+ "needs-lead": "needs-lead";
1999
+ }>;
2000
+ cause: z.ZodEnum<{
2001
+ preflight: "preflight";
2002
+ transport: "transport";
2003
+ none: "none";
2004
+ other: "other";
2005
+ "provider-auth": "provider-auth";
2006
+ stalled: "stalled";
2007
+ shutdown: "shutdown";
2008
+ "sandbox-launch": "sandbox-launch";
2009
+ "sandbox-network": "sandbox-network";
2010
+ "sandbox-filesystem": "sandbox-filesystem";
2011
+ "sandbox-policy": "sandbox-policy";
2012
+ "dependency-network": "dependency-network";
2013
+ "provider-limit": "provider-limit";
2014
+ "lease-expired": "lease-expired";
2015
+ }>;
2016
+ counted: z.ZodBoolean;
1693
2017
  }, z.core.$strict> | z.ZodObject<{
1694
2018
  leaseUntil: z.ZodNumber;
1695
2019
  }, z.core.$strict> | z.ZodObject<{
@@ -1701,6 +2025,22 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1701
2025
  }, z.core.$strict> | z.ZodObject<{
1702
2026
  resultSha: z.ZodString;
1703
2027
  integrationSha: z.ZodString;
2028
+ }, z.core.$strict> | z.ZodObject<{
2029
+ by: z.ZodEnum<{
2030
+ operator: "operator";
2031
+ recovery: "recovery";
2032
+ host: "host";
2033
+ }>;
2034
+ reset: z.ZodBoolean;
2035
+ spent: z.ZodOptional<z.ZodNumber>;
2036
+ reasonLength: z.ZodOptional<z.ZodNumber>;
2037
+ }, z.core.$strict> | z.ZodObject<{
2038
+ by: z.ZodEnum<{
2039
+ operator: "operator";
2040
+ graph: "graph";
2041
+ host: "host";
2042
+ }>;
2043
+ hadAttempt: z.ZodBoolean;
1704
2044
  }, z.core.$strict> | z.ZodObject<{
1705
2045
  code: z.ZodString;
1706
2046
  message: z.ZodString;
@@ -1740,6 +2080,12 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1740
2080
  }>;
1741
2081
  }, z.core.$strict> | z.ZodObject<{
1742
2082
  owner: z.ZodString;
2083
+ }, z.core.$strict> | z.ZodObject<{
2084
+ by: z.ZodEnum<{
2085
+ operator: "operator";
2086
+ controller: "controller";
2087
+ host: "host";
2088
+ }>;
1743
2089
  }, z.core.$strict> | z.ZodObject<{
1744
2090
  owner: z.ZodString;
1745
2091
  }, z.core.$strict> | z.ZodObject<{
@@ -7,6 +7,35 @@ 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
+ /**
11
+ * Причина отказа окружения (`attempt.diagnosed`): ставится в точке
12
+ * обнаружения (песочница gate, сеть установки зависимостей, провайдер,
13
+ * транспорт), а не разбором текста потом. `none` — отказ не окружения
14
+ * (код, ревью, область); `other` — отказ окружения без известной причины.
15
+ */
16
+ export const environmentCauses = [
17
+ 'sandbox-launch',
18
+ 'sandbox-network',
19
+ 'sandbox-filesystem',
20
+ 'sandbox-policy',
21
+ 'dependency-network',
22
+ 'provider-auth',
23
+ 'provider-limit',
24
+ 'transport',
25
+ 'preflight',
26
+ 'lease-expired',
27
+ 'stalled',
28
+ 'shutdown',
29
+ 'other',
30
+ 'none',
31
+ ];
32
+ export const environmentCauseSchema = z.enum(environmentCauses);
33
+ /** Кто повторил поручение (`work.retried`): `host` — хост не назвал актёра. */
34
+ export const retryActors = ['operator', 'recovery', 'host'];
35
+ /** Кто отменил поручение (`work.cancelled`): `graph` — новая редакция графа его убрала. */
36
+ export const cancelActors = ['operator', 'host', 'graph'];
37
+ /** Кто сдвинул ref базы (`base.moved`): `host` — хост не назвал актёра. */
38
+ export const baseMoveActors = ['operator', 'controller', 'host'];
10
39
  /** Предел имени стадии в событии `attempt.stage`. */
11
40
  export const STAGE_NAME_LIMIT = 300;
12
41
  const delivery = {
@@ -129,6 +158,16 @@ export const eventPayloads = {
129
158
  message: text,
130
159
  blocked: z.boolean(),
131
160
  }),
161
+ /**
162
+ * Причина отказа попытки: пишется в той же транзакции, что `attempt.failed`
163
+ * (и `attempt.expired`, причина `lease-expired`). `counted` — отказ
164
+ * засчитан в предел попыток поручения. Текста отказа здесь нет.
165
+ */
166
+ 'attempt.diagnosed': z.strictObject({
167
+ failureKind: failureKindSchema,
168
+ cause: environmentCauseSchema,
169
+ counted: z.boolean(),
170
+ }),
132
171
  'attempt.expired': z.strictObject({ leaseUntil: z.number().int().min(0) }),
133
172
  'attempt.cancelled': z.strictObject({ reason: text }),
134
173
  'attempt.recovered': z.strictObject({
@@ -137,6 +176,23 @@ export const eventPayloads = {
137
176
  reason: text.optional(),
138
177
  }),
139
178
  'work.accepted': z.strictObject({ resultSha: sha, integrationSha: sha }),
179
+ /**
180
+ * Поручение возвращено в очередь повтором (`engine.retry`). `reset` —
181
+ * сброс исчерпанного предела; `spent` — засчитанных попыток до сброса
182
+ * (сброс обнуляет счётчик). Причины сброса нет: только её длина.
183
+ */
184
+ 'work.retried': z.strictObject({
185
+ by: z.enum(retryActors),
186
+ reset: z.boolean(),
187
+ spent: z.number().int().min(0).optional(),
188
+ reasonLength: z.number().int().min(0).optional(),
189
+ }),
190
+ /**
191
+ * Поручение отменено (`engine.cancel` или новая редакция графа).
192
+ * `hadAttempt` — отменена и активная попытка (её `attempt.cancelled` — в
193
+ * той же транзакции).
194
+ */
195
+ 'work.cancelled': z.strictObject({ by: z.enum(cancelActors), hadAttempt: z.boolean() }),
140
196
  'work.blocked': z.strictObject({ code: z.string().min(1).max(60), message: text }),
141
197
  'control.paused': z.strictObject({
142
198
  reason: z.enum(['operator', 'shutdown', 'runtime', 'base-check', 'reconfigure']),
@@ -146,6 +202,11 @@ export const eventPayloads = {
146
202
  reason: z.enum(['operator', 'shutdown', 'runtime', 'base-check', 'reconfigure']),
147
203
  }),
148
204
  'controller.acquired': z.strictObject({ owner: z.string().min(1).max(300) }),
205
+ /**
206
+ * Ref базы сдвинут (`fencedRefMove`) — в той же транзакции, что проверка
207
+ * владения и `git update-ref`. Одно событие на репозиторий.
208
+ */
209
+ 'base.moved': z.strictObject({ by: z.enum(baseMoveActors) }),
149
210
  'controller.released': z.strictObject({ owner: z.string().min(1).max(300) }),
150
211
  'budget.blocked': z.strictObject({
151
212
  scope: z.enum(['work', 'group', 'total']),
@@ -333,8 +394,8 @@ export const transactionKinds = [
333
394
  'workspace.failed',
334
395
  'workspace.liveness',
335
396
  /**
336
- * Сдвиг ref базы операцией внутри транзакции проверки её владения: только
337
- * проверка и синхронный `git update-ref`, записей и событий нет.
397
+ * Сдвиг ref базы внутри транзакции проверки владения: проверка, синхронный
398
+ * `git update-ref` и событие `base.moved`; записей нет.
338
399
  */
339
400
  'base.moved',
340
401
  /** Только локальные записи технической очереди (`workflow-jobs`); событий журнала нет. */
@@ -1,4 +1,5 @@
1
1
  import type { FailureKind } from './execution.ts';
2
+ import type { EnvironmentCause } from './events.ts';
2
3
  /** Отказ окружения до начала работы: попытка не засчитывается. */
3
4
  export declare class BlockedError extends Error {
4
5
  name: string;
@@ -22,6 +23,8 @@ export declare class TaskFailure extends Error {
22
23
  inputClass: string;
23
24
  }[];
24
25
  } | undefined;
26
+ /** Причина отказа окружения, известная в точке обнаружения (`attempt.diagnosed`). */
27
+ readonly diagnosis?: EnvironmentCause | undefined;
25
28
  constructor(kind: FailureKind, message: string,
26
29
  /**
27
30
  * Свойства, с которыми связан отказ: `bound` — объявленные задачей
@@ -38,7 +41,9 @@ export declare class TaskFailure extends Error {
38
41
  property: string;
39
42
  inputClass: string;
40
43
  }[];
41
- } | undefined);
44
+ } | undefined,
45
+ /** Причина отказа окружения, известная в точке обнаружения (`attempt.diagnosed`). */
46
+ diagnosis?: EnvironmentCause | undefined);
42
47
  }
43
48
  /**
44
49
  * Отпечаток отказа: одинаковые сбои должны совпадать, разные — расходиться.
@@ -7,6 +7,7 @@ export class BlockedError extends Error {
7
7
  export class TaskFailure extends Error {
8
8
  kind;
9
9
  properties;
10
+ diagnosis;
10
11
  constructor(kind, message,
11
12
  /**
12
13
  * Свойства, с которыми связан отказ: `bound` — объявленные задачей
@@ -15,10 +16,13 @@ export class TaskFailure extends Error {
15
16
  * `classes` — классы входов, названные ревьюером; `pairs` — свойство и
16
17
  * класс одной находки.
17
18
  */
18
- properties) {
19
+ properties,
20
+ /** Причина отказа окружения, известная в точке обнаружения (`attempt.diagnosed`). */
21
+ diagnosis) {
19
22
  super(message);
20
23
  this.kind = kind;
21
24
  this.properties = properties;
25
+ this.diagnosis = diagnosis;
22
26
  this.name = 'TaskFailure';
23
27
  }
24
28
  }
@@ -45,6 +45,13 @@ export declare const HANDOFF_LIMITS: {
45
45
  };
46
46
  /** Предел сериализованного пакета (JSON, UTF-8). */
47
47
  export declare const HANDOFF_MAX_BYTES: number;
48
+ /**
49
+ * Наименьший предел, который хост может задать пакету (`maxBytes` у
50
+ * `handoffPack`): ниже него не помещается даже обычный минимальный пакет.
51
+ * Это не гарантия: записи, которые не отбрасываются (сводка, очередь, идущие
52
+ * попытки, задания, следующий шаг), могут не уложиться и в больший предел.
53
+ */
54
+ export declare const HANDOFF_MIN_BYTES: number;
48
55
  export declare const handoffNextSteps: readonly ["accepted", "cancelled", "recovery-awaiting-lead", "recovery-analyzing", "recovery-applying", "recovery-retry-allowed", "recovery-retrying", "recovery-awaiting-user", "recovery-stopped", "corpus-adoption", "held", "plan-review", "attempt-running", "retry-within-budget", "attempts-exhausted", "awaiting-claim"];
49
56
  /** Команда harness, которая выполняет следующий шаг, когда он — запуск команды. */
50
57
  export declare const handoffCommands: readonly ["harness run", "harness resume"];
@@ -685,6 +692,7 @@ export declare const handoffPackSchema: z.ZodObject<{
685
692
  unfinished: z.ZodNumber;
686
693
  budgets: z.ZodNumber;
687
694
  budgetsWithin: z.ZodNumber;
695
+ budgetsShared: z.ZodDefault<z.ZodNumber>;
688
696
  repairs: z.ZodNumber;
689
697
  intentions: z.ZodNumber;
690
698
  intentionsDropped: z.ZodNumber;