@logixjs/core 0.0.1

package/dist/Debug-Bq8Sqjcr.d.cts

@@ -0,0 +1,320 @@
+import * as effect_FiberRef from 'effect/FiberRef';
+import { i as RuntimeDebugEventRef$1, J as JsonValue, j as Event$1, S as Sink$1, D as DiagnosticsLevel$1, k as TraitConvergeDiagnosticsSamplingConfig$1, l as JsonValueProjectionStats, m as DowngradeReason, n as EvidencePackageSource, o as EvidencePackage } from './Observability-COqEvp2C.cjs';
+import { L as ConvergeStaticIrExport, N as TraitProvenance, M as ModuleTag, h as AnyModuleShape, z as ModuleLike, l as ModuleRuntime, x as ModuleTraitsSnapshot } from './module-B8CBqIZ_.cjs';
+import { Layer, Effect, Logger } from 'effect';
+import { a as StateTraitProgram, b as StateTraitGraph, c as StateTraitPlan } from './StateTrait-OWhbj12c.cjs';
+
+/**
+ * DevtoolsHub：
+ * - Process/page-level Debug event aggregator (global singleton).
+ *
+ * Note: this hub is only appended to Debug sinks when devtoolsHubLayer is explicitly enabled.
+ * The Snapshot API is always available (returns empty snapshots when disabled).
+ *
+ * Performance:
+ * - Devtools Debug events can be extremely dense in hot paths (EffectOp / Trait / StateTxn, etc.).
+ * - The previous implementation copied ringBuffer and Maps per event to build an "immutable snapshot" (O(bufferSize)).
+ * - The current implementation lets Snapshot reference internal Map/Array directly (read-only convention) and batches
+ *   subscriber notifications in microtasks, avoiding per-event copies and reducing main-thread interference.
+ */
+interface DevtoolsSnapshot$1 {
+    /**
+     * SnapshotToken：
+     * - Monotonic snapshot change token (a subscription-safe source of truth).
+     * - Any externally visible change must advance the token.
+     * - If the token does not change, externally visible snapshot fields must not change (avoid tearing / missed updates).
+     */
+    readonly snapshotToken: SnapshotToken$1;
+    readonly instances: ReadonlyMap<string, number>;
+    readonly events: ReadonlyArray<RuntimeDebugEventRef$1>;
+    readonly latestStates: ReadonlyMap<string, JsonValue>;
+    readonly latestTraitSummaries: ReadonlyMap<string, JsonValue>;
+    /**
+     * exportBudget：
+     * - Tracks "degrade counts" caused by export boundaries (JsonValue projection/trimming), for explainability.
+     * - Counts are cumulative (may differ from the ring buffer window); clearDevtoolsEvents resets them.
+     */
+    readonly exportBudget: {
+        readonly dropped: number;
+        readonly oversized: number;
+    };
+}
+interface DevtoolsHubOptions$1 {
+    readonly bufferSize?: number;
+}
+type SnapshotToken$1 = number;
+
+type Event = Event$1;
+interface Sink extends Sink$1 {
+}
+interface RuntimeDebugEventRef extends RuntimeDebugEventRef$1 {
+}
+type DiagnosticsLevel = DiagnosticsLevel$1;
+type TraitConvergeDiagnosticsSamplingConfig = TraitConvergeDiagnosticsSamplingConfig$1;
+type SnapshotToken = SnapshotToken$1;
+declare const toRuntimeDebugEventRef: (event: Event$1, options?: {
+    readonly diagnosticsLevel?: DiagnosticsLevel$1;
+    readonly eventSeq?: number;
+    readonly resolveConvergeStaticIr?: (staticIrDigest: string) => ConvergeStaticIrExport | undefined;
+    readonly onMetaProjection?: (projection: {
+        readonly stats: JsonValueProjectionStats;
+        readonly downgrade?: DowngradeReason;
+    }) => void;
+}) => RuntimeDebugEventRef$1 | undefined;
+declare const internal: {
+    currentDebugSinks: effect_FiberRef.FiberRef<readonly Sink$1[]>;
+    currentRuntimeLabel: effect_FiberRef.FiberRef<string | undefined>;
+    currentDiagnosticsLevel: effect_FiberRef.FiberRef<DiagnosticsLevel$1>;
+    currentTraitConvergeDiagnosticsSampling: effect_FiberRef.FiberRef<TraitConvergeDiagnosticsSamplingConfig$1>;
+    toRuntimeDebugEventRef: (event: Event$1, options?: {
+        readonly diagnosticsLevel?: DiagnosticsLevel$1;
+        readonly eventSeq?: number;
+        readonly resolveConvergeStaticIr?: (staticIrDigest: string) => ConvergeStaticIrExport | undefined;
+        readonly onMetaProjection?: (projection: {
+            readonly stats: JsonValueProjectionStats;
+            readonly downgrade?: DowngradeReason;
+        }) => void;
+    }) => RuntimeDebugEventRef$1 | undefined;
+};
+interface DevtoolsSnapshot extends DevtoolsSnapshot$1 {
+}
+interface DevtoolsHubOptions extends DevtoolsHubOptions$1 {
+    readonly diagnosticsLevel?: DiagnosticsLevel;
+    readonly traitConvergeDiagnosticsSampling?: TraitConvergeDiagnosticsSamplingConfig;
+}
+declare const getDevtoolsSnapshot: () => DevtoolsSnapshot$1;
+declare const getDevtoolsSnapshotToken: () => SnapshotToken$1;
+declare const subscribeDevtoolsSnapshot: (listener: () => void) => (() => void);
+declare const clearDevtoolsEvents: () => void;
+declare const getDevtoolsRunId: () => string;
+declare const setDevtoolsRunId: (runId: string) => void;
+declare const startDevtoolsRun: (runId?: string) => string;
+declare const setInstanceLabel: (instanceId: string, label: string) => void;
+declare const getInstanceLabel: (instanceId: string) => string | undefined;
+declare const exportEvidencePackage: (options?: {
+    readonly runId?: string;
+    readonly source?: EvidencePackageSource;
+    readonly protocolVersion?: string;
+}) => EvidencePackage;
+/**
+ * Diagnostics level for exportable events.
+ *
+ * Controls what DevtoolsHub exports (ring buffer / snapshots), without changing Debug.record's fallback semantics.
+ */
+declare const diagnosticsLevel: (level: DiagnosticsLevel) => Layer.Layer<any, never, never>;
+declare const traitConvergeDiagnosticsSampling: (config: TraitConvergeDiagnosticsSamplingConfig) => Layer.Layer<any, never, never>;
+/**
+ * Whether Devtools is enabled.
+ *
+ * Used by React/Devtools UI to decide if extra instrumentation should be active; turned on by devtoolsHubLayer.
+ */
+declare const isDevtoolsEnabled: () => boolean;
+/**
+ * A lightweight counter of active module runtimes.
+ *
+ * Derived from module:init / module:destroy events; suitable as a DevTools / Playground data source.
+ */
+interface ModuleRuntimeCounter {
+    readonly sink: Sink;
+    readonly getSnapshot: () => ReadonlyMap<string, number>;
+}
+/**
+ * A simple in-memory ring buffer for Debug events.
+ *
+ * No filtering/grouping; consumers can post-process snapshots (by moduleId/type/etc.).
+ */
+interface RingBufferSink {
+    readonly sink: Sink;
+    readonly getSnapshot: () => ReadonlyArray<Event>;
+    readonly clear: () => void;
+}
+/**
+ * Create a Debug sink that counts active instances per moduleId.
+ *
+ * Snapshots are exposed via getSnapshot(); bridging to UI (window/postMessage/etc.) is left to consumers.
+ */
+declare const makeModuleRuntimeCounterSink: () => ModuleRuntimeCounter;
+/**
+ * Create a ring-buffer Debug sink.
+ *
+ * Records the last N events in chronological order; a good foundation for event timelines.
+ */
+declare const makeRingBufferSink: (capacity?: number) => RingBufferSink;
+/**
+ * Emit a Debug event to sinks attached to the current Fiber.
+ *
+ * If no sink is provided, the runtime chooses a safe fallback (browser console grouping; node preserves error-class events).
+ */
+declare const record: (event: Event$1) => Effect.Effect<void, never, never>;
+/**
+ * A no-op Debug layer.
+ *
+ * Provides an empty sink set and drops all Debug events; useful for tests or explicitly disabling Debug.
+ */
+declare const noopLayer: Layer.Layer<any, never, never>;
+/**
+ * Debug mode selector.
+ *
+ * - `auto`: infer dev/prod from NODE_ENV.
+ * - `dev`: verbose diagnostics.
+ * - `prod`: keep only high-value diagnostics/errors.
+ * - `off`: disable sinks (benchmarks/special tests).
+ */
+type DebugMode = 'auto' | 'dev' | 'prod' | 'off';
+interface DebugLayerOptions {
+    readonly mode?: DebugMode;
+    /**
+     * In dev mode, choose what to print to the browser console:
+     * - default: diagnostic + lifecycle:error + trace:* (legacy behavior)
+     * - diagnostic: diagnostic(warn/error) + lifecycle:error only (recommended for app dev with Devtools)
+     */
+    readonly devConsole?: 'default' | 'diagnostic';
+    /**
+     * Diagnostics level for exportable debug event refs (used by DevtoolsHub and debug sinks that normalize events).
+     *
+     * Equivalent to composing `Debug.diagnosticsLevel(level)` with `Debug.layer(...)`.
+     */
+    readonly diagnosticsLevel?: DiagnosticsLevel;
+    /**
+     * Reserved for future use: enable high-noise action/state logs in dev.
+     */
+    readonly verboseActions?: boolean;
+    /**
+     * Reserved for future use: emit key events into metrics in prod.
+     */
+    readonly enableMetrics?: boolean;
+}
+/**
+ * Public entry: compose a Debug layer based on the environment or an explicit mode.
+ *
+ * Default mode is `auto`: non-production → `dev`; production → `prod`.
+ *
+ * @example
+ * ```ts
+ * const runtime = Runtime.make(AppImpl, {
+ *   layer: Layer.mergeAll(Debug.layer(), businessLayer),
+ * })
+ * ```
+ */
+declare const layer: (options?: DebugLayerOptions) => Layer.Layer<any, never, never>;
+/**
+ * PrettyLoggerOptions: parameters of Effect.Logger.prettyLogger.
+ */
+type PrettyLoggerOptions = Parameters<typeof Logger.prettyLogger>[0];
+/**
+ * Replace the default Effect logger with a pretty logger (as a Layer).
+ *
+ * Equivalent to `Logger.replace(Logger.defaultLogger, Logger.prettyLogger(options))`.
+ */
+declare const withPrettyLogger: (base: Layer.Layer<any, any, any>, options?: PrettyLoggerOptions) => Layer.Layer<any, any, any>;
+/**
+ * Replace Debug sinks with the provided sink set.
+ *
+ * Advanced: use either `Debug.layer` or `Debug.replace` in a scope, not both.
+ */
+declare const replace: (sinks: ReadonlyArray<Sink>) => Layer.Layer<any, never, never>;
+/**
+ * Append sinks to the current Fiber's sink set (without overriding existing sinks).
+ */
+declare const appendSinks: (sinks: ReadonlyArray<Sink>) => Layer.Layer<any, never, never>;
+/**
+ * Append the DevtoolsHub sink to aggregate Debug events into snapshots.
+ *
+ * Works by appending sinks; it does not override `Debug.layer` / `Debug.replace` / custom sinks.
+ */
+declare function devtoolsHubLayer(options?: DevtoolsHubOptions): Layer.Layer<any, never, never>;
+declare function devtoolsHubLayer(base: Layer.Layer<any, any, any>, options?: DevtoolsHubOptions): Layer.Layer<any, never, any>;
+/**
+ * Attach a logical runtime label to Debug events within the current Fiber scope.
+ *
+ * DevTools can group events by this label.
+ */
+declare const runtimeLabel: (label: string) => Layer.Layer<any, never, never>;
+/**
+ * StateTrait debug view for Devtools/scripts.
+ */
+interface ModuleTraitsDebug {
+    readonly program?: StateTraitProgram<any>;
+    readonly graph?: StateTraitGraph;
+    readonly plan?: StateTraitPlan;
+}
+/**
+ * A minimal enumerable trait item from the finalized snapshot (023).
+ */
+interface ModuleTraitsFinalItem {
+    readonly traitId: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly provenance: TraitProvenance;
+}
+/**
+ * Read the StateTrait program (if any) from a module definition and return a debug view.
+ */
+declare const getModuleTraits: (module: ModuleTag<string, AnyModuleShape> | ModuleLike<string, AnyModuleShape, any>) => ModuleTraitsDebug;
+/**
+ * Get a module's StateTrait debug view by moduleId (registered at Module.make time).
+ */
+declare const getModuleTraitsById: (moduleId: string) => ModuleTraitsDebug | undefined;
+/**
+ * Read the finalized traits snapshot (023) from a ModuleRuntime; undefined if not finalized.
+ */
+declare const getModuleTraitsSnapshot: (runtime: ModuleRuntime<any, any>) => ModuleTraitsSnapshot | undefined;
+/**
+ * Export a minimal, enumerable trait list from the finalized snapshot (023).
+ *
+ * Order is deterministic and matches the snapshot.
+ */
+declare const getModuleFinalTraits: (runtime: ModuleRuntime<any, any>) => ReadonlyArray<ModuleTraitsFinalItem>;
+declare function traceLayer(onTrace?: (event: Event) => Effect.Effect<void>): Layer.Layer<any, never, never>;
+declare function traceLayer(base: Layer.Layer<any, any, any>, onTrace?: (event: Event) => Effect.Effect<void>): Layer.Layer<any, never, any>;
+
+type Debug_DebugLayerOptions = DebugLayerOptions;
+type Debug_DebugMode = DebugMode;
+type Debug_DevtoolsHubOptions = DevtoolsHubOptions;
+type Debug_DevtoolsSnapshot = DevtoolsSnapshot;
+type Debug_DiagnosticsLevel = DiagnosticsLevel;
+type Debug_Event = Event;
+type Debug_ModuleRuntimeCounter = ModuleRuntimeCounter;
+type Debug_ModuleTraitsDebug = ModuleTraitsDebug;
+type Debug_ModuleTraitsFinalItem = ModuleTraitsFinalItem;
+type Debug_PrettyLoggerOptions = PrettyLoggerOptions;
+type Debug_RingBufferSink = RingBufferSink;
+type Debug_RuntimeDebugEventRef = RuntimeDebugEventRef;
+type Debug_Sink = Sink;
+type Debug_SnapshotToken = SnapshotToken;
+type Debug_TraitConvergeDiagnosticsSamplingConfig = TraitConvergeDiagnosticsSamplingConfig;
+declare const Debug_appendSinks: typeof appendSinks;
+declare const Debug_clearDevtoolsEvents: typeof clearDevtoolsEvents;
+declare const Debug_devtoolsHubLayer: typeof devtoolsHubLayer;
+declare const Debug_diagnosticsLevel: typeof diagnosticsLevel;
+declare const Debug_exportEvidencePackage: typeof exportEvidencePackage;
+declare const Debug_getDevtoolsRunId: typeof getDevtoolsRunId;
+declare const Debug_getDevtoolsSnapshot: typeof getDevtoolsSnapshot;
+declare const Debug_getDevtoolsSnapshotToken: typeof getDevtoolsSnapshotToken;
+declare const Debug_getInstanceLabel: typeof getInstanceLabel;
+declare const Debug_getModuleFinalTraits: typeof getModuleFinalTraits;
+declare const Debug_getModuleTraits: typeof getModuleTraits;
+declare const Debug_getModuleTraitsById: typeof getModuleTraitsById;
+declare const Debug_getModuleTraitsSnapshot: typeof getModuleTraitsSnapshot;
+declare const Debug_internal: typeof internal;
+declare const Debug_isDevtoolsEnabled: typeof isDevtoolsEnabled;
+declare const Debug_layer: typeof layer;
+declare const Debug_makeModuleRuntimeCounterSink: typeof makeModuleRuntimeCounterSink;
+declare const Debug_makeRingBufferSink: typeof makeRingBufferSink;
+declare const Debug_noopLayer: typeof noopLayer;
+declare const Debug_record: typeof record;
+declare const Debug_replace: typeof replace;
+declare const Debug_runtimeLabel: typeof runtimeLabel;
+declare const Debug_setDevtoolsRunId: typeof setDevtoolsRunId;
+declare const Debug_setInstanceLabel: typeof setInstanceLabel;
+declare const Debug_startDevtoolsRun: typeof startDevtoolsRun;
+declare const Debug_subscribeDevtoolsSnapshot: typeof subscribeDevtoolsSnapshot;
+declare const Debug_toRuntimeDebugEventRef: typeof toRuntimeDebugEventRef;
+declare const Debug_traceLayer: typeof traceLayer;
+declare const Debug_traitConvergeDiagnosticsSampling: typeof traitConvergeDiagnosticsSampling;
+declare const Debug_withPrettyLogger: typeof withPrettyLogger;
+declare namespace Debug {
+  export { type Debug_DebugLayerOptions as DebugLayerOptions, type Debug_DebugMode as DebugMode, type Debug_DevtoolsHubOptions as DevtoolsHubOptions, type Debug_DevtoolsSnapshot as DevtoolsSnapshot, type Debug_DiagnosticsLevel as DiagnosticsLevel, type Debug_Event as Event, type Debug_ModuleRuntimeCounter as ModuleRuntimeCounter, type Debug_ModuleTraitsDebug as ModuleTraitsDebug, type Debug_ModuleTraitsFinalItem as ModuleTraitsFinalItem, type Debug_PrettyLoggerOptions as PrettyLoggerOptions, type Debug_RingBufferSink as RingBufferSink, type Debug_RuntimeDebugEventRef as RuntimeDebugEventRef, type Debug_Sink as Sink, type Debug_SnapshotToken as SnapshotToken, type Debug_TraitConvergeDiagnosticsSamplingConfig as TraitConvergeDiagnosticsSamplingConfig, Debug_appendSinks as appendSinks, Debug_clearDevtoolsEvents as clearDevtoolsEvents, Debug_devtoolsHubLayer as devtoolsHubLayer, Debug_diagnosticsLevel as diagnosticsLevel, Debug_exportEvidencePackage as exportEvidencePackage, Debug_getDevtoolsRunId as getDevtoolsRunId, Debug_getDevtoolsSnapshot as getDevtoolsSnapshot, Debug_getDevtoolsSnapshotToken as getDevtoolsSnapshotToken, Debug_getInstanceLabel as getInstanceLabel, Debug_getModuleFinalTraits as getModuleFinalTraits, Debug_getModuleTraits as getModuleTraits, Debug_getModuleTraitsById as getModuleTraitsById, Debug_getModuleTraitsSnapshot as getModuleTraitsSnapshot, Debug_internal as internal, Debug_isDevtoolsEnabled as isDevtoolsEnabled, Debug_layer as layer, Debug_makeModuleRuntimeCounterSink as makeModuleRuntimeCounterSink, Debug_makeRingBufferSink as makeRingBufferSink, Debug_noopLayer as noopLayer, Debug_record as record, Debug_replace as replace, Debug_runtimeLabel as runtimeLabel, Debug_setDevtoolsRunId as setDevtoolsRunId, Debug_setInstanceLabel as setInstanceLabel, Debug_startDevtoolsRun as startDevtoolsRun, Debug_subscribeDevtoolsSnapshot as subscribeDevtoolsSnapshot, Debug_toRuntimeDebugEventRef as toRuntimeDebugEventRef, Debug_traceLayer as traceLayer, Debug_traitConvergeDiagnosticsSampling as traitConvergeDiagnosticsSampling, Debug_withPrettyLogger as withPrettyLogger };
+}
+
+export { layer as A, withPrettyLogger as B, replace as C, Debug as D, type Event as E, appendSinks as F, devtoolsHubLayer as G, runtimeLabel as H, type ModuleTraitsDebug as I, type ModuleTraitsFinalItem as J, getModuleTraits as K, getModuleTraitsById as L, type ModuleRuntimeCounter as M, getModuleTraitsSnapshot as N, getModuleFinalTraits as O, type PrettyLoggerOptions as P, traceLayer as Q, type RuntimeDebugEventRef as R, type SnapshotToken as S, type TraitConvergeDiagnosticsSamplingConfig as T, type Sink as a, type DiagnosticsLevel as b, type DevtoolsSnapshot as c, type DevtoolsHubOptions as d, getDevtoolsSnapshot as e, clearDevtoolsEvents as f, getDevtoolsSnapshotToken as g, getDevtoolsRunId as h, internal as i, setDevtoolsRunId as j, startDevtoolsRun as k, setInstanceLabel as l, getInstanceLabel as m, exportEvidencePackage as n, diagnosticsLevel as o, traitConvergeDiagnosticsSampling as p, isDevtoolsEnabled as q, type RingBufferSink as r, subscribeDevtoolsSnapshot as s, toRuntimeDebugEventRef as t, makeModuleRuntimeCounterSink as u, makeRingBufferSink as v, record as w, noopLayer as x, type DebugMode as y, type DebugLayerOptions as z };