@raphy-js/raph 1.0.1-dev.20 → 1.0.1-dev.25

package/dist/runtime/phases/RaphPhasePipeline.d.ts

@@ -1,25 +1,37 @@
-import { Disposer, EffectTask } from '../../reactivity/types';
 import { RaphScope } from '../ownership/RaphScope';
-import { RaphFrameContext, RaphPhase, RaphPhaseEffect, RaphPhaseTask, RaphSchedulerMode, RaphWorkCause } from './phase.types';
-export interface RaphPhaseBinding extends EffectTask {
-    readonly task: RaphPhaseTask;
-    /** Stops the owning implicit effect when a fatal discard cannot re-arm it. @internal */
-    abort?: Disposer;
-    enqueue: (cause: RaphWorkCause, key?: object, schedule?: boolean) => void;
-    pause: () => void;
-    resume: () => void;
+import { RuntimeReactivity } from '../reactivity/RuntimeReactivity';
+import { RaphFrameContext, RaphPhase, RaphPhaseEffect, RaphSchedulerMode, RaphWorkCause } from './phase.types';
+import { RaphPhaseTaskRecord } from './RaphPhaseTaskRecord';
+/**
+ * Постоянное состояние одной phase: живая очередь, запасной массив для обмена
+ * при разборе и число bindings. Состояние переживает переопределение phases, пока
+ * имя phase сохраняется, поэтому запись binding держит прямую ссылку на него и
+ * ставится в очередь без поиска по имени. Через него же запись находит свой
+ * pipeline: отдельной ссылки на pipeline у записи нет.
+ *
+ * Инвариант: каждая запись живой очереди активна и ожидает доставки, а
+ * `spare` пуст вне разбора своей phase.
+ */
+export declare class RaphPhaseState {
+    readonly name: string;
+    readonly pipeline: RaphPhasePipeline;
+    queue: RaphPhaseTaskRecord[];
+    spare: RaphPhaseTaskRecord[];
+    bindings: number;
+    constructor(name: string, pipeline: RaphPhasePipeline);
 }
 /** Единая Runtime-owned очередь persistent phase bindings. */
 export declare class RaphPhasePipeline {
     private readonly _scheduler;
-    private readonly _runUntracked;
+    private readonly _reactivity;
     private readonly _resolveCause;
     private readonly _deferSync;
     private readonly _tracePhase?;
     private _phases;
     private _phaseByName;
-    private readonly _phaseBindings;
-    private readonly _queues;
+    private _resolvedInput;
+    private _resolvedState;
+    private _queuedCount;
     private readonly _deferred;
     private readonly _idleWaiters;
     private _taskSequence;
@@ -28,51 +40,213 @@ export declare class RaphPhasePipeline {
     private _frameHandle;
     private _frameHandleKind;
     private _configurationLocked;
-    private _running;
+    /**
+     * Flush исполняется сейчас: новая работа попадёт в его следующий проход.
+     *
+     * @internal
+     */
+    _running: boolean;
+    private _idleSlotFlags;
     private _disposed;
     private _firstFrameAt;
     private _lastFrameAt;
     private _frameNumber;
     private _frame;
-    constructor(_scheduler: RaphSchedulerMode, _runUntracked: <T>(operation: () => T) => T, _resolveCause: (token: unknown) => RaphWorkCause | undefined, _deferSync?: () => boolean, _tracePhase?: ((phase: string, status: "end" | "error" | "start", error?: unknown) => void) | undefined);
+    constructor(_scheduler: RaphSchedulerMode, _reactivity: RuntimeReactivity, _resolveCause: (token: unknown) => RaphWorkCause | undefined, _deferSync?: () => boolean, _tracePhase?: ((phase: string, status: "end" | "error" | "start", error?: unknown) => void) | undefined);
     get frame(): RaphFrameContext;
     get phases(): readonly RaphPhase[];
     definePhases(phases: readonly RaphPhase[]): void;
     addPhase(phase: RaphPhase): void;
     clearPhases(): void;
-    requirePhase(name: string): void;
-    bindTask(phaseInput: string, consumerOwner: RaphScope, effect: RaphPhaseEffect, priority: number, runner: () => void): RaphPhaseBinding;
+    /**
+     * Находит состояние объявленной phase по имени, которое передал вызывающий.
+     * Подряд идущие bindings одной phase попадают в кэш из одной записи; точное
+     * имя находится без `trim()`, и только имя с пробелами по краям нормализуется.
+     */
+    resolvePhase(input: string): RaphPhaseState;
+    /**
+     * Создаёт постоянную запись одного binding. Вызывающий уже разрешил phase
+     * и проверил priority, поэтому горячий путь регистрации проверяет их один раз.
+     * Запись ничего не выполняет, пока вызывающий не подключит engine effect
+     * (`node`) или watch lifecycle (`watch`).
+     */
+    bindTask(phase: RaphPhaseState, consumerOwner: RaphScope, effect: RaphPhaseEffect, priority: number): RaphPhaseTaskRecord;
+    /**
+     * Создаёт постоянную запись группы из `count` slots: одна запись binding и
+     * её состояние с местом под запись графа каждого slot. Вызывающий уже
+     * разрешил phase и проверил priority и `count`; записи графа он подключает
+     * сам через _allocateTaskEffect() и кладёт в состояние по порядку slots.
+     * Slot ничего не исполняет, пока его запись не запланирована.
+     *
+     * `runSlot` занимает место callback записи: его показывает `task.effect`
+     * группы, а вызывает только общее тело записей engine — с состоянием
+     * группы, где лежат её context и номер slot. Поэтому запись группы несёт
+     * `TASK_TASKLESS`: вместо task тело получает поле `group`.
+     */
+    bindGroup(phase: RaphPhaseState, consumerOwner: RaphScope, runSlot: RaphPhaseEffect, context: unknown, count: number, priority: number): RaphPhaseTaskRecord;
     request(): void;
     afterFlush(): Promise<void>;
     flush(): void;
     dispose(): void;
     _debugPending(): boolean;
     private _describeQueued;
-    private _createTask;
+    /**
+     * Открывает доставку одной записью `state`. Накопленные причины остаются на
+     * своих местах и становятся причинами доставки под TASK_CAUSES_DELIVERED:
+     * ничего не копируется, а массив для `task.causes` строится, только если его
+     * прочитают. Frame доставки получает только запись с facade: без facade его
+     * нечем прочитать, а запись ссылки на новый frame в каждую доставленную
+     * запись стоит write barrier.
+     *
+     * Запись попадает сюда только из живой очереди, а в ней нет записей с
+     * открытой доставкой, поэтому причин прошлой доставки здесь не бывает.
+     */
     private _beginDelivery;
-    private _runDelivery;
-    private _deferDelivery;
-    private _cancelDelivery;
+    /**
+     * Исполняет открытую доставку binding. `failures` передаёт default runner:
+     * группа складывает туда сбой каждого slot отдельно. Без него сбои slots
+     * бросаются вызывающему — `task.run()` внутри `process` — после прохода: один
+     * как есть, несколько одним AggregateError.
+     *
+     * @internal
+     */
+    _runDelivery(record: RaphPhaseTaskRecord, failures?: unknown[]): void;
+    /** @internal */
+    _deferDelivery(record: RaphPhaseTaskRecord): void;
+    /** @internal */
+    _cancelDelivery(record: RaphPhaseTaskRecord): void;
     private _finishDelivery;
-    private _appendCause;
-    private _queue;
-    private _disposeTask;
-    private _pauseTask;
-    private _resumeTask;
+    /**
+     * Делает исполняемыми slots группы, которые остались запланированными после
+     * доставки: slot, изменивший собственную зависимость, и slot, чью зависимость
+     * изменили после его запуска. Slot, который не запланирован, не трогается:
+     * он уже прочитал актуальные значения и в следующей доставке не исполняется.
+     * Запись, сделанную до запуска slot в той же доставке, slot читает в ней же:
+     * прямую запись engine переводит в обязательный запуск, отложенную находит
+     * проверка зависимостей. Отдельный binding после такой записи исполняется
+     * ещё раз следующим проходом; slot повторно не исполняется.
+     *
+     * Запись без зависимостей пропускается. Запланированной она бывает в двух
+     * случаях: slot запущен во время доставки и ждёт первого запуска — тогда она
+     * исполняема с момента создания; либо повторно запущен slot, который уже
+     * исполнился и ничего не прочитал, — тогда исполнять его нечем.
+     */
+    private _rearmGroup;
+    /** @internal */
+    _notifyTask(record: RaphPhaseTaskRecord, token: unknown): void;
+    /** @internal */
+    _appendCause(record: RaphPhaseTaskRecord, cause: RaphWorkCause, key: object): void;
+    /**
+     * Переносит причины открытой доставки с места ожидающих в detail, без
+     * копирования, и освобождает это место. После вызова запись хранит оба
+     * набора раздельно: ожидающие причины — в своих полях, причины доставки — в
+     * detail. Массив, уже построенный для `task.causes`, остаётся тем же.
+     */
+    private _splitDeliveredCauses;
+    /** @internal */
+    _queue(record: RaphPhaseTaskRecord, schedule?: boolean): void;
+    /** @internal */
+    _disposeTask(record: RaphPhaseTaskRecord): void;
+    /**
+     * Полностью освобождает один binding; каждый шаг идемпотентен, поэтому
+     * владелец, engine и пользователь могут прийти сюда в любом порядке и
+     * повторно войти в метод.
+     *
+     * @internal
+     */
+    _disposeBinding(record: RaphPhaseTaskRecord): void;
+    /**
+     * Убирает из состояния группы slots, записи графа которых уже остановлены, и
+     * сообщает, остались ли при этом живые slots.
+     *
+     * Запись одного slot останавливается отдельно от группы в трёх случаях: упал
+     * cleanup перед повторным запуском slot; перезапускается или останавливается
+     * effect, внутри тела которого группа зарегистрирована; провалился запуск
+     * slot через `start()`. Engine сообщает о каждой такой остановке через task
+     * hook, общий для всех slots, и запись в этот момент уже остановлена. Группа
+     * тогда теряет только этот slot, как owner потерял бы один из отдельных
+     * bindings; запись binding освобождается, когда остановлен последний slot.
+     *
+     * Вызов владельца или effect scope остановленных записей не находит: место
+     * остановленного slot уже занято `null`.
+     *
+     * @returns true, если вызов был сообщением engine и живые slots остались.
+     */
+    private _forgetStoppedSlots;
+    /**
+     * Останавливает записи графа всех slots группы в порядке, обратном порядку
+     * slots: так владелец освобождал бы отдельные bindings. Сбой cleanup одного
+     * slot не мешает остановить остальные.
+     *
+     * Группа — один ресурс, поэтому порядок и вид ошибки не зависят от того, кто
+     * её освобождает. Effect scope отдельные bindings освободил бы в порядке
+     * регистрации и сложил бы их сбои в собственный список; группу он
+     * освобождает в обратном порядке slots и получает несколько сбоев одним
+     * AggregateError. Владелец получает тот же AggregateError как один сбой
+     * ресурса вместо отдельных сбоев bindings.
+     *
+     * Остановка первой же записи повторно входит в _disposeBinding() через task
+     * hook engine: вложенный вызов уже не находит состояния группы и освобождает
+     * состояние pipeline до cleanup slots. Группа без живых slots освобождает
+     * его здесь.
+     */
+    private _disposeGroup;
+    /**
+     * Освобождает подписку и состояние pipeline остановленного watch.
+     */
+    private _releaseWatch;
+    /** @internal */
+    _pauseTask(record: RaphPhaseTaskRecord): void;
+    /**
+     * Убирает ожидающую запись из живой очереди её phase. Запись, которую flush
+     * уже забрал на разбор, в живой очереди не находится и счётчик не меняет.
+     */
+    private _unqueue;
+    /** @internal */
+    _resumeTask(record: RaphPhaseTaskRecord): void;
+    /**
+     * Возвращает причины открытой доставки в ожидающие, впереди причин, которые
+     * пришли после её открытия; причины одного source сливаются. Причины доставки
+     * при этом остаются причинами доставки до её конца, поэтому сначала они
+     * отделяются от ожидающих.
+     */
     private _restoreDeliveryCausesBeforePending;
-    private _takePhase;
     private _schedule;
     private _scheduleDeferredTurn;
     private _cancelScheduled;
     private _activateDeferred;
     private _nextFrame;
     private _assertRetainedPhases;
-    private _assertDelivery;
-    private _hasQueued;
     private _hasPending;
     private _cancelAllQueued;
     private _cancelAllDeferred;
     private _acknowledgeDiscard;
+    /**
+     * Гасит ожидающую доставку slots группы.
+     *
+     * Slot, чей первый запуск ещё впереди, погасить нельзя: он не собрал
+     * зависимости, и после отмены его ничто не разбудит. Такой slot узнаётся по
+     * запланированной записи без единой зависимости: запись, которая уже
+     * исполнялась и ничего не прочитала, больше не планируется. Обычная отмена
+     * тогда не трогает ни один slot и возвращает false; fatal discard
+     * останавливает такие slots окончательно и гасит остальные.
+     *
+     * Обычная отмена отказывается только от того, что доставка знала при
+     * открытии. Причина, пришедшая группе после открытия доставки, означает
+     * запись, которую запланированный slot ещё не прочитал. Гашение снимает с
+     * записи slot и отметку планирования, и требование запуска, которое engine
+     * поставил при прямой записи, поэтому slots, ждавшие запуска, после гашения
+     * снова требуют его, как отдельный binding, отменённый при новой причине.
+     * Группа тогда доставляется ещё раз с новыми причинами. Fatal discard гасит
+     * всё.
+     *
+     * @returns false, если доставку нельзя отменить либо живых slots не осталось.
+     */
+    private _cancelGroup;
+    /**
+     * Сбрасывает ожидающую работу записи, снятой с очереди либо из отложенных.
+     * Такая запись не находится в доставке, поэтому её причины ожидающие.
+     */
     private _clearPendingDelivery;
     private _settleIdleWaiters;
     private _assertAlive;

package/dist/runtime/phases/RaphPhaseTaskRecord.d.ts

@@ -0,0 +1,195 @@
+import { EffectTask, OwnedResource, ReactiveNode, ScopeChildren } from '../../reactivity/types';
+import { RaphScope } from '../ownership/RaphScope';
+import { RaphEffectGroup, RaphEffectInitialMode, RaphFrameContext, RaphPhaseEffect, RaphPhaseTask, RaphWorkCause } from './phase.types';
+import { RaphPhaseState } from './RaphPhasePipeline';
+import { RaphPhaseWatch } from './RaphPhaseWatch';
+export declare const EMPTY_CAUSES: readonly RaphWorkCause[];
+export declare const EMPTY_FRAME: RaphFrameContext;
+export declare const TASK_ACTIVE = 1;
+export declare const TASK_PAUSED: number;
+export declare const TASK_PENDING: number;
+export declare const TASK_DEFERRED: number;
+export declare const TASK_IN_DELIVERY: number;
+export declare const TASK_DISCARD_ACKNOWLEDGED: number;
+export declare const TASK_REQUESTED: number;
+export declare const TASK_EXECUTED: number;
+export declare const TASK_CAUSES_DELIVERED: number;
+export declare const TASK_RESOLUTION: number;
+export declare const TASK_UNRESOLVED = 0;
+export declare const TASK_RUN: number;
+export declare const TASK_DEFER: number;
+export declare const TASK_CANCEL: number;
+export declare const TASK_TASKLESS: number;
+/**
+ * Состояние группы effects одного binding: плоский массив
+ * `[context, номер исполняемого slot, запись графа slot 0, slot 1, ...]`.
+ *
+ * Группа делит одну запись binding между несколькими отслеживаемыми
+ * вычислениями. У каждого slot своя запись графа engine, то есть свой набор
+ * зависимостей и свой признак invalidation; общими остаются запись binding и
+ * её место в очереди phase и в списке ресурсов владельца. Тело записи engine
+ * у всех slots одно, поэтому номер slot доставка записывает сюда перед
+ * запуском каждого slot, а тело slot получает само состояние как свой
+ * единственный аргумент — запуск `RaphEffectGroupRun`: первые два элемента и
+ * есть его публичная часть.
+ *
+ * На месте записи slot, остановленного отдельно от группы, стоит `null`.
+ *
+ * Состояние — массив, а не class: на группу приходится одна аллокация точного
+ * размера, и у неё нет hidden class, который терялся бы, когда освобождена
+ * последняя группа.
+ */
+export type RaphEffectGroupState = unknown[];
+export declare const GROUP_CONTEXT = 0;
+export declare const GROUP_CURSOR = 1;
+export declare const GROUP_NODES = 2;
+/**
+ * Frozen public facade of one phase binding. All state stays on the record, so
+ * the facade has a single own field and shares its capabilities through the
+ * prototype: `run`, `defer` and `cancel` need the task as receiver.
+ */
+export declare class RaphPhaseTaskHandle implements RaphPhaseTask {
+    /** @internal */
+    readonly _record: RaphPhaseTaskRecord;
+    constructor(record: RaphPhaseTaskRecord);
+    get phase(): string;
+    get consumerOwner(): RaphScope;
+    get effect(): RaphPhaseEffect;
+    get causes(): readonly RaphWorkCause[];
+    get frame(): RaphFrameContext;
+    get priority(): number;
+    get sequence(): number;
+    run(): void;
+    defer(): void;
+    cancel(): void;
+}
+/**
+ * Редкое состояние одного phase binding, вынесенное из записи. Объект создаётся
+ * при первом входе binding в одно из таких состояний и живёт до освобождения
+ * записи:
+ *
+ * - до доставки накопились причины от второго source (`extraCauses`);
+ * - причины открытой доставки пришлось отделить от ожидающих: во время
+ *   доставки пришла новая причина либо доставка отложена или остановлена
+ *   pause (`deliveryFirstCause`, `deliveryFirstCauseKey`,
+ *   `deliveryExtraCauses`);
+ * - причины доставки прочитаны через `task.causes` (`deliveryCauses`);
+ * - доставка отложена через `defer()` (`deferCount`).
+ *
+ * Binding, который исполняется и получает не больше одной причины на
+ * доставку, не читая `task.causes`, этого объекта не создаёт: ни effect с task
+ * или без неё, ни watch, ни группа.
+ *
+ * Поля объявлены без initializers и присваиваются в constructor в одном
+ * фиксированном порядке: у каждого экземпляра один hidden class.
+ *
+ * Engine удерживает форму экземпляров только через живые экземпляры. Когда в
+ * isolate не остаётся ни одного binding с редким состоянием, полная сборка
+ * мусора освобождает её вместе с кодом, оптимизированным под неё. Поэтому
+ * class владеет одним постоянным экземпляром `_shapeAnchor`.
+ */
+export declare class RaphPhaseTaskDetail {
+    static _shapeAnchor: RaphPhaseTaskDetail;
+    extraCauses: Map<object, RaphWorkCause> | undefined;
+    deliveryFirstCause: RaphWorkCause | undefined;
+    deliveryFirstCauseKey: object | undefined;
+    deliveryExtraCauses: Map<object, RaphWorkCause> | undefined;
+    deliveryCauses: readonly RaphWorkCause[] | undefined;
+    deferCount: number;
+    constructor();
+}
+/**
+ * Постоянное состояние одного phase binding. Один и тот же объект является
+ * элементом очереди pipeline, внешней задачей engine effect, элементом списка
+ * ресурсов своего consumer owner и pausable-регистрацией, передаваемой effect
+ * scopes, поэтому binding стоит одной аллокации.
+ *
+ * Запись несёт только то, что нужно binding между регистрацией и освобождением
+ * на обычном пути: признаки одним числом, место в очереди, владельца, callback,
+ * запись графа, lifecycle watch либо состояние группы, связи списка ресурсов,
+ * первую причину и лениво создаваемый frozen facade с frame, который он
+ * показывает. Остальное — причины со второй, причины доставки, отделённые от
+ * ожидающих, показанный массив причин и счётчик defer — лежит в `detail`,
+ * который создаётся при первом входе в такое состояние. Pipeline запись
+ * находит через её phase: `phaseState.pipeline`.
+ *
+ * Поля объявлены без initializers и присваиваются в constructor в одном
+ * фиксированном порядке: у каждой записи один hidden class, и ни один build
+ * target не может превратить поля в вызовы helper.
+ */
+export declare class RaphPhaseTaskRecord implements EffectTask, OwnedResource, RaphEffectGroup {
+    state: number;
+    sequence: number;
+    readonly phaseState: RaphPhaseState;
+    readonly priority: number;
+    readonly consumerOwner: RaphScope;
+    readonly effect: RaphPhaseEffect;
+    node: ReactiveNode | undefined;
+    watch: RaphPhaseWatch | undefined;
+    group: RaphEffectGroupState | undefined;
+    scopeParent: ScopeChildren<OwnedResource> | undefined;
+    scopePrevious: OwnedResource | undefined;
+    scopeNext: OwnedResource | undefined;
+    firstCause: RaphWorkCause | undefined;
+    firstCauseKey: object | undefined;
+    frame: RaphFrameContext;
+    facade: RaphPhaseTaskHandle | undefined;
+    detail: RaphPhaseTaskDetail | undefined;
+    constructor(phaseState: RaphPhaseState, priority: number, consumerOwner: RaphScope, effect: RaphPhaseEffect);
+    get phase(): string;
+    get dependencyOwner(): RaphScope;
+    get allowScheduleDuringRun(): boolean;
+    /**
+     * Становится false, когда binding остановлен: так запись видят effect scopes,
+     * которым она передана как pausable-регистрация.
+     */
+    get active(): boolean;
+    /**
+     * Причины текущей доставки в том виде, в каком их получает callback или
+     * `process`. Массив строится при первом чтении в доставке и до её конца
+     * остаётся тем же объектом; доставка, причины которой никто не прочитал, не
+     * создаёт ни массива, ни заморозки. Вне доставки и для доставки без причин
+     * это общий пустой массив.
+     *
+     * Это единственное место, где причины выходят наружу, поэтому здесь же они
+     * становятся неизменяемыми: WorkGraph создаёт причину без заморозки, а
+     * замораживает её первое чтение.
+     */
+    get causes(): readonly RaphWorkCause[];
+    /**
+     * One facade per record: created on first exposure, then reused.
+     *
+     * Запись начинает вести frame с появлением facade. Facade создаётся внутри
+     * открытой доставки своей записи — его запрашивают только тело binding и
+     * `process` — и получает её frame; frame каждой следующей доставки
+     * записывает её открытие.
+     */
+    get task(): RaphPhaseTask;
+    /** Возвращает редкое состояние записи и создаёт его при первом обращении. */
+    detailed(): RaphPhaseTaskDetail;
+    notify(token: unknown): void;
+    schedule(): void;
+    enqueue(cause: RaphWorkCause, key?: object, schedule?: boolean): void;
+    /**
+     * Запускает slot группы effects; у записи одиночного effect и watch ничего
+     * не делает. Запись группы сама является handle, который возвращает
+     * `effectGroup`.
+     */
+    start(slot: number, initial?: RaphEffectInitialMode): void;
+    /**
+     * Внутренний initial invocation renderer; публичный start не меняет signature.
+     * Continuation не сохраняется в записи и не вызывается при последующих runs.
+     * @internal
+     */
+    _start(slot: number, initial: RaphEffectInitialMode, onExecutionFailure: (error: unknown) => never): void;
+    pause(): void;
+    resume(): void;
+    /**
+     * Полностью освобождает binding; безопасен для повторного и вложенного вызова:
+     * снимает запись со списка владельца, останавливает engine effect или watch
+     * lifecycle и сбрасывает состояние pipeline. Engine вызывает его как task hook
+     * остановленного effect, владелец — как элемент списка ресурсов, а
+     * пользователь — через disposer.
+     */
+    dispose(): void;
+}

package/dist/runtime/phases/RaphPhaseWatch.d.ts

@@ -0,0 +1,22 @@
+import { Disposer } from '../../reactivity/types';
+import { RaphPhaseTaskRecord } from './RaphPhaseTaskRecord';
+import { RuntimeWatch } from '../reactivity/RuntimeWatch';
+/**
+ * Callback lifecycle одного explicit watch binding вместе с подпиской, которая
+ * его питает. Подписка освобождается при освобождении binding, до cleanup
+ * последней доставки.
+ *
+ * Lifecycle достаёт callback только через запись своего binding и сбрасывает
+ * эту ссылку при освобождении. Публичный watch disposer удерживает lifecycle,
+ * а не запись, поэтому disposer, переживший свой binding, не удерживает ни
+ * callback, ни захваченное им.
+ */
+export declare class RaphPhaseWatch extends RuntimeWatch {
+    source: Disposer | undefined;
+    record: RaphPhaseTaskRecord | undefined;
+    /**
+     * Создаёт lifecycle без подписки и без binding; оба поля задаёт регистрация.
+     */
+    constructor(runUntracked: <T>(operation: () => T) => T, callback: () => void | Disposer);
+}
+export declare function createPhaseWatch(runUntracked: <T>(operation: () => T) => T, record: RaphPhaseTaskRecord): RaphPhaseWatch;

package/dist/runtime/phases/phase.types.d.ts

@@ -45,7 +45,86 @@ export interface RaphWorkCause {
     readonly metadata?: unknown;
 }
 export type RaphPhaseEffect = (task: RaphPhaseTask) => void | Disposer;
-/** Persistent task identity, передаваемая phase process и effect callback. */
+/**
+ * Тело binding, зарегистрированного через `bindEffect`: task ему не передаётся,
+ * поэтому тело объявляется без параметров. Возвращённый cleanup выполняется
+ * перед следующим запуском и при освобождении binding.
+ */
+export type RaphPhaseBody = () => void | Disposer;
+/**
+ * Запуск одного slot группы: кортеж, который получает тело slot. Первый элемент
+ * — context группы, второй — номер исполняемого slot, считая с нуля.
+ *
+ * Кортеж один на группу и принадлежит ей: номер slot в нём меняется от запуска
+ * к запуску, а остальные элементы — внутреннее состояние группы. Тело читает
+ * первые два элемента по индексу во время вызова и не сохраняет кортеж.
+ *
+ * Кортеж — живое состояние группы, а не копия: от записи его защищает только
+ * тип. Тело, которое пишет в кортеж или читает элементы после второго,
+ * нарушает contract: запись в первый элемент подменяет context следующим
+ * slots, запись в остальные ломает доставку группы.
+ *
+ * @typeParam Context — значение, которое группа передаёт телу каждого slot.
+ */
+export type RaphEffectGroupRun<Context = unknown> = readonly [
+    context: Context,
+    slot: number,
+    ...state: readonly unknown[]
+];
+/**
+ * Тело одного slot группы, зарегистрированной через `effectGroup`. Получает
+ * один аргумент — запуск с context группы и номером slot; task ему не
+ * передаётся. Чтения внутри вызова отслеживаются отдельно для каждого slot, а
+ * возвращённый cleanup принадлежит этому slot: он выполняется перед его
+ * следующим запуском и при освобождении группы.
+ *
+ * Аргумент один, как у тела `effect()`: общее для всех effects тело записи
+ * engine вызывает тело slot напрямую, без промежуточной функции на каждый
+ * запуск slot.
+ *
+ * @typeParam Context — значение, которое группа передаёт телу каждого slot.
+ */
+export type RaphEffectGroupSlot<Context = unknown> = (run: RaphEffectGroupRun<Context>) => void | Disposer;
+/** Настройки группы effects: порядок её task среди bindings той же phase. */
+export interface RaphEffectGroupOptions {
+    readonly priority?: number;
+}
+/**
+ * Группа effects одного binding, которую вернул `effectGroup`. Slots группы
+ * ничего не исполняют, пока их не запустит `start`; метод вызывается через
+ * группу или с явным receiver.
+ *
+ * Возвращаемое значение — сама запись binding, а не отдельный объект: handle
+ * не стоит группе аллокации. Contract — только `start`; остальные поля и
+ * методы записи внутренние, и обращение к ним нарушает contract.
+ */
+export interface RaphEffectGroup {
+    /**
+     * Запускает slot: с этого вызова slot ведёт себя как binding, который
+     * `bindEffect()` зарегистрировал бы в этом месте. `initial` задаёт первую
+     * доставку так же, как у `effect()`: `'scheduled'` (по умолчанию) ставит её
+     * в очередь, `'sync'` исполняет её до возврата из вызова, если Runtime не
+     * занят доставкой и группа не на pause.
+     *
+     * Если первая доставка выполняется внутри вызова и flush бросает ошибку,
+     * slot останавливается окончательно, а ошибка бросается вызывающему, как
+     * при сбое регистрации отдельного binding. Остальные slots группы остаются.
+     * Запуск остановленного slot и повторный запуск уже запущенного slot не
+     * исполняют его тело.
+     *
+     * Запуск на освобождённом владельце бросает `RaphDisposedError`, как
+     * `bindEffect()`: и когда владелец освобождён до вызова, и когда его
+     * освободила первая доставка внутри этого вызова, при любом scheduler.
+     * Запуск slot группы, которую освободили при живом владельце — через её
+     * effect scope либо остановкой последнего slot, — ничего не делает.
+     */
+    start: (this: RaphEffectGroup, slot: number, initial?: RaphEffectInitialMode) => void;
+}
+/**
+ * Persistent task identity, передаваемая phase process и effect callback.
+ * run/defer/cancel вызываются через task или с явным receiver: извлечённый
+ * метод не работает без this.
+ */
 export interface RaphPhaseTask {
     readonly phase: string;
     readonly consumerOwner: RaphScope;
@@ -54,9 +133,9 @@ export interface RaphPhaseTask {
     readonly frame: RaphFrameContext;
     readonly priority: number;
     readonly sequence: number;
-    run: () => void;
-    defer: () => void;
-    cancel: () => void;
+    run: (this: RaphPhaseTask) => void;
+    defer: (this: RaphPhaseTask) => void;
+    cancel: (this: RaphPhaseTask) => void;
 }
 export interface RaphPhaseBatch {
     readonly phase: string;