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

package/dist/runtime/RaphRuntime.d.ts

@@ -6,9 +6,11 @@ import { Disposer, ReadonlySignal, Signal, WritableComputedOptions } from '../re
 import { RaphDebugOptions, RaphMachineDebugRegistration, RaphRuntimeDebug, RaphTraceEventInput, RaphTraceKind } from './diagnostics/RaphDebug';
 import { DepGraph } from './ownership/parent-graph.types';
 import { NodeOptions, RaphNode } from './ownership/RaphNode';
-import { FrameLoopLease, RaphAggregateSource, RaphEffectOptions, RaphPhase, RaphPhaseEffect, RaphSchedulerMode, RaphStructureCause, RaphWatchOptions, RaphWatchSource } from './phases/phase.types';
+import { FrameLoopLease, RaphAggregateSource, RaphEffectGroupOptions, RaphEffectGroupSlot, RaphEffectInitialMode, RaphEffectOptions, RaphPhase, RaphPhaseEffect, RaphSchedulerMode, RaphStructureCause, RaphWatchOptions, RaphWatchSource } from './phases/phase.types';
+import { RaphPhaseTaskRecord } from './phases/RaphPhaseTaskRecord';
 import { RaphMetaSourceOptions, RaphMetaSource } from './reactivity/RaphMetaSource';
 import { RaphAggregate, RaphWorkGraph } from './reactivity/RaphWorkGraph';
+import { RuntimeDisposalSweeper } from './reactivity/runtime-reactivity.types';
 import { RaphScope } from './ownership/RaphScope';
 import { PathHandle } from './reactivity/PathHandle';
 import { RuntimeReactivity } from './reactivity/RuntimeReactivity';
@@ -29,11 +31,18 @@ export interface RaphRuntimeConfiguration {
     readonly scheduler: RaphSchedulerMode;
 }
 export type RaphRuntimeMeta = Pick<RaphMeta, 'delete' | 'get' | 'has' | 'merge' | 'set'>;
-/** @internal */
+/**
+ * Один phase binding в том виде, в котором его видит effect scope. Регистрацией
+ * является сама постоянная запись binding, поэтому её capabilities вызываются
+ * только с регистрацией в качестве receiver.
+ *
+ * @internal
+ */
 export interface RaphPausableRegistration {
-    readonly dispose: Disposer;
-    readonly pause: () => void;
-    readonly resume: () => void;
+    readonly active: boolean;
+    readonly dispose: (this: RaphPausableRegistration) => void;
+    readonly pause: (this: RaphPausableRegistration) => void;
+    readonly resume: (this: RaphPausableRegistration) => void;
 }
 /** Isolated Runtime execution plane with phase-bound work only. */
 export declare class RaphRuntime {
@@ -46,8 +55,7 @@ export declare class RaphRuntime {
     private readonly _reactivity;
     private readonly _signalLifecycle;
     private readonly _workGraph;
-    private readonly _frameTickWritable;
-    private readonly _setFrameTick;
+    private readonly _frameTickSignal;
     private _pathHandles;
     private _meta;
     private _phases;
@@ -55,11 +63,17 @@ export declare class RaphRuntime {
     private _debug;
     private readonly _debugController;
     private _parentGraph;
-    private readonly _owners;
+    private readonly _topOwners;
+    private _ownerRegistrations;
+    private _ownersReleased;
     private _batchDepth;
     private _mutationDepth;
     private _kernelBatchDepth;
     private _ownerDisposalDepth;
+    private readonly _disposingNodes;
+    private _ownerDisposals;
+    private _disposalSweepers;
+    private _nextDisposalSweep;
     private _actionDepth;
     private _actionCounter;
     private readonly _traceCauseStack;
@@ -98,12 +112,63 @@ export declare class RaphRuntime {
     computed<T>(options: WritableComputedOptions<T>, owner?: RaphScope): Signal<T>;
     /** Low-level adapter form. Prefer consumer.effect(). */
     effect(consumer: RaphScope, phaseInput: string, callback: RaphPhaseEffect, options?: RaphEffectOptions): Disposer;
-    /** @internal */
-    _effectRegistration(consumer: RaphScope, phaseInput: string, callback: RaphPhaseEffect, options?: RaphEffectOptions, startPaused?: boolean): RaphPausableRegistration;
+    /**
+     * Регистрирует один implicit phase effect. Возвращаемая регистрация является
+     * записью binding: она одновременно ресурс владельца, задача engine и элемент
+     * очереди pipeline, поэтому на effect больше ничего не выделяется. Тело
+     * записи engine у всех bindings графа одно — `RuntimeReactivity._phaseBody`:
+     * свой binding оно находит через engine, а не через собственную closure.
+     *
+     * При `taskless` тело вызывается без task: запись получает `TASK_TASKLESS`,
+     * общее тело не читает `record.task`, и frozen facade этого binding не
+     * создаётся, пока его не запросит `process` своей phase. Режим — бит поля
+     * `state`: запись от него не растёт.
+     *
+     * @internal
+     */
+    _effectRegistration(consumer: RaphScope, phaseInput: string, callback: RaphPhaseEffect, options?: RaphEffectOptions, startPaused?: boolean, taskless?: boolean, onExecutionFailure?: (error: unknown) => never, isExecutionCancelled?: () => boolean): RaphPausableRegistration;
+    /**
+     * Регистрирует группу из `count` implicit phase effects на одной записи
+     * binding. Каждый slot получает собственную запись графа engine, то есть
+     * собственный набор зависимостей и собственный признак invalidation, а
+     * запись binding и её место в очереди phase и в списке ресурсов владельца у
+     * группы одни. Тело записи engine у slots то же, что у всех bindings графа.
+     * Возвращаемая регистрация — эта запись; она же handle группы.
+     *
+     * Регистрация ничего не исполняет: каждый slot запускает `_startGroupSlot`.
+     * Запись входит в список владельца сразу, поэтому владелец освобождает
+     * группу после ресурсов, которые зарегистрируют тела её slots.
+     *
+     * @internal
+     */
+    _effectGroupRegistration(consumer: RaphScope, phaseInput: string, count: number, runSlot: RaphEffectGroupSlot, context: unknown, options?: RaphEffectGroupOptions, startPaused?: boolean): RaphPhaseTaskRecord;
+    /**
+     * Запускает один slot группы: планирует его запись графа, ставит запись
+     * группы в очередь и, при `initial: 'sync'`, выполняет flush. Шаги те же, что
+     * у регистрации одиночного implicit effect после создания его записи.
+     *
+     * Сбой внутри вызова останавливает только этот slot и бросается вызывающему,
+     * как сбой первой доставки откатывает регистрацию одиночного binding; группа
+     * и остальные её slots остаются. Группа, у которой остановлен последний slot,
+     * освобождается.
+     *
+     * Запуск на освобождённом владельце бросает `RaphDisposedError`, как
+     * `bindEffect()`: и когда владелец освобождён до вызова, и когда его
+     * освободила первая доставка внутри вызова, при любом scheduler. Молчит
+     * только запуск slot группы, освобождённой при живом владельце.
+     *
+     * @internal
+     */
+    _startGroupSlot(record: RaphPhaseTaskRecord, slot: number, initial: RaphEffectInitialMode, onExecutionFailure?: (error: unknown) => never): void;
     /** Low-level adapter form. Prefer consumer.watch(). */
     watch(consumer: RaphScope, source: RaphWatchSource, phaseInput: string, callback: RaphPhaseEffect, options?: RaphWatchOptions): Disposer;
-    /** @internal */
-    _watchRegistration(consumer: RaphScope, source: RaphWatchSource, phaseInput: string, callback: RaphPhaseEffect, options?: RaphWatchOptions, startPaused?: boolean): RaphPausableRegistration;
+    /**
+     * Регистрирует один explicit phase watch. Возвращаемая запись binding является
+     * pausable-регистрацией и одновременно ресурсом владельца этого watch.
+     *
+     * @internal
+     */
+    _watchRegistration(consumer: RaphScope, source: RaphWatchSource, phaseInput: string, callback: RaphPhaseEffect, options?: RaphWatchOptions, startPaused?: boolean, onExecutionFailure?: (error: unknown) => never, isExecutionCancelled?: () => boolean): RaphPhaseTaskRecord;
     aggregate(consumer: RaphScope, sources: readonly RaphAggregateSource[]): RaphAggregate;
     /** Creates a lazy root-owned metadata event source for phase watches. */
     metaSource(masks: DataPathDef | readonly DataPathDef[], options?: RaphMetaSourceOptions): RaphMetaSource;
@@ -120,11 +185,31 @@ export declare class RaphRuntime {
     /** Batches an internal reactive-only commit without opening an unused Kernel boundary. @internal */
     _batchReactive<T>(operation: () => T): T;
     private _batch;
+    /**
+     * Закрывает один уровень batch: внешний уровень очищает transient causes и
+     * запускает фазы. Бросает ошибку операции, ошибки закрытия либо все вместе;
+     * после успешной операции и закрытия возвращает управление.
+     */
+    private _closeBatch;
+    /**
+     * Исполняет тело action: `batch(() => _runUntracked(() => operation(...args)))`
+     * без closures и без промежуточных вызовов слоёв. Runtime, который один
+     * владеет своим Kernel без derived handles, metadata watchers и adapter,
+     * открывает границы reactive batch, Kernel и path batch явными вызовами и
+     * закрывает их в том же порядке и с теми же ошибками, что вложенные
+     * `batch()` этих слоёв. В любом другом состоянии исполняется сам `batch()`.
+     */
+    private _applyBatch;
     action<Args extends unknown[], Result>(operation: (...args: Args) => Result, owner?: RaphScope): (...args: Args) => Result;
     action<Args extends unknown[], Result>(name: string, operation: (...args: Args) => Result, owner?: RaphScope): (...args: Args) => Result;
     untracked<T>(operation: () => T): T;
     scope(id: string): RaphScope;
     node<TApi = void>(options: NodeOptions, setup?: (node: RaphNode) => TApi): RaphNode<TApi>;
+    /**
+     * Создаёт provisional node, выполняет setup и публикует результат; при ошибке
+     * setup откатывает node до выхода из границы mutation.
+     */
+    private _createCommittedNode;
     getNode(id: string): RaphNode | undefined;
     definePhases(phases: readonly RaphPhase[]): void;
     addPhase(phase: RaphPhase): void;
@@ -141,6 +226,21 @@ export declare class RaphRuntime {
     _onDisposed(listener: () => void): Disposer;
     /** @internal */
     _notifyNodeStructure(node: RaphNode, structure: RaphStructureCause, oldAncestors: readonly RaphNode[], newAncestors: readonly RaphNode[]): void;
+    /**
+     * Сообщает, может ли structural publication этой node дойти до подписчика;
+     * `false` позволяет не строить structure cause и списки ancestors.
+     *
+     * @internal
+     */
+    _hasNodeStructureDemand(node: RaphNode): boolean;
+    /**
+     * Сообщает, есть ли у Runtime хотя бы один подписчик на node: runtime-,
+     * subtree- или self-watcher. Пока он есть, node поддерживает выданный массив
+     * детей на месте, потому что structure cause берёт из него индексы.
+     *
+     * @internal
+     */
+    _hasNodeSubscribers(): boolean;
     /** @internal */
     _notifyNodeTouch(node: RaphNode, metadata?: unknown): void;
     /** @internal */
@@ -149,18 +249,84 @@ export declare class RaphRuntime {
     _releaseNode(node: RaphNode): void;
     /** @internal */
     _runNodeMutation<T>(operation: () => T): T;
+    /**
+     * Выполняет границу пустой node mutation без аллокаций: эквивалент
+     * `_runWrite(noop)` с тем же запросом исполнения и flush на внешней границе.
+     *
+     * @internal
+     */
+    _touchMutationBoundary(): void;
     /** @internal */
     _runPhaseTransition<T>(operation: () => T): T;
-    /** @internal */
-    _beginOwnerDisposal(): void;
+    /**
+     * Открывает границу освобождения. `node` передаёт только dispose самой node:
+     * Runtime помнит её до парного `_endOwnerDisposal`.
+     *
+     * @internal
+     */
+    _beginOwnerDisposal(node?: RaphNode): void;
     /** @internal */
     _endOwnerDisposal(): void;
+    /**
+     * Возвращает число владельцев, освобождённых этим Runtime за всё время.
+     *
+     * @internal
+     */
+    _ownerDisposalCount(): number;
+    /**
+     * Подключает участника уборки: Runtime вызовет его на первой внешней границе
+     * освобождения, к которой число освобождённых владельцев достигнет `due`.
+     * Подключённый участник остаётся в очереди, пока сам не откажется от
+     * следующего срока либо не будет отключён.
+     *
+     * @internal
+     */
+    _addDisposalSweeper(sweeper: RuntimeDisposalSweeper, due: number): void;
+    /**
+     * Отключает участника уборки; отключение неизвестного участника безопасно.
+     *
+     * @internal
+     */
+    _removeDisposalSweeper(sweeper: RuntimeDisposalSweeper): void;
+    /**
+     * Вызывает участников уборки, чей срок подошёл, и назначает ближайший
+     * следующий срок. Участник, чей срок не подошёл, вызова не получает:
+     * освобождение владельца стоит участникам работы, только когда подходит их
+     * собственный срок.
+     */
+    private _sweepAfterDisposals;
     /** @internal */
     _ownerDisposalActive(): boolean;
-    /** @internal */
-    _registerOwner(owner: RaphScope): void;
-    /** @internal */
+    /**
+     * Учитывает нового владельца и возвращает его порядковый номер регистрации.
+     * Plain scope сразу входит в набор владельцев вне списков детей; node входит
+     * в него сама через `_addTopOwner`, и только если у неё нет parent.
+     *
+     * @internal
+     */
+    _registerOwner(owner: RaphScope): number;
+    /**
+     * Снимает владельца с учёта. Plain scope выходит и из набора владельцев вне
+     * списков детей; node без parent выходит из него сама через
+     * `_removeTopOwner`, а node с parent в нём не состоит.
+     *
+     * @internal
+     */
     _unregisterOwner(owner: RaphScope): void;
+    /**
+     * Вносит node без parent в набор владельцев вне списков детей.
+     *
+     * @internal
+     */
+    _addTopOwner(node: RaphNode): void;
+    /**
+     * Убирает node из набора владельцев вне списков детей: она освобождена либо
+     * получила parent. Повторный вызов и вызов после освобождения Runtime
+     * безопасны.
+     *
+     * @internal
+     */
+    _removeTopOwner(node: RaphNode): void;
     /** @internal */
     _assertOwnerRuntime(owner: RaphScope): void;
     /** @internal */
@@ -195,19 +361,72 @@ export declare class RaphRuntime {
     _recordTrace(event: RaphTraceEventInput): void;
     /** Наследует cause через outputs/tasks optional execution layers. @internal */
     _runWithTraceCause<T>(causeId: number | undefined, operation: () => T): T;
+    /**
+     * Выполняет единственную проверку binding: pipeline доверяет её результату.
+     */
     private _validatePhaseBinding;
+    /**
+     * Освобождает binding, регистрация которого не удалась, и повторно бросает
+     * причину сбоя; ошибка самого освобождения присоединяется к ней.
+     */
+    private _rollbackRegistration;
     private _createDebugSnapshot;
     private _createDebugTree;
     private _createDebugStats;
+    /**
+     * Возвращает число владельцев, которых Runtime числит живыми: зарегистрированных
+     * и ещё не снятых с учёта. После освобождения Runtime их нет.
+     */
+    private _liveOwnerCount;
+    /**
+     * Собирает всех владельцев, которых Runtime числит живыми. Владельцы вне
+     * списков детей идут в порядке регистрации, каждый — вместе с потомками по
+     * спискам детей. Node, чей dispose ещё исполняется, из списка parent уже
+     * вышла либо потеряла parent, который сбросил свой список: её и оставшихся
+     * у неё детей добавляют места границ освобождения.
+     */
+    private _collectOwners;
     private _releasePathHandle;
     private get _execution();
     private get _clock();
     private _tickFrameLoop;
+    /**
+     * Записывает frame signal в собственной границе записи, минуя политику
+     * actions: кадр продвигает сам Runtime.
+     */
+    private _setFrameTick;
     private _attachWritableComputed;
     private _own;
     private _runTracked;
     private _runUntracked;
     private _runWrite;
+    /**
+     * Открывает границу записи без closure; повторяет начало `_runWrite`.
+     *
+     * @internal
+     */
+    _enterWrite(): void;
+    /**
+     * Закрывает успешную запись, открытую `_enterWrite`; внешняя граница очищает
+     * transient causes и запускает фазы с теми же ошибками, что и `_runWrite`.
+     *
+     * @internal
+     */
+    _exitWrite(): void;
+    /**
+     * Закрывает запись после ошибки операции и возвращает ошибку для throw:
+     * исходную либо AggregateError, если упало и закрытие внешней границы.
+     *
+     * @internal
+     */
+    _failWrite(operationError: unknown): unknown;
+    /**
+     * Сообщает, что внешняя write-, batch-, Kernel- или disposal-граница ещё открыта.
+     * В этом состоянии оба шага `_finishExecutionBoundary` заведомо ничего не делают:
+     * transient causes очищаются и фазы запускаются только при нулевых глубинах.
+     */
+    private _executionBoundaryOpen;
+    /** Закрывает внешнюю границу; массив ошибок создаётся только при первой ошибке. */
     private _finishExecutionBoundary;
     private _clearTransientCausesIfSettled;
     private _requestExecution;

package/dist/runtime/ownership/RaphEffectScope.d.ts

@@ -1,10 +1,12 @@
 import { Disposer } from '../../reactivity/types';
-import { RaphEffectOptions, RaphOwnerWatchSource, RaphPhaseEffect, RaphWatchOptions } from '../phases/phase.types';
+import { RaphEffectGroup, RaphEffectGroupOptions, RaphEffectGroupSlot, RaphEffectOptions, RaphOwnerWatchSource, RaphPhaseBody, RaphPhaseEffect, RaphWatchOptions, RaphWatchSource } from '../phases/phase.types';
+import { RaphRuntime } from '../RaphRuntime';
 import { RaphScope } from './RaphScope';
 /** Pauses phase deliveries without detaching dependencies or losing accumulated causes. */
 export declare class RaphEffectScope {
     private readonly _owner;
     private _registrations;
+    private _pruneAt;
     private _children;
     private _selfPaused;
     private _ancestorPauses;
@@ -16,13 +18,80 @@ export declare class RaphEffectScope {
     get disposed(): boolean;
     fork(owner: RaphScope): RaphEffectScope;
     effect(phase: string, callback: RaphPhaseEffect, options?: RaphEffectOptions): Disposer;
+    /**
+     * Регистрирует в этой группе phase effect без task и без disposer: тело
+     * вызывается без аргументов, а binding живёт до освобождения группы или её
+     * владельца. Pause и resume группы действуют на него так же, как на effect,
+     * зарегистрированный через `effect()`.
+     *
+     * Binding, зарегистрированный внутри тела другого effect, останавливает ещё и
+     * перезапуск этого effect. Остановленный binding больше не исполняется и не
+     * реагирует на pause и resume; группа забывает его не сразу, а когда число её
+     * регистраций удваивается, поэтому остановленных регистраций в группе не
+     * больше, чем действующих, либо меньше `PRUNE_FLOOR`.
+     */
+    bindEffect(phase: string, body: RaphPhaseBody, options?: RaphEffectOptions): void;
+    /**
+     * Регистрирует в этой группе регистраций группу из `count` phase effects на
+     * одном binding, как `owner.effectGroup()`: без task и без disposer, с
+     * отдельным набором зависимостей у каждого slot и с запуском slots через
+     * `start()` возвращённой группы. Pause и resume действуют на все slots
+     * сразу; slots, запущенные или изменившиеся за время pause, исполняются
+     * одной доставкой после resume. Binding живёт до освобождения этой группы
+     * регистраций или её владельца.
+     *
+     * Pause изнутри тела slot останавливает доставку: оставшиеся slots
+     * исполняются после resume, и причины прерванной доставки приходят в
+     * `causes` следующей целиком, вместе с причинами уже исполненных slots.
+     *
+     * Освобождение отличается от отдельных bindings этой же группы регистраций:
+     * slots останавливаются в порядке, обратном порядку номеров, а не в порядке
+     * регистрации, и несколько сбоев их cleanup приходят одним вложенным
+     * `AggregateError` с сообщением `[Raph] Effect group disposal failed.`.
+     *
+     * @typeParam Context — значение, которое получает тело каждого slot.
+     * @param phase Имя объявленной phase.
+     * @param count Число slots: целое от 1 до 4294967293, иначе `RangeError`.
+     * @param runSlot Тело slot: получает запуск с `context` и номером slot.
+     * @param context Значение, которое группа передаёт телу каждого slot.
+     * @param options `priority` task группы, как у `effect()`.
+     */
+    effectGroup<Context>(phase: string, count: number, runSlot: RaphEffectGroupSlot<Context>, context: Context, options?: RaphEffectGroupOptions): RaphEffectGroup;
     watch(source: RaphOwnerWatchSource, phase: string, callback: RaphPhaseEffect, options?: RaphWatchOptions): Disposer;
+    /**
+     * Внутренний путь renderer сохраняет pause ancestry и late-disposal tracking.
+     * Возвращаемый disposer renderer не использует; регистрация остаётся у scope.
+     * @internal
+     */
+    _registerEffect(phase: string, callback: RaphPhaseEffect, options: RaphEffectOptions, taskless: boolean, onExecutionFailure: (error: unknown) => never, isExecutionCancelled?: () => boolean): void;
+    /** @internal */
+    _registerWatch(source: RaphWatchSource, phase: string, callback: RaphPhaseEffect, options: RaphWatchOptions, onExecutionFailure: (error: unknown) => never, isExecutionCancelled?: () => boolean): void;
+    /** @internal */
+    _registerEffectGroup<Context>(phase: string, count: number, runSlot: RaphEffectGroupSlot<Context>, context: Context, options?: RaphEffectGroupOptions): ReturnType<RaphRuntime['_effectGroupRegistration']>;
     pause(): void;
     resume(): void;
     private _pause;
     private _resume;
     dispose(): void;
     private _add;
+    /**
+     * Вносит регистрацию в группу и возвращает её элемент либо `undefined`,
+     * когда группа уже освобождена. Disposer здесь не создаётся: его строит
+     * только `_add()`, поэтому `bindEffect()` обходится без closure.
+     */
+    private _track;
+    /**
+     * Забывает регистрации, которые уже остановлены не через disposer группы:
+     * binding, вложенный в тело другого effect, останавливает engine при
+     * перезапуске этого effect, а у `bindEffect()` нет disposer, который убрал бы
+     * его отсюда. Без этого группа держала бы тело каждого такого binding до
+     * собственного освобождения.
+     *
+     * Проход выполняется, когда число регистраций достигает порога, и ставит
+     * следующий порог вдвое выше числа оставшихся: цена регистрации остаётся
+     * постоянной в среднем.
+     */
+    private _prune;
     private _assertAlive;
     private _addChild;
     private _changeAncestorPause;