devcontour-harness 0.1.0-alpha.26 → 0.1.0-alpha.28

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 (69) hide show
  1. package/README.md +15 -2
  2. package/docs/architecture.md +59 -0
  3. package/docs/compatibility.md +25 -12
  4. package/docs/connectors.md +5 -2
  5. package/docs/contracts.md +80 -25
  6. package/docs/release-notes/0.1.0-alpha.27.md +36 -0
  7. package/docs/release-notes/0.1.0-alpha.28.md +37 -0
  8. package/docs/review-protocol.md +10 -4
  9. package/docs/toolchains.md +83 -0
  10. package/docs/upgrade.md +22 -0
  11. package/lib/cli.js +13 -0
  12. package/lib/contracts/cli.d.ts +147 -19
  13. package/lib/contracts/cli.js +66 -0
  14. package/lib/contracts/diagnosis.d.ts +1 -1
  15. package/lib/contracts/events.d.ts +6 -6
  16. package/lib/contracts/execution.d.ts +268 -16
  17. package/lib/contracts/execution.js +3 -1
  18. package/lib/contracts/policy.d.ts +37 -5
  19. package/lib/contracts/policy.js +42 -2
  20. package/lib/contracts/profiles.d.ts +2 -0
  21. package/lib/contracts/published.d.ts +226 -20
  22. package/lib/contracts/result.d.ts +268 -12
  23. package/lib/contracts/result.js +66 -0
  24. package/lib/control/harness.d.ts +64 -7
  25. package/lib/control/harness.js +4 -0
  26. package/lib/control/recovery.d.ts +1 -1
  27. package/lib/control/review.js +6 -1
  28. package/lib/engine/engine.d.ts +117 -12
  29. package/lib/engine/joint-runner.d.ts +96 -6
  30. package/lib/engine/joint-runner.js +47 -1
  31. package/lib/engine/runner.d.ts +29 -0
  32. package/lib/engine/runner.js +200 -2
  33. package/lib/engine/worktree-cleanup.d.ts +131 -0
  34. package/lib/engine/worktree-cleanup.js +520 -0
  35. package/lib/environment/isolation.d.ts +1 -0
  36. package/lib/environment/isolation.js +2 -1
  37. package/lib/environment/os-tools.d.ts +4 -2
  38. package/lib/environment/os-tools.js +4 -2
  39. package/lib/environment/process.d.ts +5 -0
  40. package/lib/environment/process.js +40 -17
  41. package/lib/environment/resources.d.ts +9 -0
  42. package/lib/environment/resources.js +24 -0
  43. package/lib/index.d.ts +1 -0
  44. package/lib/index.js +1 -0
  45. package/lib/integrations/connector/commands.d.ts +2 -1
  46. package/lib/integrations/connector/commands.js +10 -2
  47. package/lib/integrations/connector/store.d.ts +1 -1
  48. package/lib/integrations/connector/store.js +11 -6
  49. package/lib/profiles/resolve.d.ts +8 -0
  50. package/lib/storage/document.d.ts +132 -12
  51. package/lib/toolchains/inspect.d.ts +1 -1
  52. package/lib/toolchains/inspect.js +29 -1
  53. package/lib/toolchains/probe.d.ts +16 -0
  54. package/lib/toolchains/probe.js +20 -0
  55. package/lib/verification/confirm.d.ts +3 -1
  56. package/lib/verification/confirm.js +16 -2
  57. package/lib/verification/dependencies.d.ts +3 -0
  58. package/lib/verification/dependencies.js +11 -0
  59. package/lib/verification/dependency-store.d.ts +117 -0
  60. package/lib/verification/dependency-store.js +811 -0
  61. package/lib/verification/gate-artifacts.d.ts +34 -0
  62. package/lib/verification/gate-artifacts.js +303 -0
  63. package/lib/verification/gates-at.js +18 -0
  64. package/lib/verification/gates.js +15 -0
  65. package/lib/verification/joint.d.ts +48 -3
  66. package/package.json +1 -1
  67. package/schemas/execution-document.schema.json +372 -0
  68. package/schemas/execution-policy.schema.json +56 -0
  69. package/schemas/joint-verification.schema.json +279 -0
@@ -26,3 +26,19 @@ export declare function versionOf(output: string): string | undefined;
26
26
  export declare function moduleVersionOf(output: string): string | undefined;
27
27
  /** Требование версии: `1.12.3` — названные компоненты совпадают, `>=1.24` — не ниже. */
28
28
  export declare function satisfies(version: string, required: string): boolean;
29
+ /**
30
+ * Версии менеджера, на которых хранилище зависимостей проверено настоящим
31
+ * прогоном. Граница сверху — не осторожность: с pnpm 10.27.0 `pnpm fetch` кладёт
32
+ * в store символическую ссылку `<store>/v10/projects/<hash>`, а seed с ссылками
33
+ * отклоняется; с 11.0.0 pnpm ещё и не читает `npm_config_store_dir`. Вне диапазона
34
+ * хранилище не вмешивается в окружение.
35
+ */
36
+ export declare const dependencyStoreVersions: {
37
+ readonly pnpm: {
38
+ readonly from: "9.15.0";
39
+ readonly below: "10.27.0";
40
+ };
41
+ };
42
+ export declare function dependencyStoreSupports(manager: keyof typeof dependencyStoreVersions, version: string): boolean;
43
+ /** Версия менеджера из поля `packageManager`: `pnpm@10.12.3+sha512…` → `10.12.3`. */
44
+ export declare function declaredManagerVersion(field: unknown, manager: string): string | undefined;
@@ -52,3 +52,23 @@ export function satisfies(version, required) {
52
52
  const have = parse(version);
53
53
  return want.every((n, i) => have[i] === n);
54
54
  }
55
+ /**
56
+ * Версии менеджера, на которых хранилище зависимостей проверено настоящим
57
+ * прогоном. Граница сверху — не осторожность: с pnpm 10.27.0 `pnpm fetch` кладёт
58
+ * в store символическую ссылку `<store>/v10/projects/<hash>`, а seed с ссылками
59
+ * отклоняется; с 11.0.0 pnpm ещё и не читает `npm_config_store_dir`. Вне диапазона
60
+ * хранилище не вмешивается в окружение.
61
+ */
62
+ export const dependencyStoreVersions = {
63
+ pnpm: { from: '9.15.0', below: '10.27.0' },
64
+ };
65
+ export function dependencyStoreSupports(manager, version) {
66
+ const { from, below } = dependencyStoreVersions[manager];
67
+ return satisfies(version, '>=' + from) && !satisfies(version, '>=' + below);
68
+ }
69
+ /** Версия менеджера из поля `packageManager`: `pnpm@10.12.3+sha512…` → `10.12.3`. */
70
+ export function declaredManagerVersion(field, manager) {
71
+ if (typeof field !== 'string' || !field.startsWith(manager + '@'))
72
+ return undefined;
73
+ return /^\d+\.\d+\.\d+/.exec(field.slice(manager.length + 1))?.[0];
74
+ }
@@ -32,8 +32,8 @@ export declare const caseInputSchema: z.ZodObject<{
32
32
  command: "command";
33
33
  tolerance: "tolerance";
34
34
  coverage: "coverage";
35
- add: "add";
36
35
  remove: "remove";
36
+ add: "add";
37
37
  "replace-expected": "replace-expected";
38
38
  checker: "checker";
39
39
  }>>;
@@ -65,6 +65,8 @@ export interface ConfirmContext {
65
65
  checkout?(repositoryId: string, kind: string, id: string): string;
66
66
  /** Источник переменных окружения (по умолчанию — процесс). */
67
67
  environment?: NodeJS.ProcessEnv;
68
+ /** База закреплений и аренд хранилища зависимостей. */
69
+ resourceDatabase?: string;
68
70
  }
69
71
  /** Изменённые закреплённые файлы на SHA: checker должен быть утверждённой редакцией. */
70
72
  export declare function staleArtifacts(repoPath: string, sha: string, artifacts: ContractArtifact[]): Promise<string[]>;
@@ -7,8 +7,10 @@ import { HarnessError, idSchema, } from "../contracts/index.js";
7
7
  import { OversizedFile, readBounded } from "../environment/bounded-read.js";
8
8
  import { executionEnvironment, runSteps, withEnvironment } from "../environment/lifecycle.js";
9
9
  import { git, hostGitArgs } from "../environment/process.js";
10
+ import { defaultResourceDatabase } from "../environment/resources.js";
10
11
  import { contractDocuments, obligationOf } from "./checks.js";
11
12
  import { MAX_CASE_BYTES, canonicalJson, scrubLocalPaths, sha256, } from "./corpus.js";
13
+ import { materializeStore } from "./dependency-store.js";
12
14
  import { runCheck } from "./gates.js";
13
15
  /**
14
16
  * Быстрый маршрут: подтверждённый пример становится обязательным случаем.
@@ -293,12 +295,24 @@ async function decide(ctx, work, ref, input, source) {
293
295
  DEVCONTOUR_TASK_ID: work.id,
294
296
  DEVCONTOUR_PHASE: 'case',
295
297
  }, ctx.environment ?? process.env);
296
- const signal = AbortSignal.timeout(gate.timeoutMs * 3 + 120000);
298
+ const limitMs = gate.timeoutMs * 3 + 120000;
299
+ const deadline = Date.now() + limitMs;
300
+ const signal = AbortSignal.timeout(limitMs);
297
301
  await withEnvironment(repo.lifecycle ?? ctx.policy.lifecycle, dir, join(io, 'environment'), execution, signal, async () => {
302
+ const boundary = ctx.boundary();
303
+ await materializeStore({
304
+ policy: ctx.policy,
305
+ root: (id) => ctx.checkout?.(id, 'dependency-store', '') ??
306
+ join(ctx.stateDir, 'dependency-store', id),
307
+ repoPath: (r) => ctx.repoPath(r),
308
+ boundary,
309
+ resourceDatabase: ctx.resourceDatabase ?? defaultResourceDatabase(),
310
+ deadline,
311
+ phaseMs: limitMs,
312
+ }, { repo, cwd: dir, execution, signal, dir: io });
298
313
  await runSteps(repo.prepare, dir, join(io, 'prepare'), execution, signal);
299
314
  const request = join(io, 'case.json');
300
315
  await writeFile(request, JSON.stringify({ property: input.property, input: JSON.parse(text) }));
301
- const boundary = ctx.boundary();
302
316
  for (let i = 0; i < 2; i++) {
303
317
  const out = join(io, `result-${i}.json`);
304
318
  const started = Date.now();
@@ -1,5 +1,6 @@
1
1
  import type { ExecutionPolicy } from '../contracts/index.ts';
2
2
  import type { AttemptState } from '../contracts/index.ts';
3
+ import { type StoreContext } from './dependency-store.ts';
3
4
  type Repo = ExecutionPolicy['repositories'][number];
4
5
  export type DependencySnapshot = NonNullable<AttemptState['dependencies']>[number];
5
6
  export type DependencyFreshness = NonNullable<AttemptState['dependencyFreshness']>[number];
@@ -41,6 +42,8 @@ export declare function snapshotDependencies(input: {
41
42
  path: string;
42
43
  sha: string;
43
44
  }>;
45
+ /** Хранилище зависимостей для `dependencyBuild` снимков. */
46
+ store?: StoreContext;
44
47
  }): Promise<{
45
48
  repositoryId: string;
46
49
  sha: string;
@@ -3,6 +3,7 @@ import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
3
3
  import { join, sep } from 'node:path';
4
4
  import { git } from "../environment/process.js";
5
5
  import { executionEnvironment, runSteps } from "../environment/lifecycle.js";
6
+ import { materializeStore } from "./dependency-store.js";
6
7
  /** Зависимости компонентов в топологическом порядке, транзитивно. */
7
8
  export function dependencyOrder(repos, ids) {
8
9
  const ordered = [];
@@ -88,6 +89,16 @@ export async function snapshotDependencies(input) {
88
89
  DEVCONTOUR_RUN_ID: input.runId,
89
90
  DEVCONTOUR_COMPONENTS_JSON: JSON.stringify(paths),
90
91
  }, input.environment);
92
+ // Подставленное дерево (`overrides`) снимку не принадлежит: его хранилище
93
+ // уже развёрнуто на своей фазе.
94
+ if (input.store && repo.dependencyBuild.length && created.includes(snapshot))
95
+ await materializeStore(input.store, {
96
+ repo,
97
+ cwd: snapshot.path,
98
+ execution,
99
+ signal,
100
+ dir: join(input.artifacts, 'dependency-build', repo.id),
101
+ });
91
102
  await runSteps(repo.dependencyBuild, snapshot.path, join(input.artifacts, 'dependency-build', repo.id), execution, signal);
92
103
  for (const path of repo.dependencyArtifacts)
93
104
  snapshot.artifacts.push({ path, digest: await artifactDigest(snapshot.path, path) });
@@ -0,0 +1,117 @@
1
+ import { type DependencyStorePolicy, type ExecutionPolicy } from '../contracts/index.ts';
2
+ import { type CheckoutRoot } from '../environment/checkout-root.ts';
3
+ import type { executionEnvironment } from '../environment/lifecycle.ts';
4
+ import { runCheck, type Boundary } from './gates.ts';
5
+ /**
6
+ * Хранилище зависимостей: один seed на lockfile целевой ветки и его копия в
7
+ * каждом checkout. Проект ничего не пишет сам: установка остаётся обычным
8
+ * `pnpm install --frozen-lockfile` в его gate, только хранилище уже заполнено.
9
+ *
10
+ * Граница доверия:
11
+ *
12
+ * - Seed собирается только из lockfile целевой ветки — принятой истории.
13
+ * Сам harness не даёт кандидату запустить сборку или выбрать её содержимое:
14
+ * его lockfile только сравнивается с seed (частичное попадание).
15
+ * - Сборка идёт в песочнице проверок с её `isolation.domains`, в каталоге из
16
+ * одного lockfile: `.npmrc`, `.pnpmfile.cjs` и `pnpm-workspace.yaml` проекта
17
+ * туда не попадают, и его хуки не исполняются.
18
+ * - Seed лежит под корнем рабочих деревьев или в каталоге состояния: оба
19
+ * закрыты песочницей на чтение и запись. Копия в checkout принадлежит этому
20
+ * checkout: обратно в seed ничего не возвращается, а integration и следующая
21
+ * попытка получают новую копию.
22
+ * - Проверяются байты копии, а не источника: те, что прочитает менеджер, и без
23
+ * окна между сверкой и копированием. Манифест закреплён в базе ресурсов, вне
24
+ * дерева seed. Несовпадение — отказ от seed с причиной в квитанции.
25
+ * - Байты, докачанные менеджером при частичном попадании, защищены не seed, а
26
+ * lockfile: в дереве кандидата они доверены не больше, чем `node_modules`.
27
+ *
28
+ * Условие границы: шаги `prepare` и `lifecycle` идут на хосте вне песочницы, а на
29
+ * integration — над слитым деревом. Если они исполняют код кандидата (скрипт из
30
+ * репозитория), он работает с правами controller и может изменить seed и базу
31
+ * закреплений: граница seed держится только там, где эти шаги кода кандидата не
32
+ * исполняют. `doctor` предупреждает о хранилище рядом с непустым `prepare`.
33
+ *
34
+ * Отсутствие seed, отказ сборки и частичное попадание сводятся к обычной
35
+ * установке: хранилище — ускорение, и проверка из-за него не падает.
36
+ */
37
+ type Repo = ExecutionPolicy['repositories'][number];
38
+ type Execution = ReturnType<typeof executionEnvironment>;
39
+ export interface StoreContext {
40
+ policy: Pick<ExecutionPolicy, 'isolation'>;
41
+ /** Каталог seeds репозитория (`dependencyStoreRoot`). */
42
+ root(repositoryId: string): string;
43
+ repoPath(repo: Repo): string;
44
+ /** Граница сборки seed — та же, что у проверок этого контура. */
45
+ boundary: Pick<Boundary, 'hidden' | 'checkouts'>;
46
+ resourceDatabase: string;
47
+ /** Момент (ms), когда истекает время фазы; от остатка считается бюджет хранилища. */
48
+ deadline: number;
49
+ /** Полная длина этого предела фазы: так видно, что фаза пришла с остатком. */
50
+ phaseMs: number;
51
+ }
52
+ export interface StoreReceipt {
53
+ outcome: 'hit' | 'partial' | 'miss';
54
+ manager: DependencyStorePolicy['manager'];
55
+ /** Ключ использованного seed. */
56
+ seed?: string;
57
+ mode?: 'clone' | 'copy';
58
+ /** Seed собран этим вызовом. */
59
+ built?: boolean;
60
+ files?: number;
61
+ bytes?: number;
62
+ durationMs: number;
63
+ /** Причина промаха. */
64
+ reason?: string;
65
+ /** Seeds, от которых отказались: причина отказа. */
66
+ refused?: string[];
67
+ /** Переменные окружения процессов этого checkout. */
68
+ env: NodeJS.ProcessEnv;
69
+ }
70
+ /** Каталог seeds: том рабочих деревьев и уже закрытое песочницей место. */
71
+ export declare function dependencyStoreRoot(placement: CheckoutRoot, stateDir: string, repositoryId: string): string;
72
+ /** Способы размещения дерева; тест подменяет `cloneable`, чтобы проверить обычную копию. */
73
+ export declare const storeTree: {
74
+ /**
75
+ * Предел файлов seed: копия лежит в checkout и входит в сверку защищённых
76
+ * путей. Seed больше неё превратил бы ускорение в отказ каждой проверки.
77
+ */
78
+ maxFiles: number;
79
+ /**
80
+ * Предел элементов checkout вместе с копией seed. Запас — на то, что проверки
81
+ * допишут в дерево после развёртывания.
82
+ */
83
+ maxEntries: number;
84
+ /**
85
+ * Меньше этого остатка сборка не начинается и ничего не отмечает: за такое время
86
+ * она не успеет, а опоздавшая фаза не должна закрывать сборку остальным.
87
+ */
88
+ minBuildMs: number;
89
+ /** Запуск сборки; тест подменяет его: исход гонки с отменой иначе не воспроизвести. */
90
+ run: typeof runCheck;
91
+ /** Запись `.gitignore` хранилища; тест подменяет её, чтобы проверить отказ. */
92
+ ignore: (dest: string) => Promise<void>;
93
+ /**
94
+ * Том клонирует файлы. `cp -c` на другом томе молча копирует, поэтому способ
95
+ * выясняется заранее: от него зависит проверка свободного места.
96
+ */
97
+ cloneable(from: string, to: string, sample: string, signal: AbortSignal): Promise<boolean>;
98
+ freeBytes(path: string): Promise<number>;
99
+ /** Копия-при-записи порциями: один `cp` на всё дерево вдвое медленнее. */
100
+ clone(from: string, to: string, signal: AbortSignal): Promise<void>;
101
+ copy(from: string, to: string): Promise<void>;
102
+ };
103
+ /**
104
+ * Подготовить хранилище checkout до `prepare` и gates. Промах — обычный исход:
105
+ * исключение бывает только при отмене, а сводка пишется в `dir`.
106
+ * Окружение менеджера дописывается в `execution` (как `withEnvironment` дописывает
107
+ * каталог окружения) и повторяется в квитанции для хостов с окружением на gate.
108
+ */
109
+ export declare function materializeStore(ctx: StoreContext, input: {
110
+ repo: Repo;
111
+ cwd: string;
112
+ execution: Execution;
113
+ signal: AbortSignal;
114
+ /** Каталог артефактов фазы: квитанция и журнал сборки. */
115
+ dir: string;
116
+ }): Promise<StoreReceipt | undefined>;
117
+ export {};