devcontour-harness 0.1.0-alpha.5 → 0.1.0-alpha.6

package/lib/integrations/connector/steps.js

@@ -0,0 +1,188 @@
+import { TransportError } from "./transport.js";
+export class StepUncertain extends Error {
+    step;
+    name = 'StepUncertain';
+    constructor(step, message) {
+        super(message);
+        this.step = step;
+    }
+}
+export class StepConflict extends Error {
+    step;
+    currentRevision;
+    name = 'StepConflict';
+    constructor(step, message, currentRevision) {
+        super(message);
+        this.step = step;
+        this.currentRevision = currentRevision;
+    }
+}
+/** Отправка точно не состоялась (или доказано отсутствие записи): шаг можно повторить позже. */
+export class StepRetry extends Error {
+    step;
+    name = 'StepRetry';
+    constructor(step, message) {
+        super(message);
+        this.step = step;
+    }
+}
+const at = () => new Date().toISOString();
+const reasonOf = (error) => (error instanceof Error ? error.message : String(error)).slice(0, 1000);
+/**
+ * Выполнить шаг по протоколу. `prepare` — входы, известные только в момент
+ * отправки (CAS-ревизия), записываются вместе с `sending` до вызова.
+ */
+export async function runStep(io, handlers) {
+    let step = io.load();
+    if (step.status === 'done' || step.status === 'skipped')
+        return step.result ?? {};
+    if (step.status === 'uncertain')
+        throw new StepUncertain(step.n, step.reason ?? 'исход шага не доказан');
+    if (step.status === 'conflict')
+        throw new StepConflict(step.n, step.reason ?? 'конфликт');
+    const settle = (rb, context) => {
+        switch (rb.state) {
+            case 'found':
+                io.save({ ...step, status: 'done', result: rb.result, reason: context, updatedAt: at() });
+                return rb.result;
+            case 'absent':
+                // Запись не применена: шаг снова planned; повтор — следующим явным вызовом.
+                io.save({
+                    ...step,
+                    status: 'planned',
+                    reason: `${context}: ${rb.reason}`,
+                    updatedAt: at(),
+                });
+                throw new StepRetry(step.n, `${context}: ${rb.reason}`);
+            case 'foreign':
+                io.save({
+                    ...step,
+                    status: 'conflict',
+                    reason: `${context}: ${rb.reason}`,
+                    updatedAt: at(),
+                });
+                throw new StepConflict(step.n, `${context}: ${rb.reason}`);
+            case 'ambiguous':
+                io.save({
+                    ...step,
+                    status: 'uncertain',
+                    reason: `${context}: ${rb.reason}`,
+                    updatedAt: at(),
+                });
+                throw new StepUncertain(step.n, `${context}: ${rb.reason}`);
+        }
+    };
+    const readBack = async (context) => {
+        let rb;
+        try {
+            rb = await handlers.readBack(step.input);
+        }
+        catch (error) {
+            rb = { state: 'ambiguous', reason: 'read-back недоступен: ' + reasonOf(error) };
+        }
+        return settle(rb, context);
+    };
+    if (step.status === 'sending') {
+        // Прежний процесс оборвался во время вызова: только факты получателя.
+        try {
+            return await readBack('после прерванной отправки');
+        }
+        catch (error) {
+            if (!(error instanceof StepRetry))
+                throw error;
+            step = io.load();
+        }
+    }
+    const refused = (error) => {
+        const reason = `подтверждённый отказ получателя (${error.details.code ?? error.kind}): ${reasonOf(error)}`;
+        io.save({ ...step, status: 'planned', reason, updatedAt: at() });
+        throw new StepRetry(step.n, reason);
+    };
+    const extra = handlers.prepare?.() ?? {};
+    step = {
+        ...step,
+        status: 'sending',
+        input: { ...step.input, ...extra },
+        sends: step.sends + 1,
+        updatedAt: at(),
+    };
+    io.save(step);
+    let result;
+    try {
+        result = await handlers.send(step.input);
+    }
+    catch (error) {
+        // Составной шаг (история) сам разобрал свои записи и назвал итог.
+        if (error instanceof StepConflict) {
+            io.save({ ...step, status: 'conflict', reason: error.message, updatedAt: at() });
+            throw new StepConflict(step.n, error.message, error.currentRevision);
+        }
+        if (error instanceof StepUncertain) {
+            io.save({ ...step, status: 'uncertain', reason: error.message, updatedAt: at() });
+            throw new StepUncertain(step.n, error.message);
+        }
+        if (error instanceof StepRetry) {
+            io.save({ ...step, status: 'planned', reason: error.message, updatedAt: at() });
+            throw new StepRetry(step.n, error.message);
+        }
+        if (!(error instanceof TransportError)) {
+            // Не транспорт (ошибка кода/отмена): исход вызова неизвестен.
+            return readBack('исключение во время вызова: ' + reasonOf(error));
+        }
+        switch (error.kind) {
+            case 'unavailable':
+                io.save({ ...step, status: 'planned', reason: reasonOf(error), updatedAt: at() });
+                throw new StepRetry(step.n, 'получатель недоступен, запрос не отправлен: ' + reasonOf(error));
+            case 'unsupported':
+                io.save({ ...step, status: 'planned', reason: reasonOf(error), updatedAt: at() });
+                throw new StepRetry(step.n, 'операция не поддерживается: ' + reasonOf(error));
+            case 'conflict': {
+                // Запись без CAS (комментарий): получатель её подтверждённо отклонил —
+                // записи нет, повтор безопасен (тот же маркер).
+                if (handlers.appendOnly)
+                    return refused(error);
+                // Отказ CAS/состояния: своё ли это изменение — решают только факты.
+                // Ответ conflict означает, что получатель запись отклонил: «нет
+                // записи» здесь — конфликт (WORK_*, REVISION_CONFLICT), а не повод
+                // повторить старую команду по новой ревизии.
+                const code = error.details.code ?? 'CONFLICT';
+                let rb;
+                try {
+                    rb = await handlers.readBack(step.input);
+                }
+                catch (failure) {
+                    rb = { state: 'ambiguous', reason: 'read-back недоступен: ' + reasonOf(failure) };
+                }
+                if (rb.state === 'absent')
+                    rb = { state: 'foreign', reason: `${code}: ${reasonOf(error)}` };
+                return settle(rb, 'конфликт ' + code);
+            }
+            case 'refused':
+                // Подтверждённый отказ (структурный ответ получателя): мутации не было.
+                // Это не неизвестный исход: шаг снова planned, повтор — следующей доставкой.
+                return refused(error);
+            case 'not-found':
+                io.save({ ...step, status: 'conflict', reason: reasonOf(error), updatedAt: at() });
+                throw new StepConflict(step.n, `запись получателя не найдена (${error.details.code ?? error.kind}): ${reasonOf(error)}`, 'removed');
+            case 'protocol':
+                // Ответ вне договора на чтение/немутирующий вызов — не неизвестный исход записи.
+                if (error.details.mutation === false)
+                    return refused(error);
+                return readBack('неизвестный исход (' + error.kind + ')');
+            case 'uncertain':
+                return readBack('неизвестный исход (' + error.kind + ')');
+        }
+    }
+    io.save({ ...step, status: 'done', result, updatedAt: at() });
+    return result;
+}
+export const markerOf = (key, n) => `<!-- devcontour-harness:op=${key}:step=${n} -->`;
+export const newStep = (n, kind, key, input) => ({
+    n,
+    kind,
+    status: 'planned',
+    marker: markerOf(key, n),
+    input,
+    sends: 0,
+    updatedAt: at(),
+});

package/lib/integrations/connector/store.d.ts

@@ -0,0 +1,140 @@
+import { HarnessError } from '../../contracts/index.ts';
+import type { ProviderId } from './transport.ts';
+export type StepStatus = 'planned' | 'sending' | 'done' | 'skipped' | 'conflict' | 'uncertain';
+/** Шаг доставки или истории: внешний вызов с маркером и его подтверждённый итог. */
+export interface StepRecord {
+    n: number;
+    kind: 'comment' | 'historical-comment' | 'criterion' | 'move' | 'history' | 'session.start' | 'session.intent' | 'session.fork' | 'session.attach' | 'session.checkpoint' | 'session.finish';
+    status: StepStatus;
+    marker: string;
+    /** Параметры шага, закреплённые при планировании (критерий, колонка, выход истории). */
+    input: Record<string, unknown>;
+    /** Подтверждённый итог (ID комментария, новая ревизия, ID сессии). */
+    result?: Record<string, unknown>;
+    reason?: string;
+    /** Сколько раз шаг отправлялся (вне `planned`); не повод для повтора. */
+    sends: number;
+    updatedAt: string;
+}
+export type OperationStatus = 'intent' | 'in-progress' | 'delivered' | 'conflict' | 'uncertain' | 'failed';
+export interface OperationRecord {
+    key: string;
+    provider: ProviderId;
+    projectId: string;
+    workId: string;
+    runId: string;
+    taskId: string;
+    resultDigest: string;
+    /** Редакция (semantic digest) постановки, к которой относится результат. */
+    revision: string;
+    outcome: string;
+    status: OperationStatus;
+    steps: StepRecord[];
+    /** Шаги спланированы (после предварительной сверки, до первой мутации). */
+    planned: boolean;
+    reason?: string;
+    /** Текущая редакция источника при конфликте. */
+    currentRevision?: string;
+    receipt?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LeaseRecord {
+    key: string;
+    token: string;
+    owner: string;
+    expiresAt: number;
+    fence: number;
+}
+export interface SnapshotRecord {
+    revision: string;
+    graphId: string;
+    graph: unknown;
+    context: unknown;
+    manifest: unknown;
+    createdAt: string;
+}
+/** Доверенный receipt доставки принятого результата: основание предпосылки зависимой задачи. */
+export interface ReceiptRecord {
+    issuer: string;
+    orderId: string;
+    taskId: string;
+    repositoryId: string;
+    resultSha: string;
+    workId: string;
+    runId: string;
+    operation: string;
+}
+export declare class LeaseLost extends HarnessError {
+    constructor(key: string);
+}
+export declare class ConnectorStore {
+    readonly file: string;
+    readonly identity: {
+        provider: ProviderId;
+        projectId: string;
+    };
+    readonly options: {
+        readOnly?: boolean;
+        onWrite?: (what: string) => void;
+    };
+    private readonly db;
+    /**
+     * `onWrite` — точка отказа для тестов: вызывается перед каждой записью с её
+     * названием и может бросить исключение (запись не выполняется).
+     */
+    constructor(file: string, identity: {
+        provider: ProviderId;
+        projectId: string;
+    }, options?: {
+        readOnly?: boolean;
+        onWrite?: (what: string) => void;
+    });
+    private checkIdentity;
+    close(): void;
+    /** Синхронная транзакция записи; внутри нет сети, процессов и `await`. */
+    private tx;
+    putSnapshot(record: Omit<SnapshotRecord, 'createdAt'>): {
+        record: SnapshotRecord;
+        created: boolean;
+    };
+    snapshot(revision: string): SnapshotRecord | undefined;
+    /** Последний снимок графа (по времени записи). */
+    latestSnapshot(graphId: string): SnapshotRecord | undefined;
+    /** Последний закреплённый снимок любого графа этого коннектора. */
+    latestSnapshotAny(): SnapshotRecord | undefined;
+    /**
+     * Взять владение операцией. Действующий lease другого владельца — отказ
+     * (`undefined` с текущим держателем); истёкший — перехват с новым токеном
+     * и увеличенным fence. Intent операции при этом не теряется: он в
+     * отдельной записи.
+     */
+    acquire(key: string, owner: string, ms: number): {
+        lease?: LeaseRecord;
+        holder?: LeaseRecord;
+    };
+    lease(key: string): LeaseRecord | undefined;
+    private assertLease;
+    /** Продлить владение; утраченное — `LeaseLost`. */
+    renew(key: string, token: string, ms: number): void;
+    release(key: string, token: string): void;
+    operation(key: string): OperationRecord | undefined;
+    operations(filter?: {
+        workId?: string;
+        taskId?: string;
+    }): OperationRecord[];
+    /** Записать intent до любого внешнего вызова; повтор существующего не меняет его. */
+    putIntent(record: Omit<OperationRecord, 'createdAt' | 'updatedAt' | 'status' | 'steps' | 'planned'>, token: string): OperationRecord;
+    /** Изменить операцию под владением `token` (fencing в той же транзакции). */
+    updateOp(key: string, token: string, mutate: (op: OperationRecord) => OperationRecord, what?: string): OperationRecord;
+    private writeOp;
+    putReceipt(receipt: ReceiptRecord, token: string): void;
+    receipts(orderId?: string): ReceiptRecord[];
+    history<T>(key: string): T | undefined;
+    histories<T>(prefix: string): {
+        key: string;
+        value: T;
+    }[];
+    /** Записать связь истории; `mutate` получает прежнее значение. */
+    putHistory<T>(key: string, mutate: (prior: T | undefined) => T): T;
+}

package/lib/integrations/connector/store.js

@@ -0,0 +1,277 @@
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { HarnessError } from "../../contracts/index.js";
+/**
+ * Служебная запись коннектора — отдельная SQLite
+ * `<stateDir>/connectors/<provider>-<hash(projectId)>.sqlite`. Это не
+ * состояние исполнения (оно остаётся в `state.sqlite` harness): здесь только
+ * минимальные данные восстановления — снимки (manifest и digest), операции
+ * доставки (intent, шаги, receipt), владение доставкой (lease) и связи с
+ * историей backend.
+ *
+ * Каждая запись — отдельная транзакция `BEGIN IMMEDIATE` без сети и `await`
+ * внутри. Записи операции, начиная с владения, проверяют lease в той же
+ * транзакции: процесс, потерявший владение, ничего не записывает.
+ */
+const SCHEMA_VERSION = '1';
+export class LeaseLost extends HarnessError {
+    constructor(key) {
+        super('LEASE_STALE', 'Владение доставкой утрачено: ' + key.slice(0, 16));
+    }
+}
+const now = () => new Date().toISOString();
+export class ConnectorStore {
+    file;
+    identity;
+    options;
+    db;
+    /**
+     * `onWrite` — точка отказа для тестов: вызывается перед каждой записью с её
+     * названием и может бросить исключение (запись не выполняется).
+     */
+    constructor(file, identity, options = {}) {
+        this.file = file;
+        this.identity = identity;
+        this.options = options;
+        if (options.readOnly) {
+            if (!existsSync(file))
+                throw new HarnessError('NOT_FOUND', 'Состояние коннектора не найдено');
+            this.db = new DatabaseSync(file, { readOnly: true });
+            this.db.exec('PRAGMA busy_timeout=20000;');
+            this.checkIdentity();
+            return;
+        }
+        mkdirSync(dirname(file), { recursive: true });
+        this.db = new DatabaseSync(file);
+        this.db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=20000; PRAGMA synchronous=FULL;');
+        this.tx(() => {
+            this.db.exec(`
+        CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS snapshots (revision TEXT PRIMARY KEY, graph_id TEXT NOT NULL, data TEXT NOT NULL, created_at TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS operations (key TEXT PRIMARY KEY, work_id TEXT NOT NULL, run_id TEXT NOT NULL, task_id TEXT NOT NULL, status TEXT NOT NULL, data TEXT NOT NULL, updated_at TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS leases (key TEXT PRIMARY KEY, token TEXT NOT NULL, owner TEXT NOT NULL, expires_at INTEGER NOT NULL, fence INTEGER NOT NULL);
+        CREATE TABLE IF NOT EXISTS receipts (operation TEXT PRIMARY KEY, order_id TEXT NOT NULL, data TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS history (key TEXT PRIMARY KEY, data TEXT NOT NULL, updated_at TEXT NOT NULL);`);
+            const ins = this.db.prepare('INSERT OR IGNORE INTO meta VALUES(?, ?)');
+            ins.run('schema', SCHEMA_VERSION);
+            ins.run('provider', identity.provider);
+            ins.run('projectId', identity.projectId);
+        });
+        this.checkIdentity();
+    }
+    checkIdentity() {
+        const get = (k) => this.db.prepare('SELECT value FROM meta WHERE key=?').get(k)?.value;
+        if (get('schema') !== SCHEMA_VERSION)
+            throw new HarnessError('STATE_VERSION_UNSUPPORTED', 'Состояние коннектора другой версии: ' + String(get('schema')));
+        if (get('provider') !== this.identity.provider || get('projectId') !== this.identity.projectId)
+            throw new HarnessError('INVALID_INPUT', 'Состояние коннектора принадлежит другому provider/проекту: ' + this.file);
+    }
+    close() {
+        this.db.close();
+    }
+    /** Синхронная транзакция записи; внутри нет сети, процессов и `await`. */
+    tx(fn, what) {
+        if (what)
+            this.options.onWrite?.(what);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const out = fn();
+            this.db.exec('COMMIT');
+            return out;
+        }
+        catch (error) {
+            if (this.db.isTransaction)
+                this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    /* ---------------------------------------------------------------- */
+    /* Снимки                                                            */
+    /* ---------------------------------------------------------------- */
+    putSnapshot(record) {
+        return this.tx(() => {
+            const prior = this.snapshot(record.revision);
+            // Повтор той же редакции не меняет записанный снимок (и время его создания).
+            if (prior)
+                return { record: prior, created: false };
+            const full = { ...record, createdAt: now() };
+            this.db
+                .prepare('INSERT INTO snapshots VALUES(?, ?, ?, ?)')
+                .run(record.revision, record.graphId, JSON.stringify(full), full.createdAt);
+            return { record: full, created: true };
+        }, 'snapshot');
+    }
+    snapshot(revision) {
+        const row = this.db.prepare('SELECT data FROM snapshots WHERE revision=?').get(revision);
+        return row ? JSON.parse(row.data) : undefined;
+    }
+    /** Последний снимок графа (по времени записи). */
+    latestSnapshot(graphId) {
+        const row = this.db
+            .prepare('SELECT data FROM snapshots WHERE graph_id=? ORDER BY created_at DESC, rowid DESC LIMIT 1')
+            .get(graphId);
+        return row ? JSON.parse(row.data) : undefined;
+    }
+    /** Последний закреплённый снимок любого графа этого коннектора. */
+    latestSnapshotAny() {
+        const row = this.db
+            .prepare('SELECT data FROM snapshots ORDER BY created_at DESC, rowid DESC LIMIT 1')
+            .get();
+        return row ? JSON.parse(row.data) : undefined;
+    }
+    /* ---------------------------------------------------------------- */
+    /* Владение доставкой                                                */
+    /* ---------------------------------------------------------------- */
+    /**
+     * Взять владение операцией. Действующий lease другого владельца — отказ
+     * (`undefined` с текущим держателем); истёкший — перехват с новым токеном
+     * и увеличенным fence. Intent операции при этом не теряется: он в
+     * отдельной записи.
+     */
+    acquire(key, owner, ms) {
+        return this.tx(() => {
+            const prior = this.lease(key);
+            const at = Date.now();
+            if (prior && prior.expiresAt > at)
+                return { holder: prior };
+            const lease = {
+                key,
+                token: randomUUID(),
+                owner,
+                expiresAt: at + ms,
+                fence: (prior?.fence ?? 0) + 1,
+            };
+            this.db
+                .prepare('INSERT OR REPLACE INTO leases VALUES(?, ?, ?, ?, ?)')
+                .run(key, lease.token, owner, lease.expiresAt, lease.fence);
+            return { lease };
+        }, 'lease');
+    }
+    lease(key) {
+        const row = this.db.prepare('SELECT * FROM leases WHERE key=?').get(key);
+        return row
+            ? {
+                key: row.key,
+                token: row.token,
+                owner: row.owner,
+                expiresAt: row.expires_at,
+                fence: row.fence,
+            }
+            : undefined;
+    }
+    assertLease(key, token) {
+        const lease = this.lease(key);
+        if (!lease || lease.token !== token || lease.expiresAt <= Date.now())
+            throw new LeaseLost(key);
+    }
+    /** Продлить владение; утраченное — `LeaseLost`. */
+    renew(key, token, ms) {
+        this.tx(() => {
+            this.assertLease(key, token);
+            this.db
+                .prepare('UPDATE leases SET expires_at=? WHERE key=? AND token=?')
+                .run(Date.now() + ms, key, token);
+        }, 'lease.renew');
+    }
+    release(key, token) {
+        try {
+            this.tx(() => {
+                this.db.prepare('UPDATE leases SET expires_at=0 WHERE key=? AND token=?').run(key, token);
+            });
+        }
+        catch {
+            /* Невозможность освободить — lease истечёт сам. */
+        }
+    }
+    /* ---------------------------------------------------------------- */
+    /* Операции доставки                                                 */
+    /* ---------------------------------------------------------------- */
+    operation(key) {
+        const row = this.db.prepare('SELECT data FROM operations WHERE key=?').get(key);
+        return row ? JSON.parse(row.data) : undefined;
+    }
+    operations(filter = {}) {
+        const rows = this.db
+            .prepare('SELECT data FROM operations WHERE (:w IS NULL OR work_id=:w) AND (:t IS NULL OR task_id=:t) ORDER BY rowid')
+            .all({ w: filter.workId ?? null, t: filter.taskId ?? null });
+        return rows.map((r) => JSON.parse(r.data));
+    }
+    /** Записать intent до любого внешнего вызова; повтор существующего не меняет его. */
+    putIntent(record, token) {
+        return this.tx(() => {
+            this.assertLease(record.key, token);
+            const prior = this.operation(record.key);
+            if (prior)
+                return prior;
+            const full = {
+                ...record,
+                status: 'intent',
+                steps: [],
+                planned: false,
+                createdAt: now(),
+                updatedAt: now(),
+            };
+            this.writeOp(full);
+            return full;
+        }, 'intent');
+    }
+    /** Изменить операцию под владением `token` (fencing в той же транзакции). */
+    updateOp(key, token, mutate, what = 'operation') {
+        return this.tx(() => {
+            this.assertLease(key, token);
+            const prior = this.operation(key);
+            if (!prior)
+                throw new HarnessError('NOT_FOUND', 'Операция доставки не найдена');
+            const next = { ...mutate(structuredClone(prior)), updatedAt: now() };
+            this.writeOp(next);
+            return next;
+        }, what);
+    }
+    writeOp(op) {
+        this.db
+            .prepare('INSERT OR REPLACE INTO operations VALUES(?, ?, ?, ?, ?, ?, ?)')
+            .run(op.key, op.workId, op.runId, op.taskId, op.status, JSON.stringify(op), op.updatedAt);
+    }
+    /* ---------------------------------------------------------------- */
+    /* Доверенные receipts                                               */
+    /* ---------------------------------------------------------------- */
+    putReceipt(receipt, token) {
+        this.tx(() => {
+            this.assertLease(receipt.operation, token);
+            this.db
+                .prepare('INSERT OR REPLACE INTO receipts VALUES(?, ?, ?)')
+                .run(receipt.operation, receipt.orderId, JSON.stringify(receipt));
+        }, 'receipt');
+    }
+    receipts(orderId) {
+        const rows = this.db
+            .prepare('SELECT data FROM receipts WHERE (:o IS NULL OR order_id=:o) ORDER BY rowid')
+            .all({ o: orderId ?? null });
+        return rows.map((r) => JSON.parse(r.data));
+    }
+    /* ---------------------------------------------------------------- */
+    /* История                                                           */
+    /* ---------------------------------------------------------------- */
+    history(key) {
+        const row = this.db.prepare('SELECT data FROM history WHERE key=?').get(key);
+        return row ? JSON.parse(row.data) : undefined;
+    }
+    histories(prefix) {
+        const rows = this.db
+            .prepare('SELECT key, data FROM history WHERE substr(key, 1, length(:p)) = :p ORDER BY rowid')
+            .all({ p: prefix });
+        return rows.map((r) => ({ key: r.key, value: JSON.parse(r.data) }));
+    }
+    /** Записать связь истории; `mutate` получает прежнее значение. */
+    putHistory(key, mutate) {
+        return this.tx(() => {
+            const next = mutate(this.history(key));
+            this.db
+                .prepare('INSERT OR REPLACE INTO history VALUES(?, ?, ?)')
+                .run(key, JSON.stringify(next), now());
+            return next;
+        }, 'history');
+    }
+}

package/lib/integrations/connector/summary.d.ts

@@ -0,0 +1,38 @@
+import type { RunResult } from '../../contracts/index.ts';
+import { type Redactor } from '../../environment/redaction.ts';
+/**
+ * Краткий итог для внешнего хранилища задач. В нём: исход, проверяемые SHA,
+ * сводка gates, сопоставление критериев, источник снимка и receipt. Не
+ * попадают: полный runtime log, вызовы инструментов, локальные пути (они не
+ * являются ссылками, доступными с другого компьютера), lease/fencing токены
+ * и секреты (маскируются `redact`).
+ */
+export interface CriterionOutcome {
+    criterionId: string;
+    title: string;
+    gate?: string;
+    testId?: string;
+    /** `closed` — закрыт этой доставкой; `already` — уже был отмечен; остальные — блокеры. */
+    outcome: 'closed' | 'already' | 'unproven' | 'manual';
+    reason?: string;
+}
+export declare const stripPaths: (text: string) => string;
+export declare function summaryText(input: {
+    marker: string;
+    result: RunResult;
+    task: {
+        key: string;
+        identity: string;
+    };
+    snapshot: {
+        revision: string;
+        casRevision: number;
+    };
+    criteria: CriterionOutcome[];
+    completion: string;
+    historical?: boolean;
+    redact?: Redactor;
+}): {
+    title: string;
+    body: string;
+};