devcontour-harness 0.1.0-alpha.45 → 0.1.0-alpha.47

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 (53) hide show
  1. package/README.md +20 -2
  2. package/docs/architecture.md +8 -0
  3. package/docs/compatibility.md +4 -1
  4. package/docs/contracts.md +25 -5
  5. package/docs/release-notes/0.1.0-alpha.46.md +63 -0
  6. package/docs/release-notes/0.1.0-alpha.47.md +138 -0
  7. package/docs/upgrade.md +119 -19
  8. package/lib/agents/review-probe.js +8 -3
  9. package/lib/contracts/cli.d.ts +11 -0
  10. package/lib/contracts/events.d.ts +13 -1
  11. package/lib/contracts/events.js +2 -0
  12. package/lib/contracts/execution.d.ts +1 -0
  13. package/lib/contracts/execution.js +13 -0
  14. package/lib/contracts/handoff.d.ts +1 -0
  15. package/lib/contracts/handoff.js +6 -1
  16. package/lib/contracts/ports.d.ts +54 -0
  17. package/lib/contracts/published.d.ts +8 -0
  18. package/lib/contracts/report.d.ts +4 -0
  19. package/lib/control/harness.d.ts +1 -1
  20. package/lib/control/workflow.d.ts +5 -1
  21. package/lib/control/workflow.js +18 -3
  22. package/lib/engine/classify.d.ts +6 -0
  23. package/lib/engine/classify.js +26 -0
  24. package/lib/engine/engine.d.ts +25 -2
  25. package/lib/engine/engine.js +76 -7
  26. package/lib/engine/runner.d.ts +11 -6
  27. package/lib/engine/runner.js +107 -34
  28. package/lib/environment/host-load.d.ts +12 -0
  29. package/lib/environment/host-load.js +7 -0
  30. package/lib/environment/lifecycle.d.ts +12 -1
  31. package/lib/environment/lifecycle.js +19 -2
  32. package/lib/environment/process.d.ts +71 -1
  33. package/lib/environment/process.js +149 -31
  34. package/lib/handoff/pack.js +7 -1
  35. package/lib/index.d.ts +5 -1
  36. package/lib/index.js +7 -1
  37. package/lib/report/document.js +2 -0
  38. package/lib/storage/sqlite.d.ts +47 -4
  39. package/lib/storage/sqlite.js +279 -34
  40. package/lib/testing/store-contract.d.ts +9 -0
  41. package/lib/testing/store-contract.js +235 -0
  42. package/lib/verification/applicability.d.ts +25 -2
  43. package/lib/verification/applicability.js +34 -1
  44. package/lib/verification/gates-at.js +15 -1
  45. package/lib/verification/gates.d.ts +3 -10
  46. package/lib/verification/gates.js +136 -15
  47. package/lib/verification/reaped.d.ts +24 -0
  48. package/lib/verification/reaped.js +24 -0
  49. package/package.json +1 -1
  50. package/schemas/execution-document.schema.json +4 -0
  51. package/schemas/handoff-pack.schema.json +4 -0
  52. package/schemas/run-event.schema.json +2 -0
  53. package/schemas/value-report.schema.json +3 -1
@@ -11,7 +11,8 @@ import { idSchema, relativePathSchema, sha256, TaskFailure, gateTimeoutMs, } fro
11
11
  import { dependencyNetworkFailure, dependencyNetworkMessage, } from "../environment/dependency-network.js";
12
12
  import { osToolEnv } from "../environment/os-tools.js";
13
13
  import { redactor } from "../environment/redaction.js";
14
- import { completedCheck, freshnessEnv, propertyReportEnv, junitSummary, runCheck, sandboxBlockedHosts, } from "../verification/gates.js";
14
+ import { completedCheck, freshnessEnv, propertyReportEnv, junitSummary, reapedFailure, runCheck, sandboxBlockedHosts, } from "../verification/gates.js";
15
+ import { ReapFailure } from "../environment/process.js";
15
16
  /**
16
17
  * Пробные проверки reviewer под пределами harness.
17
18
  *
@@ -339,7 +340,9 @@ export class ReviewProbes {
339
340
  exitCode: done.timedOut || signal.aborted ? null : done.code,
340
341
  stdout: tail(done.stdout),
341
342
  stderr: tail(done.stderr),
342
- note: 'Проверка завершилась, но controller не убрал её временные каталоги — отказ среды после исхода: ' +
343
+ note: (error instanceof ReapFailure
344
+ ? 'Проверка завершилась, но её потомки не остановлены или не пересчитаны — отказ среды после исхода: '
345
+ : 'Проверка завершилась, но controller не убрал её временные каталоги — отказ среды после исхода: ') +
343
346
  message,
344
347
  }
345
348
  : signal.aborted && !launch.started
@@ -665,7 +668,9 @@ export class ReviewProbes {
665
668
  // процесса: код и вывод завершившейся проверки остаются в результате.
666
669
  outcome = launch.started
667
670
  ? {
668
- ...environment(`Gate запустился, но его evidence не сохранено: ${message}.`),
671
+ ...environment(reapedFailure(error)
672
+ ? `Gate завершился, но его потомки не остановлены или не пересчитаны: ${message}.`
673
+ : `Gate запустился, но его evidence не сохранено: ${message}.`),
669
674
  ...((finished ??= completedCheck(error))
670
675
  ? {
671
676
  exitCode: finished.timedOut || signal.aborted ? null : finished.code,
@@ -1449,6 +1449,8 @@ export declare const eventsDataSchema: z.ZodObject<{
1449
1449
  "dependency-network": "dependency-network";
1450
1450
  "provider-limit": "provider-limit";
1451
1451
  "lease-expired": "lease-expired";
1452
+ "process-reap": "process-reap";
1453
+ cleanup: "cleanup";
1452
1454
  }>;
1453
1455
  counted: z.ZodBoolean;
1454
1456
  }, z.core.$strict> | z.ZodObject<{
@@ -1948,6 +1950,8 @@ export declare const eventsDataSchema: z.ZodObject<{
1948
1950
  "dependency-network": "dependency-network";
1949
1951
  "provider-limit": "provider-limit";
1950
1952
  "lease-expired": "lease-expired";
1953
+ "process-reap": "process-reap";
1954
+ cleanup: "cleanup";
1951
1955
  }>;
1952
1956
  counted: z.ZodBoolean;
1953
1957
  }, z.core.$strict> | z.ZodObject<{
@@ -4273,6 +4277,8 @@ export declare const cliDataSchemas: {
4273
4277
  "dependency-network": "dependency-network";
4274
4278
  "provider-limit": "provider-limit";
4275
4279
  "lease-expired": "lease-expired";
4280
+ "process-reap": "process-reap";
4281
+ cleanup: "cleanup";
4276
4282
  }>;
4277
4283
  counted: z.ZodBoolean;
4278
4284
  }, z.core.$strict> | z.ZodObject<{
@@ -4772,6 +4778,8 @@ export declare const cliDataSchemas: {
4772
4778
  "dependency-network": "dependency-network";
4773
4779
  "provider-limit": "provider-limit";
4774
4780
  "lease-expired": "lease-expired";
4781
+ "process-reap": "process-reap";
4782
+ cleanup: "cleanup";
4775
4783
  }>;
4776
4784
  counted: z.ZodBoolean;
4777
4785
  }, z.core.$strict> | z.ZodObject<{
@@ -7146,6 +7154,8 @@ export declare const cliDataSchemas: {
7146
7154
  "dependency-network": "dependency-network";
7147
7155
  "provider-limit": "provider-limit";
7148
7156
  "lease-expired": "lease-expired";
7157
+ "process-reap": "process-reap";
7158
+ cleanup: "cleanup";
7149
7159
  }>;
7150
7160
  count: z.ZodNumber;
7151
7161
  counted: z.ZodNumber;
@@ -7840,6 +7850,7 @@ export declare const cliDataSchemas: {
7840
7850
  }, z.core.$strict>>;
7841
7851
  repairs: z.ZodArray<z.ZodObject<{
7842
7852
  graphId: z.ZodString;
7853
+ key: z.ZodOptional<z.ZodString>;
7843
7854
  status: z.ZodString;
7844
7855
  used: z.ZodNumber;
7845
7856
  budget: z.ZodNumber;
@@ -5,7 +5,7 @@ import { z } from 'zod';
5
5
  * транспорт), а не разбором текста потом. `none` — отказ не окружения
6
6
  * (код, ревью, область); `other` — отказ окружения без известной причины.
7
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"];
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", "process-reap", "cleanup", "other", "none"];
9
9
  export declare const environmentCauseSchema: z.ZodEnum<{
10
10
  preflight: "preflight";
11
11
  transport: "transport";
@@ -21,6 +21,8 @@ export declare const environmentCauseSchema: z.ZodEnum<{
21
21
  "dependency-network": "dependency-network";
22
22
  "provider-limit": "provider-limit";
23
23
  "lease-expired": "lease-expired";
24
+ "process-reap": "process-reap";
25
+ cleanup: "cleanup";
24
26
  }>;
25
27
  export type EnvironmentCause = (typeof environmentCauses)[number];
26
28
  /** Кто повторил поручение (`work.retried`): `host` — хост не назвал актёра. */
@@ -269,6 +271,8 @@ export declare const eventPayloads: {
269
271
  "dependency-network": "dependency-network";
270
272
  "provider-limit": "provider-limit";
271
273
  "lease-expired": "lease-expired";
274
+ "process-reap": "process-reap";
275
+ cleanup: "cleanup";
272
276
  }>;
273
277
  counted: z.ZodBoolean;
274
278
  }, z.core.$strict>;
@@ -871,6 +875,8 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
871
875
  "dependency-network": "dependency-network";
872
876
  "provider-limit": "provider-limit";
873
877
  "lease-expired": "lease-expired";
878
+ "process-reap": "process-reap";
879
+ cleanup: "cleanup";
874
880
  }>;
875
881
  counted: z.ZodBoolean;
876
882
  }, z.core.$strict> | z.ZodObject<{
@@ -1370,6 +1376,8 @@ export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1370
1376
  "dependency-network": "dependency-network";
1371
1377
  "provider-limit": "provider-limit";
1372
1378
  "lease-expired": "lease-expired";
1379
+ "process-reap": "process-reap";
1380
+ cleanup: "cleanup";
1373
1381
  }>;
1374
1382
  counted: z.ZodBoolean;
1375
1383
  }, z.core.$strict> | z.ZodObject<{
@@ -1899,6 +1907,8 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
1899
1907
  "dependency-network": "dependency-network";
1900
1908
  "provider-limit": "provider-limit";
1901
1909
  "lease-expired": "lease-expired";
1910
+ "process-reap": "process-reap";
1911
+ cleanup: "cleanup";
1902
1912
  }>;
1903
1913
  counted: z.ZodBoolean;
1904
1914
  }, z.core.$strict> | z.ZodObject<{
@@ -2398,6 +2408,8 @@ export declare const readRunEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
2398
2408
  "dependency-network": "dependency-network";
2399
2409
  "provider-limit": "provider-limit";
2400
2410
  "lease-expired": "lease-expired";
2411
+ "process-reap": "process-reap";
2412
+ cleanup: "cleanup";
2401
2413
  }>;
2402
2414
  counted: z.ZodBoolean;
2403
2415
  }, z.core.$strict> | z.ZodObject<{
@@ -28,6 +28,8 @@ export const environmentCauses = [
28
28
  'lease-expired',
29
29
  'stalled',
30
30
  'shutdown',
31
+ 'process-reap',
32
+ 'cleanup',
31
33
  'other',
32
34
  'none',
33
35
  ];
@@ -4231,6 +4231,7 @@ export declare const executionDocumentSchema: z.ZodObject<{
4231
4231
  leaseUntil: z.ZodNumber;
4232
4232
  engineVersion: z.ZodOptional<z.ZodString>;
4233
4233
  }, z.core.$strict>>;
4234
+ leaseRows: z.ZodOptional<z.ZodLiteral<true>>;
4234
4235
  sequence: z.ZodNumber;
4235
4236
  }, z.core.$strict>;
4236
4237
  export type ExecutionDocument = z.infer<typeof executionDocumentSchema>;
@@ -999,8 +999,13 @@ export const workflowJobSchema = z.strictObject({
999
999
  token: z.string().optional(),
1000
1000
  leaseUntil: z.number().int().min(0).optional(),
1001
1001
  startedAt: isoTimeSchema,
1002
+ /**
1003
+ * Время окончания: `completed`, `failed`, `stale`. Повтор человека его
1004
+ * снимает. У заданий, остановленных прежними версиями, может отсутствовать.
1005
+ */
1002
1006
  finishedAt: isoTimeSchema.optional(),
1003
1007
  error: z.string().optional(),
1008
+ /** События стадий: захват (`running`), исход (`completed`, `failed`, `stale`, `queued`), восстановления. */
1004
1009
  history: z.array(z.strictObject({ at: isoTimeSchema, stage: z.number().int().min(0), event: z.string() })),
1005
1010
  });
1006
1011
  /* ------------------------------------------------------------------ */
@@ -1134,6 +1139,14 @@ export const executionDocumentSchema = z.strictObject({
1134
1139
  verifications: z.array(jointVerificationStateSchema).default([]),
1135
1140
  control: controlStateSchema,
1136
1141
  controller: controllerLeaseSchema.optional(),
1142
+ /**
1143
+ * Метка D53: сроки аренды активных попыток держат строки таблицы
1144
+ * `leases`, а `leaseUntil` попытки в документе — не источник (для отладки).
1145
+ * Прежние версии не знают поля и отказывают до любой записи (строгая
1146
+ * схема). Ставится первой строкой аренды вместе с переносом сроков всех
1147
+ * активных попыток; снимается шагом вниз (`stepDownLeases`).
1148
+ */
1149
+ leaseRows: z.literal(true).optional(),
1137
1150
  sequence: z.number().int().min(0),
1138
1151
  });
1139
1152
  /** Текст, который хранит fencing-токен, — проверка утечки в тестах и адаптерах. */
@@ -622,6 +622,7 @@ export declare const handoffPackSchema: z.ZodObject<{
622
622
  }, z.core.$strict>>;
623
623
  repairs: z.ZodArray<z.ZodObject<{
624
624
  graphId: z.ZodString;
625
+ key: z.ZodOptional<z.ZodString>;
625
626
  status: z.ZodString;
626
627
  used: z.ZodNumber;
627
628
  budget: z.ZodNumber;
@@ -267,10 +267,15 @@ export const handoffPackSchema = z.strictObject({
267
267
  })),
268
268
  })
269
269
  .optional(),
270
- /** Восстановления заданий графов: потрачено против бюджета. */
270
+ /**
271
+ * Восстановления заданий графов: потрачено против бюджета. `key` — ключ
272
+ * задания (у графа после новой редакции их несколько: прежнее — `stale`);
273
+ * `status` — статус задания. У пакетов прежних версий ключа нет.
274
+ */
271
275
  repairs: z
272
276
  .array(z.strictObject({
273
277
  graphId: idSchema,
278
+ key: digestSchema.optional(),
274
279
  status: z.string().max(40),
275
280
  used: count,
276
281
  budget: count,
@@ -25,6 +25,34 @@ export interface ExecutionView {
25
25
  activeAttempts?(): AttemptState[];
26
26
  verification(id: string): JointVerificationState | undefined;
27
27
  verifications(): JointVerificationState[];
28
+ /**
29
+ * Аренда активной попытки — строка хранилища (D53), без проекции всей
30
+ * попытки и без чтения документа. `undefined` — у попытки нет аренды
31
+ * (она не активна, строки нет или token строки не её). Необязательный
32
+ * метод: адаптер, у которого он есть, обязан иметь и `renewLease`,
33
+ * `dataVersion` — тогда продление идёт строкой (`activeLeases` — по
34
+ * желанию: движок его не вызывает).
35
+ *
36
+ * Продление строкой проверяет политику и guards полностью (`withAttempt`)
37
+ * не на каждом продлении, а когда сменилась `dataVersion` или с прошлой
38
+ * полной проверки прошёл `leaseMs`. Условие guard хоста, которое хранится
39
+ * вне записей с `dataVersion`, движок замечает не позже чем через
40
+ * ~`leaseMs + leaseMs/3` (интервал продления — `leaseMs/3`), а не на
41
+ * следующем продлении.
42
+ */
43
+ attemptLease?(id: string): AttemptLease | undefined;
44
+ /**
45
+ * Аренды активных попыток, ещё действующие в момент `at` (`leaseUntil > at`).
46
+ * Необязателен и движком не вызывается — для хоста и диагностики.
47
+ */
48
+ activeLeases?(at: number): AttemptLease[];
49
+ /**
50
+ * Счётчик версии данных: меняется при каждой фиксации, которая записала
51
+ * записи модели, локальные записи или события, и не меняется продлением
52
+ * аренды (`renewLease`). По нему движок решает, нужна ли продлению полная
53
+ * проверка политики и guards.
54
+ */
55
+ dataVersion?(): number;
28
56
  /**
29
57
  * Локальные записи исполнения, адресуемые `(namespace, owner, key)`.
30
58
  * Пространства и схемы — `localSchemas`; `owner` — репозиторий, за которым
@@ -53,6 +81,24 @@ export interface ExecutionTransaction extends ExecutionView {
53
81
  setController(lease: ControllerLease | undefined): void;
54
82
  putLocal<N extends LocalNamespace>(namespace: N, owner: string, key: string, value: LocalValue<N>): void;
55
83
  emit(event: RunEventDraft): void;
84
+ /**
85
+ * Условное продление одной строки аренды (D53): срок становится `until`,
86
+ * только если строка `(kind, id)` есть, её token, владелец и версия движка
87
+ * совпадают с переданными и срок ещё не истёк (`leaseUntil > now`).
88
+ * `true` — продлено. Записи модели, события и `dataVersion` не меняются.
89
+ * Истёкший срок не продлевается даже прежним token.
90
+ */
91
+ renewLease?(kind: LeaseKind, id: string, token: string, owner: string, engineVersion: string | undefined, until: number, now: number): boolean;
92
+ }
93
+ /** Вид аренды, которую хранилище держит строкой. Пока только попытки. */
94
+ export type LeaseKind = 'attempt';
95
+ /** Строка аренды попытки: кто держит попытку и до какого момента. */
96
+ export interface AttemptLease {
97
+ id: string;
98
+ token: string;
99
+ owner: string;
100
+ engineVersion: string | undefined;
101
+ leaseUntil: number;
56
102
  }
57
103
  /** Результат транзакции не может быть Promise: внутри нельзя ждать внешней работы. */
58
104
  export type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
@@ -72,6 +118,14 @@ export type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
72
118
  * - событие фиксируется вместе с транзакцией, даже если она не изменила
73
119
  * записей модели (только `emit` или только локальная запись и `emit`);
74
120
  * - `kind === 'heartbeat'` продлевает только сроки владения и не создаёт события;
121
+ * у адаптера со строками аренды (`renewLease`) продление попытки меняет
122
+ * только её строку: документ, записи модели и `dataVersion` прежние;
123
+ * - аренда попытки (D53): `putAttempt` активной попытки пишет её строку
124
+ * аренды (token, владелец, версия движка, `leaseUntil`) той же
125
+ * транзакцией, неактивной — удаляет; чтение попытки (`attempt`,
126
+ * `attempts`, `activeAttempts`) отдаёт срок из строки, пока token строки
127
+ * равен token попытки, а без такой строки у активной попытки срок 0
128
+ * (аренды нет). Правило «максимум строки и документа» не действует;
75
129
  * - внутри `fn` допустим один синхронный внешний эффект — CAS продвижения
76
130
  * target ref (`git update-ref <ref> <new> <old>`) при приёмке: он
77
131
  * выполняется до фиксации, и его отказ откатывает транзакцию. Падение
@@ -1916,6 +1916,8 @@ export declare const publishedSchemas: {
1916
1916
  "dependency-network": "dependency-network";
1917
1917
  "provider-limit": "provider-limit";
1918
1918
  "lease-expired": "lease-expired";
1919
+ "process-reap": "process-reap";
1920
+ cleanup: "cleanup";
1919
1921
  }>;
1920
1922
  counted: z.ZodBoolean;
1921
1923
  }, z.core.$strict> | z.ZodObject<{
@@ -2415,6 +2417,8 @@ export declare const publishedSchemas: {
2415
2417
  "dependency-network": "dependency-network";
2416
2418
  "provider-limit": "provider-limit";
2417
2419
  "lease-expired": "lease-expired";
2420
+ "process-reap": "process-reap";
2421
+ cleanup: "cleanup";
2418
2422
  }>;
2419
2423
  counted: z.ZodBoolean;
2420
2424
  }, z.core.$strict> | z.ZodObject<{
@@ -4102,6 +4106,7 @@ export declare const publishedSchemas: {
4102
4106
  leaseUntil: z.ZodNumber;
4103
4107
  engineVersion: z.ZodOptional<z.ZodString>;
4104
4108
  }, z.core.$strict>>;
4109
+ leaseRows: z.ZodOptional<z.ZodLiteral<true>>;
4105
4110
  sequence: z.ZodNumber;
4106
4111
  }, z.core.$strict>;
4107
4112
  readonly 'stack-profile': z.ZodObject<{
@@ -4994,6 +4999,8 @@ export declare const publishedSchemas: {
4994
4999
  "dependency-network": "dependency-network";
4995
5000
  "provider-limit": "provider-limit";
4996
5001
  "lease-expired": "lease-expired";
5002
+ "process-reap": "process-reap";
5003
+ cleanup: "cleanup";
4997
5004
  }>;
4998
5005
  count: z.ZodNumber;
4999
5006
  counted: z.ZodNumber;
@@ -5679,6 +5686,7 @@ export declare const publishedSchemas: {
5679
5686
  }, z.core.$strict>>;
5680
5687
  repairs: z.ZodArray<z.ZodObject<{
5681
5688
  graphId: z.ZodString;
5689
+ key: z.ZodOptional<z.ZodString>;
5682
5690
  status: z.ZodString;
5683
5691
  used: z.ZodNumber;
5684
5692
  budget: z.ZodNumber;
@@ -551,6 +551,8 @@ export declare const valueReportSchema: z.ZodObject<{
551
551
  "dependency-network": "dependency-network";
552
552
  "provider-limit": "provider-limit";
553
553
  "lease-expired": "lease-expired";
554
+ "process-reap": "process-reap";
555
+ cleanup: "cleanup";
554
556
  }>;
555
557
  count: z.ZodNumber;
556
558
  counted: z.ZodNumber;
@@ -1174,6 +1176,8 @@ export declare const reportDataSchema: z.ZodUnion<readonly [z.ZodObject<{
1174
1176
  "dependency-network": "dependency-network";
1175
1177
  "provider-limit": "provider-limit";
1176
1178
  "lease-expired": "lease-expired";
1179
+ "process-reap": "process-reap";
1180
+ cleanup: "cleanup";
1177
1181
  }>;
1178
1182
  count: z.ZodNumber;
1179
1183
  counted: z.ZodNumber;
@@ -3809,7 +3809,7 @@ export declare class Harness {
3809
3809
  timeLimit: number;
3810
3810
  causes: {
3811
3811
  rows: {
3812
- cause: "preflight" | "transport" | "none" | "other" | "provider-auth" | "stalled" | "shutdown" | "sandbox-launch" | "sandbox-network" | "sandbox-filesystem" | "sandbox-policy" | "dependency-network" | "provider-limit" | "lease-expired";
3812
+ cause: "preflight" | "transport" | "none" | "other" | "provider-auth" | "stalled" | "shutdown" | "sandbox-launch" | "sandbox-network" | "sandbox-filesystem" | "sandbox-policy" | "dependency-network" | "provider-limit" | "lease-expired" | "process-reap" | "cleanup";
3813
3813
  count: number;
3814
3814
  counted: number;
3815
3815
  }[];
@@ -221,7 +221,11 @@ export declare class WorkflowQueue {
221
221
  finishedAt?: string | undefined;
222
222
  error?: string | undefined;
223
223
  };
224
- /** Отказ стадии: прерванная — снова в очереди, изменившийся вход — `stale`, иначе `failed`. */
224
+ /**
225
+ * Отказ стадии: прерванная — снова в очереди, изменившийся вход — `stale`,
226
+ * иначе `failed`. Новый статус — событие истории; остановленное задание
227
+ * (`failed`, `stale`) получает время окончания.
228
+ */
225
229
  fail(job: WorkflowJob, message: string, interrupted?: boolean): void;
226
230
  /**
227
231
  * Записать восстановление и выполнить его одной транзакцией. Счётчик и само
@@ -166,6 +166,8 @@ export class WorkflowQueue {
166
166
  next.leaseUntil = this.now() + this.policy.leaseMs;
167
167
  next.attempts = job.attempts + 1;
168
168
  }
169
+ if (next.status !== 'running')
170
+ next.finishedAt = iso(this.now());
169
171
  next.history.push({ at: iso(this.now()), stage: job.stage, event: next.status });
170
172
  tx.putLocal('workflow-jobs', WorkflowQueue.owner(owner), key, next);
171
173
  return next.status === 'running' ? next : undefined;
@@ -232,16 +234,24 @@ export class WorkflowQueue {
232
234
  return next;
233
235
  });
234
236
  }
235
- /** Отказ стадии: прерванная — снова в очереди, изменившийся вход — `stale`, иначе `failed`. */
237
+ /**
238
+ * Отказ стадии: прерванная — снова в очереди, изменившийся вход — `stale`,
239
+ * иначе `failed`. Новый статус — событие истории; остановленное задание
240
+ * (`failed`, `stale`) получает время окончания.
241
+ */
236
242
  fail(job, message, interrupted = false) {
237
243
  this.store.transact('workflow.updated', (tx) => {
238
244
  const current = tx.local('workflow-jobs', WorkflowQueue.owner(job.owner), job.key);
239
245
  if (!current || current.token !== job.token || current.status !== 'running')
240
246
  return;
247
+ const at = iso(this.now());
248
+ const status = !this.current(job, tx) ? 'stale' : interrupted ? 'queued' : 'failed';
241
249
  const next = {
242
250
  ...current,
243
- status: !this.current(job, tx) ? 'stale' : interrupted ? 'queued' : 'failed',
251
+ status,
244
252
  error: message.slice(0, 1000),
253
+ history: [...current.history, { at, stage: current.stage, event: status }],
254
+ ...(status === 'queued' ? {} : { finishedAt: at }),
245
255
  };
246
256
  delete next.token;
247
257
  delete next.leaseUntil;
@@ -274,8 +284,13 @@ export class WorkflowQueue {
274
284
  throw new HarnessError('NOT_READY', 'Повтор задания недоступен; проверьте статус и попытки');
275
285
  if (!this.current(job, tx))
276
286
  throw new HarnessError('APPROVAL_STALE', 'Вход задания изменился: нужно новое задание');
277
- const next = { ...job, status: 'queued' };
287
+ const next = {
288
+ ...job,
289
+ status: 'queued',
290
+ history: [...job.history, { at: iso(this.now()), stage: job.stage, event: 'queued' }],
291
+ };
278
292
  delete next.error;
293
+ delete next.finishedAt;
279
294
  tx.putLocal('workflow-jobs', WorkflowQueue.owner(owner), key, next);
280
295
  return next;
281
296
  });
@@ -1,5 +1,11 @@
1
1
  import { BlockedError, type EnvironmentCause, type FailureKind } from '../contracts/index.ts';
2
2
  export { BlockedError };
3
+ /**
4
+ * Отказ, по которому судится попытка: у незавершённой очистки окружения —
5
+ * исходный отказ работы (`CleanupFailure.original`, через все вложенные
6
+ * очистки), иначе сам отказ.
7
+ */
8
+ export declare function failureOrigin(error: unknown): unknown;
3
9
  /**
4
10
  * Отказ провайдера, а не работы: он повторится на любой следующей выдаче.
5
11
  * Список узкий намеренно — временные ошибки сети сюда не входят.
@@ -1,5 +1,19 @@
1
1
  import { BlockedError, HarnessError, TaskFailure, } from "../contracts/index.js";
2
+ import { CleanupFailure } from "../environment/lifecycle.js";
3
+ import { ReapFailure } from "../environment/process.js";
4
+ import { ReapedGate } from "../verification/reaped.js";
2
5
  export { BlockedError };
6
+ /**
7
+ * Отказ, по которому судится попытка: у незавершённой очистки окружения —
8
+ * исходный отказ работы (`CleanupFailure.original`, через все вложенные
9
+ * очистки), иначе сам отказ.
10
+ */
11
+ export function failureOrigin(error) {
12
+ let origin = error;
13
+ while (origin instanceof CleanupFailure && origin.original)
14
+ origin = origin.original;
15
+ return origin;
16
+ }
3
17
  /**
4
18
  * Отказ провайдера, а не работы: он повторится на любой следующей выдаче.
5
19
  * Список узкий намеренно — временные ошибки сети сюда не входят.
@@ -22,6 +36,10 @@ const byCode = {
22
36
  BUDGET_EXHAUSTED: 'budget',
23
37
  };
24
38
  export function classifyFailure(error, message) {
39
+ // Незавершённая очистка не меняет класс отказа работы; без него это отказ
40
+ // окружения — ресурсы попытки не освобождены.
41
+ if (error instanceof CleanupFailure)
42
+ return error.original ? classifyFailure(error.original, message) : 'environment';
25
43
  if (error instanceof TaskFailure)
26
44
  return error.kind;
27
45
  // Приёмка отказала по правилу (нет доказательства, ревью, область): класс —
@@ -54,6 +72,8 @@ export function environmentCauseOf(error, message, kind) {
54
72
  return providerLimit(message) ? 'provider-limit' : 'provider-auth';
55
73
  if (kind !== 'environment')
56
74
  return 'none';
75
+ if (error instanceof CleanupFailure)
76
+ return error.original ? environmentCauseOf(error.original, message, kind) : 'cleanup';
57
77
  if (error instanceof TaskFailure && error.diagnosis)
58
78
  return error.diagnosis;
59
79
  if (transportFailure(message) ||
@@ -69,6 +89,12 @@ export function environmentCauseOf(error, message, kind) {
69
89
  * `Error` с исходным в `cause`.
70
90
  */
71
91
  export function withSuffix(failure, suffix) {
92
+ // Признак незавершённой очистки и неостановленных потомков сохраняется:
93
+ // по нему решаются сохранение деревьев и запрет повтора на дереве.
94
+ if (failure instanceof CleanupFailure ||
95
+ failure instanceof ReapedGate ||
96
+ failure instanceof ReapFailure)
97
+ return failure.extend(suffix);
72
98
  return failure instanceof TaskFailure
73
99
  ? new TaskFailure(failure.kind, `${failure.message}; ${suffix}`, failure.properties, failure.diagnosis, failure.contextLimit)
74
100
  : new Error(`${failure.message}; ${suffix}`, { cause: failure });
@@ -495,7 +495,10 @@ export declare class Engine {
495
495
  * Снять паузу — решение человека (семантика DevContour `pause(false)`):
496
496
  * снимает паузу оператора, штатной остановки и отказа runtime вместе с её
497
497
  * классами отказов. Паузу операции reconfigure снимает только сама
498
- * операция: `PAUSED`.
498
+ * операция: `PAUSED`. Это и явный маршрут человека «подтвердить базу и
499
+ * начать»: `resume` снимает ожидания `base-check`. Других путей снять их у
500
+ * движка нет — пока такое ожидание есть, `claim` не выдаёт работу при
501
+ * любом значении `paused`.
499
502
  */
500
503
  resume(): {
501
504
  control: {
@@ -527,7 +530,14 @@ export declare class Engine {
527
530
  };
528
531
  changed: boolean;
529
532
  };
530
- /** Снять паузу отказа после устранения причины: только названные классы. */
533
+ /**
534
+ * Снять паузу отказа после устранения причины: только названные классы.
535
+ * Пока есть ожидание `base-check`, пауза остаётся и переходит в паузу
536
+ * `base-check`: устранённый отказ не подтверждает перенесённую базу (это
537
+ * делает человек через `resume`), а пауза `runtime` без классов отказа
538
+ * звала бы чинить окружение. Новая причина — новая пауза: `pausedAt` —
539
+ * время перехода (как у перехода хоста DevContour).
540
+ */
531
541
  clearFailure(kinds: FailureKind[]): {
532
542
  paused: boolean;
533
543
  pauseReason?: "operator" | "runtime" | "shutdown" | "base-check" | "reconfigure" | undefined;
@@ -672,6 +682,19 @@ export declare class Engine {
672
682
  * поручения, политика не сменилась и хост не возражает.
673
683
  */
674
684
  withAttempt<T>(id: string, token: string, kind: TransactionKind, fn: (attempt: AttemptState, work: WorkState, tx: ExecutionTransaction) => NotPromise<T>): T;
685
+ /**
686
+ * Когда продление попытки последний раз проверяло политику и guards
687
+ * полностью: token, версия данных и момент проверки (D53).
688
+ */
689
+ private readonly leaseChecks;
690
+ /**
691
+ * Продление владения попыткой. У хранилища со строками аренды (D53) —
692
+ * условное продление одной строки: документ не читается и не пишется.
693
+ * Политика и guards, которые раньше проверяло каждое продление,
694
+ * проверяются полностью (`withAttempt`), когда сменилась версия данных
695
+ * или с прошлой полной проверки прошёл срок аренды: смена политики или
696
+ * отказ хоста по-прежнему прерывают идущую попытку.
697
+ */
675
698
  heartbeat(id: string, token: string): void;
676
699
  /** Причина неудавшегося продления: записывается первой и не затирается. Истёкший срок допустим, чужой токен — нет. */
677
700
  heartbeatFailed(id: string, token: string, reason: string): boolean;