@casecore/release-agent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# @casecore/release-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Общий движок поставки CaseCore, Alvori и MyRobotica. Канонический исходный код
+находится в репозитории CaseCore. Продукты подключают точную опубликованную версию;
+отдельные редактируемые копии движка в репозиториях продуктов не поддерживаются.
+
+Движок сохраняет исходную идентичность команды, ограничение времени, защищённый
+журнал, блокировки, повторное выполнение и восстановление наблюдаемого результата.
+Сборку, подпись, миграции, резервное копирование, активацию и независимую проверку
+выполняет адаптер конкретного продукта. Установка уже принятой команды продолжается
+по локальному журналу и не требует постоянной доступности API CaseCore.
+
+## Подключение
+
+```sh
+pnpm add --save-exact @casecore/release-agent@0.1.0
+```
+
+В проекте фиксируются точная версия и `pnpm-lock.yaml`. Поддерживается Node.js
+22.14 или новее и POSIX-система с приватными каталогами и файлами. Перед активацией
+на сервере с Node.js 18 необходимо обновить среду исполнения до поддерживаемой
+версии. Публикация пакета сама по себе не означает обновление серверов продуктов.
+
+```js
+import { executePipeline, newExecution } from '@casecore/release-agent/pipeline';
+import { sourceStore } from '@casecore/release-agent/source-store';
+import { ReleaseControlProducer } from '@casecore/release-agent/producer';
+```
+
+## Контракт адаптеров
+
+| Вход пакета    | Назначение                                                                                                                                |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `pipeline`     | Семь последовательных этапов, повторное использование успешных этапов, остановка при неопределённом результате, восстановление блокировки |
+| `source-store` | Приём команд публикации и установки, неизменяемые входы, источник кандидатов и прогресс                                                   |
+| `producer`     | Протокол исполнительного агента, адаптер `provider`, планирование, наблюдение и восстановление                                            |
+| `protocol`     | Проверка команд, снимков, источника и независимого подтверждения установки                                                                |
+| `journal`      | Приватная атомарная запись с `fsync` файла и каталога, отказ при ссылках и повреждённых данных                                            |
+
+`executePipeline` получает команды и их аргументы от адаптера через `stages` и
+вызывает предоставленный `run`. Каждый этап фиксирует `inputsDigest`.
+`reconcileExecution` снимает блокировку только после подтверждения отсутствия
+живого исполнителя и проверки фактического результата адаптером. Истёкший срок
+не продлевается. Неопределённые действия не запускаются повторно автоматически.
+
+`ReleaseControlProducer` получает `provider` с существующими операциями продукта:
+`snapshot`, `execute`, `readProduction` и подключёнными операциями восстановления.
+`provider.execute(command, context)` вызывает `context.stage` для реальных этапов;
+`production_acceptance` подтверждается через независимый `readProduction`.
+Журнал сохраняет прежний формат MyRobotica и исходные идентификаторы команд.
+
+Источник публикации ограничивается установкой. Для `main` передаётся точная
+политика, например `sourcePolicy: { repository: 'owner/product', ref: 'main' }`.
+Без политики сохраняется прежнее ограничение MyRobotica на ветки `codex/`.
+Регулярное выражение допустимо только для явно указанного репозитория и без
+флагов `g`/`y`. Это не разрешает публикацию произвольного источника другой установки.
+
+`sourceStore(directory, { filename, validateState })` сохраняет исторический путь
+и проверку схемы журнала адаптера. CaseCore использует `source-publication.json`,
+Alvori — `release-control-source.json`. Для старого формата Alvori адаптер передаёт
+проверку допустимого состояния и ту же проверку в `progress(state, cursor, now,
+{ validateState })`. Проверки идентичности, коллизий и срока команды выполняет
+движок независимо от проверки формата журнала.
+
+Процессы записи `source-store` и `producer` запускаются под существующей общей
+блокировкой установки; внутрипроцессная очередь не заменяет блокировку процессов.
+Переход не допускает одновременную работу старого и нового исполнителей.
+`createStageJournal({ store, state, record, now })` использует этот же журнал:
+переход этапа, время, событие и сохранение выполняются общей реализацией;
+адаптер передаёт фактическое начало и завершение своей операции.
+
+## Сборка и выпуск
+
+```sh
+pnpm --dir packages/libs/release-agent run build
+pnpm --dir packages/libs/release-agent pack
+```
+
+Сборка использует только встроенные средства Node.js. `dist/provenance.json`
+фиксирует версию, исходный commit и SHA-256 каждого исходного модуля и декларации.
+Сборка вне Git требует явного `RELEASE_AGENT_SOURCE_COMMIT` с точным commit.
+Разработческая сборка с изменёнными или непроверенными исходниками помечается
+`buildKind: development`, `sourceVerified: false`. Для официальной сборки
+задаётся `RELEASE_AGENT_REQUIRE_CLEAN_SOURCE=1`: грязная ревизия или другой
+переданный commit блокируют выпуск. Сборка сверяет исходники с байтами commit.
+Официальный выпуск выполняется из чистой ревизии через отдельный трек
+публикации npm-пакетов CaseCore. Содержимое опубликованной версии не заменяется.
+
+После изменения движка продукты обновляют точную зависимость и lockfile,
+собирают собственный артефакт и применяют его через существующую процедуру
+обновления исполнителя. Отдельная подпись, миграции и проверки сервера остаются
+границей доставки каждого продукта.
+
+## Подключение конфигурации установки
+
+В третьем аргументе `producerServer` адаптер может передать `configure(request)`
+и `reconcileConfiguration(configurationId)`. Без этих обработчиков маршруты
+недоступны. Используется тот же сервер и Bearer-аутентификация исполнителя.
+
+`POST /v1/release-control/configuration` принимает ровно восемь полей:
+`protocolVersion: 1`, UUID `configurationId`, положительный целочисленный
+`configurationRevision`, `installationKey`, `executionProvider: github | local`,
+`repository: owner/repo`, `ref: main`, `githubToken: string | null`.
+Размер тела ограничен 16384 байтами; установка должна совпадать с исполнителем.
+Регистр репозитория сохраняется. `githubToken: null` явно отзывает credential.
+
+Обработчик возвращает семь полей идентичности без токена, `state: applied | rejected`
+и `reason`: `null` для применённой конфигурации или `{code, message, retryable}`
+для отказа. Если результат ещё не подтверждён, обработчик возвращает `undefined`:
+сервер отвечает HTTP 503 с `{error: "UNKNOWN"}`. Успех не подставляется автоматически.
+
+`GET /v1/release-control/configuration/:configurationId` вызывает восстановление
+результата через адаптер. `null` означает отсутствие конфигурации (HTTP 404),
+`undefined` — незавершённый или неопределённый результат (HTTP 503 `UNKNOWN`).
+Готовый ответ должен совпадать с UUID и установкой и не содержать токен.
+
+Адаптер продукта отвечает за идентичность и ревизии конфигурации, блокировки,
+хранение credential, изменение окружения и фактическую активацию. Общий движок
+не записывает токен, конфигурацию или её ответ в журнал релизов. Ошибки обработчика
+и небезопасные ответы возвращаются без внутренних подробностей.
+
+Перед фактическим изменением или восстановлением конфигурации адаптер вызывает
+`producer.reserveExclusiveOperation({ operationId })`. Метод синхронно резервирует
+исполнителя и возвращает `assertOwned()` и `release({ resolved })`. Пока есть
+активный или неопределённый владелец, команды, откат, продолжение публикации,
+плановая установка, привязка артефакта и восстановление релиза не выполняются.
+Резервирование также запрещено во время уже начатой операции или неразрешённого
+состояния установки. Чтение снимка и поиск отсутствующей конфигурации доступны.
+
+`release({ resolved: true })` снимает резервирование после подтверждённого результата.
+`false` или отсутствие `resolved` сохраняет удержание и лишает текущий handle прав.
+Для проверки неопределённого результата тот же `operationId` получает новый handle;
+другой ID и старые handles не могут снять или заменить удержание. Повторное
+получение активного handle запрещено даже для того же ID.
+
+Резервирование хранится только в памяти движка. После перезапуска адаптер сначала
+восстанавливает его из своего защищённого журнала незавершённой конфигурации,
+затем вызывает `initialize` и открывает сервер. `initialize`, снимок и поиск
+ответа не снимают удержание и не разрешают продолжение эффектов. Сам HTTP-обработчик
+не резервирует установку: callback делает это только перед фактической операцией.
+
+## Проверки
+
+```sh
+pnpm --dir packages/libs/release-agent test
+pnpm --dir packages/libs/release-agent run test:pack
+```
+
+Проверки покрывают повторное выполнение, коллизии, исходный срок, неопределённый
+результат, блокировки, повреждённый журнал и старые пути состояния. `test:pack`
+выполняет `pnpm pack` и запускает потребителя в изолированном каталоге, используя
+только распакованный пакет. Для повторного использования готового архива:
+
+```sh
+RELEASE_AGENT_TARBALL=/absolute/path/casecore-release-agent-0.1.0.tgz \
+  pnpm --dir packages/libs/release-agent run test:pack
+```
+
+Запуск проверок и сборок должен учитывать действующее разрешение владельца задачи;
+наличие команд и тестов не является подтверждением их успешного выполнения.

package/dist/configuration-hook.mjs

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { keys, uuid, validateBlocker } from './protocol-internals.mjs';
+
+const identityFields = ['protocolVersion', 'configurationId', 'configurationRevision',
+  'installationKey', 'executionProvider', 'repository', 'ref'];
+const pat = /(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+)/;
+function validateIdentity(value, installationKey) {
+  assert.equal(value.protocolVersion, 1);
+  assert.match(value.configurationId, uuid);
+  assert.ok(Number.isSafeInteger(value.configurationRevision) && value.configurationRevision > 0);
+  assert.equal(value.installationKey, installationKey);
+  assert.ok(['github', 'local'].includes(value.executionProvider));
+  assert.ok(typeof value.repository === 'string' && value.repository.length <= 200);
+  assert.match(value.repository, /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/);
+  assert.equal(value.ref, 'main');
+}
+function validateRequest(value, installationKey) {
+  keys(value, [...identityFields, 'githubToken']);
+  validateIdentity(value, installationKey);
+  assert.ok(value.githubToken === null || typeof value.githubToken === 'string');
+}
+function validateAcknowledgement(value, installationKey, expected, token) {
+  // Snapshot callback data before validation; inherited serializers and getters
+  // must not replace a checked acknowledgement when the server emits JSON.
+  value = structuredClone(value);
+  keys(value, [...identityFields, 'state', 'reason']);
+  validateIdentity(value, installationKey);
+  for (const field of Object.keys(expected)) assert.equal(value[field], expected[field]);
+  assert.ok(['applied', 'rejected'].includes(value.state));
+  if (value.state === 'applied') assert.equal(value.reason, null);
+  else {
+    validateBlocker(value.reason);
+  }
+  for (const text of [...Object.values(value), value.reason?.code, value.reason?.message]) {
+    if (typeof text !== 'string') continue;
+    assert.ok(!pat.test(text));
+    if (typeof token === 'string' && token.length) assert.ok(!text.includes(token));
+  }
+  return value;
+}
+function readBody(request) {
+  return new Promise((resolve, reject) => {
+    let bytes = 0;
+    const chunks = [];
+    const clean = () => {
+      request.off('data', data);
+      request.off('end', end);
+      request.off('error', error);
+      request.off('aborted', aborted);
+    };
+    const tooLarge = () => {
+      clean(); request.resume();
+      reject(Object.assign(Error('Configuration request rejected'), { code: 'CONFIGURATION_BODY_TOO_LARGE' }));
+    };
+    const data = (chunk) => {
+      bytes += chunk.length;
+      if (bytes > 16384) return tooLarge();
+      chunks.push(chunk);
+    };
+    const end = () => { clean(); resolve(Buffer.concat(chunks).toString('utf8')); };
+    const error = () => { clean(); reject(Error('Configuration request rejected')); };
+    const aborted = error;
+    request.on('data', data); request.on('end', end);
+    request.on('error', error); request.on('aborted', aborted);
+    if (Number(request.headers['content-length']) > 16384) tooLarge();
+  });
+}
+
+/** Optional transport only: credential persistence and activation stay in the product adapter. */
+export async function configurationHook(request, url, producer, options, reply) {
+  if (request.method === 'POST' && url.pathname === '/v1/release-control/configuration' &&
+      typeof options.configure === 'function') {
+    assert.equal(url.search, '');
+    const command = JSON.parse(await readBody(request));
+    validateRequest(command, producer.installationKey);
+    const identity = Object.fromEntries(identityFields.map((field) => [field, command[field]]));
+    const token = command.githubToken;
+    const result = await options.configure(structuredClone(command));
+    reply(result === undefined ? 503 : 200, result === undefined ? { error: 'UNKNOWN' } :
+      validateAcknowledgement(result, producer.installationKey, identity, token));
+    return true;
+  }
+  const match = url.pathname.match(/^\/v1\/release-control\/configuration\/([^/]+)$/);
+  if (request.method === 'GET' && match && typeof options.reconcileConfiguration === 'function') {
+    assert.equal(url.search, '');
+    assert.match(match[1], uuid);
+    const result = await options.reconcileConfiguration(match[1]);
+    if (result === null) reply(404, { error: 'Unknown configuration' });
+    else if (result === undefined) reply(503, { error: 'UNKNOWN' });
+    else reply(200, validateAcknowledgement(result, producer.installationKey,
+      { configurationId: match[1] }));
+    return true;
+  }
+  return false;
+}

package/dist/exclusive-operation.mjs

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+
+// Generic process-local ownership only. Products restore pending ownership from
+// their own durable configuration state before exposing effect-bearing methods.
+const operations = new WeakMap();
+const mutableMethods = ['command', 'execute', 'resumeScheduled', 'resumePublication',
+  'reconcile', 'bindPublicationDelivery', 'bindPublicationArtifact', 'qualifyForwardRecovery'];
+function metadata(producer) {
+  const state = operations.get(producer);
+  assert.ok(state, 'DELIVERY_OPERATION_BARRIER_REQUIRED');
+  return state;
+}
+export function installOperationBarrier(producer) {
+  assert.ok(!operations.has(producer), 'DELIVERY_OPERATION_BARRIER_ALREADY_INSTALLED');
+  operations.set(producer, { activity: 0, lease: null, loaded: false });
+  for (const name of mutableMethods) {
+    const method = producer[name];
+    assert.equal(typeof method, 'function');
+    Object.defineProperty(producer, name, {
+      value: async function (...args) {
+        const state = metadata(this);
+        assert.ok(!state.lease, 'DELIVERY_EXCLUSIVE_OPERATION_HELD');
+        state.activity++;
+        try { return await method.apply(this, args); }
+        finally { state.activity--; }
+      },
+    });
+  }
+}
+export function markOperationStateLoaded(producer) {
+  metadata(producer).loaded = true;
+}
+function installationBusy(producer, state) {
+  // A restored configuration reservation precedes initialize. Inspect the
+  // protected existing journal so an empty constructor cannot hide a live run.
+  const runs = state.loaded ? producer.state.runs :
+    [...producer.state.runs, ...producer.journal.read().runs];
+  return state.activity > 0 || producer.admitting !== undefined ||
+    producer.pending.size > 0 || producer.scheduling === true ||
+    runs.some((run) =>
+      ['queued', 'running'].includes(run.status) ||
+      (run.status === 'blocked' && (run.recoveryState !== 'verified' ||
+        run.blockers?.some((reason) => reason.code === 'RECONCILIATION_REQUIRED'))) ||
+      ['failed', 'unverified'].includes(run.recoveryState));
+}
+export function reserveExclusiveOperation(producer, { operationId } = {}) {
+  assert.ok(typeof operationId === 'string' && operationId.trim().length > 0 && operationId.length <= 200,
+    'DELIVERY_OPERATION_ID_REQUIRED');
+  const state = metadata(producer);
+  assert.ok(!state.lease || (state.lease.status === 'held' && state.lease.operationId === operationId),
+    'DELIVERY_EXCLUSIVE_OPERATION_HELD');
+  assert.ok(!installationBusy(producer, state), 'DELIVERY_INSTALLATION_BUSY');
+  const generation = Symbol();
+  state.lease = { operationId, generation, status: 'active' };
+  const assertOwned = () => assert.ok(state.lease?.generation === generation &&
+    state.lease.status === 'active', 'DELIVERY_EXCLUSIVE_OPERATION_NOT_OWNED');
+  return {
+    assertOwned,
+    release(options = {}) {
+      assertOwned();
+      assert.ok(options && typeof options === 'object' && !Array.isArray(options) &&
+        (options.resolved === undefined || typeof options.resolved === 'boolean'),
+      'DELIVERY_OPERATION_RESOLUTION_INVALID');
+      if (options?.resolved === true) state.lease = null;
+      else state.lease.status = 'held';
+    },
+  };
+}

package/dist/identity.mjs

@@ -0,0 +1,12 @@
+export function sourceTimestamp(value) {
+  if (
+    typeof value !== 'string' ||
+    !/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/u.test(
+      value
+    ) ||
+    !Number.isFinite(Date.parse(value))
+  )
+    return false;
+  const date = value.slice(0, 10);
+  return new Date(Date.parse(`${date}T00:00:00Z`)).toISOString().slice(0, 10) === date;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './pipeline.js';
+export * from './source-store.js';
+export * from './producer.js';
+export { createProtectedJsonStore } from './journal.js';

package/dist/index.mjs

@@ -0,0 +1,4 @@
+export * from './pipeline.mjs';
+export * from './source-store.mjs';
+export * from './producer.mjs';
+export { createProtectedJsonStore } from './journal.mjs';

package/dist/journal.d.ts

@@ -0,0 +1,20 @@
+export interface ProtectedJsonStore<T> {
+  directory: string;
+  path: string;
+  read(): T;
+  save(state: T): void;
+}
+export interface JsonStoreOptions<T> {
+  filename: string;
+  validate?: (state: T) => boolean;
+  initial?: () => T;
+}
+export function createProtectedJsonStore<T = unknown>(
+  directory: string,
+  options: JsonStoreOptions<T>
+): ProtectedJsonStore<T>;
+export function atomicJson<T>(
+  path: string,
+  value: T,
+  options?: Omit<JsonStoreOptions<T>, 'filename'>
+): Promise<void>;

package/dist/journal.mjs

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import {
+  closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync,
+  readFileSync, renameSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, parse, resolve, sep } from 'node:path';
+
+function directoryChain(directory) {
+  let current = parse(directory).root;
+  for (const segment of directory.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, segment);
+    try {
+      const metadata = lstatSync(current);
+      if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error('Journal path must contain only real directories.');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      mkdirSync(current, { mode: 0o700 });
+    }
+  }
+}
+function protectedFile(metadata, owner) {
+  return metadata.isFile() && !metadata.isSymbolicLink() && metadata.nlink === 1 &&
+    (metadata.mode & 0o077) === 0 && metadata.uid === owner;
+}
+
+/** Synchronous protected persistence for host drivers already serialized by flock.
+ * Validation is product-schema-specific, while private files and fsync are shared. */
+export function createProtectedJsonStore(directory, {
+  filename, validate = () => true, initial = () => null,
+} = {}) {
+  if (!isAbsolute(directory) || typeof filename !== 'string' ||
+      !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,199}$/.test(filename) ||
+      typeof validate !== 'function' || typeof initial !== 'function')
+    throw new Error('An absolute protected journal directory and basename are required.');
+  if (typeof process.getuid !== 'function')
+    throw new Error('Protected host journals require a POSIX runtime.');
+  directory = resolve(directory);
+  const owner = process.getuid();
+  const verifyDirectory = () => {
+    directoryChain(directory);
+    const metadata = lstatSync(directory);
+    if ((metadata.mode & 0o077) !== 0 || metadata.uid !== owner)
+      throw new Error('Protected journal directory is required.');
+  };
+  verifyDirectory();
+  const path = join(directory, filename);
+  const read = () => {
+    verifyDirectory();
+    let descriptor;
+    try {
+      descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    } catch (error) {
+      if (error.code === 'ENOENT') return initial();
+      throw error;
+    }
+    try {
+      if (!protectedFile(fstatSync(descriptor), owner))
+        throw new Error('Protected canonical journal is required.');
+      const state = JSON.parse(readFileSync(descriptor, 'utf8'));
+      if (!validate(state)) throw new Error('Journal requires reconciliation.');
+      return state;
+    } finally {
+      closeSync(descriptor);
+    }
+  };
+  const save = (state) => {
+    if (!validate(state)) throw new Error('Invalid canonical journal state.');
+    verifyDirectory();
+    try {
+      if (!protectedFile(lstatSync(path), owner))
+        throw new Error('Protected canonical journal is required.');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    let descriptor;
+    try {
+      descriptor = openSync(temporary,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+        0o600);
+      writeFileSync(descriptor, `${JSON.stringify(state, null, 2)}\n`);
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = undefined;
+      renameSync(temporary, path);
+      const parent = openSync(directory,
+        constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      try { fsyncSync(parent); } finally { closeSync(parent); }
+    } finally {
+      if (descriptor !== undefined) closeSync(descriptor);
+      try { unlinkSync(temporary); } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+    }
+  };
+  return { directory, path, read, save };
+}
+
+/** Promise API retains producer/pipeline callers; the durable write completes before resolution. */
+export async function atomicJson(path, value, options = {}) {
+  createProtectedJsonStore(dirname(path), { ...options, filename: basename(path) }).save(value);
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,43 @@
+import type { Execution, PipelineStage, PipelineState, StageRecord, StageId } from './types.js';
+export type { Execution, PipelineStage, PipelineState, StageRecord, StageId } from './types.js';
+export { atomicJson } from './journal.js';
+export const DELIVERY_STAGES: StageId[];
+export function newExecution(input: {
+  product: string;
+  installationKey: string;
+  sourceCommit: string;
+  now?: number;
+}): Execution;
+export interface ReconcileStageContext {
+  stage: PipelineStage;
+  execution: Execution;
+  previous: StageRecord;
+  remainingMs: number;
+}
+export interface PipelineOptions {
+  execution: Execution;
+  stages: PipelineStage[];
+  stateDir: string;
+  run(
+    command: string,
+    args: string[],
+    context: { execution: Execution; stageId: StageId; timeoutMs: number; inputsDigest: string }
+  ): Promise<{ exitCode: number }>;
+  reconcile?(context: ReconcileStageContext): Promise<'passed' | 'not_applied'>;
+  now?: () => number;
+  preflight?(context: { execution: Execution; remainingMs: number }): Promise<void>;
+  recover?(context: {
+    execution: Execution;
+    stage: PipelineStage;
+    state: PipelineState;
+  }): Promise<void>;
+}
+export function executePipeline(options: PipelineOptions): Promise<PipelineState>;
+export function reconcileExecution(options: {
+  execution: Execution;
+  stages: PipelineStage[];
+  stateDir: string;
+  reconcile(context: ReconcileStageContext): Promise<'passed' | 'not_applied'>;
+  recover?(context: { execution: Execution; state: PipelineState }): Promise<void>;
+  isAlive?(pid: number): boolean;
+}): Promise<PipelineState>;