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

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

@@ -0,0 +1,291 @@
+import { type CheckpointInput, type CheckpointRecord, type CommentRecord, type CriterionRecord, type DocumentRecord, type HistoryMutation, type ProviderId, type RelayTransport, type SessionRecord, type TaskColumn, type TaskRead, type TransportIdentity } from './transport.ts';
+/**
+ * Управляемый поддельный backend задач для contract tests — **fixture, не
+ * настоящий Relay**. Он воспроизводит договор транспорта: CAS-ревизии задач
+ * и сессий, done guards, append-only комментарии, сессии с fencing по run,
+ * счётчик поколения, который растёт при каждой записи (как generation
+ * Relay-2), и многостраничное чтение задачи (между страницами может пройти
+ * чужая запись). Состояние — в памяти или в файле SQLite: второй вариант
+ * разделяется несколькими процессами (crash/restart и гонки владельцев).
+ */
+interface FakeTask {
+    id: string;
+    key: string;
+    title: string;
+    description: string;
+    column: TaskColumn;
+    revision: number;
+    parentId: string | null;
+    dependencies: string[];
+    criteria: CriterionRecord[];
+}
+interface FakeSession extends SessionRecord {
+    runs: {
+        id: string;
+        state: 'active' | 'ended';
+    }[];
+    /** ID intent-чекпоинтов, ещё не закрытых. */
+    openIntents: string[];
+    accepted: string[];
+}
+interface FakeCheckpoint extends CheckpointRecord {
+    closed: boolean;
+    children: string[];
+    acceptedSessionIds: string[];
+}
+export interface FakeState {
+    provider: ProviderId;
+    projectId: string;
+    generation: number;
+    seq: number;
+    tasks: Record<string, FakeTask>;
+    comments: Record<string, CommentRecord[]>;
+    documents: Record<string, DocumentRecord & {
+        targets: string[];
+    }>;
+    sessions: Record<string, FakeSession>;
+    checkpoints: Record<string, FakeCheckpoint>;
+    /** Принятые мутации по операциям (для отчёта; проверки считают по записям получателя). */
+    mutations: Record<string, number>;
+}
+/** Хранилище состояния подделки: в памяти либо в общей SQLite. */
+export interface FakeBackend {
+    with<T>(fn: (state: FakeState) => T, write: boolean): T;
+    close(): void;
+}
+export declare const emptyFakeState: (provider: ProviderId, projectId: string) => FakeState;
+export declare function memoryBackend(state: FakeState): FakeBackend;
+/** Состояние в файле SQLite: каждая операция — транзакция `BEGIN IMMEDIATE`. */
+export declare function fileBackend(file: string, init?: FakeState): FakeBackend;
+/** Транспорт поверх подделки — тот же договор, что у настоящих адаптеров. */
+export declare class FakeRelayTransport implements RelayTransport {
+    readonly backend: FakeBackend;
+    readonly options: {
+        provider: ProviderId;
+        actor: string;
+        history?: boolean;
+    };
+    readonly provider: ProviderId;
+    /** Хук между страницами чтения задачи: тесты вносят здесь чужую запись. */
+    onPage?: (page: 'task' | 'links' | 'documents', ref: string) => void | Promise<void>;
+    private readonly projectId;
+    constructor(backend: FakeBackend, options: {
+        provider: ProviderId;
+        actor: string;
+        history?: boolean;
+    });
+    private fail;
+    private read;
+    private write;
+    private static resolve;
+    private taskOf;
+    /** Транзитивно завершена: done, все критерии, дети и зависимости. */
+    static finished(s: FakeState, id: string, seen?: Set<string>): boolean;
+    private static summary;
+    identity(): Promise<TransportIdentity>;
+    readTask(ref: string): Promise<TaskRead>;
+    listComments(ref: string): Promise<CommentRecord[]>;
+    addComment(ref: string, input: {
+        title: string;
+        body: string;
+    }): Promise<{
+        commentId: string;
+    }>;
+    setCriterion(ref: string, input: {
+        criterionId: string;
+        completed: boolean;
+        ifRevision: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    move(ref: string, input: {
+        column: TaskColumn;
+        ifRevision: number;
+    }): Promise<{
+        revision: number;
+    }>;
+    private requireHistory;
+    private sessionOf;
+    private view;
+    /** CAS ревизии сессии и fencing по run. */
+    private guard;
+    private newRun;
+    startSession(input: {
+        title: string;
+        description: string;
+        client: string;
+    }): Promise<HistoryMutation>;
+    getSession(ref: string): Promise<SessionRecord>;
+    findSessions(marker: string): Promise<SessionRecord[]>;
+    checkpoints(sessionRef: string): Promise<{
+        id: string;
+        key: string;
+        sessionId: string;
+        runId: string;
+        kind: "intent" | "progress" | "result" | "cancel";
+        intentId: string | null;
+        title: string;
+        body: string;
+    }[]>;
+    openIntent(sessionRef: string, input: CheckpointInput & {
+        runId: string;
+        ifRevision: number;
+    }): Promise<{
+        session: SessionRecord;
+        checkpoint: FakeCheckpoint;
+    }>;
+    checkpoint(intentRef: string, kind: 'progress' | 'result' | 'cancel', input: CheckpointInput & {
+        runId: string;
+        ifRevision: number;
+    }): Promise<{
+        session: SessionRecord;
+        checkpoint: FakeCheckpoint;
+    }>;
+    fork(intentRef: string, input: {
+        runId: string;
+        ifRevision: number;
+        title: string;
+        description: string;
+    }): Promise<{
+        session: SessionRecord;
+        childSession: SessionRecord;
+    }>;
+    attach(sessionRef: string, input: {
+        ifRevision: number;
+        client: string;
+    }): Promise<{
+        session: SessionRecord;
+        runId: string;
+    }>;
+    takeover(sessionRef: string, input: {
+        ifRevision: number;
+        reason: string;
+        client: string;
+    }): Promise<{
+        session: SessionRecord;
+        runId: string;
+    }>;
+    finishSession(sessionRef: string, outcome: 'complete' | 'cancel', input: {
+        runId?: string;
+        ifRevision: number;
+        result: string;
+    }): Promise<{
+        session: SessionRecord;
+    }>;
+}
+/**
+ * Действия «другого участника» прямо в подделке: постановка задач, правки,
+ * перехват сессии. Ядро коннектора ими не пользуется.
+ */
+export declare class FakeAdmin {
+    readonly backend: FakeBackend;
+    constructor(backend: FakeBackend);
+    private write;
+    createTask(input: {
+        title: string;
+        description: string;
+        column?: TaskColumn;
+        criteria?: {
+            title: string;
+            summary?: string;
+        }[];
+        dependencies?: string[];
+        parentId?: string;
+    }): {
+        id: string;
+        key: string;
+        criteria: string[];
+    };
+    task(id: string): FakeTask | undefined;
+    updateTask(id: string, patch: {
+        title?: string;
+        description?: string;
+    }): void;
+    addCriterion(id: string, title: string): string;
+    updateCriterion(id: string, criterionId: string, title: string): void;
+    completeCriterion(id: string, criterionId: string, completed?: boolean): void;
+    addDocument(taskId: string, doc: {
+        name: string;
+        body: string;
+    }): {
+        id: string;
+    };
+    updateDocument(id: string, body: string): void;
+    addDependency(id: string, dependsOn: string): void;
+    /** Перемещение с соблюдением done guards (как у человека в backend). */
+    move(id: string, column: TaskColumn): void;
+    comment(id: string, body: string, actor?: string): void;
+    takeover(sessionId: string): void;
+    state(): FakeState;
+}
+export interface Barrier {
+    /** Вызывается внутри транспорта: отметить прибытие и ждать разрешения. */
+    arrive(): Promise<void>;
+}
+/** Барьер одного процесса. */
+export declare class LocalBarrier implements Barrier {
+    private arrived;
+    private released;
+    readonly reached: Promise<void>;
+    private readonly gate;
+    arrive(): Promise<void>;
+    release(): void;
+}
+/** Барьер между процессами: файлы `<name>.reached` и `<name>.release` в общем каталоге. */
+export declare class FileBarrier implements Barrier {
+    readonly dir: string;
+    readonly name: string;
+    readonly timeoutMs: number;
+    constructor(dir: string, name: string, timeoutMs?: number);
+    private file;
+    arrive(): Promise<void>;
+    /** Ждать прибытия (конечный срок). */
+    reached(timeoutMs?: number): Promise<number>;
+    release(): void;
+}
+export type FaultAction = 
+/** Отказ до отправки (`unavailable`): получатель запроса не видел. */
+'fail-before-send'
+/** Запрос выполнен получателем, ответ потерян (`uncertain`). */
+ | 'drop-response'
+/** Таймаут без применения (`uncertain`): исход для ядра неизвестен. */
+ | 'timeout'
+/** Ответ не по договору после выполнения (`protocol`, мутация могла пройти). */
+ | 'protocol-after'
+/** Подтверждённый структурный отказ получателя без выполнения (`refused`/`conflict` с кодом). */
+ | 'refuse'
+/** Ждать барьер перед вызовом. */
+ | 'barrier'
+/** Завершить процесс до вызова (crash до отправки). */
+ | 'exit-before'
+/** Завершить процесс после выполнения получателем (crash до сохранения итога). */
+ | 'exit-after'
+/** После вызова выполнить действие (чужая запись между страницами/чтениями). */
+ | 'after';
+export interface FaultRule {
+    /** Метод транспорта (`addComment`, `readTask`, `checkpoint`…). */
+    op: keyof RelayTransport;
+    /** Номер вызова (с 1); без него — каждый вызов. */
+    nth?: number;
+    /** Сколько вызовов подряд, начиная с `nth`. */
+    times?: number;
+    action: FaultAction;
+    barrier?: Barrier;
+    after?: () => void | Promise<void>;
+    exitCode?: number;
+    /** Текст ошибки получателя вместо стандартного (например, с canary-строкой). */
+    message?: string;
+    /** Для `refuse`: класс и код отказа (по умолчанию refused/VALIDATION_ERROR). */
+    refusal?: {
+        kind: 'refused' | 'conflict';
+        code: string;
+    };
+}
+/**
+ * Обёртка отказов вокруг **любого** транспорта (подделки или настоящего
+ * адаптера): управляемые точки отказа без случайных задержек.
+ */
+export declare function faultyTransport(inner: RelayTransport, rules: FaultRule[]): RelayTransport & {
+    calls: Record<string, number>;
+};
+export {};