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

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 (50) hide show
  1. package/README.md +44 -2
  2. package/docs/architecture.md +13 -0
  3. package/docs/compatibility.md +2 -0
  4. package/docs/connectors.md +69 -3
  5. package/docs/contracts.md +15 -1
  6. package/docs/release-notes/0.1.0-alpha.25.md +33 -0
  7. package/docs/release-notes/0.1.0-alpha.26.md +35 -0
  8. package/docs/review-protocol.md +9 -1
  9. package/lib/agents/cli-adapter.d.ts +6 -0
  10. package/lib/agents/cli-adapter.js +12 -2
  11. package/lib/agents/review-probe.d.ts +5 -0
  12. package/lib/agents/review-probe.js +29 -9
  13. package/lib/agents/schemas.d.ts +4 -0
  14. package/lib/agents/schemas.js +3 -1
  15. package/lib/cli.js +9 -5
  16. package/lib/contracts/cli.d.ts +60 -1
  17. package/lib/contracts/cli.js +36 -2
  18. package/lib/contracts/failure.js +1 -1
  19. package/lib/contracts/ports.d.ts +17 -0
  20. package/lib/contracts/review.d.ts +69 -0
  21. package/lib/contracts/review.js +29 -14
  22. package/lib/contracts/work.d.ts +6 -0
  23. package/lib/contracts/work.js +13 -12
  24. package/lib/control/review.js +9 -2
  25. package/lib/engine/engine.js +4 -2
  26. package/lib/engine/prompt.js +8 -2
  27. package/lib/engine/runner.js +7 -3
  28. package/lib/environment/bounded-read.d.ts +12 -0
  29. package/lib/environment/bounded-read.js +40 -0
  30. package/lib/integrations/connector/commands.d.ts +35 -7
  31. package/lib/integrations/connector/commands.js +52 -7
  32. package/lib/integrations/connector/config.d.ts +37 -0
  33. package/lib/integrations/connector/config.js +37 -5
  34. package/lib/integrations/connector/delivery.js +17 -1
  35. package/lib/integrations/connector/index.d.ts +2 -2
  36. package/lib/integrations/connector/index.js +1 -1
  37. package/lib/integrations/connector/snapshot.d.ts +10 -8
  38. package/lib/integrations/connector/snapshot.js +78 -8
  39. package/lib/integrations/connector/source.d.ts +8 -2
  40. package/lib/integrations/connector/source.js +32 -6
  41. package/lib/integrations/connector/summary.d.ts +6 -0
  42. package/lib/integrations/connector/summary.js +5 -0
  43. package/lib/integrations/connector/testing.js +18 -0
  44. package/lib/integrations/relay-v1/index.js +6 -4
  45. package/lib/integrations/relay-v2/protocol.js +8 -6
  46. package/lib/verification/confirm.js +10 -2
  47. package/lib/verification/gates.js +34 -12
  48. package/lib/verification/joint.d.ts +120 -1
  49. package/lib/verification/joint.js +38 -1
  50. package/package.json +6 -3
@@ -4,6 +4,7 @@ import type { RunnerHooks } from '../../engine/runner.ts';
4
4
  import { type LoadedConfig } from './config.ts';
5
5
  import { RelaySink, type ReconcileDecision } from './delivery.ts';
6
6
  import { HistoryRecorder } from './history.ts';
7
+ import { type BaselineManifest } from './snapshot.ts';
7
8
  import { RelayWorkSource } from './source.ts';
8
9
  import { ConnectorStore } from './store.ts';
9
10
  import type { RelayTransport } from './transport.ts';
@@ -87,6 +88,11 @@ export declare class Connector {
87
88
  };
88
89
  stateDir?: string | undefined;
89
90
  contextDir?: string | undefined;
91
+ baseline?: {
92
+ sha: string;
93
+ tasks: string[];
94
+ reason: string;
95
+ } | undefined;
90
96
  } | {
91
97
  provider: "relay-v2-cli";
92
98
  relay: Record<string, unknown> & {
@@ -141,6 +147,11 @@ export declare class Connector {
141
147
  };
142
148
  stateDir?: string | undefined;
143
149
  contextDir?: string | undefined;
150
+ baseline?: {
151
+ sha: string;
152
+ tasks: string[];
153
+ reason: string;
154
+ } | undefined;
144
155
  };
145
156
  /** Каталог пакетов `tasks[].context`: `contextDir` конфигурации, иначе `work/context` рядом с ней. */
146
157
  get contextDir(): string;
@@ -154,12 +165,19 @@ export declare class Connector {
154
165
  /** Хуки runner для `HarnessOptions.hooks`: история до исполнения попытки. */
155
166
  hooks(): RunnerHooks;
156
167
  close(): void;
168
+ /**
169
+ * `baseline` — решение человека, поэтому файл конфигурации не должен быть
170
+ * доступен писателю поручения: он вне репозиториев политики или в их
171
+ * `protectedPaths` (runner отказывает попытке, которая их меняет).
172
+ */
173
+ baselineIssue(policy: ExecutionPolicy, baseDir: string): string | undefined;
174
+ assertBaselineProtected(policy: ExecutionPolicy, baseDir: string): void;
157
175
  /**
158
176
  * Подключение, идентичность, capabilities, совпадение проекта и mapping —
159
177
  * только чтением: без мутаций backend, без записи истории и без создания
160
178
  * состояния коннектора.
161
179
  */
162
- check(policy?: ExecutionPolicy): Promise<{
180
+ check(policy?: ExecutionPolicy, baseDir?: string): Promise<{
163
181
  history: {
164
182
  enabled: boolean;
165
183
  capability: boolean;
@@ -192,11 +210,6 @@ export declare class Connector {
192
210
  * semantic digest: повтор неизменной постановки ничего не меняет.
193
211
  */
194
212
  snapshot(outDir?: string): Promise<{
195
- revision: string;
196
- created: boolean;
197
- eligible: boolean;
198
- problems: string[];
199
- truncated: string[];
200
213
  tasks: {
201
214
  identity: string;
202
215
  key: string;
@@ -211,7 +224,19 @@ export declare class Connector {
211
224
  manifest: string;
212
225
  };
213
226
  snapshot: import("./snapshot.ts").BuiltSnapshot;
214
- localContext?: import("./snapshot.ts").LocalContextManifest[] | undefined;
227
+ baseline?: BaselineManifest | undefined;
228
+ revision: string;
229
+ created: boolean;
230
+ eligible: boolean;
231
+ problems: string[];
232
+ truncated: string[];
233
+ localContext?: {
234
+ id: string;
235
+ digest: string;
236
+ files: number;
237
+ references: number;
238
+ bytes: number;
239
+ }[] | undefined;
215
240
  connector: string;
216
241
  graphId: string;
217
242
  graphDigest: string;
@@ -226,11 +251,13 @@ export declare class Connector {
226
251
  prepareRun(h: Harness): Promise<{
227
252
  graph: WorkGraph;
228
253
  context: ContextSnapshot;
254
+ baseline?: BaselineManifest;
229
255
  }>;
230
256
  run(h: Harness, options?: {
231
257
  author?: Author;
232
258
  once?: boolean;
233
259
  }): Promise<{
260
+ baseline?: BaselineManifest | undefined;
234
261
  works: {
235
262
  blockers: {
236
263
  code: "NOT_READY" | "PAUSED" | "ATTEMPTS_EXHAUSTED" | "APPROVAL_STALE" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "REVIEWER_SAME_VENDOR" | "REVIEWER_MISSING" | "INVALID_INPUT";
@@ -312,6 +339,7 @@ export declare class Connector {
312
339
  ref: string;
313
340
  }[];
314
341
  snapshot?: {
342
+ baseline?: BaselineManifest | undefined;
315
343
  revision: string;
316
344
  graphId: string;
317
345
  } | undefined;
@@ -1,7 +1,8 @@
1
- import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
2
- import { join, resolve } from 'node:path';
1
+ import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
2
+ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
3
3
  import { API_VERSION, HarnessError, } from "../../contracts/index.js";
4
4
  import { redactor } from "../../environment/redaction.js";
5
+ import { withinPaths } from "../../validate.js";
5
6
  import { connectorIdOf, loadConfig, orderIdOf, resolveFrom, storeFileOf, } from "./config.js";
6
7
  import { RelaySink } from "./delivery.js";
7
8
  import { HistoryRecorder } from "./history.js";
@@ -99,6 +100,33 @@ export class Connector {
99
100
  this.storeInstance?.close();
100
101
  this.storeInstance = undefined;
101
102
  }
103
+ /**
104
+ * `baseline` — решение человека, поэтому файл конфигурации не должен быть
105
+ * доступен писателю поручения: он вне репозиториев политики или в их
106
+ * `protectedPaths` (runner отказывает попытке, которая их меняет).
107
+ */
108
+ baselineIssue(policy, baseDir) {
109
+ const file = this.loaded.file;
110
+ if (!this.config.baseline || !file)
111
+ return undefined;
112
+ const real = realpathSync(file);
113
+ for (const repo of policy.repositories) {
114
+ const root = resolveFrom(baseDir, repo.path);
115
+ if (!existsSync(root))
116
+ continue;
117
+ const path = relative(realpathSync(root), real);
118
+ if (path === '..' || path.startsWith('..' + sep) || isAbsolute(path))
119
+ continue;
120
+ if (!withinPaths(path, repo.protectedPaths))
121
+ return `Конфигурация коннектора с baseline лежит в репозитории ${repo.id} вне protectedPaths (${path}): писатель поручения мог бы выдать себе baseline; перенесите файл или защитите путь в политике`;
122
+ }
123
+ return undefined;
124
+ }
125
+ assertBaselineProtected(policy, baseDir) {
126
+ const issue = this.baselineIssue(policy, baseDir);
127
+ if (issue)
128
+ throw new HarnessError('NOT_READY', issue);
129
+ }
102
130
  /* ---------------------------------------------------------------- */
103
131
  /* source-check */
104
132
  /* ---------------------------------------------------------------- */
@@ -107,9 +135,12 @@ export class Connector {
107
135
  * только чтением: без мутаций backend, без записи истории и без создания
108
136
  * состояния коннектора.
109
137
  */
110
- async check(policy) {
138
+ async check(policy, baseDir) {
111
139
  const config = this.config;
112
140
  const problems = [];
141
+ const unprotected = policy && baseDir && this.baselineIssue(policy, baseDir);
142
+ if (unprotected)
143
+ problems.push(unprotected);
113
144
  let identity;
114
145
  try {
115
146
  identity = await checkIdentity(this.transport, config);
@@ -221,6 +252,7 @@ export class Connector {
221
252
  eligible: snapshot.problems.length === 0,
222
253
  problems: snapshot.problems.map((p) => `${p.key}: ${p.code}: ${p.message}`),
223
254
  truncated: snapshot.manifest.truncated,
255
+ ...(snapshot.manifest.baseline ? { baseline: snapshot.manifest.baseline } : {}),
224
256
  tasks: snapshot.manifest.tasks.map((t) => ({
225
257
  identity: t.identity,
226
258
  key: t.key,
@@ -243,6 +275,7 @@ export class Connector {
243
275
  * закреплённый граф и контекст (те же байты, что видел reviewer плана).
244
276
  */
245
277
  async prepareRun(h) {
278
+ this.assertBaselineProtected(h.policy, h.options.baseDir);
246
279
  const fresh = await this.source.snapshot();
247
280
  const stored = this.store.latestSnapshot(fresh.graph.id);
248
281
  if (!stored)
@@ -266,11 +299,16 @@ export class Connector {
266
299
  .some((o) => o.status === 'delivered' && o.revision === digest);
267
300
  };
268
301
  assertEligible({ ...fresh, problems: fresh.problems.filter((p) => !own(p)) });
269
- return { graph: stored.graph, context: stored.context };
302
+ const { baseline } = stored.manifest;
303
+ return {
304
+ graph: stored.graph,
305
+ context: stored.context,
306
+ ...(baseline ? { baseline } : {}),
307
+ };
270
308
  }
271
309
  async run(h, options = {}) {
272
- const { graph, context } = await this.prepareRun(h);
273
- return h.run({
310
+ const { graph, context, baseline } = await this.prepareRun(h);
311
+ const data = await h.run({
274
312
  graph,
275
313
  context,
276
314
  author: options.author ?? 'external',
@@ -278,6 +316,7 @@ export class Connector {
278
316
  sink: this.sink,
279
317
  ...(options.once ? { once: true } : {}),
280
318
  });
319
+ return { ...data, ...(baseline ? { baseline } : {}) };
281
320
  }
282
321
  /* ---------------------------------------------------------------- */
283
322
  /* source-status / deliver / reconcile */
@@ -376,7 +415,13 @@ export class Connector {
376
415
  provider: this.config.provider,
377
416
  projectId: this.config.projectId,
378
417
  ...(manifest
379
- ? { snapshot: { revision: manifest.revision, graphId: manifest.graphId } }
418
+ ? {
419
+ snapshot: {
420
+ revision: manifest.revision,
421
+ graphId: manifest.graphId,
422
+ ...(manifest.baseline ? { baseline: manifest.baseline } : {}),
423
+ },
424
+ }
380
425
  : {}),
381
426
  ownership: { stateDir: this.stateDir, store: this.storeFile, note: OWNERSHIP_NOTE },
382
427
  tasks,
@@ -43,6 +43,17 @@ export declare const taskMappingSchema: z.ZodObject<{
43
43
  context: z.ZodOptional<z.ZodArray<z.ZodString>>;
44
44
  }, z.core.$strict>;
45
45
  export type TaskMapping = z.infer<typeof taskMappingSchema>;
46
+ /**
47
+ * Базовая линия: зависимости, закрытые до внедрения harness, принимает человек.
48
+ * Только явные ключи задач и один полный SHA: без шаблонов, дат и общего
49
+ * переключателя. Это решение оператора, а не доказательство результата.
50
+ */
51
+ export declare const baselineSchema: z.ZodObject<{
52
+ sha: z.ZodString;
53
+ tasks: z.ZodArray<z.ZodString>;
54
+ reason: z.ZodString;
55
+ }, z.core.$strict>;
56
+ export type Baseline = z.infer<typeof baselineSchema>;
46
57
  export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
47
58
  provider: z.ZodLiteral<"relay-v1-http">;
48
59
  relay: z.ZodIntersection<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodObject<{
@@ -76,6 +87,11 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
76
87
  requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
77
88
  context: z.ZodOptional<z.ZodArray<z.ZodString>>;
78
89
  }, z.core.$strict>>;
90
+ baseline: z.ZodOptional<z.ZodObject<{
91
+ sha: z.ZodString;
92
+ tasks: z.ZodArray<z.ZodString>;
93
+ reason: z.ZodString;
94
+ }, z.core.$strict>>;
79
95
  completion: z.ZodDefault<z.ZodObject<{
80
96
  mode: z.ZodDefault<z.ZodEnum<{
81
97
  complete: "complete";
@@ -149,6 +165,11 @@ export declare const connectorConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject
149
165
  requiredDocuments: z.ZodDefault<z.ZodArray<z.ZodString>>;
150
166
  context: z.ZodOptional<z.ZodArray<z.ZodString>>;
151
167
  }, z.core.$strict>>;
168
+ baseline: z.ZodOptional<z.ZodObject<{
169
+ sha: z.ZodString;
170
+ tasks: z.ZodArray<z.ZodString>;
171
+ reason: z.ZodString;
172
+ }, z.core.$strict>>;
152
173
  completion: z.ZodDefault<z.ZodObject<{
153
174
  mode: z.ZodDefault<z.ZodEnum<{
154
175
  complete: "complete";
@@ -214,6 +235,22 @@ export declare const contextIdOf: (orderId: string) => string;
214
235
  export declare const graphIdOf: (provider: ProviderId, projectId: string, taskIds: string[]) => string;
215
236
  /** Digest сопоставления задачи: входит в semantic digest — смена mapping требует нового согласования. */
216
237
  export declare const mappingDigest: (config: ConnectorConfig, mapping: TaskMapping) => string;
238
+ /**
239
+ * Запись базовой линии для зависимости; её digest — receipt предпосылки. Вся
240
+ * `baseline` внутри: любая её правка отзывает выданные предпосылки.
241
+ */
242
+ export declare const baselineRecord: (config: ConnectorConfig, key: string, orderId: string, repositoryId: string) => {
243
+ kind: string;
244
+ issuer: string;
245
+ key: string;
246
+ orderId: string;
247
+ repositoryId: string;
248
+ baseline: {
249
+ sha: string;
250
+ tasks: string[];
251
+ reason: string;
252
+ } | undefined;
253
+ };
217
254
  /** Колонка завершения по правилам конфигурации. */
218
255
  export declare const completionColumn: (config: ConnectorConfig) => TaskColumn;
219
256
  /** Файл хранилища коннектора внутри каталога состояния. */
@@ -1,7 +1,7 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { dirname, isAbsolute, resolve } from 'node:path';
3
3
  import { z } from 'zod';
4
- import { HarnessError, digestOf, gateRefSchema, idSchema, relativePathSchema, roleIdSchema, sha256, gateScopeSchema, } from "../../contracts/index.js";
4
+ import { HarnessError, digestOf, gateRefSchema, idSchema, roleIdSchema, sha256, gateScopeSchema, writeScopeSchema, } from "../../contracts/index.js";
5
5
  /**
6
6
  * Конфигурация коннектора внешнего хранилища задач.
7
7
  *
@@ -49,10 +49,7 @@ export const taskMappingSchema = z.strictObject({
49
49
  ref: z.string().min(1).max(200),
50
50
  role: roleIdSchema.default('developer'),
51
51
  repositoryId: idSchema.optional(),
52
- writeScope: z
53
- .array(z.union([z.literal('.'), relativePathSchema]))
54
- .min(1)
55
- .max(100),
52
+ writeScope: writeScopeSchema,
56
53
  gates: gateScopeSchema(gateRefSchema).optional(),
57
54
  criteria: z.array(criterionMappingSchema).max(100).default([]),
58
55
  /** Документы, без которых запуск блокируется (ID, ключ или имя). Остальные — дополнительные. */
@@ -65,6 +62,25 @@ export const taskMappingSchema = z.strictObject({
65
62
  */
66
63
  context: z.array(idSchema).min(1).max(10).optional(),
67
64
  });
65
+ /**
66
+ * Базовая линия: зависимости, закрытые до внедрения harness, принимает человек.
67
+ * Только явные ключи задач и один полный SHA: без шаблонов, дат и общего
68
+ * переключателя. Это решение оператора, а не доказательство результата.
69
+ */
70
+ export const baselineSchema = z.strictObject({
71
+ /** Полный SHA коммита; движок проверяет его доступность в target ref. */
72
+ sha: z.string().regex(/^[a-f0-9]{40}$/, 'Ожидается полный SHA коммита (40 hex)'),
73
+ tasks: z
74
+ .array(z
75
+ .string()
76
+ .max(200)
77
+ .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'Ожидается точный ключ задачи, без шаблонов'))
78
+ .min(1)
79
+ .max(500)
80
+ .refine((keys) => new Set(keys).size === keys.length, { message: 'Ключ задачи указан дважды' }),
81
+ /** Почему человек принимает эти задачи без receipt. */
82
+ reason: z.string().trim().min(1).max(1000),
83
+ });
68
84
  const relaySettings = z.record(z.string(), z.unknown());
69
85
  const common = {
70
86
  version: z.literal(1),
@@ -84,6 +100,7 @@ const common = {
84
100
  path: z.string().min(1).max(1000).optional(),
85
101
  }),
86
102
  tasks: z.array(taskMappingSchema).min(1).max(50),
103
+ baseline: baselineSchema.optional(),
87
104
  completion: z
88
105
  .strictObject({
89
106
  /** `complete` — закрыть задачу по правилам backend; `review-only` — оставить на проверку человеку. */
@@ -170,6 +187,9 @@ export function parseConfig(value, baseDir, file) {
170
187
  const dup = refs.find((r, i) => refs.indexOf(r) !== i);
171
188
  if (dup)
172
189
  throw new HarnessError('INVALID_INPUT', 'source: задача указана дважды: ' + dup);
190
+ const own = parsed.data.baseline?.tasks.find((key) => refs.includes(key));
191
+ if (own)
192
+ throw new HarnessError('INVALID_INPUT', `source: задача ${own} исполняется этой конфигурацией и не может быть в baseline`);
173
193
  // ID контекста задачи — `c` + 20 hex (contextIdOf): локальный пакет не может его занять.
174
194
  const taken = parsed.data.tasks
175
195
  .flatMap((t) => t.context ?? [])
@@ -225,6 +245,18 @@ export const mappingDigest = (config, mapping) => digestOf({
225
245
  repository: config.repository.id,
226
246
  completion: config.completion,
227
247
  });
248
+ /**
249
+ * Запись базовой линии для зависимости; её digest — receipt предпосылки. Вся
250
+ * `baseline` внутри: любая её правка отзывает выданные предпосылки.
251
+ */
252
+ export const baselineRecord = (config, key, orderId, repositoryId) => ({
253
+ kind: 'baseline',
254
+ issuer: connectorIdOf(config.provider, config.projectId),
255
+ key,
256
+ orderId,
257
+ repositoryId,
258
+ baseline: config.baseline,
259
+ });
228
260
  /** Колонка завершения по правилам конфигурации. */
229
261
  export const completionColumn = (config) => config.completion.column ?? (config.completion.mode === 'complete' ? 'done' : 'review');
230
262
  /** Файл хранилища коннектора внутри каталога состояния. */
@@ -158,7 +158,20 @@ export class RelaySink {
158
158
  ? 'задача уже завершена другим участником'
159
159
  : undefined;
160
160
  const identity = `${this.config.provider}:${this.config.projectId}:${read.task.id}`;
161
- const base = { casRevision: read.task.revision, taskKey: read.task.key, identity };
161
+ // Принятое без доказательства остаётся видно в итоге: только этой постановки.
162
+ const pinned = store.latestSnapshot(result.graphId)?.manifest;
163
+ const accepted = pinned?.tasks
164
+ .find((t) => t.id === read.task.id && t.semanticDigest === digest)
165
+ ?.dependencies.filter((d) => d.proof === 'baseline')
166
+ .map((d) => d.key);
167
+ const base = {
168
+ casRevision: read.task.revision,
169
+ taskKey: read.task.key,
170
+ identity,
171
+ ...(accepted?.length && pinned?.baseline
172
+ ? { baseline: { ...pinned.baseline, tasks: accepted } }
173
+ : {}),
174
+ };
162
175
  if (problem) {
163
176
  // Текущая задача не закрывается старым результатом; допустим только явно исторический комментарий.
164
177
  const steps = this.config.completion.historicalComment && result.outcome === 'accepted'
@@ -397,6 +410,9 @@ export class RelaySink {
397
410
  criteria: step.input.criteria ?? [],
398
411
  completion: op.receipt?.completion ?? op.reason ?? '',
399
412
  historical: step.kind === 'historical-comment',
413
+ ...(step.input.baseline
414
+ ? { baseline: step.input.baseline }
415
+ : {}),
400
416
  redact: this.redact,
401
417
  });
402
418
  return {
@@ -4,9 +4,9 @@
4
4
  * загружается только для явно выбранного provider.
5
5
  */
6
6
  export * from './transport.ts';
7
- export { connectorConfigSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, type ConnectorConfig, type ConnectorConfigInput, type CriterionMapping, type TaskMapping, type LoadedConfig, } from './config.ts';
7
+ export { connectorConfigSchema, baselineSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, type Baseline, type ConnectorConfig, type ConnectorConfigInput, type CriterionMapping, type TaskMapping, type LoadedConfig, } from './config.ts';
8
8
  export { ConnectorStore, LeaseLost, type OperationRecord, type OperationStatus, type StepRecord, type StepStatus, type LeaseRecord, type ReceiptRecord, type SnapshotRecord, } from './store.ts';
9
- export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, type BuiltSnapshot, type SnapshotManifest, type SnapshotProblem, type TaskManifest, } from './snapshot.ts';
9
+ export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, type BaselineManifest, type BuiltSnapshot, type SnapshotManifest, type SnapshotProblem, type TaskManifest, } from './snapshot.ts';
10
10
  export { RelayWorkSource } from './source.ts';
11
11
  export { RelaySink, operationKey, type ReconcileDecision, type SinkOptions } from './delivery.ts';
12
12
  export { HistoryRecorder, type SessionLink } from './history.ts';
@@ -4,7 +4,7 @@
4
4
  * загружается только для явно выбранного provider.
5
5
  */
6
6
  export * from "./transport.js";
7
- export { connectorConfigSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, } from "./config.js";
7
+ export { connectorConfigSchema, baselineSchema, criterionMappingSchema, taskMappingSchema, loadConfig, parseConfig, connectorIdOf, taskIdentity, parseIdentity, orderIdOf, graphIdOf, contextIdOf, mappingDigest, completionColumn, storeFileOf, } from "./config.js";
8
8
  export { ConnectorStore, LeaseLost, } from "./store.js";
9
9
  export { buildSnapshot, checkIdentity, readStable, semanticDigest, contextLimitIssues, localContext, takeSnapshot, assertEligible, } from "./snapshot.js";
10
10
  export { RelayWorkSource } from "./source.js";
@@ -1,4 +1,4 @@
1
- import { HarnessError, type ContextSnapshot, type ContextSourceEntry, type WorkGraph } from '../../contracts/index.ts';
1
+ import { HarnessError, type ContextSnapshot, type ContextSourceEntry, type LocalContextManifest, type WorkGraph } from '../../contracts/index.ts';
2
2
  import { type ConnectorConfig, type TaskMapping } from './config.ts';
3
3
  import type { ReceiptRecord } from './store.ts';
4
4
  import { type CriterionRecord, type RelayTransport, type TaskRead, type TransportIdentity } from './transport.ts';
@@ -57,6 +57,8 @@ export interface TaskManifest {
57
57
  column: string;
58
58
  finished: boolean;
59
59
  inGraph: boolean;
60
+ /** Основание внешней зависимости: `receipt` доказан, `baseline` принят человеком. */
61
+ proof?: 'receipt' | 'baseline';
60
62
  }[];
61
63
  children: {
62
64
  id: string;
@@ -86,13 +88,13 @@ export interface SnapshotManifest {
86
88
  problems: SnapshotProblem[];
87
89
  /** Закреплённые локальные пакеты `tasks[].context`; без них поля нет. */
88
90
  localContext?: LocalContextManifest[];
91
+ /** Зависимости, принятые человеком по базовой линии; без них поля нет. */
92
+ baseline?: BaselineManifest;
89
93
  }
90
- export interface LocalContextManifest {
91
- id: string;
92
- digest: string;
93
- files: number;
94
- references: number;
95
- bytes: number;
94
+ export interface BaselineManifest {
95
+ sha: string;
96
+ reason: string;
97
+ tasks: string[];
96
98
  }
97
99
  export interface BuiltSnapshot {
98
100
  graph: WorkGraph;
@@ -131,7 +133,7 @@ export declare function buildSnapshot(input: {
131
133
  /** Закреплённые локальные пакеты `tasks[].context` (localContext). */
132
134
  local?: ContextSourceEntry[];
133
135
  }): BuiltSnapshot;
134
- /** Нарушения пределов снимка контекста: число источников, размер файла и сумма. */
136
+ /** Нарушения пределов снимка контекста: число источников, размер файла, сумма и договор источника. */
135
137
  export declare function contextLimitIssues(context: ContextSnapshot): string[];
136
138
  /**
137
139
  * Локальные пакеты `tasks[].context` из `contextDir`: те же правила, что у
@@ -1,6 +1,6 @@
1
1
  import { existsSync, statSync } from 'node:fs';
2
- import { API_VERSION, HarnessError, CONTEXT_LIMITS, contextDigest, contextIssues, digestOf, sha256, sourceDigest, workGraphDigest, workGraphSchema, } from "../../contracts/index.js";
3
- import { connectorIdOf, contextIdOf, graphIdOf, mappingDigest, orderIdOf, taskIdentity, } from "./config.js";
2
+ import { API_VERSION, HarnessError, CONTEXT_LIMITS, contextDigest, contextIssues, contextSnapshotSchema, digestOf, sha256, sourceDigest, workGraphDigest, workGraphSchema, } from "../../contracts/index.js";
3
+ import { baselineRecord, connectorIdOf, contextIdOf, graphIdOf, mappingDigest, orderIdOf, taskIdentity, } from "./config.js";
4
4
  import { TransportError, } from "./transport.js";
5
5
  import { FileContextSource } from "../../connectors/files.js";
6
6
  /** Безопасная причина отказа транспорта при чтении: сеть/CLI — не пустой список. */
@@ -125,6 +125,7 @@ export function buildSnapshot(input) {
125
125
  const sources = [];
126
126
  const missing = [];
127
127
  const prerequisites = new Map();
128
+ const accepted = new Set();
128
129
  const tasks = [];
129
130
  /** Какие локальные пакеты у какой задачи (по порядку): часть ревизии набора. */
130
131
  const packsByTask = [];
@@ -154,12 +155,20 @@ export function buildSnapshot(input) {
154
155
  else
155
156
  mapped.add(found[0].id);
156
157
  });
157
- // Зависимости: внутри графа — dependsOn; вне — только с доверенным receipt.
158
+ // Зависимости: внутри графа — dependsOn; вне — с доверенным receipt или,
159
+ // если receipt нет, по явной записи базовой линии.
158
160
  const dependsOn = [];
159
161
  const deps = [];
160
162
  for (const dep of read.dependencies) {
161
163
  const inGraph = graphTasks.has(dep.id);
162
- deps.push({ id: dep.id, key: dep.key, column: dep.column, finished: dep.finished, inGraph });
164
+ const entry = {
165
+ id: dep.id,
166
+ key: dep.key,
167
+ column: dep.column,
168
+ finished: dep.finished,
169
+ inGraph,
170
+ };
171
+ deps.push(entry);
163
172
  const depOrder = orderIdOf(config.provider, config.projectId, dep.id);
164
173
  if (inGraph) {
165
174
  dependsOn.push(depOrder);
@@ -171,9 +180,32 @@ export function buildSnapshot(input) {
171
180
  }
172
181
  const receipt = input.receiptOf(depOrder);
173
182
  if (!receipt) {
174
- problem('DEPENDENCY_UNPROVEN', `Зависимость ${dep.key} в done, но проверяемого receipt этого коннектора нет: статус done не доказывает результат`);
183
+ const repositoryId = mapping.repositoryId ?? config.repository.id;
184
+ const prior = prerequisites.get(depOrder);
185
+ if (!config.baseline?.tasks.includes(dep.key)) {
186
+ problem('DEPENDENCY_UNPROVEN', `Зависимость ${dep.key} в done, но проверяемого receipt этого коннектора нет: статус done не доказывает результат. Если она закрыта до внедрения harness, человек может принять её явно: добавьте ${dep.key} в baseline.tasks конфигурации коннектора (baseline: sha, tasks, reason; docs/connectors.md)`);
187
+ }
188
+ else if (prior && prior.repositoryId !== repositoryId) {
189
+ problem('DEPENDENCY_UNPROVEN', `Зависимость ${dep.key} в baseline, но её требуют задачи разных репозиториев (${prior.repositoryId}, ${repositoryId}); baseline — один коммит`);
190
+ }
191
+ else {
192
+ dependsOn.push(depOrder);
193
+ entry.proof = 'baseline';
194
+ accepted.add(dep.key);
195
+ prerequisites.set(depOrder, {
196
+ id: depOrder,
197
+ repositoryId,
198
+ resultSha: config.baseline.sha,
199
+ receipt: {
200
+ kind: 'trusted',
201
+ issuer: connector,
202
+ digest: digestOf(baselineRecord(config, dep.key, depOrder, repositoryId)),
203
+ },
204
+ });
205
+ }
175
206
  continue;
176
207
  }
208
+ entry.proof = 'receipt';
177
209
  dependsOn.push(depOrder);
178
210
  prerequisites.set(depOrder, {
179
211
  id: depOrder,
@@ -372,6 +404,8 @@ export function buildSnapshot(input) {
372
404
  connector,
373
405
  tasks: tasks.map((t) => [t.identity, t.semanticDigest]),
374
406
  prerequisites: prereqs,
407
+ // Любая правка базовой линии — новое согласование; без неё ревизия прежняя.
408
+ ...(config.baseline ? { baseline: digestOf(config.baseline) } : {}),
375
409
  // Без локальных пакетов ревизия та же, что до их появления. С ними —
376
410
  // содержимое пакетов и их распределение по задачам: перенос пакета между
377
411
  // задачами или смена порядка — тоже новое согласование.
@@ -383,7 +417,7 @@ export function buildSnapshot(input) {
383
417
  : {}),
384
418
  });
385
419
  const joined = `${config.provider}:${config.projectId}:${taskIds.join('+')}`;
386
- const graph = workGraphSchema.parse({
420
+ const parsed = workGraphSchema.safeParse({
387
421
  apiVersion: API_VERSION,
388
422
  id: graphId,
389
423
  source: {
@@ -394,6 +428,15 @@ export function buildSnapshot(input) {
394
428
  orders,
395
429
  prerequisites: prereqs,
396
430
  });
431
+ // Конфигурация уже проверена: сюда доходит только то, что зависит от данных
432
+ // задач (например, число зависимостей), и причина называется, а не теряется.
433
+ if (!parsed.success)
434
+ throw new HarnessError('NOT_READY', 'Поручения не собираются из задач: ' +
435
+ parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '), parsed.error.issues.map((i) => ({
436
+ path: ['source', ...i.path],
437
+ message: i.message,
438
+ })));
439
+ const graph = parsed.data;
397
440
  const context = {
398
441
  apiVersion: API_VERSION,
399
442
  sources: [...sources, ...(input.local ?? [])],
@@ -421,13 +464,40 @@ export function buildSnapshot(input) {
421
464
  truncated,
422
465
  problems,
423
466
  ...(input.local?.length ? { localContext: input.local.map(localManifest) } : {}),
467
+ ...(accepted.size
468
+ ? {
469
+ baseline: {
470
+ sha: config.baseline.sha,
471
+ reason: config.baseline.reason,
472
+ tasks: [...accepted].sort(),
473
+ },
474
+ }
475
+ : {}),
424
476
  };
425
477
  return { graph, context, manifest, revision, problems };
426
478
  }
427
479
  const CONTEXT_SOURCES_MAX = 30;
428
- /** Нарушения пределов снимка контекста: число источников, размер файла и сумма. */
480
+ /**
481
+ * Нарушения договора источника (число файлов и справок, имя файла): запуск
482
+ * проверяет снимок той же схемой, поэтому они видны здесь, а не после approve.
483
+ * Число источников называет `contextLimitIssues`.
484
+ */
485
+ function sourceSchemaIssues(context) {
486
+ const parsed = contextSnapshotSchema.safeParse(context);
487
+ if (parsed.success)
488
+ return [];
489
+ return parsed.error.issues
490
+ .filter((i) => i.path[0] === 'sources' && i.path.length > 2)
491
+ .map((i) => {
492
+ const [, index, field, file] = i.path;
493
+ const source = context.sources[index];
494
+ const name = file === undefined ? field : (source[field]?.[file]?.path ?? field);
495
+ return `${source.id}/${name}: ${i.message}`;
496
+ });
497
+ }
498
+ /** Нарушения пределов снимка контекста: число источников, размер файла, сумма и договор источника. */
429
499
  export function contextLimitIssues(context) {
430
- const issues = contextIssues(context);
500
+ const issues = [...contextIssues(context), ...sourceSchemaIssues(context)];
431
501
  if (context.sources.length > CONTEXT_SOURCES_MAX)
432
502
  issues.push(`Источников контекста ${context.sources.length} при пределе ${CONTEXT_SOURCES_MAX} (задачи и локальные пакеты)`);
433
503
  return issues.map((i) => /больше предела/.test(i)
@@ -11,8 +11,9 @@ import { type RelayTransport } from './transport.ts';
11
11
  * - `revision` — текущий semantic digest задачи (или набора) для обнаружения
12
12
  * конфликта; ошибка сети/CLI — исключение, а не «записи нет»;
13
13
  * - `trusts` — только receipt, выданный этим коннектором (`issuer` = его ID),
14
- * digest которого совпадает с записью в его состоянии. Статус задачи done
15
- * доверием не является.
14
+ * digest которого совпадает с записью в его состоянии, либо запись базовой
15
+ * линии текущей конфигурации для задачи, которую подтверждает backend.
16
+ * Статус задачи done доверием не является.
16
17
  */
17
18
  export declare class RelayWorkSource implements WorkSource {
18
19
  readonly options: {
@@ -38,4 +39,9 @@ export declare class RelayWorkSource implements WorkSource {
38
39
  }>;
39
40
  revision(ref: string): Promise<string | undefined>;
40
41
  trusts(prerequisite: Prerequisite): Promise<boolean>;
42
+ /**
43
+ * Предпосылка базовой линии сверяется с загруженной конфигурацией целиком.
44
+ * Digest не секрет: что ключ — именно задача предпосылки, подтверждает backend.
45
+ */
46
+ private trustsBaseline;
41
47
  }