devcontour-harness 0.1.0-alpha.44 → 0.1.0-alpha.46

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 (57) hide show
  1. package/README.md +20 -2
  2. package/docs/architecture.md +8 -0
  3. package/docs/contracts.md +122 -2
  4. package/docs/release-notes/0.1.0-alpha.45.md +77 -0
  5. package/docs/release-notes/0.1.0-alpha.46.md +63 -0
  6. package/docs/upgrade.md +98 -18
  7. package/lib/contracts/cli.d.ts +68 -0
  8. package/lib/contracts/cli.js +6 -1
  9. package/lib/contracts/events.d.ts +5 -0
  10. package/lib/contracts/events.js +2 -0
  11. package/lib/contracts/execution.d.ts +39 -0
  12. package/lib/contracts/execution.js +20 -2
  13. package/lib/contracts/handoff.d.ts +1 -0
  14. package/lib/contracts/handoff.js +6 -1
  15. package/lib/contracts/policy.d.ts +39 -0
  16. package/lib/contracts/policy.js +64 -0
  17. package/lib/contracts/profiles.d.ts +6 -0
  18. package/lib/contracts/published.d.ts +70 -0
  19. package/lib/contracts/result.d.ts +91 -0
  20. package/lib/contracts/result.js +31 -1
  21. package/lib/contracts/review.d.ts +1 -1
  22. package/lib/control/harness.d.ts +24 -2
  23. package/lib/control/workflow.d.ts +5 -1
  24. package/lib/control/workflow.js +18 -3
  25. package/lib/engine/engine.d.ts +30 -5
  26. package/lib/engine/engine.js +104 -13
  27. package/lib/engine/result.js +7 -3
  28. package/lib/engine/runner.d.ts +8 -0
  29. package/lib/engine/runner.js +96 -3
  30. package/lib/environment/git-trust.js +3 -0
  31. package/lib/environment/process.d.ts +2 -0
  32. package/lib/environment/process.js +7 -1
  33. package/lib/explain/state.js +1 -1
  34. package/lib/handoff/pack.js +7 -1
  35. package/lib/index.d.ts +1 -0
  36. package/lib/index.js +1 -0
  37. package/lib/integrations/connector/history.js +1 -1
  38. package/lib/integrations/connector/summary.js +2 -1
  39. package/lib/profiles/resolve.d.ts +6 -0
  40. package/lib/projections/attempt.d.ts +4 -2
  41. package/lib/projections/attempt.js +14 -1
  42. package/lib/report/compute.js +4 -3
  43. package/lib/storage/document.d.ts +26 -2
  44. package/lib/verification/acceptance.d.ts +12 -0
  45. package/lib/verification/acceptance.js +62 -7
  46. package/lib/verification/applicability.d.ts +157 -0
  47. package/lib/verification/applicability.js +406 -0
  48. package/lib/verification/gates.d.ts +6 -0
  49. package/lib/verification/proof.d.ts +18 -4
  50. package/lib/verification/proof.js +52 -9
  51. package/package.json +1 -1
  52. package/schemas/execution-document.schema.json +73 -1
  53. package/schemas/execution-policy.schema.json +38 -0
  54. package/schemas/handoff-pack.schema.json +4 -0
  55. package/schemas/result-envelope.schema.json +138 -2
  56. package/schemas/run-event.schema.json +4 -0
  57. package/schemas/run-result.schema.json +138 -2
@@ -478,7 +478,7 @@ export declare class DocumentView {
478
478
  evidence: {
479
479
  id: string;
480
480
  runId: string;
481
- kind: "review" | "test";
481
+ kind: "review" | "test" | "not-applicable";
482
482
  phase: "candidate" | "integration";
483
483
  sha: string;
484
484
  gate: string;
@@ -634,6 +634,18 @@ export declare class DocumentView {
634
634
  skippedMore?: number | undefined;
635
635
  } | undefined;
636
636
  checks?: string | undefined;
637
+ gateBasis?: string | undefined;
638
+ notApplicable?: {
639
+ gateDigest: string;
640
+ patterns: string[];
641
+ ranges: {
642
+ from: string;
643
+ to: string;
644
+ }[];
645
+ count: number;
646
+ files: string[];
647
+ pathsDigest: string;
648
+ } | undefined;
637
649
  alreadySatisfied?: {
638
650
  gates: string[];
639
651
  evidence: string;
@@ -838,7 +850,7 @@ export declare class DocumentView {
838
850
  evidence: {
839
851
  id: string;
840
852
  runId: string;
841
- kind: "review" | "test";
853
+ kind: "review" | "test" | "not-applicable";
842
854
  phase: "candidate" | "integration";
843
855
  sha: string;
844
856
  gate: string;
@@ -994,6 +1006,18 @@ export declare class DocumentView {
994
1006
  skippedMore?: number | undefined;
995
1007
  } | undefined;
996
1008
  checks?: string | undefined;
1009
+ gateBasis?: string | undefined;
1010
+ notApplicable?: {
1011
+ gateDigest: string;
1012
+ patterns: string[];
1013
+ ranges: {
1014
+ from: string;
1015
+ to: string;
1016
+ }[];
1017
+ count: number;
1018
+ files: string[];
1019
+ pathsDigest: string;
1020
+ } | undefined;
997
1021
  alreadySatisfied?: {
998
1022
  gates: string[];
999
1023
  evidence: string;
@@ -210,6 +210,18 @@ export declare const receiptTrust: {
210
210
  readonly 'evidence[].summary': readonly ["informative", "описание записи"];
211
211
  readonly 'evidence[].consumer': readonly ["expected", "объявленный потребитель"];
212
212
  readonly 'evidence[].checks': readonly ["expected", "версия проверок, вычисленная получателем, у каждой записи"];
213
+ readonly 'evidence[].notApplicable': readonly ["consistency", "только у записи not-applicable: обычный gate с when, не доказательство и не предпосылка исполненного"];
214
+ readonly 'evidence[].notApplicable.gateDigest': readonly ["expected", "digest определения gate у получателя"];
215
+ readonly 'evidence[].notApplicable.patterns': readonly ["informative", "пути when; их задаёт определение gate"];
216
+ readonly 'evidence[].notApplicable.patterns[]': readonly ["informative", "пути when; их задаёт определение gate"];
217
+ readonly 'evidence[].notApplicable.ranges': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
218
+ readonly 'evidence[].notApplicable.ranges[]': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
219
+ readonly 'evidence[].notApplicable.ranges[].from': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
220
+ readonly 'evidence[].notApplicable.ranges[].to': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
221
+ readonly 'evidence[].notApplicable.count': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
222
+ readonly 'evidence[].notApplicable.files': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
223
+ readonly 'evidence[].notApplicable.files[]': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
224
+ readonly 'evidence[].notApplicable.pathsDigest': readonly ["informative", "diff фазы — наблюдение Git исполнителя"];
213
225
  readonly 'evidence[].tests': readonly ["expected", "доказательство названного testcase решающей записью"];
214
226
  readonly 'evidence[].tests[]': readonly ["expected", "элемент названного testcase; прочие элементы — сведения"];
215
227
  readonly 'evidence[].tests[].id': readonly ["expected", "ID названного testcase"];
@@ -3,6 +3,7 @@ import { corpusBindingHolds, effectiveChecks, obligationOf, orderCheckManifest,
3
3
  import { manifestDigest } from "./property.js";
4
4
  import { unprovenReason } from "./proof.js";
5
5
  import { REQUIREMENT_GATE } from "./requirements.js";
6
+ import { notApplicableProblem, proofGates } from "./applicability.js";
6
7
  /** Решающая запись gate на фазе: последняя запись этой фазы, SHA и версии. */
7
8
  function decisive(input, phase, gate) {
8
9
  const sha = phase === 'candidate' ? input.candidateSha : input.resultSha;
@@ -236,6 +237,24 @@ export const receiptTrust = {
236
237
  'evidence[].summary': ['informative', 'описание записи'],
237
238
  'evidence[].consumer': ['expected', 'объявленный потребитель'],
238
239
  'evidence[].checks': ['expected', 'версия проверок, вычисленная получателем, у каждой записи'],
240
+ 'evidence[].notApplicable': [
241
+ 'consistency',
242
+ 'только у записи not-applicable: обычный gate с when, не доказательство и не предпосылка исполненного',
243
+ ],
244
+ 'evidence[].notApplicable.gateDigest': ['expected', 'digest определения gate у получателя'],
245
+ 'evidence[].notApplicable.patterns': ['informative', 'пути when; их задаёт определение gate'],
246
+ 'evidence[].notApplicable.patterns[]': ['informative', 'пути when; их задаёт определение gate'],
247
+ 'evidence[].notApplicable.ranges': ['informative', 'diff фазы — наблюдение Git исполнителя'],
248
+ 'evidence[].notApplicable.ranges[]': ['informative', 'diff фазы — наблюдение Git исполнителя'],
249
+ 'evidence[].notApplicable.ranges[].from': [
250
+ 'informative',
251
+ 'diff фазы — наблюдение Git исполнителя',
252
+ ],
253
+ 'evidence[].notApplicable.ranges[].to': ['informative', 'diff фазы — наблюдение Git исполнителя'],
254
+ 'evidence[].notApplicable.count': ['informative', 'diff фазы — наблюдение Git исполнителя'],
255
+ 'evidence[].notApplicable.files': ['informative', 'diff фазы — наблюдение Git исполнителя'],
256
+ 'evidence[].notApplicable.files[]': ['informative', 'diff фазы — наблюдение Git исполнителя'],
257
+ 'evidence[].notApplicable.pathsDigest': ['informative', 'diff фазы — наблюдение Git исполнителя'],
239
258
  'evidence[].tests': ['expected', 'доказательство названного testcase решающей записью'],
240
259
  'evidence[].tests[]': ['expected', 'элемент названного testcase; прочие элементы — сведения'],
241
260
  'evidence[].tests[].id': ['expected', 'ID названного testcase'],
@@ -415,13 +434,25 @@ export function resultProblems(result, context) {
415
434
  integrity.push(`запись ${e.id}: сведения о свойствах недопустимы у записи вида ${e.kind}`);
416
435
  if ((e.reviewer !== undefined) !== (e.kind === 'review'))
417
436
  integrity.push(`запись ${e.id}: сведения о reviewer не согласованы с видом записи`);
437
+ if ((e.notApplicable !== undefined) !== (e.kind === 'not-applicable'))
438
+ integrity.push(`запись ${e.id}: сведения о неприменимости не согласованы с видом записи`);
439
+ if (e.kind === 'not-applicable' && (e.passed || e.consumer !== undefined))
440
+ integrity.push(`запись ${e.id}: неприменимый gate не бывает PASS или проверкой потребителя`);
418
441
  }
419
442
  if (integrity.length)
420
443
  return integrity;
421
444
  const evidence = result.evidence
422
- .filter((e) => e.kind === 'test' || e.kind === 'review' || e.kind === 'consumer')
445
+ .filter((e) => e.kind === 'test' ||
446
+ e.kind === 'review' ||
447
+ e.kind === 'consumer' ||
448
+ e.kind === 'not-applicable')
423
449
  .map((e) => ({
424
- kind: e.kind === 'review' ? 'review' : 'test',
450
+ kind: e.kind === 'review'
451
+ ? 'review'
452
+ : e.kind === 'not-applicable'
453
+ ? 'not-applicable'
454
+ : 'test',
455
+ ...(e.notApplicable ? { notApplicable: e.notApplicable } : {}),
425
456
  phase: e.phase,
426
457
  gate: e.gate,
427
458
  sha: e.sha,
@@ -432,7 +463,7 @@ export function resultProblems(result, context) {
432
463
  tests: e.tests,
433
464
  testsTruncated: e.testsTruncated,
434
465
  }));
435
- const last = (kind, phase, gate, consumer) => evidence.findLast((e) => e.kind === kind &&
466
+ const last = (kind, phase, gate, consumer) => evidence.findLast((e) => (typeof kind === 'string' ? e.kind === kind : kind.includes(e.kind)) &&
436
467
  e.phase === phase &&
437
468
  e.gate === gate &&
438
469
  e.sha === sha(phase) &&
@@ -457,13 +488,37 @@ export function resultProblems(result, context) {
457
488
  if (declared && !sameSet(declared, own))
458
489
  problems.push(`область результата [${declared.join(', ')}] — ожидалась ровно [${own.join(', ')}]`);
459
490
  const required = [...new Set([...own, ...(gates.byGate?.keys() ?? [])])];
491
+ // Обычный gate с `when` закрывается и записью неприменимости
492
+ // (`notApplicableProblem` по политике получателя); доказательства
493
+ // требований и договоров — только PASS.
494
+ const named = proofGates(order, context.contracts);
460
495
  const decisiveAll = ['candidate', 'integration'].flatMap((phase) => [
461
- ...required.map((gate) => ({ phase, gate, check: last('test', phase, gate) })),
496
+ ...required.map((gate) => ({
497
+ phase,
498
+ gate,
499
+ // Исход исполнения решает всегда; неприменимость — только без него.
500
+ check: last('test', phase, gate) ??
501
+ (named.has(gate) ? undefined : last(['not-applicable'], phase, gate)),
502
+ })),
462
503
  { phase, gate: 'independent-review', check: last('review', phase, 'independent-review') },
463
504
  ]);
464
- for (const { phase, gate, check } of decisiveAll)
465
- if (!check?.passed)
466
- problems.push(`Нет PASS: ${phase}/${gate}`);
505
+ for (const { phase, gate, check } of decisiveAll) {
506
+ if (check?.passed)
507
+ continue;
508
+ const problem = check?.kind === 'not-applicable'
509
+ ? notApplicableProblem({
510
+ gates: repo.gates,
511
+ gate,
512
+ record: check,
513
+ proof: named,
514
+ ran: decisiveAll
515
+ .filter((d) => d.phase === phase && d.check?.kind === 'test')
516
+ .map((d) => d.gate),
517
+ })
518
+ : 'нет записи';
519
+ if (problem)
520
+ problems.push(`Нет PASS: ${phase}/${gate}` + (check?.kind === 'not-applicable' ? ': ' + problem : ''));
521
+ }
467
522
  // Ревью: writer — роли поручения в политике получателя; reviewer решающих
468
523
  // записей обеих фаз — тот, кого политика назначает этому writer, и правило
469
524
  // вендора соблюдено (тот же вендор — только явным разрешением). Для
@@ -0,0 +1,157 @@
1
+ import { type ExecutionPolicy, type ContractDocument, type AttemptState, type GateApplicability, type GatePolicy, type WorkOrder } from '../contracts/index.ts';
2
+ /**
3
+ * Применимость gate с `when.paths`. Решение принимает controller по
4
+ * настоящему diff фазы из Git, а не по заявлению исполнителя. Правило
5
+ * консервативное: всё, в чём нет уверенности, исполняет gate.
6
+ */
7
+ /** Изменённые пути фазы: объединение diff сравненных пар коммитов. */
8
+ export interface ChangedPaths {
9
+ ranges: {
10
+ from: string;
11
+ to: string;
12
+ }[];
13
+ /** Отсортированные уникальные пути; при `complete: false` — неполны. */
14
+ files: string[];
15
+ /** Diff прочитан целиком и не превысил предел. */
16
+ complete: boolean;
17
+ /** Почему diff неполон. */
18
+ problem?: string;
19
+ }
20
+ /**
21
+ * Регулярное выражение шаблона `when.paths`. `**` целым сегментом — любое
22
+ * число сегментов (и ни одного), `*` — любые символы внутри сегмента, `?` —
23
+ * один символ сегмента, `{a,b}` — варианты. Шаблон задевает и всё внутри
24
+ * совпавшего каталога: `src/ui` и `src/ui/` задевают `src/ui/a.ts`.
25
+ */
26
+ export declare function gatePathRegExp(pattern: string): RegExp;
27
+ /**
28
+ * Пути, которые задевает хотя бы один шаблон: совпадение glob или путь —
29
+ * каталог-предок буквального префикса шаблона (`vendor` для `vendor/lib/**`:
30
+ * файл или подмодуль на месте каталога шаблона).
31
+ */
32
+ export declare function matchingPaths(patterns: readonly string[], files: readonly string[]): string[];
33
+ /**
34
+ * Изменённые пути объединения пар `from..to` (`git diff --no-renames
35
+ * --name-only`: переименование — оба пути; удаление, смена режима и
36
+ * подмодуль — их пути). Ошибка Git или больше `gateApplicabilityLimits.changed`
37
+ * путей — `complete: false`, и gate исполняется.
38
+ */
39
+ export declare function changedPaths(cwd: string, ranges: {
40
+ from: string;
41
+ to: string;
42
+ }[]): Promise<ChangedPaths>;
43
+ /**
44
+ * Неявный вход gate, задетый изменением, или undefined: защищённые пути
45
+ * репозитория, каталог проекта harness, манифесты и lockfiles, файлы и
46
+ * каталоги, названные в команде gate.
47
+ */
48
+ export declare function implicitInput(repo: {
49
+ protectedPaths: readonly string[];
50
+ }, gate: Pick<GatePolicy, 'command' | 'cwd'>, files: readonly string[]): string | undefined;
51
+ /**
52
+ * Основание исполнения условного gate: его определение (`gateDigest`),
53
+ * описания его ресурсов, определения и ресурсы его предпосылок
54
+ * (`gatePrerequisites`, транзитивно), окружение, lifecycle, подготовка, хранилище
55
+ * зависимостей и toolchain репозитория, изоляция и версия harness. Зелёный
56
+ * SHA gate засчитывается только под тем же основанием: смена любого из них
57
+ * исполняет gate заново.
58
+ */
59
+ export declare function gateBasis(policy: Pick<ExecutionPolicy, 'resources' | 'environment' | 'lifecycle' | 'isolation'>, repo: Pick<ExecutionPolicy['repositories'][number], 'gates' | 'environment' | 'lifecycle' | 'prepare' | 'dependencyStore' | 'toolchain'>, gate: GatePolicy, harnessVersion: string): string;
60
+ /** Решение по одному gate с `when`: исполнять (с причиной) или нет (с записью). */
61
+ export type PathDecision = {
62
+ applies: true;
63
+ reason: string;
64
+ } | {
65
+ applies: false;
66
+ record: GateApplicability;
67
+ };
68
+ /** Применимость gate с `when` по diff (без правил области задачи). */
69
+ export declare function pathApplicability(repo: {
70
+ protectedPaths: readonly string[];
71
+ }, gate: GatePolicy, changed: ChangedPaths): PathDecision;
72
+ /**
73
+ * Gates, которые не бывают неприменимыми у поручения: источник требований,
74
+ * gates его требований и gates договоров проверки (свойства, эталоны,
75
+ * обязательства). Их доказательство — только исполнение.
76
+ */
77
+ export declare function proofGates(order: Pick<WorkOrder, 'requirements' | 'properties'>, contracts: readonly ContractDocument[]): Set<string>;
78
+ /** Снимок провайдера, против которого шла попытка (`AttemptState.dependencies`). */
79
+ export type ProviderSnapshot = Pick<NonNullable<AttemptState['dependencies']>[number], 'repositoryId' | 'sha'>;
80
+ /**
81
+ * Почему база провайдеров сдвинулась с зелёного SHA gate, или undefined.
82
+ * Провайдеры — `dependsOn` репозитория и все репозитории снимков (в том числе
83
+ * транзитивные). Сдвиг — другой SHA провайдера; снимок провайдера, которого
84
+ * нет у зелёной попытки или у текущей (запись прежней версии, новый
85
+ * провайдер), — тоже сдвиг: изменение провайдера меняет вход gate
86
+ * потребителя, даже если diff потребителя не задел его путей. Artifacts
87
+ * провайдера не сравниваются: их пересобирают в каждой попытке, и
88
+ * невоспроизводимая сборка давала бы сдвиг на каждой; при том же SHA их
89
+ * вход — тот же источник.
90
+ */
91
+ export declare function providerMovement(providers: readonly string[], green: readonly ProviderSnapshot[] | undefined, current: readonly ProviderSnapshot[] | undefined): string | undefined;
92
+ export interface GateDecisionInput {
93
+ repo: {
94
+ gates: GatePolicy[];
95
+ protectedPaths: readonly string[];
96
+ };
97
+ /** Область фазы в порядке исполнения. */
98
+ scope: GatePolicy[];
99
+ /**
100
+ * Diff фазы условного gate от его последнего зелёного SHA (integration
101
+ * принятой попытки под тем же основанием gate, предок базы попытки) до
102
+ * SHA фазы; undefined — такого SHA нет, и gate исполняется.
103
+ */
104
+ changedFor(gate: GatePolicy): ChangedPaths | undefined;
105
+ /**
106
+ * Почему база провайдеров сдвинулась с того же зелёного SHA
107
+ * (`providerMovement`), или undefined. Спрашивается только у условного gate
108
+ * с зелёным SHA. Без поля провайдеры считаются не сдвинувшимися: вызывающий
109
+ * ручается, что `changedFor` даёт зелёный SHA только под теми же SHA
110
+ * провайдеров (или что провайдеров нет). Runner его передаёт всегда.
111
+ */
112
+ providersMoved?(gate: GatePolicy): string | undefined;
113
+ /** `proofGates` поручения. */
114
+ proof: ReadonlySet<string>;
115
+ }
116
+ export interface GateDecision {
117
+ gate: GatePolicy;
118
+ run: boolean;
119
+ reason: string;
120
+ record?: GateApplicability;
121
+ }
122
+ /**
123
+ * Решения по области фазы. Gate без `when` исполняется всегда. Условный
124
+ * исполняется, если: он доказывает требование или договор; среди предков
125
+ * базы нет его зелёного SHA под тем же основанием (`changedFor`); с этого
126
+ * зелёного SHA сдвинулась база провайдеров (`providersMoved`); diff
127
+ * неизвестен, пуст или задевает его путь или неявный вход; он — предпосылка
128
+ * (`gatePrerequisites`: `dependsOn` или более ранний check gate) исполняемого
129
+ * gate области. Иначе — запись `not-applicable`.
130
+ */
131
+ export declare function gateDecisions(input: GateDecisionInput): GateDecision[];
132
+ /**
133
+ * Почему запись `not-applicable` не закрывает обязательный gate, или
134
+ * undefined. Закрывает только обычный gate с `when` под тем же определением,
135
+ * не доказательство требования или договора и не предпосылку исполненного
136
+ * gate той же фазы.
137
+ */
138
+ export declare function notApplicableProblem(input: {
139
+ gates: readonly GatePolicy[];
140
+ gate: string;
141
+ record: {
142
+ notApplicable?: GateApplicability | undefined;
143
+ };
144
+ proof: ReadonlySet<string>;
145
+ /** Gates той же фазы с решающей записью исполнения. */
146
+ ran: readonly string[];
147
+ }): string | undefined;
148
+ /**
149
+ * Объединённый diff набора для `uncoveredGates`: от зелёного SHA каждой
150
+ * записи неприменимости фазы интеграции (`notApplicable.ranges[0].from`) до
151
+ * итогового SHA репозитория. Хосту не нужно собирать пары самому.
152
+ */
153
+ export declare function coverageChanges(cwd: string, evidence: readonly {
154
+ kind: string;
155
+ phase: string;
156
+ notApplicable?: GateApplicability | undefined;
157
+ }[], finalSha: string): Promise<ChangedPaths>;