stroid 0.1.0 → 0.1.2

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.7"
+    }
+  ]
+}

package/dist/types/adapters/options.d.ts

@@ -1,4 +1,8 @@
+import type { TraceContext } from "../types/utility.js";
 export type StoreValue = unknown;
+export interface FeatureOptionsMap {
+}
+export type FeatureOptions = Partial<FeatureOptionsMap> & Record<string, unknown>;
 export interface PersistDriver {
     getItem?: (k: string) => string | null | Promise<string | null>;
     setItem?: (k: string, v: string) => void | Promise<void>;
@@ -69,6 +73,11 @@ export interface PersistOptions<State = StoreValue> {
      * `encrypt` hook is provided.
      */
     sensitiveData?: boolean;
+    /**
+     * Maximum allowed persisted payload size (in characters).
+     * When exceeded, hydration is skipped and an error is reported.
+     */
+    maxSize?: number;
     /**
      * Integrity check mode for persisted payloads.
      * - "hash" (default): store and validate a checksum.
@@ -96,6 +105,7 @@ export interface PersistConfig {
     decryptAsync?: (v: string) => Promise<string>;
     allowPlaintext?: boolean;
     sensitiveData?: boolean;
+    maxSize?: number;
     checksum: "hash" | "none" | "sha256";
     onMigrationFail?: "reset" | "keep" | ((state: unknown) => unknown);
     onStorageCleared?: (info: {
@@ -110,21 +120,44 @@ export interface MiddlewareCtx {
     prev: StoreValue;
     next: StoreValue;
     path: unknown;
+    correlationId?: string;
+    traceContext?: TraceContext;
 }
 export interface SyncOptions {
     channel?: string;
     maxPayloadBytes?: number;
+    /**
+     * Authentication policy for sync.
+     * - "strict": require authToken or verify (blocks sync if missing)
+     * - "insecure": allow unauthenticated sync (explicit opt-out)
+     */
+    policy?: "strict" | "insecure";
     /**
      * Optional shared token for lightweight cross-tab authentication.
      * When set, incoming sync messages without a matching token are rejected.
      */
     authToken?: string;
+    /**
+     * Explicitly allow unauthenticated sync.
+     * Deprecated in favor of policy: "insecure".
+     */
+    insecure?: boolean;
     conflictResolver?: (args: {
         local: StoreValue;
         incoming: StoreValue;
         localUpdated: number;
         incomingUpdated: number;
     }) => StoreValue | void;
+    /**
+     * Optional guard to prevent rapid feedback loops when sync updates trigger local reactions.
+     *
+     * - true: enable with a default window (100ms)
+     * - { windowMs }: customize the guard window in milliseconds
+     * - false: disable (default is enabled when sync is truthy)
+     */
+    loopGuard?: boolean | {
+        windowMs?: number;
+    };
     /**
      * Optional checksum mode for sync payloads.
      * - "hash" (default): include a checksum of the payload.
@@ -208,14 +241,27 @@ export interface StoreOptions<State = StoreValue> {
     historyLimit?: number;
     allowSSRGlobalStore?: boolean;
     sync?: boolean | SyncOptions;
+    /**
+     * Optional feature option bag for third-party plugins.
+     * Keys are plugin names, values are plugin-specific options.
+     */
+    features?: FeatureOptions;
     /**
      * Snapshot cloning strategy used by subscriptions and selector snapshots.
      *
      * - "deep" (default): deep clone and dev-freeze snapshot values.
      * - "shallow": shallow clone (top-level) only; nested references are shared.
-     * - "ref": return the live store reference (no cloning).
+     * - "ref": return the live store reference (dev-freeze by default).
      */
     snapshot?: SnapshotMode;
+    /**
+     * Safety policy for snapshot deliveries when using "ref" or "shallow" modes.
+     * - "warn": (default) log a warning in dev when mutation is detected.
+     * - "throw": throw an error in dev when mutation is detected.
+     * - "auto-clone": in dev, if a subscriber mutates a frozen snapshot, deliver a cloned
+     *   snapshot to that subscriber so the mutation does not affect other subscribers or the store.
+     */
+    snapshotSafety?: 'warn' | 'throw' | 'auto-clone';
 }
 export interface NormalizedOptions {
     scope: StoreScope;
@@ -236,12 +282,54 @@ export interface NormalizedOptions {
     historyLimit: number;
     allowSSRGlobalStore?: boolean;
     sync?: boolean | SyncOptions;
+    features?: FeatureOptions;
     snapshot: SnapshotMode;
+    /** normalized snapshotSafety value */
+    snapshotSafety?: 'warn' | 'throw' | 'auto-clone';
     explicitPersist: boolean;
     explicitSync: boolean;
     explicitDevtools: boolean;
 }
+/**
+ * Resets the internal set of legacy options that have been warned
+ * about. Used for testing purposes to prevent warnings from leaking
+ * between tests.
+ */
 export declare const resetLegacyOptionDeprecationWarningsForTests: () => void;
+/**
+ * Normalize persist options for a store.
+ *
+ * This function takes the raw persist options from a store and returns
+ * a normalized PersistConfig object. If the raw persist options are
+ * invalid, this function returns null.
+ *
+ * @template State
+ * @param {StoreOptions<State>["persist"]} persist - The raw persist options for the store.
+ * @param {string} name - The name of the store.
+ * @returns {PersistConfig | null} A normalized PersistConfig object, or null if the raw persist options are invalid.
+ */
 export declare const normalizePersistOptions: <State>(persist: StoreOptions<State>["persist"], name: string) => PersistConfig | null;
+/**
+ * Collect deprecation warnings for a store options object.
+ *
+ * This function walks through the store options object and checks if any
+ * deprecated options are present. If a deprecated option is found, a
+ * warning message is added to the warnings array.
+ *
+ * The function returns an array of warning messages. If no deprecated
+ * options are found, an empty array is returned.
+ *
+ * @template State The type of the state stored in the store.
+ * @param option The store options object to check for deprecated options.
+ * @returns An array of warning messages for deprecated options. If no deprecated
+ *          options are found, an empty array is returned.
+ */
 export declare const collectLegacyOptionDeprecationWarnings: <State>(option: StoreOptions<State>) => string[];
-export declare const normalizeStoreOptions: <State>(option: StoreOptions<State> | undefined, name: string) => NormalizedOptions;
+/**
+ * Normalize a store options object, merging default values and performing deprecation checks.
+ * @param option The store options object to normalize.
+ * @param name The name of the store.
+ * @param defaultSnapshotMode The default snapshot mode to use if none is specified.
+ * @returns A normalized store options object.
+ */
+export declare const normalizeStoreOptions: <State>(option: StoreOptions<State> | undefined, name: string, defaultSnapshotMode?: SnapshotMode) => NormalizedOptions;

package/dist/types/async/cache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module async-cache
+*
+* LAYER: Module
+* OWNS:  Module-level behavior and exports for async-cache.
+*
+* Consumers: Internal imports and public API.
+*/
+import { getActiveAsyncRegistry } from "../core/store-core.js";
+export { getActiveAsyncRegistry } from "../core/store-core.js";
+import type { WarnCategory, StoreCleanupKind } from "./registry.js";
+export type { FetchOptions, AsyncStateSnapshot, AsyncStateAdapter, StoreCleanupKind } from "./registry.js";
+export type FetchInput = string | Promise<unknown> | (() => string | Promise<unknown>);
+export declare const MAX_CACHE_SLOTS_PER_STORE = 100;
+export declare const MAX_INFLIGHT_SLOTS_PER_STORE = 100;
+export declare const MAX_WARNED_ENTRIES = 1000;
+export declare const getFetchRegistry: () => ReturnType<typeof getActiveAsyncRegistry>["fetchRegistry"];
+export declare const getInflightRegistry: () => ReturnType<typeof getActiveAsyncRegistry>["inflight"];
+export declare const getRequestVersionRegistry: () => ReturnType<typeof getActiveAsyncRegistry>["requestVersion"];
+export declare const getCacheMeta: () => ReturnType<typeof getActiveAsyncRegistry>["cacheMeta"];
+export declare const getRateWindowStartRegistry: () => ReturnType<typeof getActiveAsyncRegistry>["rateWindowStart"];
+export declare const getRateCountRegistry: () => ReturnType<typeof getActiveAsyncRegistry>["rateCount"];
+export declare const getRatePruneState: () => ReturnType<typeof getActiveAsyncRegistry>["ratePruneState"];
+export declare const getRevalidateHandlers: () => ReturnType<typeof getActiveAsyncRegistry>["revalidateHandlers"];
+export declare const getStoreCleanups: () => ReturnType<typeof getActiveAsyncRegistry>["storeCleanups"];
+export declare const getWarnedOnce: () => ReturnType<typeof getActiveAsyncRegistry>["warnedOnce"];
+export declare const getRevalidateKeys: () => ReturnType<typeof getActiveAsyncRegistry>["revalidateKeys"];
+export declare const getAsyncMetrics: () => ReturnType<typeof getActiveAsyncRegistry>["asyncMetrics"];
+export declare const markWarned: (set: Set<string>, key: string) => void;
+export declare const warnOnce: (category: WarnCategory, key: string, onWarn: () => void) => void;
+export declare const cleanupStoreCleanupsByKind: (kind: StoreCleanupKind) => void;
+export declare const resetAsyncState: () => void;
+export declare const shouldUseCache: (cacheSlot: string, ttl?: number) => boolean;
+export declare const clearAsyncMeta: (name: string) => void;
+export declare const pruneAsyncCache: (name: string) => void;
+export declare const countInflightSlots: (name: string) => number;
+export declare const registerStoreCleanup: (name: string, fn: () => void, kind?: StoreCleanupKind) => void;
+export declare const unregisterStoreCleanup: (name: string, fn: () => void, kind?: StoreCleanupKind) => void;
+export declare const ensureCleanupSubscription: (_name: string) => void;

package/dist/types/async/clone.d.ts

@@ -1,2 +1,10 @@
-import type { FetchOptions } from "../async-cache.js";
+/**
+ * @module async/clone
+ *
+ * LAYER: Async subsystem
+ * OWNS:  Module-level behavior and exports for async/clone.
+ *
+ * Consumers: Internal imports and public API.
+ */
+import type { FetchOptions } from "./cache.js";
 export declare const cloneAsyncResult: (value: unknown, mode: FetchOptions["cloneResult"]) => unknown;

package/dist/types/{async-fetch.d.ts → async/fetch.d.ts}

@@ -1,5 +1,5 @@
-import { type StoreDefinition, type StoreKey, type StoreName } from "./store-lifecycle.js";
-import { type FetchInput, type FetchOptions } from "./async-cache.js";
+import type { StoreDefinition, StoreKey, StoreName } from "../core/store-lifecycle/types.js";
+import { type FetchInput, type FetchOptions } from "./cache.js";
 export declare function fetchStore<Name extends string, State>(name: StoreDefinition<Name, State>, urlOrRequest: FetchInput, options?: FetchOptions): Promise<unknown>;
 export declare function fetchStore<Name extends string, State>(name: StoreKey<Name, State>, urlOrRequest: FetchInput, options?: FetchOptions): Promise<unknown>;
 export declare function fetchStore<Name extends StoreName>(name: Name, urlOrRequest: FetchInput, options?: FetchOptions): Promise<unknown>;

package/dist/types/async/inflight.d.ts

@@ -1,4 +1,4 @@
-import type { FetchOptions } from "../async-cache.js";
+import type { FetchOptions } from "./cache.js";
 export type InflightEntry = {
     promise: Promise<unknown>;
     raw: Promise<unknown>;

package/dist/types/{async-registry.d.ts → async/registry.d.ts}

@@ -1,3 +1,12 @@
+/**
+ * @module async-registry
+ *
+ * LAYER: Module
+ * OWNS:  Module-level behavior and exports for async-registry.
+ *
+ * Consumers: Internal imports and public API.
+ */
+import type { TraceContext } from "../types/utility.js";
 export type AsyncStateSnapshot = {
     data?: unknown;
     loading: boolean;
@@ -5,6 +14,8 @@ export type AsyncStateSnapshot = {
     status: "idle" | "loading" | "success" | "error" | "aborted";
     cached?: boolean;
     revalidating?: boolean;
+    correlationId?: string;
+    traceContext?: TraceContext;
 };
 export type AsyncStateAdapter = (ctx: {
     name: string;
@@ -12,6 +23,9 @@ export type AsyncStateAdapter = (ctx: {
     next: AsyncStateSnapshot;
     set: (value: unknown | ((draft: any) => void)) => void;
 }) => void;
+export type WarnCategory = "noSignal" | "shape" | "autoCreate" | "mutableResult";
+export type StoreCleanupKind = "store" | "revalidate";
+export type StoreCleanupBucket = Partial<Record<StoreCleanupKind, Set<() => void>>>;
 export interface FetchOptions {
     transform?: (result: unknown) => unknown;
     onSuccess?: (data: unknown) => void;
@@ -33,6 +47,15 @@ export interface FetchOptions {
     signal?: AbortSignal;
     cacheKey?: string;
     responseType?: "auto" | "json" | "text" | "arrayBuffer" | "blob" | "formData";
+    /**
+     * Optional correlation ID for tracing async writes.
+     * When provided, it is propagated into store metadata and middleware context.
+     */
+    correlationId?: string;
+    /**
+     * Optional trace context (e.g. OpenTelemetry).
+     */
+    traceContext?: TraceContext;
     /**
      * Auto-create the backing store if missing.
      * Defaults to the global config setting (true by default).
@@ -74,11 +97,8 @@ export type AsyncRegistry = {
         lastAt: number;
     };
     ratePruneTimer: ReturnType<typeof setTimeout> | null;
-    noSignalWarned: Set<string>;
-    shapeWarned: Set<string>;
-    autoCreateWarned: Set<string>;
-    cleanupSubs: Record<string, () => void>;
-    storeCleanupFns: Record<string, Set<() => void>>;
+    warnedOnce: Map<WarnCategory, Set<string>>;
+    storeCleanups: Record<string, StoreCleanupBucket>;
     revalidateKeys: Set<string>;
     revalidateHandlers: Record<string, () => void>;
     asyncMetrics: {

package/dist/types/async/request.d.ts

@@ -1,3 +1,11 @@
-import type { FetchOptions } from "../async-cache.js";
+/**
+ * @module async/request
+ *
+ * LAYER: Async subsystem
+ * OWNS:  Module-level behavior and exports for async/request.
+ *
+ * Consumers: Internal imports and public API.
+ */
+import type { FetchOptions } from "./cache.js";
 export declare const buildFetchOptions: (options: FetchOptions) => RequestInit;
 export declare const parseResponseBody: (response: Response, responseType: FetchOptions["responseType"]) => Promise<unknown>;

package/dist/types/async.d.ts

@@ -1,2 +1,10 @@
-export type { FetchOptions, FetchInput, AsyncStateSnapshot, AsyncStateAdapter } from "./async-cache.js";
-export { fetchStore, refetchStore, enableRevalidateOnFocus, getAsyncMetrics, _resetAsyncStateForTests, } from "./async-fetch.js";
+/**
+ * @module async
+ *
+ * LAYER: Async subsystem
+ * OWNS:  Module-level behavior and exports for async.
+ *
+ * Consumers: Internal imports and public API.
+ */
+export type { FetchOptions, FetchInput, AsyncStateSnapshot, AsyncStateAdapter } from "./async/cache.js";
+export { fetchStore, refetchStore, enableRevalidateOnFocus, getAsyncMetrics, _resetAsyncStateForTests, } from "./async/fetch.js";

package/dist/types/{computed-graph.d.ts → computed/computed-graph.d.ts}

@@ -1,14 +1,12 @@
 /**
  * @module computed-graph
  *
- * LAYER: Internal graph engine
- * OWNS:  Dependency tracking, cycle detection, topological ordering,
- *        computed entry CRUD. Zero React. Zero async.
+ * LAYER: Module
+ * OWNS:  Module-level behavior and exports for computed-graph.
  *
- * Consumers: computed.ts (public API), store-notify.ts (flush ordering),
- *            store-admin.ts (cleanup on delete), runtime-tools.ts (diagnostics)
+ * Consumers: Internal imports and public API.
  */
-import { type ComputedEntry } from "./store-registry.js";
+import { type ComputedEntry } from "../core/store-registry.js";
 export declare const detectCycle: (name: string, deps: string[]) => string | null;
 export declare const registerComputed: (name: string, deps: string[], compute: (...args: unknown[]) => unknown) => boolean;
 export declare const unregisterComputed: (name: string) => void;

package/dist/types/{computed.d.ts → computed/index.d.ts}

@@ -1,4 +1,5 @@
-import type { StoreDefinition, StoreKey, StoreName, StateFor, StoreValue } from "./store-lifecycle.js";
+import "../core/store-notify.js";
+import type { StoreDefinition, StoreKey, StoreName, StateFor, StoreValue } from "../core/store-lifecycle/types.js";
 export type ComputedOptions = {
     autoDispose?: boolean;
     onError?: (err: unknown) => void;
@@ -12,4 +13,4 @@ export declare const invalidateComputed: (name: string) => void;
 export declare const deleteComputed: (name: string) => void;
 export declare const isComputedStore: (name: string) => boolean;
 export declare const _resetComputedForTests: () => void;
-export {};
+export { getFullComputedGraph, getComputedDepsFor } from "./computed-graph.js";

package/dist/types/config.d.ts

@@ -1,2 +1,10 @@
-export { configureStroid, resetConfig } from "./internals/config.js";
+/**
+ * @module config
+ *
+ * LAYER: Public API
+ * OWNS:  Module-level behavior and exports for config.
+ *
+ * Consumers: Internal imports and public API.
+ */
+export { configureStroid, resetConfig, registerMutatorProduce } from "./internals/config.js";
 export type { LogSink, StroidConfig, FlushConfig, RevalidateOnFocusConfig, } from "./internals/config.js";

package/dist/types/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module core
+ *
+ * LAYER: Public API (minimal runtime)
+ * OWNS:  Core store primitives only.
+ *
+ * Consumers: Bundle-size-sensitive consumers and explicit core usage.
+ */
+export { createStore } from "./store-create.js";
+export { setStore, resetStore, deleteStore } from "./store-write.js";
+export { getStore, hasStore } from "./store-read.js";

package/dist/types/core/lifecycle-hooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module core/lifecycle-hooks
+ *
+ * LAYER: Core utilities
+ * OWNS:  Cross-cutting lifecycle hooks without dependencies on other modules.
+ *
+ * Consumers: notification/*, async-cache.ts, internals/store-admin.ts
+ */
+export type LifecycleHookEvent = {
+    type: string;
+    [key: string]: unknown;
+};
+export type LifecycleHook = (storeId: string, event: LifecycleHookEvent) => void;
+export declare const registerHook: (name: string, fn: LifecycleHook) => (() => void);
+export declare const hasHook: (name: string) => boolean;
+export declare const fireHook: (name: string, storeId: string, event: LifecycleHookEvent) => void;

package/dist/types/core/store-admin-impl.d.ts

@@ -0,0 +1,9 @@
+import type { StoreDefinition, StoreKey, StoreName, WriteResult } from "./store-lifecycle/types.js";
+export declare function deleteStore<Name extends string, State>(name: StoreDefinition<Name, State>): void;
+export declare function deleteStore<Name extends string, State>(name: StoreKey<Name, State>): void;
+export declare function deleteStore<Name extends StoreName>(name: Name): void;
+export declare function resetStore<Name extends string, State>(name: StoreDefinition<Name, State>): WriteResult;
+export declare function resetStore<Name extends string, State>(name: StoreKey<Name, State>): WriteResult;
+export declare function resetStore<Name extends StoreName>(name: Name): WriteResult;
+export declare const clearAllStores: () => void;
+export declare const _hardResetAllStoresForTest: () => void;

package/dist/types/core/store-admin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module store-admin
+ *
+ * LAYER: Store runtime
+ * OWNS:  Public delete/reset/clear exports.
+ *
+ * Consumers: store-write barrel.
+ */
+export { deleteStore, resetStore, clearAllStores, _hardResetAllStoresForTest, } from "./store-admin-impl.js";

package/dist/types/core/store-core.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module store-core
+ *
+ * LAYER: Store core
+ * OWNS:  Minimal core adapters and registry accessors.
+ *
+ * Consumers: Internal async modules.
+ */
+import type { StoreRegistry } from "./store-registry.js";
+import type { IStoreCore } from "./store-shared/core.js";
+export declare const getActiveRegistry: () => StoreRegistry;
+export declare const getActiveAsyncRegistry: () => StoreRegistry["async"];
+export declare const createStoreCore: <T = any>(name: string) => IStoreCore<T>;

package/dist/types/core/store-create.d.ts

@@ -0,0 +1,16 @@
+import { type StoreOptions } from "../adapters/options.js";
+import type { NonFunction } from "../types/utility.js";
+import type { StoreDefinition } from "./store-lifecycle/types.js";
+type LazyDisallow<T> = T extends {
+    lazy: true;
+} ? never : T;
+export declare const clearSsrGlobalAllowWarned: (name?: string) => void;
+export declare function createStore<Name extends string, State>(name: Name, initialData: () => State, option: StoreOptions<State> & {
+    lazy: true;
+}): StoreDefinition<Name, State> | undefined;
+export declare function createStore<Name extends string, State, Opt extends StoreOptions<State>>(name: Name, initialData: NonFunction<State>, option?: LazyDisallow<Opt>): StoreDefinition<Name, State> | undefined;
+export declare function createStoreStrict<Name extends string, State>(name: Name, initialData: () => State, option: StoreOptions<State> & {
+    lazy: true;
+}): StoreDefinition<Name, State>;
+export declare function createStoreStrict<Name extends string, State, Opt extends StoreOptions<State>>(name: Name, initialData: NonFunction<State>, option?: LazyDisallow<Opt>): StoreDefinition<Name, State>;
+export {};

package/dist/types/core/store-hydrate-impl.d.ts

@@ -0,0 +1,35 @@
+import { type StoreOptions } from "../adapters/options.js";
+import type { StoreStateMap, StrictStoreMap, HydrateSnapshotFor, HydrationResult } from "./store-lifecycle/types.js";
+type HydrateSnapshot = HydrateSnapshotFor<StoreStateMap & StrictStoreMap>;
+type HydrateOptions<Snapshot extends object> = Partial<{
+    [K in keyof Snapshot]: StoreOptions<Snapshot[K]>;
+}> & {
+    default?: StoreOptions;
+};
+type HydrationTrustBase<Snapshot extends object> = {
+    /**
+     * Explicitly trust this snapshot and allow hydration.
+     */
+    allowTrusted?: boolean;
+    /**
+     * Alias for allowTrusted.
+     */
+    allowHydration?: boolean;
+    /**
+     * @deprecated Use allowTrusted instead.
+     */
+    allowUntrusted?: boolean;
+    validate?: (snapshot: Snapshot) => boolean;
+    onValidationError?: (error: unknown, snapshot: Snapshot) => boolean;
+};
+type HydrationTrust<Snapshot extends object> = (HydrationTrustBase<Snapshot> & {
+    allowTrusted: true;
+}) | (HydrationTrustBase<Snapshot> & {
+    allowHydration: true;
+}) | (HydrationTrustBase<Snapshot> & {
+    allowUntrusted: true;
+}) | (HydrationTrustBase<Snapshot> & {
+    validate: (snapshot: Snapshot) => boolean;
+});
+export declare const hydrateStores: <Snapshot extends object = HydrateSnapshot>(snapshot: Snapshot, options: HydrateOptions<Snapshot> | undefined, trust: HydrationTrust<Snapshot>) => HydrationResult;
+export {};

package/dist/types/core/store-hydrate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module store-hydrate
+ *
+ * LAYER: Store runtime
+ * OWNS:  Public hydrateStores export.
+ *
+ * Consumers: store-write barrel.
+ */
+export { hydrateStores } from "./store-hydrate-impl.js";

package/dist/types/core/store-lifecycle/hooks.d.ts

@@ -0,0 +1,19 @@
+import { MIDDLEWARE_ABORT } from "../../features/lifecycle.js";
+import { type FeatureHookContext } from "../../features/feature-registry.js";
+import type { NormalizedOptions } from "../../adapters/options.js";
+import type { StoreValue } from "./types.js";
+export declare const clearFeatureContexts: () => void;
+export declare const createBaseFeatureContext: (name: string) => FeatureHookContext | null;
+export declare const runFeatureCreateHooks: (name: string, notify: (name: string) => void) => void;
+export declare const runFeatureWriteHooks: (name: string, action: string, prev: StoreValue, next: StoreValue, notify: (name: string) => void) => void;
+export declare const runFeatureDeleteHooks: (name: string, prev: StoreValue, notify: (name: string) => void) => void;
+export declare const runMiddlewareForStore: (name: string, payload: {
+    action: string;
+    prev: StoreValue;
+    next: StoreValue;
+    path: unknown;
+    correlationId?: string;
+    traceContext?: import("../../types/utility.js").TraceContext;
+}) => StoreValue | typeof MIDDLEWARE_ABORT;
+export declare const runStoreHookSafe: (name: string, label: "onCreate" | "onSet" | "onReset" | "onDelete", fn: ((...args: any[]) => void) | undefined, args: any[]) => void;
+export declare const resolveFeatureAvailability: (name: string, options: NormalizedOptions) => NormalizedOptions;

package/dist/types/{store-lifecycle → core/store-lifecycle}/identity.d.ts

@@ -1,5 +1,5 @@
-import { type IssueSeverity, type IssueVisibility } from "../internals/reporting.js";
-import type { FeatureName } from "../feature-registry.js";
+import { type IssueSeverity, type IssueVisibility } from "../../internals/reporting.js";
+import type { FeatureName } from "../../features/feature-registry.js";
 import type { StoreDefinition } from "./types.js";
 export declare const getSsrWarningIssued: (name?: string) => boolean;
 export declare const markSsrWarningIssued: (name: string) => void;
@@ -20,4 +20,4 @@ export declare const reportStoreCreationWarning: (message: string, onError?: (me
 export declare const reportStoreError: (name: string, message: string) => void;
 export declare const reportStoreCreationError: (message: string, onError?: (message: string) => void) => void;
 export declare const warnMissingFeature: (storeName: string, featureName: FeatureName, onError?: (message: string) => void) => void;
-export declare const getFeatureApi: (name: FeatureName) => import("../feature-registry.js").DevtoolsFeatureApi | undefined;
+export declare const getFeatureApi: (name: FeatureName) => import("../../features/feature-registry.js").DevtoolsFeatureApi | undefined;

package/dist/types/{store-lifecycle → core/store-lifecycle}/registry.d.ts

@@ -1,11 +1,22 @@
-import { getStoreRegistry, type StoreRegistry } from "../store-registry.js";
-import { type FeatureName, type StoreFeatureRuntime, type StoreFeatureMeta } from "../feature-registry.js";
-import { createStoreAdmin } from "../internals/store-admin.js";
+/**
+ * @module store-lifecycle/registry
+ *
+ * LAYER: Store lifecycle
+ * OWNS:  Module-level behavior and exports for store-lifecycle/registry.
+ *
+ * Consumers: Internal imports and public API.
+ */
+import { getStoreRegistry, type StoreRegistry, type StoreLifecycleEvent, type StoreLifecycleListener } from "../store-registry.js";
+import { type FeatureName, type StoreFeatureRuntime, type StoreFeatureMeta } from "../../features/feature-registry.js";
+import { createStoreAdmin } from "../../internals/store-admin.js";
 import type { StoreValue, Subscriber } from "./types.js";
 export { defaultRegistryScope } from "../store-registry.js";
+export type { StoreLifecycleEvent } from "../store-registry.js";
 export declare const setRegistryContext: (scope: string, registry: StoreRegistry) => void;
 export declare const getRegistry: () => StoreRegistry;
-export declare const setPathCacheInvalidator: (fn: (name: string) => void) => void;
+export declare const onStoreLifecycle: (fn: StoreLifecycleListener | null) => (() => void);
+export declare const emitStoreLifecycle: (registry: StoreRegistry, event: StoreLifecycleEvent) => void;
+export declare function setPathCacheInvalidator(fn: (name: string) => void): void;
 export declare const stores: Record<string, unknown>;
 export declare const subscribers: Record<string, Set<Subscriber>>;
 export declare const initialStates: Record<string, unknown>;
@@ -14,8 +25,10 @@ export declare const meta: Record<string, StoreFeatureMeta>;
 export declare const snapshotCache: Record<string, {
     version: number;
     snapshot: StoreValue | null;
+    source?: StoreValue | null;
+    mode?: "deep" | "shallow" | "ref";
 }>;
-export declare const featureRuntimes: Map<FeatureName, StoreFeatureRuntime>;
+export declare const featureRuntimes: Map<FeatureName, StoreFeatureRuntime<{}>>;
 export declare const storeAdmin: {
     deleteExistingStore: (name: string) => void;
     clearAllStores: () => string[];
@@ -25,10 +38,11 @@ export declare const storeAdmin: {
 export declare const getStoreAdmin: () => ReturnType<typeof createStoreAdmin>;
 export declare const getFeatureRuntime: (name: FeatureName) => StoreFeatureRuntime | undefined;
 export declare const initializeRegisteredFeatureRuntimes: () => void;
-export declare const hasStoreEntryInternal: (name: string) => boolean;
-export declare const getStoreValueRef: (name: string) => StoreValue | undefined;
-export declare const setStoreValueInternal: (name: string, value: StoreValue) => void;
+export declare const hasStoreEntryInternal: (name: string, registry?: StoreRegistry) => boolean;
+export declare const getStoreValueRef: (name: string, registry?: StoreRegistry) => StoreValue | undefined;
+export declare const setStoreValueInternal: (name: string, value: StoreValue, registry?: StoreRegistry) => void;
 export declare const applyFeatureState: (name: string, value: StoreValue, updatedAtMs?: number) => void;
+export declare const recordStoreRead: (name: string, registry?: StoreRegistry) => void;
 export declare const clearAllRegistries: () => void;
 export declare const resetFeaturesForTests: () => void;
 export declare const getMetaEntry: (name: string) => StoreFeatureMeta | undefined;

package/dist/types/{store-lifecycle → core/store-lifecycle}/types.d.ts

@@ -1,3 +1,11 @@
+/**
+ * @module store-lifecycle/types
+ *
+ * LAYER: Store lifecycle
+ * OWNS:  Module-level behavior and exports for store-lifecycle/types.
+ *
+ * Consumers: Internal imports and public API.
+ */
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 type PathInternal<T, Depth extends number> = Depth extends 0 ? never : T extends Primitive ? never : {
@@ -10,6 +18,26 @@ export type PartialDeep<T> = T extends Primitive ? T : unknown extends T ? T : {
     [K in keyof T]?: PartialDeep<T[K]>;
 };
 export type StoreValue = unknown;
+export type HydrateSnapshotFor<Map extends object> = Partial<{
+    [K in keyof Map & string]: Map[K];
+}>;
+export type HydrationFailureReason = "invalid-name" | "create-failed" | "merge-failed";
+export type HydrationFailure = {
+    name: string;
+    reason: HydrationFailureReason;
+    cause?: unknown;
+    received?: unknown;
+};
+export type HydrationBlockReason = "transaction" | "untrusted" | "validation-error" | "validation-failed";
+export type HydrationResult = {
+    hydrated: string[];
+    created: string[];
+    failed: HydrationFailure[];
+    blocked?: {
+        reason: HydrationBlockReason;
+        cause?: unknown;
+    };
+};
 export interface StoreStateMap {
 }
 export interface StrictStoreMap {
@@ -33,7 +61,7 @@ export type WriteResult = {
     ok: true;
 } | {
     ok: false;
-    reason: "not-found" | "validate" | "path" | "middleware" | "ssr" | "invalid-args";
+    reason: "not-found" | "validate" | "path" | "middleware" | "ssr" | "invalid-args" | "lazy-uninitialized";
 };
 export type Subscriber = (value: StoreValue | null) => void;
 export {};