@raphy-js/raph 1.0.0-dev.18

package/dist/reactivity/types.d.ts

@@ -0,0 +1,175 @@
+export type Disposer = () => void;
+export interface ReadonlySignal<T> {
+    get: (this: ReadonlySignal<unknown>) => T;
+    peek: (this: ReadonlySignal<unknown>) => T;
+}
+export interface Signal<T> extends ReadonlySignal<T> {
+    set: (value: T) => void;
+}
+export interface WritableComputedOptions<T> {
+    readonly get: () => T;
+    readonly set: (value: T) => void;
+}
+export type EffectCallback = () => void | Disposer;
+export interface EffectTask {
+    dependencyOwner?: object;
+    allowScheduleDuringRun?: boolean;
+    notify?: (source: unknown) => void;
+    cancelPending?: () => boolean;
+    rearmPending?: () => void;
+    schedule: () => void;
+    dispose: Disposer;
+}
+export interface EffectScheduler {
+    bind: (run: () => void) => EffectTask;
+}
+export interface ReactivityOptions {
+    readonly adaptiveDependencyIndex?: boolean;
+    readonly effectScheduler?: EffectScheduler;
+}
+export type WatchSource<T = unknown> = ReadonlySignal<T> | (() => T);
+export interface WatchOptions {
+    readonly immediate?: boolean;
+}
+export type WatchValue<S> = S extends readonly unknown[] ? {
+    [K in keyof S]: S[K] extends WatchSource<infer V> ? V : never;
+} : S extends WatchSource<infer V> ? V : never;
+export type WatchCallback<S> = (value: WatchValue<S>, previous: WatchValue<S> | undefined) => void | Disposer;
+export type EffectFactory = (callback: EffectCallback, onStop?: Disposer) => Disposer;
+export type TrackedOperation = <T>(operation: () => T) => T;
+/**
+ * Финализатор источника: true означает завершение, false — необходимость повторной
+ * попытки после освобождения зависимостей. Не является дублем Disposer.
+ * @internal
+ */
+export type SourceFinalizer = () => boolean;
+/**
+ * Запись произвольного ресурса в списке владельца.
+ * Функция dispose отсоединяет запись перед вызовом пользовательской очистки.
+ * @internal
+ */
+export interface OwnedResource extends ScopeLink<OwnedResource> {
+    dispose: Disposer;
+}
+/**
+ * Границы списка принадлежащих ресурсов. Не описывают граф зависимостей
+ * или дерево исполнения RaphNode.
+ * @internal
+ */
+export interface ScopeChildren<T> {
+    scopeFirstChild?: T;
+    scopeLastChild?: T;
+}
+/**
+ * Встроенные связи ресурса с владельцем и соседями списка.
+ * Не требуют отдельного ScopeNode для каждого эффекта.
+ * @internal
+ */
+export interface ScopeLink<T> {
+    scopeParent?: ScopeChildren<T>;
+    scopePrevious?: T;
+    scopeNext?: T;
+}
+/**
+ * Одна зависимость производителя и потребителя, одновременно включённая
+ * в список потребителей производителя и список зависимостей потребителя.
+ * @internal
+ */
+export interface ReactiveEdge {
+    dep: ReactiveNode;
+    sub: ReactiveNode;
+    prevSub: ReactiveEdge | null;
+    nextSub: ReactiveEdge | null;
+    prevDep: ReactiveEdge | null;
+    nextDep: ReactiveEdge | null;
+    dependencyCleanup?: Disposer;
+}
+/**
+ * Материализованная запись графа: signal, computed либо effect.
+ * Не наследует ScopeNode/RaphNode; поля scope используются только для вложенных эффектов.
+ * Гетерогенные значения графа намеренно имеют внутренний параметр any.
+ * @internal
+ */
+export interface ReactiveNode<T = any> extends ScopeChildren<ReactiveNode>, ScopeLink<ReactiveNode> {
+    flags: number;
+    firstSub: ReactiveEdge | null;
+    lastSub: ReactiveEdge | null;
+    firstDep: ReactiveEdge | null;
+    tailDep: ReactiveEdge | null;
+    depCount: number;
+    subSearchCursor?: ReactiveEdge;
+    dependencyIndex?: Map<ReactiveNode, ReactiveEdge>;
+    dependencyLookupDebt?: number;
+    dependencyLookupSearches?: number;
+    evaluate: (() => any) | undefined;
+    cachedValue: T;
+    pendingValue?: T;
+    pendingAuthor?: ReactiveNode | null;
+    effectTask?: EffectTask;
+    onStop?: Disposer;
+    sourceHooks?: OwnedSourceHooks;
+}
+/**
+ * Низкоуровневые read/write для raw-дорожки Bench Lab.
+ * Публичный объектный API намеренно не использует этот контракт.
+ * @internal
+ */
+export interface SignalAccess<T> {
+    read: () => T;
+    write: (value: T) => void;
+}
+/**
+ * Низкоуровневый computed с требованием сохранить receiver первого чтения.
+ * @internal
+ */
+export interface ComputedAccess<T> {
+    read: (this: ComputedAccess<unknown>) => T;
+}
+/**
+ * Ленивый raw handle: до первого чтения поля ReactiveNode отсутствуют.
+ * Partial описывает стадию материализации, а не ослабляет контракт готового узла.
+ * @internal
+ */
+export interface ComputedAccessHandle<T> extends Partial<ReactiveNode<T>>, ComputedAccess<T> {
+    evaluate: (() => T) | undefined;
+}
+/**
+ * Ленивый объектный computed: графовые поля становятся обязательными
+ * только после initializeComputedHandle(). Отдельной записи графа не выделяет.
+ * @internal
+ */
+export interface ComputedSourceAccessHandle<T> extends Partial<ReactiveNode<T>>, ReadonlySignal<T> {
+    evaluate: (() => T) | undefined;
+}
+/**
+ * Handle источника вместе с независимым финализатором для владельца.
+ * @internal
+ */
+export interface OwnedSource<T> {
+    source: T;
+    hasSubscribers?: () => boolean;
+    dispose: SourceFinalizer;
+}
+/**
+ * Необязательные Runtime hooks owned-источника. Standalone sources не передают
+ * этот объект и сохраняют прежний hot path без ownership metadata.
+ * @internal
+ */
+export interface OwnedSourceHooks {
+    readonly token?: unknown;
+    readonly dependencyOwner?: object;
+    readonly onDependency?: (consumerOwner: object) => Disposer | undefined;
+    readonly onChange?: (previous: unknown, value: unknown, hasReactiveSubscribers: boolean) => void;
+    readonly onInvalidate?: (hasReactiveSubscribers: boolean) => void;
+    readonly onDispose?: (hasReactiveSubscribers: boolean) => void;
+}
+/**
+ * Общие для одного графа адаптеры receiver его handles.
+ * Не хранят состояние алгоритмов: передают исходный handle методам движка.
+ * @internal
+ */
+export interface HandleReaders {
+    initializeComputed: <T>(this: ReadonlySignal<unknown>) => T;
+    initializeRaw: <T>(this: ComputedAccess<unknown>) => T;
+    peek: <T>(this: ReadonlySignal<unknown>) => T;
+}

package/dist/reactivity/watch.d.ts

@@ -0,0 +1,15 @@
+import { Disposer, EffectFactory, TrackedOperation, WatchCallback, WatchOptions, WatchSource } from './types';
+/**
+ * Создаёт watch поверх переданной фабрики эффектов и политики чтения.
+ * Фабрика обязана поддерживать второй аргумент onStop: он связывает окончательную
+ * очистку watch с остановкой эффекта родителем, scope или внешним disposer.
+ * Повторный запуск с равным результатом не вызывает cleanup callback.
+ * @param effect Фабрика с независимым финализатором окончательной остановки.
+ * @param untracked Выполняет callback и cleanup без сбора зависимостей.
+ * @param source Один источник либо список источников.
+ * @param callback Обрабатывает новое и предыдущее значения.
+ * @param options Настройки первоначального вызова.
+ * @param runTracked Оборачивает только чтение selector; используется Runtime.
+ * @internal
+ */
+export declare function watchWithReactivity<S extends WatchSource | readonly WatchSource[]>(effect: EffectFactory, untracked: TrackedOperation, source: S, callback: WatchCallback<S>, options?: WatchOptions, runTracked?: TrackedOperation): Disposer;

package/dist/reactivity.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./debug/reactivity/engine.cjs"),t=require("./debug/reactivity/scope.cjs");exports.RaphReactivity=e.RaphReactivity;exports.batch=e.batch;exports.computed=e.computed;exports.effect=e.effect;exports.reactive=e.reactive;exports.scope=e.scope;exports.signal=e.signal;exports.untracked=e.untracked;exports.watch=e.watch;exports.ScopeNode=t.ScopeNode;

package/dist/reactivity.js

@@ -0,0 +1,14 @@
+import { RaphReactivity as c, batch as o, computed as a, effect as p, reactive as r, scope as f, signal as i, untracked as d, watch as h } from "./debug/reactivity/engine.js";
+import { ScopeNode as n } from "./debug/reactivity/scope.js";
+export {
+  c as RaphReactivity,
+  n as ScopeNode,
+  o as batch,
+  a as computed,
+  p as effect,
+  r as reactive,
+  f as scope,
+  i as signal,
+  d as untracked,
+  h as watch
+};

package/dist/runtime/RaphRuntime.d.ts

@@ -0,0 +1,225 @@
+import { DerivedOptions, RaphDerivedHandle } from '../path/derived/RaphDerivedHandle';
+import { RaphMeta } from '../path/meta/RaphMeta';
+import { DataPathDef, PathOptions } from '../path/path.types';
+import { RaphKernelRoot, RaphKernel } from '../path/RaphKernel';
+import { Disposer, ReadonlySignal, Signal, WritableComputedOptions } from '../reactivity/types';
+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 { RaphMetaSourceOptions, RaphMetaSource } from './reactivity/RaphMetaSource';
+import { RaphAggregate, RaphWorkGraph } from './reactivity/RaphWorkGraph';
+import { RaphScope } from './ownership/RaphScope';
+import { PathHandle } from './reactivity/PathHandle';
+import { RuntimeReactivity } from './reactivity/RuntimeReactivity';
+export interface RaphRuntimeOptions {
+    readonly adaptiveDependencyIndex?: boolean;
+    readonly debug?: RaphDebugOptions;
+    readonly id?: string;
+    readonly kernel?: RaphKernel;
+    readonly enforceActions?: boolean;
+    readonly scheduler?: RaphSchedulerMode;
+}
+export interface RaphRuntimeConfiguration {
+    readonly adaptiveDependencyIndex: boolean;
+    readonly debug?: RaphDebugOptions;
+    readonly id: string;
+    readonly kernel: RaphKernel;
+    readonly enforceActions: boolean;
+    readonly scheduler: RaphSchedulerMode;
+}
+export type RaphRuntimeMeta = Pick<RaphMeta, 'delete' | 'get' | 'has' | 'merge' | 'set'>;
+/** @internal */
+export interface RaphPausableRegistration {
+    readonly dispose: Disposer;
+    readonly pause: () => void;
+    readonly resume: () => void;
+}
+/** Isolated Runtime execution plane with phase-bound work only. */
+export declare class RaphRuntime {
+    private static _runtimeCounter;
+    readonly mode: "runtime";
+    readonly configuration: RaphRuntimeConfiguration;
+    readonly rootScope: RaphScope;
+    readonly root: RaphNode;
+    readonly frameTick: ReadonlySignal<number>;
+    private readonly _reactivity;
+    private readonly _signalLifecycle;
+    private readonly _workGraph;
+    private readonly _frameTickWritable;
+    private readonly _setFrameTick;
+    private _pathHandles;
+    private _meta;
+    private _phases;
+    private _frameLoop;
+    private _debug;
+    private readonly _debugController;
+    private _parentGraph;
+    private readonly _owners;
+    private _batchDepth;
+    private _mutationDepth;
+    private _kernelBatchDepth;
+    private _ownerDisposalDepth;
+    private _actionDepth;
+    private _actionCounter;
+    private readonly _traceCauseStack;
+    private _phaseTraceOperations;
+    private _executionRequested;
+    private _disposed;
+    private readonly _disposedListeners;
+    constructor(options?: RaphRuntimeOptions);
+    /** @internal */
+    _getReactivity(): RuntimeReactivity;
+    /**
+     * Возвращает внутренний WorkGraph для optional execution layers.
+     *
+     * @internal
+     */
+    _getWorkGraph(): RaphWorkGraph;
+    get id(): string;
+    get kernel(): RaphKernel;
+    get disposed(): boolean;
+    get graph(): DepGraph;
+    get loopEnabled(): boolean;
+    get frame(): import('./phases/phase.types').RaphFrameContext;
+    get phases(): readonly RaphPhase[];
+    /** Runtime metadata facade intentionally excludes unphased watch(). */
+    get meta(): RaphRuntimeMeta;
+    getDerivedSnapshot(): ReturnType<RaphKernel['getDerivedSnapshot']>;
+    get debug(): RaphRuntimeDebug;
+    signal<T>(value: T, owner?: RaphScope): Signal<T>;
+    /**
+     * Creates a deep reactive Proxy owned by this Runtime root scope.
+     * Property dependencies use the intrusive graph directly and intentionally
+     * do not create per-property WorkGraph producers or phase causes.
+     */
+    reactive<T extends object>(value: T): T;
+    computed<T>(getter: () => T, owner?: RaphScope): ReadonlySignal<T>;
+    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;
+    /** 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;
+    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;
+    path<T>(path: DataPathDef, options?: PathOptions): PathHandle<T>;
+    get<T = RaphKernelRoot>(): T | undefined;
+    get<T = unknown>(path: DataPathDef, options?: PathOptions): T | undefined;
+    peek<T = RaphKernelRoot>(): T | undefined;
+    peek<T = unknown>(path: DataPathDef, options?: PathOptions): T | undefined;
+    has(path: DataPathDef, options?: PathOptions): boolean;
+    set<T>(path: DataPathDef, value: T, options?: PathOptions): void;
+    merge(path: DataPathDef, value: unknown, options?: PathOptions): void;
+    delete(path: DataPathDef, options?: PathOptions): void;
+    batch<T>(operation: () => T): T;
+    /** Batches an internal reactive-only commit without opening an unused Kernel boundary. @internal */
+    _batchReactive<T>(operation: () => T): T;
+    private _batch;
+    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>;
+    getNode(id: string): RaphNode | undefined;
+    definePhases(phases: readonly RaphPhase[]): void;
+    addPhase(phase: RaphPhase): void;
+    clearPhases(): void;
+    requestExecution(): void;
+    flush(): void;
+    afterFlush(): Promise<void>;
+    acquireLoop(owner: string): FrameLoopLease;
+    startLoop(): void;
+    stopLoop(): void;
+    derive<TSource, TTarget>(options: DerivedOptions<TSource, TTarget>): RaphDerivedHandle<TSource, TTarget>;
+    dispose(): void;
+    /** @internal */
+    _onDisposed(listener: () => void): Disposer;
+    /** @internal */
+    _notifyNodeStructure(node: RaphNode, structure: RaphStructureCause, oldAncestors: readonly RaphNode[], newAncestors: readonly RaphNode[]): void;
+    /** @internal */
+    _notifyNodeTouch(node: RaphNode, metadata?: unknown): void;
+    /** @internal */
+    _assertNodeReparentAllowed(node: RaphNode, newParent: RaphNode): void;
+    /** @internal */
+    _releaseNode(node: RaphNode): void;
+    /** @internal */
+    _runNodeMutation<T>(operation: () => T): T;
+    /** @internal */
+    _runPhaseTransition<T>(operation: () => T): T;
+    /** @internal */
+    _beginOwnerDisposal(): void;
+    /** @internal */
+    _endOwnerDisposal(): void;
+    /** @internal */
+    _ownerDisposalActive(): boolean;
+    /** @internal */
+    _registerOwner(owner: RaphScope): void;
+    /** @internal */
+    _unregisterOwner(owner: RaphScope): void;
+    /** @internal */
+    _assertOwnerRuntime(owner: RaphScope): void;
+    /** @internal */
+    _beginKernelBatch(): void;
+    /** @internal */
+    _endKernelBatch(): void;
+    /** Регистрирует read-only diagnostics projection optional Machine. @internal */
+    _registerMachineDebug(registration: RaphMachineDebugRegistration): Disposer;
+    /**
+     * Проверяет optional diagnostic identity без создания public facade.
+     *
+     * @internal
+     */
+    _hasMachineDebug(id: string): boolean;
+    /**
+     * Проверяет optional trace path без выделения operation ID.
+     *
+     * @internal
+     */
+    _traces(kind: RaphTraceKind): boolean;
+    /** Возвращает наследуемый cause для optional execution layers. @internal */
+    _currentTraceCauseId(): number | undefined;
+    /** Выдаёт operation id только на активном trace path. @internal */
+    _nextTraceOperation(kind: RaphTraceKind): number | undefined;
+    /**
+     * Проверяет, должен ли untracked work изолировать reactive или Runtime owner context.
+     *
+     * @internal
+     */
+    _hasActiveReactiveContext(): boolean;
+    /** Записывает optional trace event без machine dependency. @internal */
+    _recordTrace(event: RaphTraceEventInput): void;
+    /** Наследует cause через outputs/tasks optional execution layers. @internal */
+    _runWithTraceCause<T>(causeId: number | undefined, operation: () => T): T;
+    private _validatePhaseBinding;
+    private _createDebugSnapshot;
+    private _createDebugTree;
+    private _createDebugStats;
+    private _releasePathHandle;
+    private get _execution();
+    private get _clock();
+    private _tickFrameLoop;
+    private _attachWritableComputed;
+    private _own;
+    private _runTracked;
+    private _runUntracked;
+    private _runWrite;
+    private _finishExecutionBoundary;
+    private _clearTransientCausesIfSettled;
+    private _requestExecution;
+    private _assertTrackedRead;
+    /**
+     * Проверяет tracked read из optional owned source.
+     *
+     * @internal
+     */
+    _assertSourceReadable(owner: RaphScope): void;
+    private _assertImplicitDependency;
+    private _assertWriteAllowed;
+    private _throwCrossRuntime;
+    private _assertAlive;
+}

package/dist/runtime/diagnostics/RaphDebug.d.ts

@@ -0,0 +1,239 @@
+import { Disposer } from '../../reactivity/types';
+import { RaphScope } from '../ownership/RaphScope';
+export type RaphTraceKind = 'action' | 'error' | 'machine' | 'phase';
+export type RaphTraceGuardMode = 'all' | 'failed' | 'none';
+export type RaphTraceContextMode = 'keys' | 'none';
+export interface RaphTraceOptions {
+    readonly capacity?: number;
+    readonly context?: RaphTraceContextMode;
+    readonly guards?: RaphTraceGuardMode;
+    readonly include?: readonly RaphTraceKind[];
+}
+export interface RaphDebugOptions {
+    readonly trace?: false | RaphTraceOptions;
+}
+export interface RaphTraceEventInput {
+    readonly causeId?: number;
+    readonly context?: Readonly<Record<string, unknown>>;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly guard?: 'failed' | 'passed';
+    readonly kind: RaphTraceKind;
+    readonly name: string;
+    readonly operationId?: number;
+    readonly status?: 'end' | 'error' | 'ignored' | 'start';
+}
+export interface RaphTraceEvent {
+    readonly causeId?: number;
+    readonly contextKeys?: readonly string[];
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly guard?: 'failed' | 'passed';
+    readonly kind: RaphTraceKind;
+    readonly name: string;
+    readonly operationId?: number;
+    readonly sequence: number;
+    readonly status?: 'end' | 'error' | 'ignored' | 'start';
+    readonly timestamp: number;
+}
+export interface RaphTraceReadOptions {
+    readonly limit?: number;
+    readonly since?: number;
+}
+export interface RaphTraceStatus {
+    readonly capacity: number;
+    readonly context: RaphTraceContextMode;
+    readonly enabled: boolean;
+    readonly guards: RaphTraceGuardMode;
+    readonly include: readonly RaphTraceKind[];
+    readonly size: number;
+}
+export interface RaphDebugTraceApi {
+    clear: () => void;
+    read: (options?: RaphTraceReadOptions) => readonly RaphTraceEvent[];
+    start: (options?: RaphTraceOptions) => void;
+    status: () => RaphTraceStatus;
+    stop: () => void;
+}
+export interface RaphMachineDebugSnapshot {
+    readonly active: readonly string[];
+    readonly contextKeys: readonly string[];
+    readonly id: string;
+    readonly modelId: string;
+    readonly meta: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    readonly ownerId: string;
+    readonly parentId?: string;
+    readonly revision: number;
+    readonly status: string;
+    readonly actors: readonly string[];
+}
+export interface RaphMachineDebugSummary {
+    readonly active: readonly string[];
+    readonly id: string;
+    readonly modelId: string;
+    readonly ownerId: string;
+    readonly parentId?: string;
+    readonly revision: number;
+    readonly status: string;
+}
+/** @internal */
+export interface RaphMachineDebugRegistration {
+    readonly id: string;
+    readonly ownerId: string;
+    readonly parentId?: string;
+    readonly snapshot: () => RaphMachineDebugSnapshot;
+}
+export interface RaphDebugMachinesApi {
+    list: () => readonly RaphMachineDebugSummary[];
+    snapshot: (id: string) => RaphMachineDebugSnapshot | undefined;
+}
+export interface RaphDebugOwnerSnapshot {
+    readonly children: readonly RaphDebugOwnerSnapshot[];
+    readonly disposed: boolean;
+    readonly id: string;
+    readonly kind: 'node' | 'scope';
+    readonly resources: number;
+    readonly sources: number;
+}
+export interface RaphDebugFrameLoopSnapshot {
+    readonly leases: number;
+    readonly manual: boolean;
+    readonly running: boolean;
+}
+export interface RaphDebugSnapshot {
+    readonly actionDepth: number;
+    readonly batchDepth: number;
+    readonly disposed: boolean;
+    readonly frameLoop: RaphDebugFrameLoopSnapshot;
+    readonly id: string;
+    readonly kernelBatchDepth: number;
+    readonly machines: number;
+    readonly owners: number;
+    readonly pathHandles: number;
+    readonly pending: boolean;
+    readonly root: RaphDebugOwnerSnapshot;
+    readonly rootScope: RaphDebugOwnerSnapshot;
+    readonly scopes: readonly RaphDebugOwnerSnapshot[];
+    readonly traceEvents: number;
+}
+export interface RaphDebugTreeNode {
+    readonly children: readonly RaphDebugTreeNode[];
+    readonly count?: number;
+    readonly disposed?: boolean;
+    readonly id: string;
+    readonly kind: 'actor' | 'machine' | 'node' | 'resource' | 'runtime' | 'scope';
+    readonly status?: string;
+}
+export interface RaphDebugStats {
+    readonly actors: number;
+    readonly machines: number;
+    readonly nodes: number;
+    readonly owners: number;
+    readonly pathHandles: number;
+    readonly pending: boolean;
+    readonly resources: number;
+    readonly scopes: number;
+    readonly sources: number;
+    readonly traceEvents: number;
+}
+export interface RaphRuntimeDebug {
+    readonly machines: RaphDebugMachinesApi;
+    readonly trace: RaphDebugTraceApi;
+    getTree: () => RaphDebugTreeNode;
+    snapshot: () => RaphDebugSnapshot;
+    stats: () => RaphDebugStats;
+}
+/**
+ * Хранит opt-in trace и ленивый registry machine diagnostics одного Runtime.
+ * @internal
+ */
+export declare class RaphDebugController {
+    private _capacity;
+    private _context;
+    private _guards;
+    private _include;
+    private _enabled;
+    private _events;
+    private _eventStart;
+    private _eventSize;
+    private _sequence;
+    private _operationSequence;
+    private _machines;
+    readonly trace: RaphDebugTraceApi;
+    readonly machines: RaphDebugMachinesApi;
+    /**
+     * Создаёт controller; ring buffer появляется только при включённом trace.
+     */
+    constructor(options?: RaphDebugOptions);
+    /**
+     * Включает trace с текущими или явно переданными настройками.
+     */
+    start(options?: RaphTraceOptions): void;
+    /**
+     * Останавливает запись, сохраняя уже накопленные events.
+     */
+    stop(): void;
+    /**
+     * Удаляет все накопленные events, не меняя status trace.
+     */
+    clear(): void;
+    /**
+     * Формирует immutable chronological copy ring buffer.
+     */
+    read(options?: RaphTraceReadOptions): readonly RaphTraceEvent[];
+    /**
+     * Возвращает текущую конфигурацию и заполнение buffer.
+     */
+    status(): RaphTraceStatus;
+    /**
+     * Выделяет operation ID только когда trace активен для этого kind.
+     * @internal
+     */
+    nextOperationId(kind: RaphTraceKind): number | undefined;
+    /**
+     * Проверяет active trace path без выделения operation ID.
+     *
+     * @internal
+     */
+    traces(kind: RaphTraceKind): boolean;
+    /**
+     * Записывает одно событие без allocations/timestamp на disabled path.
+     * @internal
+     */
+    record(input: RaphTraceEventInput): void;
+    /**
+     * Регистрирует read-only machine projection без импорта machine engine в Runtime.
+     * @internal
+     */
+    registerMachine(registration: RaphMachineDebugRegistration): Disposer;
+    /**
+     * Проверяет diagnostic identity без создания public snapshot.
+     *
+     * @internal
+     */
+    hasMachine(id: string): boolean;
+    /**
+     * Возвращает compact machine summaries без выполнения guards.
+     */
+    listMachines(): readonly RaphMachineDebugSummary[];
+    /**
+     * Читает готовый machine snapshot; transition selection и guards не вызываются.
+     */
+    machineSnapshot(id: string): RaphMachineDebugSnapshot | undefined;
+    /**
+     * Возвращает число зарегистрированных machines.
+     * @internal
+     */
+    get machineCount(): number;
+    /**
+     * Возвращает число текущих trace events.
+     * @internal
+     */
+    get traceSize(): number;
+    /** Возвращает число child actors по уже готовым snapshots. @internal */
+    get actorCount(): number;
+    /** Группирует machine/actor ветви по фактическому lifecycle owner. @internal */
+    machineTreeNodesByOwner(): ReadonlyMap<string, readonly RaphDebugTreeNode[]>;
+    private _applyOptions;
+    private _ensureBuffer;
+}
+export declare function createOwnerSnapshot(owner: RaphScope): RaphDebugOwnerSnapshot;
+export declare function createOwnerTree(owner: RaphScope, machinesByOwner?: ReadonlyMap<string, readonly RaphDebugTreeNode[]>): RaphDebugTreeNode;