@logixjs/react 0.1.0

package/dist/chunk-2WFULYPJ.js

@@ -0,0 +1,856 @@
+// src/internal/provider/ReactContext.ts
+import { createContext } from "react";
+var RuntimeContext = createContext(null);
+
+// src/internal/provider/env.ts
+import { getNodeEnv, isDevEnv } from "@logixjs/core/Env";
+
+// src/internal/provider/runtimeBindings.ts
+import { useEffect, useRef, useState } from "react";
+import { Layer, Exit, Context, Effect, Cause, FiberRef, Scope } from "effect";
+import * as Logix from "@logixjs/core";
+var toErrorString = (error) => error instanceof Error ? error.stack ?? error.message : String(error);
+var debugScopeCloseFailure = (error) => {
+  if (!isDevEnv()) return;
+  console.debug("[RuntimeProvider] Scope.close failed", toErrorString(error));
+};
+var useLayerBinding = (runtime, layer, enabled, onError) => {
+  const activeBindingRef = useRef(null);
+  const [state, setState] = useState(() => ({
+    binding: null,
+    isLoading: enabled && !!layer,
+    runtime,
+    layer,
+    enabled
+  }));
+  useEffect(() => {
+    if (!enabled || !layer) {
+      const current2 = activeBindingRef.current;
+      if (current2) {
+        activeBindingRef.current = null;
+        void runtime.runPromise(Scope.close(current2.scope, Exit.void)).catch(debugScopeCloseFailure);
+      }
+      setState((prev) => {
+        if (prev.binding === null && prev.isLoading === false && prev.layer === void 0 && prev.enabled === enabled) {
+          return prev;
+        }
+        return {
+          binding: null,
+          isLoading: false,
+          runtime: prev.runtime,
+          layer: void 0,
+          enabled
+        };
+      });
+      return;
+    }
+    const current = activeBindingRef.current;
+    if (current && current.runtime === runtime && current.layer === layer && current.enabled === enabled) {
+      setState({
+        binding: current,
+        isLoading: false,
+        runtime,
+        layer,
+        enabled
+      });
+      return;
+    }
+    const previousBinding = current ?? state.binding;
+    if (isDevEnv() && previousBinding && previousBinding.layer !== layer && enabled && layer) {
+      console.warn(
+        "[RuntimeProvider] Rebuilding layer due to a new layer reference. Memoize the Layer in the caller to avoid repeated rebuilds and resource churn."
+      );
+    }
+    if (current) {
+      activeBindingRef.current = null;
+      void runtime.runPromise(Scope.close(current.scope, Exit.void)).catch(debugScopeCloseFailure);
+    }
+    let cancelled = false;
+    setState({
+      binding: null,
+      isLoading: true,
+      runtime,
+      layer,
+      enabled
+    });
+    const newScope = Effect.runSync(Scope.make());
+    const buildEffect = Effect.gen(function* () {
+      const context = yield* Layer.buildWithScope(layer, newScope);
+      const applyEnv = (effect) => Effect.mapInputContext(
+        Scope.extend(effect, newScope),
+        (parent) => Context.merge(parent, context)
+      );
+      const loggers = yield* applyEnv(FiberRef.get(FiberRef.currentLoggers));
+      const logLevel = yield* applyEnv(FiberRef.get(FiberRef.currentLogLevel));
+      const debugSinks = yield* applyEnv(
+        FiberRef.get(Logix.Debug.internal.currentDebugSinks)
+      );
+      return { context, loggers, logLevel, debugSinks };
+    });
+    const assignBinding = (result) => {
+      if (cancelled) {
+        return runtime.runPromise(Scope.close(newScope, Exit.void)).catch(debugScopeCloseFailure);
+      }
+      const previous = activeBindingRef.current;
+      const newBinding = {
+        context: result.context,
+        loggers: result.loggers,
+        logLevel: result.logLevel,
+        debugSinks: result.debugSinks,
+        scope: newScope,
+        runtime,
+        layer,
+        enabled
+      };
+      activeBindingRef.current = newBinding;
+      setState({
+        binding: newBinding,
+        isLoading: false,
+        runtime,
+        layer,
+        enabled
+      });
+      if (previous) {
+        return runtime.runPromise(Scope.close(previous.scope, Exit.void)).catch(debugScopeCloseFailure);
+      }
+      return Promise.resolve();
+    };
+    let builtSync = false;
+    try {
+      const result = runtime.runSync(buildEffect);
+      builtSync = true;
+      void assignBinding(result);
+    } catch {
+    }
+    if (!builtSync) {
+      void runtime.runPromise(buildEffect).then(assignBinding).catch((error) => {
+        if (onError) {
+          const cause = Cause.die(error);
+          runtime.runFork(
+            onError(cause, { source: "provider", phase: "provider.layer.build" }).pipe(
+              Effect.catchAllCause(() => Effect.void)
+            )
+          );
+        }
+        void runtime.runPromise(Scope.close(newScope, Exit.void)).catch(debugScopeCloseFailure);
+        if (!cancelled) {
+          console.error("[RuntimeProvider] Failed to build layer", error);
+          setState({
+            binding: null,
+            isLoading: false,
+            runtime,
+            layer,
+            enabled
+          });
+        }
+      });
+    }
+    return () => {
+      cancelled = true;
+      const current2 = activeBindingRef.current;
+      if (current2) {
+        activeBindingRef.current = null;
+        void runtime.runPromise(Scope.close(current2.scope, Exit.void)).catch(debugScopeCloseFailure);
+        return;
+      }
+      void runtime.runPromise(Scope.close(newScope, Exit.void)).catch(debugScopeCloseFailure);
+    };
+  }, [runtime, layer, enabled, onError]);
+  const isCurrentBinding = state.binding !== null && state.runtime === runtime && state.layer === layer && state.enabled === enabled && enabled && !!layer;
+  return {
+    binding: isCurrentBinding ? state.binding : null,
+    isLoading: isCurrentBinding ? state.isLoading : enabled && !!layer
+  };
+};
+var createRuntimeAdapter = (runtime, contexts, scopes, loggerSets, logLevels, debugSinks) => {
+  if (contexts.length === 0 && scopes.length === 0 && loggerSets.length === 0 && logLevels.length === 0 && debugSinks.length === 0) {
+    return runtime;
+  }
+  const applyContexts = (effect) => (
+    // First inherit Provider scopes via scope.extend (preserving FiberRef/Logger changes),
+    // then merge Context via mapInputContext (inner overrides outer).
+    contexts.reduceRight(
+      (acc, ctx) => Effect.mapInputContext(
+        acc,
+        (parent) => Context.merge(parent, ctx)
+      ),
+      scopes.reduceRight(
+        (acc, scope) => Scope.extend(acc, scope),
+        effect
+      )
+    )
+  );
+  const applyLoggers = (effect) => {
+    const last = loggerSets.length > 0 ? loggerSets[loggerSets.length - 1] : null;
+    const logLevel = logLevels.length > 0 ? logLevels[logLevels.length - 1] : null;
+    const sinks = debugSinks.length > 0 ? debugSinks[debugSinks.length - 1] : null;
+    let result = effect;
+    if (last) {
+      result = Effect.locally(FiberRef.currentLoggers, last)(result);
+    }
+    if (logLevel) {
+      result = Effect.locally(FiberRef.currentLogLevel, logLevel)(result);
+    }
+    if (sinks && sinks.length > 0) {
+      result = Effect.locally(
+        Logix.Debug.internal.currentDebugSinks,
+        sinks
+      )(result);
+    }
+    return result;
+  };
+  const adapted = {
+    ...runtime,
+    runFork: (effect, options) => runtime.runFork(applyLoggers(applyContexts(effect)), options),
+    runPromise: (effect, options) => runtime.runPromise(applyLoggers(applyContexts(effect)), options),
+    runPromiseExit: (effect, options) => runtime.runPromiseExit(applyLoggers(applyContexts(effect)), options),
+    runSync: (effect) => runtime.runSync(applyLoggers(applyContexts(effect))),
+    runSyncExit: (effect) => runtime.runSyncExit(applyLoggers(applyContexts(effect))),
+    runCallback: (effect, options) => runtime.runCallback(applyLoggers(applyContexts(effect)), options)
+  };
+  return adapted;
+};
+
+// src/internal/store/ModuleCache.ts
+import * as Logix3 from "@logixjs/core";
+import { Cause as Cause2, Effect as Effect3, Exit as Exit2, Fiber, Option, Scope as Scope2 } from "effect";
+
+// src/internal/store/perfWorkloads.ts
+import * as Logix2 from "@logixjs/core";
+import { Effect as Effect2, Schema } from "effect";
+var PerfCounterStateSchema = Schema.Struct({
+  value: Schema.Number
+});
+var PerfCounterActions = {
+  inc: Schema.Void
+};
+var PerfListScopeRowSchema = Schema.Struct({
+  id: Schema.String,
+  warehouseId: Schema.String
+});
+var PerfListScopeStateSchema = Schema.Struct({
+  items: Schema.Array(PerfListScopeRowSchema),
+  digest: Schema.String,
+  errors: Schema.Any
+});
+var GLOBAL_YIELD_BUDGET_MEMORY_KEY = "__LOGIX_REACT_YIELD_BUDGET_MEMORY__";
+var getGlobalYieldBudgetMemory = () => {
+  const root = globalThis;
+  const existing = root[GLOBAL_YIELD_BUDGET_MEMORY_KEY];
+  if (existing && existing.byRuntime instanceof WeakMap) {
+    return existing;
+  }
+  const created = { byRuntime: /* @__PURE__ */ new WeakMap() };
+  root[GLOBAL_YIELD_BUDGET_MEMORY_KEY] = created;
+  return created;
+};
+var getStatsMapForRuntime = (runtime) => {
+  const global = getGlobalYieldBudgetMemory();
+  const cached = global.byRuntime.get(runtime);
+  if (cached) return cached;
+  const created = /* @__PURE__ */ new Map();
+  global.byRuntime.set(runtime, created);
+  return created;
+};
+var quantile = (sorted, q) => {
+  if (sorted.length === 0) return Number.NaN;
+  const clamped = Math.min(1, Math.max(0, q));
+  const idx = Math.floor(clamped * (sorted.length - 1));
+  return sorted[idx];
+};
+var p95 = (samplesMs) => {
+  if (samplesMs.length === 0) return Number.NaN;
+  const sorted = samplesMs.slice().sort((a, b) => a - b);
+  return quantile(sorted, 0.95);
+};
+var YieldBudgetMemory = {
+  shouldYield(args) {
+    const budgetMs = args.policy?.onlyWhenOverBudgetMs;
+    if (budgetMs === void 0) {
+      return { shouldYield: true, reason: "budgetDisabled", p95Ms: void 0 };
+    }
+    const byKey = getStatsMapForRuntime(args.runtime);
+    const stats = byKey.get(args.workloadKey) ?? { seen: false, samplesMs: [] };
+    if (!byKey.has(args.workloadKey)) {
+      byKey.set(args.workloadKey, stats);
+    }
+    if (!stats.seen) {
+      stats.seen = true;
+      return { shouldYield: true, reason: "firstRun", p95Ms: void 0 };
+    }
+    if (stats.samplesMs.length === 0) {
+      return { shouldYield: true, reason: "insufficientSamples", p95Ms: void 0 };
+    }
+    const p95Ms = p95(stats.samplesMs);
+    if (!Number.isFinite(p95Ms)) {
+      return { shouldYield: true, reason: "insufficientSamples", p95Ms: void 0 };
+    }
+    return p95Ms > budgetMs ? { shouldYield: true, reason: "overBudget", p95Ms } : { shouldYield: false, reason: "underBudget", p95Ms };
+  },
+  record(args) {
+    if (!Number.isFinite(args.durationMs) || args.durationMs < 0) return;
+    const byKey = getStatsMapForRuntime(args.runtime);
+    const stats = byKey.get(args.workloadKey) ?? { seen: true, samplesMs: [] };
+    if (!byKey.has(args.workloadKey)) {
+      byKey.set(args.workloadKey, stats);
+    }
+    stats.samplesMs.push(args.durationMs);
+    if (stats.samplesMs.length > 20) {
+      stats.samplesMs.shift();
+    }
+  }
+};
+
+// src/internal/store/ModuleCache.ts
+var RUNTIME_CACHE = /* @__PURE__ */ new WeakMap();
+var DEFAULT_GC_DELAY_MS = 500;
+var ERROR_GC_DELAY_MS = 500;
+var DEFAULT_RENDER_SYNC_BLOCKING_WARN_THRESHOLD_MS = 5;
+var toErrorString2 = (error) => {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  return String(error);
+};
+var seenBestEffortFailures = /* @__PURE__ */ new Set();
+var debugBestEffortFailure = (label, error) => {
+  if (!isDevEnv()) return;
+  const message = toErrorString2(error);
+  if (message.includes("ManagedRuntime disposed")) {
+    return;
+  }
+  const key = `${label}
+${message}`;
+  if (seenBestEffortFailures.has(key)) return;
+  seenBestEffortFailures.add(key);
+  console.debug(label, message);
+};
+var causeToUnknown = (cause) => {
+  const failure = Option.getOrUndefined(Cause2.failureOption(cause));
+  if (failure !== void 0) return failure;
+  const defect = Option.getOrUndefined(Cause2.dieOption(cause));
+  if (defect !== void 0) return defect;
+  return cause;
+};
+var yieldEffect = (strategy) => {
+  switch (strategy) {
+    case "none":
+      return Effect3.void;
+    case "microtask":
+      return Effect3.yieldNow();
+    case "macrotask":
+      return Effect3.promise(
+        () => new Promise((resolve) => {
+          setTimeout(resolve, 0);
+        })
+      );
+  }
+};
+var decideYieldStrategy = (runtime, workloadKey, policy) => {
+  const baseStrategy = policy?.strategy ?? "microtask";
+  if (baseStrategy === "none") {
+    return { strategy: "none", reason: "disabled" };
+  }
+  const budgetMs = policy?.onlyWhenOverBudgetMs;
+  if (budgetMs === void 0) {
+    return { strategy: baseStrategy };
+  }
+  const decision = YieldBudgetMemory.shouldYield({ runtime, workloadKey, policy });
+  return decision.shouldYield ? { strategy: baseStrategy, reason: decision.reason, p95Ms: decision.p95Ms } : { strategy: "none", reason: decision.reason, p95Ms: decision.p95Ms };
+};
+var warnedSyncBlockingKeys = /* @__PURE__ */ new Set();
+var ModuleCache = class {
+  constructor(runtime, gcDelayMs = DEFAULT_GC_DELAY_MS) {
+    this.runtime = runtime;
+    this.gcDelayMs = gcDelayMs;
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  scheduleGC(key, entry) {
+    if (entry.gcTimeout) {
+      return;
+    }
+    const delay = entry.gcTime;
+    if (!Number.isFinite(delay)) {
+      return;
+    }
+    const timeoutMs = delay <= 0 ? 0 : delay;
+    entry.gcTimeout = setTimeout(() => {
+      const current = this.entries.get(key);
+      if (!current || current !== entry) {
+        return;
+      }
+      current.gcTimeout = void 0;
+      if (current.refCount > 0 || current.preloadRefCount > 0) {
+        return;
+      }
+      if (current.status === "pending") {
+        this.scheduleGC(key, current);
+        return;
+      }
+      void this.runtime.runPromise(Scope2.close(current.scope, Exit2.void)).catch((error) => {
+        debugBestEffortFailure("[ModuleCache] Scope.close failed", error);
+      });
+      void this.runtime.runPromise(
+        Logix3.Debug.record({
+          type: "trace:react.module-instance",
+          moduleId: current.ownerId,
+          instanceId: current.value?.instanceId,
+          data: {
+            event: "gc",
+            key
+          }
+        })
+      ).catch((error) => {
+        debugBestEffortFailure("[ModuleCache] Debug.record failed", error);
+      });
+      this.entries.delete(key);
+    }, timeoutMs);
+  }
+  read(key, factory, gcTime, ownerId, options) {
+    const existing = this.entries.get(key);
+    if (existing) {
+      if (isDevEnv() && existing.ownerId !== void 0 && ownerId !== void 0 && existing.ownerId !== ownerId) {
+        console.error(
+          "[ModuleCache.read] resource key ownership mismatch:",
+          `key="${key}" previously owned by "${existing.ownerId}",`,
+          `but now requested by "${ownerId}".`
+        );
+        throw new Error(
+          `[ModuleCache.read] resource key "${key}" has already been claimed by module "${existing.ownerId}", but is now requested by module "${ownerId}". Within the same ManagedRuntime, a given key must not be shared across different ModuleImpl definitions. Please ensure each ModuleImpl uses a distinct key when sharing ModuleRuntime instances.`
+        );
+      }
+      if (existing.status === "pending") {
+        throw existing.promise;
+      }
+      if (existing.status === "error") {
+        throw existing.error;
+      }
+      return existing.value;
+    }
+    const scope = Effect3.runSync(Scope2.make());
+    const workloadKey = `${options?.entrypoint ?? "unknown"}::${ownerId ?? "unknown"}`;
+    const yieldDecision = decideYieldStrategy(this.runtime, workloadKey, options?.yield);
+    const entry = {
+      scope,
+      status: "pending",
+      // Placeholder; will be replaced immediately with the real Promise.
+      promise: Promise.resolve(null),
+      refCount: 0,
+      preloadRefCount: 0,
+      gcTime: gcTime ?? this.gcDelayMs,
+      ownerId,
+      createdBy: "read",
+      workloadKey,
+      yieldStrategy: yieldDecision.strategy
+    };
+    this.scheduleGC(key, entry);
+    const startedAt = performance.now();
+    const buildEffect = yieldEffect(yieldDecision.strategy).pipe(Effect3.zipRight(factory(scope)));
+    const fiber = this.runtime.runFork(buildEffect);
+    entry.fiber = fiber;
+    const promise = this.runtime.runPromise(Fiber.await(fiber)).then((exit) => {
+      if (Exit2.isSuccess(exit)) return exit.value;
+      throw causeToUnknown(exit.cause);
+    });
+    promise.then((value) => {
+      entry.status = "success";
+      entry.value = value;
+      const durationMs = performance.now() - startedAt;
+      YieldBudgetMemory.record({ runtime: this.runtime, workloadKey, durationMs });
+      if (isDevEnv() || Logix3.Debug.isDevtoolsEnabled()) {
+        void this.runtime.runPromise(
+          Logix3.Debug.record({
+            type: "trace:react.module.init",
+            moduleId: ownerId,
+            instanceId: value.instanceId,
+            data: {
+              mode: "suspend",
+              key,
+              durationMs: Math.round(durationMs * 100) / 100,
+              yieldStrategy: yieldDecision.strategy,
+              yieldReason: yieldDecision.reason,
+              yieldP95Ms: yieldDecision.p95Ms
+            }
+          })
+        ).catch((error) => {
+          debugBestEffortFailure("[ModuleCache] Debug.record failed", error);
+        });
+        void this.runtime.runPromise(
+          Logix3.Debug.record({
+            type: "trace:react.module-instance",
+            moduleId: ownerId,
+            instanceId: value.instanceId,
+            data: {
+              event: "attach",
+              key,
+              mode: "suspend",
+              gcTime: entry.gcTime
+            }
+          })
+        ).catch((error) => {
+          debugBestEffortFailure("[ModuleCache] Debug.record failed", error);
+        });
+      }
+      return value;
+    }).catch((error) => {
+      entry.status = "error";
+      entry.error = error;
+      entry.gcTime = ERROR_GC_DELAY_MS;
+      if (entry.gcTimeout) {
+        clearTimeout(entry.gcTimeout);
+        entry.gcTimeout = void 0;
+      }
+      this.scheduleGC(key, entry);
+      YieldBudgetMemory.record({
+        runtime: this.runtime,
+        workloadKey,
+        durationMs: performance.now() - startedAt
+      });
+      void this.runtime.runPromise(Scope2.close(scope, Exit2.fail(error))).catch((closeError) => {
+        debugBestEffortFailure("[ModuleCache] Scope.close failed", closeError);
+      });
+      throw error;
+    });
+    this.entries.set(key, entry);
+    entry.promise = promise;
+    throw promise;
+  }
+  readSync(key, factory, gcTime, ownerId, options) {
+    const existing = this.entries.get(key);
+    if (existing) {
+      if (isDevEnv() && existing.ownerId !== void 0 && ownerId !== void 0 && existing.ownerId !== ownerId) {
+        console.error(
+          "[ModuleCache.readSync] resource key ownership mismatch:",
+          `key="${key}" previously owned by "${existing.ownerId}",`,
+          `but now requested by "${ownerId}".`
+        );
+        throw new Error(
+          `[ModuleCache.readSync] resource key "${key}" has already been claimed by module "${existing.ownerId}", but is now requested by module "${ownerId}". Within the same ManagedRuntime, a given key must not be shared across different ModuleImpl definitions. Please ensure each ModuleImpl uses a distinct key when sharing ModuleRuntime instances.`
+        );
+      }
+      if (existing.status === "error") {
+        throw existing.error;
+      }
+      if (existing.status === "pending") {
+        throw new Error(
+          `[ModuleCache.readSync] encountered pending entry for key="${key}". This usually indicates that the same resource key is being used by both suspend:true (async) and sync consumers. Please either give different keys to async/sync callers, or stick to a single access mode for this resource.`
+        );
+      }
+      return existing.value;
+    }
+    const scope = this.runtime.runSync(Scope2.make());
+    const startedAt = performance.now();
+    try {
+      const value = this.runtime.runSync(factory(scope));
+      const durationMs = performance.now() - startedAt;
+      const entry = {
+        scope,
+        status: "success",
+        promise: Promise.resolve(value),
+        value,
+        refCount: 0,
+        preloadRefCount: 0,
+        gcTime: gcTime ?? this.gcDelayMs,
+        ownerId,
+        createdBy: "read",
+        workloadKey: `${options?.entrypoint ?? "unknown"}::${ownerId ?? "unknown"}`,
+        yieldStrategy: "none"
+      };
+      this.scheduleGC(key, entry);
+      this.entries.set(key, entry);
+      if (isDevEnv()) {
+        const threshold = options?.warnSyncBlockingThresholdMs ?? DEFAULT_RENDER_SYNC_BLOCKING_WARN_THRESHOLD_MS;
+        if (threshold > 0 && durationMs > threshold) {
+          const dedupeKey = `${options?.entrypoint ?? "unknown"}::${ownerId ?? "unknown"}::${key}`;
+          if (!warnedSyncBlockingKeys.has(dedupeKey)) {
+            warnedSyncBlockingKeys.add(dedupeKey);
+            const hint = options?.policyMode === "defer" ? 'Fix: \u5F53\u524D policy.mode="defer"\uFF1A\u8BF7\u68C0\u67E5\u8BE5\u6A21\u5757\u662F\u5426\u5728 policy.preload \u5217\u8868\u4E2D\uFF1B\u672A\u9884\u52A0\u8F7D\u7684\u6A21\u5757\u4ECD\u53EF\u80FD\u89E6\u53D1\u4E8C\u6B21 fallback \u6216\u540C\u6B65\u91CD\u6D3B\u3002' : 'Fix: \u5EFA\u8BAE\u5207\u6362\u5230 policy.mode="suspend"\uFF08\u9ED8\u8BA4\uFF09\uFF0C\u5E76\u63D0\u4F9B RuntimeProvider.fallback\uFF1B\u5FC5\u8981\u65F6\u542F\u7528 yield \u7B56\u7565\u3002';
+            const example = options?.policyMode === "defer" ? 'Example: <RuntimeProvider policy={{ mode: "defer", preload: [MyImpl] }} fallback={<Loading />}>\u2026</RuntimeProvider>' : 'Example: <RuntimeProvider policy={{ mode: "suspend" }} fallback={<Loading />}>\u2026</RuntimeProvider>';
+            const docs = "Docs: apps/docs/content/docs/guide/essentials/react-integration.md";
+            console.warn(
+              "[Logix][React] Render-phase sync blocking detected",
+              `(${Math.round(durationMs * 100) / 100}ms > ${threshold}ms)`,
+              "\n",
+              `entrypoint=${options?.entrypoint ?? "unknown"}`,
+              "\n",
+              `ownerId=${ownerId ?? "unknown"}`,
+              "\n",
+              `key=${key}`,
+              "\n",
+              hint,
+              "\n",
+              example,
+              "\n",
+              docs
+            );
+          }
+        }
+      }
+      if (isDevEnv() || Logix3.Debug.isDevtoolsEnabled()) {
+        void this.runtime.runPromise(
+          Logix3.Debug.record({
+            type: "trace:react.module.init",
+            moduleId: ownerId,
+            instanceId: value.instanceId,
+            data: {
+              mode: "sync",
+              key,
+              durationMs: Math.round(durationMs * 100) / 100,
+              yieldStrategy: "none"
+            }
+          })
+        ).catch((error) => {
+          debugBestEffortFailure("[ModuleCache] Debug.record failed", error);
+        });
+        void this.runtime.runPromise(
+          Logix3.Debug.record({
+            type: "trace:react.module-instance",
+            moduleId: ownerId,
+            instanceId: value.instanceId,
+            data: {
+              event: "attach",
+              key,
+              mode: "sync",
+              gcTime: entry.gcTime
+            }
+          })
+        ).catch((error) => {
+          debugBestEffortFailure("[ModuleCache] Debug.record failed", error);
+        });
+      }
+      return value;
+    } catch (error) {
+      void this.runtime.runPromise(Scope2.close(scope, Exit2.fail(error))).catch((closeError) => {
+        debugBestEffortFailure("[ModuleCache] Scope.close failed", closeError);
+      });
+      const entry = {
+        scope,
+        status: "error",
+        promise: Promise.reject(error),
+        error,
+        refCount: 0,
+        preloadRefCount: 0,
+        gcTime: ERROR_GC_DELAY_MS,
+        ownerId,
+        createdBy: "read",
+        workloadKey: `${options?.entrypoint ?? "unknown"}::${ownerId ?? "unknown"}`,
+        yieldStrategy: "none"
+      };
+      this.scheduleGC(key, entry);
+      this.entries.set(key, entry);
+      throw error;
+    }
+  }
+  preload(key, factory, options) {
+    const existing = this.entries.get(key);
+    if (existing) {
+      if (existing.status === "success") {
+        existing.preloadRefCount += 1;
+        return {
+          promise: Promise.resolve(existing.value),
+          cancel: () => {
+            this.cancelPreload(key, existing);
+          }
+        };
+      }
+      if (existing.status === "error") {
+        return { promise: Promise.reject(existing.error), cancel: () => {
+        } };
+      }
+      existing.preloadRefCount += 1;
+      return {
+        promise: existing.promise,
+        cancel: () => {
+          this.cancelPreload(key, existing);
+        }
+      };
+    }
+    const scope = Effect3.runSync(Scope2.make());
+    const ownerId = options?.ownerId;
+    const gcTime = options?.gcTime ?? this.gcDelayMs;
+    const workloadKey = `${options?.entrypoint ?? "unknown"}::${ownerId ?? "unknown"}`;
+    const yieldDecision = decideYieldStrategy(this.runtime, workloadKey, options?.yield);
+    const entry = {
+      scope,
+      status: "pending",
+      promise: Promise.resolve(null),
+      refCount: 0,
+      preloadRefCount: 1,
+      gcTime,
+      ownerId,
+      createdBy: "preload",
+      workloadKey,
+      yieldStrategy: yieldDecision.strategy
+    };
+    this.scheduleGC(key, entry);
+    this.entries.set(key, entry);
+    const startedAt = performance.now();
+    const buildEffect = yieldEffect(yieldDecision.strategy).pipe(Effect3.zipRight(factory(scope)));
+    const fiber = this.runtime.runFork(buildEffect);
+    entry.fiber = fiber;
+    const promise = this.runtime.runPromise(Fiber.await(fiber)).then((exit) => {
+      if (Exit2.isSuccess(exit)) return exit.value;
+      throw causeToUnknown(exit.cause);
+    });
+    entry.promise = promise;
+    void promise.then((value) => {
+      entry.status = "success";
+      entry.value = value;
+      YieldBudgetMemory.record({
+        runtime: this.runtime,
+        workloadKey,
+        durationMs: performance.now() - startedAt
+      });
+    }).catch((error) => {
+      entry.status = "error";
+      entry.error = error;
+      entry.gcTime = ERROR_GC_DELAY_MS;
+      if (entry.gcTimeout) {
+        clearTimeout(entry.gcTimeout);
+        entry.gcTimeout = void 0;
+      }
+      this.scheduleGC(key, entry);
+      YieldBudgetMemory.record({
+        runtime: this.runtime,
+        workloadKey,
+        durationMs: performance.now() - startedAt
+      });
+      void this.runtime.runPromise(Scope2.close(scope, Exit2.fail(error))).catch((closeError) => {
+        debugBestEffortFailure("[ModuleCache] Scope.close failed", closeError);
+      });
+    });
+    return {
+      promise,
+      cancel: () => {
+        this.cancelPreload(key, entry);
+      }
+    };
+  }
+  cancelPreload(key, entry) {
+    const current = this.entries.get(key);
+    if (!current || current !== entry) {
+      return;
+    }
+    entry.preloadRefCount = Math.max(0, entry.preloadRefCount - 1);
+    if (entry.preloadRefCount > 0) {
+      return;
+    }
+    if (entry.refCount > 0) {
+      return;
+    }
+    if (entry.status === "pending") {
+      if (entry.createdBy !== "preload") {
+        this.scheduleGC(key, entry);
+        return;
+      }
+      const running = entry.fiber;
+      entry.fiber = void 0;
+      this.entries.delete(key);
+      if (running) {
+        this.runtime.runFork(Fiber.interrupt(running));
+      }
+      void this.runtime.runPromise(Scope2.close(entry.scope, Exit2.void)).catch((closeError) => {
+        debugBestEffortFailure("[ModuleCache] Scope.close failed", closeError);
+      });
+      return;
+    }
+    if (entry.gcTimeout) {
+      clearTimeout(entry.gcTimeout);
+      entry.gcTimeout = void 0;
+    }
+    this.scheduleGC(key, entry);
+  }
+  /**
+   * Declares ownership of a resource after component commit.
+   * The returned function releases the reference during cleanup.
+   */
+  retain(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return () => {
+      };
+    }
+    entry.refCount += 1;
+    if (entry.gcTimeout) {
+      clearTimeout(entry.gcTimeout);
+      entry.gcTimeout = void 0;
+    }
+    return () => {
+      this.release(key);
+    };
+  }
+  release(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    entry.refCount -= 1;
+    if (entry.refCount > 0) {
+      return;
+    }
+    this.scheduleGC(key, entry);
+  }
+  dispose() {
+    for (const [key, entry] of this.entries) {
+      if (entry.gcTimeout) {
+        clearTimeout(entry.gcTimeout);
+      }
+      void this.runtime.runPromise(Scope2.close(entry.scope, Exit2.void)).catch((error) => {
+        debugBestEffortFailure("[ModuleCache] Scope.close failed", error);
+      });
+      this.entries.delete(key);
+    }
+  }
+};
+var getModuleCache = (runtime, config, version) => {
+  const cached = RUNTIME_CACHE.get(runtime);
+  if (cached && cached.version === version) {
+    return cached.cache;
+  }
+  if (cached) {
+    cached.cache.dispose();
+  }
+  const cache = new ModuleCache(runtime, config.gcTime);
+  RUNTIME_CACHE.set(runtime, { version, cache });
+  return cache;
+};
+var hashOf = (value) => {
+  if (value === null) {
+    return "null";
+  }
+  const type = typeof value;
+  if (type === "string") {
+    return `s:${value}`;
+  }
+  if (type === "number") {
+    return `n:${value}`;
+  }
+  if (type === "boolean") {
+    return `b:${value}`;
+  }
+  return `${type}:${Object.prototype.toString.call(value)}`;
+};
+var stableHash = (deps) => {
+  if (isDevEnv()) {
+    const hasNonPrimitive = deps.some((value) => {
+      if (value === null) return false;
+      const type = typeof value;
+      return type === "object" || type === "function";
+    });
+    if (hasNonPrimitive) {
+      console.warn(
+        "[ModuleCache] deps contains non-primitive values. stableHash() only distinguishes primitives (string/number/boolean/null/undefined); object/function entries may not trigger expected cache updates. Consider passing explicit primitive deps or controlling invalidation via `key`."
+      );
+    }
+  }
+  return deps.map(hashOf).join("|");
+};
+
+export {
+  RuntimeContext,
+  isDevEnv,
+  useLayerBinding,
+  createRuntimeAdapter,
+  getModuleCache,
+  stableHash
+};