@directive-run/core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Comes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @directive-run/core
+
+Constraint-driven runtime for TypeScript. Declare requirements, let the runtime resolve them.
+
+## Install
+
+```bash
+npm install @directive-run/core
+```
+
+## Usage
+
+```typescript
+import { createModule, createSystem, t } from "@directive-run/core";
+
+const counter = createModule("counter", {
+  schema: {
+    facts: { count: t.number() },
+    derivations: { doubled: t.number() },
+    events: { increment: {} },
+    requirements: {},
+  },
+  init: (facts) => {
+    facts.count = 0;
+  },
+  derive: {
+    doubled: (facts) => facts.count * 2,
+  },
+  on: {
+    increment: (facts) => {
+      facts.count += 1;
+    },
+  },
+});
+
+const system = createSystem({ module: counter });
+system.start();
+
+system.events.increment();
+console.log(system.facts.count);    // 1
+console.log(system.read("doubled")); // 2
+```
+
+## Subpath Exports
+
+| Import | Purpose |
+|--------|---------|
+| `@directive-run/core` | Core runtime, modules, systems |
+| `@directive-run/core/plugins` | Logging, devtools, persistence plugins |
+| `@directive-run/core/testing` | Mock resolvers, fake timers, assertions |
+| `@directive-run/core/migration` | Redux/Zustand/XState migration helpers |
+
+## License
+
+MIT
+
+[Full documentation](https://directive.run/docs)

package/dist/adapter-utils.cjs

@@ -0,0 +1,2 @@
+'use strict';function f(){let t=new Set;return {get isTracking(){return  true},track(e){t.add(e);},getDependencies(){return t}}}function d(t){let e=f();try{return {value:t(),deps:e.getDependencies()}}finally{}}function g(t,e,r){t[e]=r;}function m(t,e){return t[e]}function p(t,e){return {name:t,onRequirementCreated:e.onRequirementCreated?r=>e.onRequirementCreated(r.requirement):void 0,onRequirementMet:e.onRequirementResolved?r=>e.onRequirementResolved(r.requirement):void 0,onError:e.onError}}function h(t){return e=>e.type===t}function y(t){let e=new Set(t);return r=>e.has(r.type)}function x(t,e){if(t===e)return  true;if(!t||!e)return  false;let r=Object.keys(t),n=Object.keys(e);if(r.length!==n.length)return  false;for(let o of r)if(t[o]!==e[o])return  false;return  true}function w(t){let e=t.inspect();return {isSettled:t.isSettled,unmet:e.unmet,inflight:e.inflight,isWorking:e.unmet.length>0||e.inflight.length>0,hasUnmet:e.unmet.length>0,hasInflight:e.inflight.length>0}}function b(t,e){let r=null,n=null,o=0;return {throttled:((...s)=>{let i=Date.now(),c=i-o;c>=e?(o=i,t(...s)):(n=s,r||(r=setTimeout(()=>{r=null,o=Date.now(),n&&(t(...n),n=null);},e-c)));}),cleanup:()=>{r&&(clearTimeout(r),r=null),n=null;}}}function q(t,e){if(process.env.NODE_ENV!=="production"&&e==null)throw new Error(`[Directive] ${t}() requires a system instance as the first argument. Received ${e}.`)}function v(t,e){return Object.is(t,e)}function A(t){let e=t.debug;if(!e)return null;let r=e.snapshots.map(n=>({id:n.id,timestamp:n.timestamp,trigger:n.trigger}));return {canUndo:e.currentIndex>0,canRedo:e.currentIndex<e.snapshots.length-1,undo:()=>e.goBack(),redo:()=>e.goForward(),currentIndex:e.currentIndex,totalSnapshots:e.snapshots.length,snapshots:r,getSnapshotFacts:n=>{let o=e.snapshots.find(a=>a.id===n);return o?o.facts:null},goTo:n=>e.goTo(n),goBack:n=>e.goBack(n),goForward:n=>e.goForward(n),replay:()=>e.replay(),exportSession:()=>e.export(),importSession:n=>e.import(n),beginChangeset:n=>e.beginChangeset(n),endChangeset:()=>e.endChangeset(),isPaused:e.isPaused,pause:()=>e.pause(),resume:()=>e.resume()}}function C(t,e){let r={};for(let n of e)r[n]=t.facts.$store.get(n);return r}function D(t,e,r){let n=[],o=new Proxy({},{get(s,i){if(typeof i=="string")return e.has(i)?(n.push(i),t.read(i)):t.facts.$store.get(i)},has(s,i){return typeof i!="string"?false:e.has(i)||t.facts.$store.has(i)},ownKeys(){let s=Object.keys(t.facts.$store.toObject()),i=new Set(s);for(let c of e)i.add(c);return [...i]},getOwnPropertyDescriptor(){return {configurable:true,enumerable:true,writable:true}}}),{value:a,deps:u}=d(()=>r(o));return {value:a,factKeys:Array.from(u),deriveKeys:n}}function E(t,e,r,n){let o=e.length!==t.length||e.some((u,s)=>u!==t[s]),a=n.length!==r.length||n.some((u,s)=>u!==r[s]);return o||a}exports.assertSystem=q;exports.buildTimeTravelState=A;exports.computeInspectState=w;exports.createCallbackPlugin=p;exports.createThrottle=b;exports.defaultEquality=v;exports.depsChanged=E;exports.getBridgeFact=m;exports.pickFacts=C;exports.requirementGuard=h;exports.requirementGuardMultiple=y;exports.runTrackedSelector=D;exports.setBridgeFact=g;exports.shallowEqual=x;//# sourceMappingURL=adapter-utils.cjs.map
+//# sourceMappingURL=adapter-utils.cjs.map

package/dist/adapter-utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/tracking.ts","../src/core/types/adapter-utils.ts","../src/utils/utils.ts","../src/adapter-utils.ts"],"names":["createTrackingContext","dependencies","key","withTracking","fn","context","setBridgeFact","facts","value","getBridgeFact","createCallbackPlugin","name","callbacks","req","requirementGuard","type","requirementGuardMultiple","types","typeSet","shallowEqual","a","b","keysA","keysB","computeInspectState","system","inspection","createThrottle","callback","ms","timeoutId","lastArgs","lastCallTime","args","now","timeSinceLastCall","assertSystem","hookName","defaultEquality","buildTimeTravelState","debug","snapshots","s","id","snap","snapshotId","steps","json","label","pickFacts","keys","result","runTrackedSelector","deriveKeySet","selector","accessedDeriveKeys","stateProxy","_","prop","factKeys","combined","k","deps","depsChanged","prevFacts","newFacts","prevDerived","newDerived","factsChanged","i","derivedChanged"],"mappings":"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","file":"adapter-utils.cjs","sourcesContent":["/**\n * Dependency tracking context for auto-tracking derivations\n *\n * Uses a stack-based approach to handle nested derivation computations.\n * When a derivation accesses a fact, the tracking context records it.\n */\n\nimport type { TrackingContext } from \"./types.js\";\n\n/** Stack of active tracking contexts */\nconst trackingStack: TrackingContext[] = [];\n\n/** Create a new tracking context */\nfunction createTrackingContext(): TrackingContext {\n\tconst dependencies = new Set<string>();\n\n\treturn {\n\t\tget isTracking() {\n\t\t\treturn true;\n\t\t},\n\t\ttrack(key: string) {\n\t\t\tdependencies.add(key);\n\t\t},\n\t\tgetDependencies() {\n\t\t\treturn dependencies;\n\t\t},\n\t};\n}\n\n/** Null tracking context when not tracking */\nconst nullContext: TrackingContext = {\n\tisTracking: false,\n\ttrack() {},\n\tgetDependencies() {\n\t\treturn new Set();\n\t},\n};\n\n/**\n * Get the current tracking context.\n * Returns null context if no tracking is active.\n */\nexport function getCurrentTracker(): TrackingContext {\n\treturn trackingStack[trackingStack.length - 1] ?? nullContext;\n}\n\n/**\n * Check if we're currently tracking dependencies.\n */\nexport function isTracking(): boolean {\n\treturn trackingStack.length > 0;\n}\n\n/**\n * Run a function with dependency tracking.\n * Returns the computed value and the set of dependencies accessed.\n */\nexport function withTracking<T>(fn: () => T): { value: T; deps: Set<string> } {\n\tconst context = createTrackingContext();\n\ttrackingStack.push(context);\n\n\ttry {\n\t\tconst value = fn();\n\t\treturn { value, deps: context.getDependencies() };\n\t} finally {\n\t\ttrackingStack.pop();\n\t}\n}\n\n/**\n * Run a function without tracking.\n * Useful for reading facts without creating dependencies.\n */\nexport function withoutTracking<T>(fn: () => T): T {\n\t// Temporarily clear the stack\n\tconst saved = trackingStack.splice(0, trackingStack.length);\n\n\ttry {\n\t\treturn fn();\n\t} finally {\n\t\t// Restore the stack\n\t\ttrackingStack.push(...saved);\n\t}\n}\n\n/**\n * Track a specific key in the current context.\n * No-op if not currently tracking.\n */\nexport function trackAccess(key: string): void {\n\tgetCurrentTracker().track(key);\n}\n","/**\n * Adapter Type Utilities - Shared types and helpers for framework adapters\n *\n * These utilities reduce type assertions in adapters by providing:\n * - Schema composition types\n * - Constraint/resolver converters\n * - Plugin factory helpers\n */\n\nimport type { Schema, InferSchema } from \"./schema.js\";\nimport type { Facts } from \"./facts.js\";\nimport type { Requirement, ConstraintDef } from \"./requirements.js\";\nimport type { ResolverDef, ResolverContext } from \"./resolvers.js\";\nimport type { Plugin } from \"./plugins.js\";\n\n// ============================================================================\n// Schema Composition Types\n// ============================================================================\n\n/**\n * Merge two schemas into one.\n * Useful for adapters that add bridge-specific facts to user schemas.\n *\n * @example\n * ```typescript\n * type BridgeFields = { __state: SchemaType<Record<string, unknown>> };\n * type Combined = MergedSchema<UserSchema, BridgeFields>;\n * ```\n */\nexport type MergedSchema<\n\tBase extends Schema,\n\tExtra extends Schema,\n> = Base & Extra;\n\n/**\n * Create a schema type from a fields definition.\n * Helper for defining adapter bridge schemas.\n *\n * @example\n * ```typescript\n * type AdapterBridgeSchema = BridgeSchema<{\n *   __adapterState: SchemaType<Record<string, unknown>>;\n * }>;\n * ```\n */\nexport type BridgeSchema<Fields extends Schema> = Fields;\n\n// ============================================================================\n// Bridge Schema Helper\n// ============================================================================\n\n/**\n * Create a bridge schema definition for adapters.\n * Returns a schema object compatible with createModule().\n *\n * @example\n * ```typescript\n * const bridgeSchema = createBridgeSchema({\n *   __state: t.object<Record<string, unknown>>(),\n * });\n * ```\n */\nexport function createBridgeSchema<S extends Schema>(schema: S): S {\n\treturn schema;\n}\n\n// ============================================================================\n// Type-Safe Fact Mutation\n// ============================================================================\n\n/**\n * Type-safe fact setter for known schema keys.\n * Use when you have a typed schema and want to set a specific fact.\n *\n * @example\n * ```typescript\n * setFact(facts, \"count\", 10); // Type-checked\n * ```\n */\nexport function setFact<S extends Schema, K extends keyof InferSchema<S>>(\n\tfacts: Facts<S>,\n\tkey: K,\n\tvalue: InferSchema<S>[K],\n): void {\n\t(facts as Record<string, unknown>)[key as string] = value;\n}\n\n/**\n * Set a bridge fact without strict typing.\n * Use for adapter-internal bridge fields like `__adapterState`.\n *\n * @example\n * ```typescript\n * setBridgeFact(facts, \"__adapterState\", currentState);\n * ```\n */\nexport function setBridgeFact<V>(\n\tfacts: Facts<Schema>,\n\tkey: string,\n\tvalue: V,\n): void {\n\t(facts as Record<string, unknown>)[key] = value;\n}\n\n/**\n * Get a bridge fact without strict typing.\n * Use for adapter-internal bridge fields.\n *\n * @example\n * ```typescript\n * const state = getBridgeFact<MyState>(facts, \"__adapterState\");\n * ```\n */\nexport function getBridgeFact<V>(\n\tfacts: Facts<Schema>,\n\tkey: string,\n): V {\n\treturn (facts as Record<string, unknown>)[key] as V;\n}\n\n// ============================================================================\n// Constraint Converters\n// ============================================================================\n\n/**\n * Adapter constraint definition (generic form used by adapters).\n */\nexport interface AdapterConstraint<TState> {\n\twhen: (state: TState) => boolean | Promise<boolean>;\n\trequire: Requirement | ((state: TState) => Requirement | null);\n\tpriority?: number;\n}\n\n/**\n * Convert adapter-style constraints to Directive format.\n * Maps adapter constraints that work with external state (TState) to\n * Directive constraints that work with Facts<Schema>.\n *\n * @param constraints - Adapter constraints keyed by name\n * @param extractState - Function to extract adapter state from facts\n *\n * @example\n * ```typescript\n * const directiveConstraints = convertConstraints<MyState, BridgeSchema>(\n *   adapterConstraints,\n *   (facts) => getBridgeFact<MyState>(facts, \"__state\"),\n * );\n * ```\n */\nexport function convertConstraints<TState, S extends Schema>(\n\tconstraints: Record<string, AdapterConstraint<TState>>,\n\textractState: (facts: Facts<S>) => TState,\n): Record<string, ConstraintDef<S, Requirement>> {\n\tconst result: Record<string, ConstraintDef<S, Requirement>> = {};\n\n\tfor (const [id, constraint] of Object.entries(constraints)) {\n\t\tresult[id] = {\n\t\t\tpriority: constraint.priority ?? 0,\n\t\t\twhen: (facts) => constraint.when(extractState(facts)),\n\t\t\trequire: (facts) => {\n\t\t\t\tconst req = typeof constraint.require === \"function\"\n\t\t\t\t\t? constraint.require(extractState(facts))\n\t\t\t\t\t: constraint.require;\n\t\t\t\treturn req;\n\t\t\t},\n\t\t};\n\t}\n\n\treturn result;\n}\n\n// ============================================================================\n// Resolver Converters\n// ============================================================================\n\n/**\n * Adapter resolver context (generic form used by adapters).\n */\nexport interface AdapterResolverContext<TContext> {\n\tcontext: TContext;\n\tsignal: AbortSignal;\n}\n\n/**\n * Adapter resolver definition (generic form used by adapters).\n */\nexport interface AdapterResolver<TContext, R extends Requirement = Requirement> {\n\trequirement: (req: Requirement) => req is R;\n\tkey?: (req: R) => string;\n\tresolve: (req: R, ctx: AdapterResolverContext<TContext>) => void | Promise<void>;\n}\n\n/**\n * Convert adapter-style resolvers to Directive format.\n * Maps adapter resolvers that work with external context (TContext) to\n * Directive resolvers that work with ResolverContext<Schema>.\n *\n * @param resolvers - Adapter resolvers keyed by name\n * @param createContext - Function to create adapter context from Directive context\n *\n * @example\n * ```typescript\n * const directiveResolvers = convertResolvers<MyContext, BridgeSchema>(\n *   adapterResolvers,\n *   (ctx) => ({\n *     getState: () => getBridgeFact<MyState>(ctx.facts, \"__state\"),\n *     setState: (update) => setBridgeFact(ctx.facts, \"__state\", update),\n *     signal: ctx.signal,\n *   }),\n * );\n * ```\n */\nexport function convertResolvers<TContext, S extends Schema>(\n\tresolvers: Record<string, AdapterResolver<TContext, Requirement>>,\n\tcreateContext: (ctx: ResolverContext<S>) => TContext,\n): Record<string, ResolverDef<S, Requirement>> {\n\tconst result: Record<string, ResolverDef<S, Requirement>> = {};\n\n\tfor (const [id, resolver] of Object.entries(resolvers)) {\n\t\tresult[id] = {\n\t\t\trequirement: resolver.requirement,\n\t\t\tkey: resolver.key,\n\t\t\tresolve: async (req, ctx) => {\n\t\t\t\tconst adapterCtx = createContext(ctx);\n\t\t\t\tawait resolver.resolve(req, { context: adapterCtx, signal: ctx.signal });\n\t\t\t},\n\t\t};\n\t}\n\n\treturn result;\n}\n\n// ============================================================================\n// Plugin Factory\n// ============================================================================\n\n/**\n * Callback definitions for adapter plugins.\n */\nexport interface AdapterCallbacks {\n\tonRequirementCreated?: (req: Requirement) => void;\n\tonRequirementResolved?: (req: Requirement) => void;\n\tonError?: (error: Error) => void;\n}\n\n/**\n * Create a callback plugin for adapter events.\n * Wraps adapter callbacks in a Directive plugin.\n *\n * @param name - Plugin name (for debugging)\n * @param callbacks - Callback functions to invoke\n *\n * @example\n * ```typescript\n * const callbackPlugin = createCallbackPlugin(\"adapter-callbacks\", {\n *   onRequirementCreated: (req) => console.log(\"Created:\", req),\n *   onRequirementResolved: (req) => console.log(\"Resolved:\", req),\n * });\n * ```\n */\n// biome-ignore lint/suspicious/noExplicitAny: Plugins work with any schema type\nexport function createCallbackPlugin(\n\tname: string,\n\tcallbacks: AdapterCallbacks,\n): Plugin<any> {\n\treturn {\n\t\tname,\n\t\tonRequirementCreated: callbacks.onRequirementCreated\n\t\t\t? (req) => callbacks.onRequirementCreated!(req.requirement)\n\t\t\t: undefined,\n\t\tonRequirementMet: callbacks.onRequirementResolved\n\t\t\t? (req) => callbacks.onRequirementResolved!(req.requirement)\n\t\t\t: undefined,\n\t\tonError: callbacks.onError,\n\t};\n}\n\n// ============================================================================\n// Module Config Helpers\n// ============================================================================\n\n/**\n * Cast constraints to the correct type for createModule.\n * Use this when TypeScript can't infer the constraint types correctly.\n */\nexport function asConstraints<S extends Schema>(\n\tconstraints: Record<string, ConstraintDef<S, Requirement>>,\n): Record<string, ConstraintDef<S, Requirement>> {\n\treturn constraints;\n}\n\n/**\n * Cast resolvers to the correct type for createModule.\n * Use this when TypeScript can't infer the resolver types correctly.\n */\nexport function asResolvers<S extends Schema>(\n\tresolvers: Record<string, ResolverDef<S, Requirement>>,\n): Record<string, ResolverDef<S, Requirement>> {\n\treturn resolvers;\n}\n\n// ============================================================================\n// Type Guards\n// ============================================================================\n\n/**\n * Create a type guard for a specific requirement type.\n * Simplifies the common pattern of checking req.type.\n *\n * @example\n * ```typescript\n * const isResetReq = requirementGuard<ResetReq>(\"RESET\");\n * // Use in resolver:\n * { requirement: isResetReq, resolve: ... }\n * ```\n */\nexport function requirementGuard<R extends Requirement>(\n\ttype: R[\"type\"],\n): (req: Requirement) => req is R {\n\treturn (req): req is R => req.type === type;\n}\n\n/**\n * Create a type guard that matches multiple requirement types.\n *\n * @example\n * ```typescript\n * const isDataReq = requirementGuardMultiple<FetchReq | RefreshReq>([\"FETCH\", \"REFRESH\"]);\n * ```\n */\nexport function requirementGuardMultiple<R extends Requirement>(\n\ttypes: Array<R[\"type\"]>,\n): (req: Requirement) => req is R {\n\tconst typeSet = new Set(types);\n\treturn (req): req is R => typeSet.has(req.type);\n}\n","/**\n * Shared utilities for Directive\n */\n\n/**\n * Execute a promise with a timeout, properly cleaning up the timer.\n * Used by both constraints and resolvers for timeout handling.\n *\n * @param promise - The promise to wrap with a timeout\n * @param ms - Timeout duration in milliseconds\n * @param errorMessage - Error message if timeout occurs\n * @returns The promise result\n * @throws Error if timeout is exceeded\n */\nexport async function withTimeout<T>(\n\tpromise: Promise<T>,\n\tms: number,\n\terrorMessage: string,\n): Promise<T> {\n\tlet timeoutId: ReturnType<typeof setTimeout>;\n\n\tconst timeoutPromise = new Promise<never>((_, reject) => {\n\t\ttimeoutId = setTimeout(() => reject(new Error(errorMessage)), ms);\n\t});\n\n\ttry {\n\t\treturn await Promise.race([promise, timeoutPromise]);\n\t} finally {\n\t\tclearTimeout(timeoutId!);\n\t}\n}\n\n/**\n * Normalize an error to an Error instance.\n * Ensures consistent error handling throughout the library.\n *\n * @param error - The error to normalize (can be anything)\n * @returns An Error instance\n */\nexport function normalizeError(error: unknown): Error {\n\tif (error instanceof Error) {\n\t\treturn error;\n\t}\n\treturn new Error(String(error));\n}\n\n/**\n * Create a stable JSON string with sorted keys.\n * Handles circular references and deeply nested objects safely.\n *\n * @param value - The value to stringify\n * @param maxDepth - Maximum nesting depth (default: 50)\n * @returns A stable JSON string\n */\nexport function stableStringify(value: unknown, maxDepth = 50): string {\n\tconst seen = new WeakSet();\n\n\tfunction stringify(val: unknown, depth: number): string {\n\t\tif (depth > maxDepth) {\n\t\t\treturn '\"[max depth exceeded]\"';\n\t\t}\n\n\t\tif (val === null) return \"null\";\n\t\tif (val === undefined) return \"undefined\";\n\n\t\tconst type = typeof val;\n\n\t\tif (type === \"string\") return JSON.stringify(val);\n\t\tif (type === \"number\" || type === \"boolean\") return String(val);\n\t\tif (type === \"function\") return '\"[function]\"';\n\t\tif (type === \"symbol\") return '\"[symbol]\"';\n\n\t\tif (Array.isArray(val)) {\n\t\t\t// Check for circular reference\n\t\t\tif (seen.has(val)) {\n\t\t\t\treturn '\"[circular]\"';\n\t\t\t}\n\t\t\tseen.add(val);\n\t\t\tconst result = `[${val.map((v) => stringify(v, depth + 1)).join(\",\")}]`;\n\t\t\tseen.delete(val);\n\t\t\treturn result;\n\t\t}\n\n\t\tif (type === \"object\") {\n\t\t\tconst obj = val as Record<string, unknown>;\n\t\t\t// Check for circular reference\n\t\t\tif (seen.has(obj)) {\n\t\t\t\treturn '\"[circular]\"';\n\t\t\t}\n\t\t\tseen.add(obj);\n\t\t\tconst keys = Object.keys(obj).sort();\n\t\t\tconst pairs = keys.map((k) => `${JSON.stringify(k)}:${stringify(obj[k], depth + 1)}`);\n\t\t\tconst result = `{${pairs.join(\",\")}}`;\n\t\t\tseen.delete(obj);\n\t\t\treturn result;\n\t\t}\n\n\t\treturn '\"[unknown]\"';\n\t}\n\n\treturn stringify(value, 0);\n}\n\n/**\n * Check for prototype pollution in an object, including nested objects.\n * Returns true if the object is safe, false if dangerous keys are found.\n *\n * @param obj - The object to check\n * @param maxDepth - Maximum nesting depth to check (default: 50)\n * @returns True if safe, false if dangerous keys found\n */\nexport function isPrototypeSafe(obj: unknown, maxDepth = 50): boolean {\n\tconst dangerousKeys = new Set([\"__proto__\", \"constructor\", \"prototype\"]);\n\tconst seen = new WeakSet();\n\n\tfunction check(val: unknown, depth: number): boolean {\n\t\tif (depth > maxDepth) return false; // Fail safe at max depth - don't assume safety\n\t\tif (val === null || val === undefined) return true;\n\t\tif (typeof val !== \"object\") return true;\n\n\t\tconst objVal = val as Record<string, unknown>;\n\n\t\t// Check for circular reference\n\t\tif (seen.has(objVal)) return true;\n\t\tseen.add(objVal);\n\n\t\t// Check array elements\n\t\tif (Array.isArray(objVal)) {\n\t\t\tfor (const item of objVal) {\n\t\t\t\tif (!check(item, depth + 1)) {\n\t\t\t\t\tseen.delete(objVal);\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t}\n\t\t\tseen.delete(objVal);\n\t\t\treturn true;\n\t\t}\n\n\t\t// Check object keys and values\n\t\tfor (const key of Object.keys(objVal)) {\n\t\t\tif (dangerousKeys.has(key)) {\n\t\t\t\tseen.delete(objVal);\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tif (!check(objVal[key], depth + 1)) {\n\t\t\t\tseen.delete(objVal);\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\n\t\tseen.delete(objVal);\n\t\treturn true;\n\t}\n\n\treturn check(obj, 0);\n}\n\n/**\n * Shallow equality comparison for objects.\n * Used by React hooks to avoid unnecessary re-renders.\n *\n * @param a - First object\n * @param b - Second object\n * @returns True if objects are shallowly equal\n */\nexport function shallowEqual<T extends Record<string, unknown>>(a: T, b: T): boolean {\n\tif (a === b) return true;\n\tif (!a || !b) return false;\n\n\tconst keysA = Object.keys(a);\n\tconst keysB = Object.keys(b);\n\n\tif (keysA.length !== keysB.length) return false;\n\n\tfor (const key of keysA) {\n\t\tif (a[key] !== b[key]) return false;\n\t}\n\n\treturn true;\n}\n\n/**\n * Generate a simple hash string from an object.\n * Uses djb2 algorithm on the stable stringified value.\n *\n * **Limitations:**\n * - 32-bit hash output means collision probability increases with data set size\n *   (birthday paradox: ~50% collision chance at ~77,000 distinct values)\n * - Suitable for: cache invalidation, change detection, deduplication of small sets\n * - NOT suitable for: cryptographic use, security-sensitive operations, large-scale deduplication\n *\n * For security-sensitive use cases requiring stronger collision resistance,\n * consider using a cryptographic hash like SHA-256.\n *\n * @param value - The value to hash\n * @returns A hex hash string (8 characters, 32 bits)\n */\nexport function hashObject(value: unknown): string {\n\tconst str = stableStringify(value);\n\tlet hash = 5381;\n\tfor (let i = 0; i < str.length; i++) {\n\t\thash = ((hash << 5) + hash) ^ str.charCodeAt(i);\n\t}\n\t// Convert to unsigned 32-bit and then to hex\n\treturn (hash >>> 0).toString(16);\n}\n\n// ============================================================================\n// Distributable Snapshot Utilities\n// ============================================================================\n\n/**\n * Distributable snapshot type for type-safe helper functions.\n */\nexport interface DistributableSnapshotLike<T = Record<string, unknown>> {\n\tdata: T;\n\tcreatedAt: number;\n\texpiresAt?: number;\n\tversion?: string;\n\tmetadata?: Record<string, unknown>;\n}\n\n/**\n * Check if a distributable snapshot has expired.\n * Returns false if the snapshot has no expiresAt field.\n *\n * @example\n * ```typescript\n * const snapshot = system.getDistributableSnapshot({ ttlSeconds: 3600 });\n * // ... later ...\n * if (isSnapshotExpired(snapshot)) {\n *   // Refresh the snapshot\n * }\n * ```\n *\n * @param snapshot - The snapshot to check\n * @param now - Optional current timestamp (defaults to Date.now())\n * @returns True if the snapshot has expired, false otherwise\n */\nexport function isSnapshotExpired<T>(\n\tsnapshot: DistributableSnapshotLike<T>,\n\tnow: number = Date.now(),\n): boolean {\n\treturn snapshot.expiresAt !== undefined && now > snapshot.expiresAt;\n}\n\n/**\n * Validate a distributable snapshot and return its data.\n * Throws if the snapshot is malformed or has expired.\n *\n * @example\n * ```typescript\n * const cached = JSON.parse(await redis.get(`entitlements:${userId}`));\n * try {\n *   const data = validateSnapshot(cached);\n *   // Use data.canUseFeature, etc.\n * } catch (e) {\n *   // Snapshot invalid or expired, refresh it\n * }\n * ```\n *\n * @example Using custom timestamp for testing\n * ```typescript\n * const snapshot = { data: { test: true }, createdAt: 1000, expiresAt: 2000 };\n * validateSnapshot(snapshot, 1500); // Returns { test: true }\n * validateSnapshot(snapshot, 2500); // Throws: Snapshot expired\n * ```\n *\n * @param snapshot - The snapshot to validate\n * @param now - Optional current timestamp (defaults to Date.now())\n * @returns The snapshot data if valid\n * @throws Error if the snapshot is malformed or has expired\n */\nexport function validateSnapshot<T>(\n\tsnapshot: DistributableSnapshotLike<T>,\n\tnow: number = Date.now(),\n): T {\n\t// Structural validation\n\tif (!snapshot || typeof snapshot !== \"object\") {\n\t\tthrow new Error(\n\t\t\t\"[Directive] Invalid snapshot: expected an object with 'data' and 'createdAt' properties.\",\n\t\t);\n\t}\n\tif (!(\"data\" in snapshot)) {\n\t\tthrow new Error(\n\t\t\t\"[Directive] Invalid snapshot: missing required 'data' property.\",\n\t\t);\n\t}\n\tif (!(\"createdAt\" in snapshot) || typeof snapshot.createdAt !== \"number\") {\n\t\tthrow new Error(\n\t\t\t\"[Directive] Invalid snapshot: missing or invalid 'createdAt' property (expected number).\",\n\t\t);\n\t}\n\n\t// Expiration validation\n\tif (isSnapshotExpired(snapshot, now)) {\n\t\tconst expiredAt = new Date(snapshot.expiresAt!).toISOString();\n\t\tthrow new Error(\n\t\t\t`[Directive] Snapshot expired at ${expiredAt}. Obtain a fresh snapshot from the source.`,\n\t\t);\n\t}\n\treturn snapshot.data;\n}\n\n/**\n * Diff result for a single changed value.\n */\nexport interface SnapshotDiffEntry {\n\t/** The key path that changed (e.g., \"canUseApi\" or \"limits.apiCalls\") */\n\tpath: string;\n\t/** The value in the old snapshot */\n\toldValue: unknown;\n\t/** The value in the new snapshot */\n\tnewValue: unknown;\n\t/** Type of change: \"added\", \"removed\", or \"changed\" */\n\ttype: \"added\" | \"removed\" | \"changed\";\n}\n\n/**\n * Result of diffing two snapshots.\n */\nexport interface SnapshotDiff {\n\t/** Whether the snapshots are identical */\n\tidentical: boolean;\n\t/** List of changes between snapshots */\n\tchanges: SnapshotDiffEntry[];\n\t/** Whether the version changed (if both have versions) */\n\tversionChanged: boolean;\n\t/** Old version (if available) */\n\toldVersion?: string;\n\t/** New version (if available) */\n\tnewVersion?: string;\n}\n\n/**\n * Compare two distributable snapshots and return the differences.\n * Useful for debugging, audit logs, and webhook payloads.\n *\n * @example\n * ```typescript\n * const oldSnapshot = system.getDistributableSnapshot({ includeVersion: true });\n * system.dispatch({ type: \"upgradePlan\", plan: \"pro\" });\n * const newSnapshot = system.getDistributableSnapshot({ includeVersion: true });\n *\n * const diff = diffSnapshots(oldSnapshot, newSnapshot);\n * if (!diff.identical) {\n *   console.log(\"Changes:\", diff.changes);\n *   // [{ path: \"canUseApi\", oldValue: false, newValue: true, type: \"changed\" }]\n * }\n * ```\n *\n * @param oldSnapshot - The previous snapshot\n * @param newSnapshot - The new snapshot\n * @returns A diff result with all changes\n */\nexport function diffSnapshots<T = Record<string, unknown>>(\n\toldSnapshot: DistributableSnapshotLike<T>,\n\tnewSnapshot: DistributableSnapshotLike<T>,\n): SnapshotDiff {\n\tconst changes: SnapshotDiffEntry[] = [];\n\n\t// Deep compare function\n\tfunction compare(\n\t\toldObj: unknown,\n\t\tnewObj: unknown,\n\t\tpath: string,\n\t): void {\n\t\t// Handle null/undefined\n\t\tif (oldObj === null || oldObj === undefined) {\n\t\t\tif (newObj !== null && newObj !== undefined) {\n\t\t\t\tchanges.push({ path, oldValue: oldObj, newValue: newObj, type: \"added\" });\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t\tif (newObj === null || newObj === undefined) {\n\t\t\tchanges.push({ path, oldValue: oldObj, newValue: newObj, type: \"removed\" });\n\t\t\treturn;\n\t\t}\n\n\t\t// Handle primitives\n\t\tif (typeof oldObj !== \"object\" || typeof newObj !== \"object\") {\n\t\t\tif (!Object.is(oldObj, newObj)) {\n\t\t\t\tchanges.push({ path, oldValue: oldObj, newValue: newObj, type: \"changed\" });\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// Handle arrays\n\t\tif (Array.isArray(oldObj) && Array.isArray(newObj)) {\n\t\t\tif (oldObj.length !== newObj.length) {\n\t\t\t\tchanges.push({ path, oldValue: oldObj, newValue: newObj, type: \"changed\" });\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tfor (let i = 0; i < oldObj.length; i++) {\n\t\t\t\tcompare(oldObj[i], newObj[i], `${path}[${i}]`);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\t// Handle objects\n\t\tconst oldRecord = oldObj as Record<string, unknown>;\n\t\tconst newRecord = newObj as Record<string, unknown>;\n\t\tconst allKeys = new Set([...Object.keys(oldRecord), ...Object.keys(newRecord)]);\n\n\t\tfor (const key of allKeys) {\n\t\t\tconst childPath = path ? `${path}.${key}` : key;\n\t\t\tif (!(key in oldRecord)) {\n\t\t\t\tchanges.push({ path: childPath, oldValue: undefined, newValue: newRecord[key], type: \"added\" });\n\t\t\t} else if (!(key in newRecord)) {\n\t\t\t\tchanges.push({ path: childPath, oldValue: oldRecord[key], newValue: undefined, type: \"removed\" });\n\t\t\t} else {\n\t\t\t\tcompare(oldRecord[key], newRecord[key], childPath);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Compare data\n\tcompare(oldSnapshot.data, newSnapshot.data, \"\");\n\n\t// Check version change\n\tconst versionChanged = oldSnapshot.version !== newSnapshot.version &&\n\t\t(oldSnapshot.version !== undefined || newSnapshot.version !== undefined);\n\n\treturn {\n\t\tidentical: changes.length === 0,\n\t\tchanges,\n\t\tversionChanged,\n\t\toldVersion: oldSnapshot.version,\n\t\tnewVersion: newSnapshot.version,\n\t};\n}\n\n// ============================================================================\n// Snapshot Signing (HMAC)\n// ============================================================================\n\n/**\n * A signed distributable snapshot.\n * Contains the original snapshot plus a cryptographic signature.\n */\nexport interface SignedSnapshot<T = Record<string, unknown>>\n\textends DistributableSnapshotLike<T> {\n\t/** HMAC-SHA256 signature in hex format */\n\tsignature: string;\n\t/** Signing algorithm used */\n\talgorithm: \"hmac-sha256\";\n}\n\n/**\n * Check if a snapshot is signed.\n *\n * @param snapshot - The snapshot to check\n * @returns True if the snapshot has a signature\n */\nexport function isSignedSnapshot<T>(\n\tsnapshot: DistributableSnapshotLike<T> | SignedSnapshot<T>,\n): snapshot is SignedSnapshot<T> {\n\treturn \"signature\" in snapshot && typeof snapshot.signature === \"string\";\n}\n\n/**\n * Sign a distributable snapshot using HMAC-SHA256.\n * Creates a tamper-proof signature that can be verified later.\n *\n * **Security Notes:**\n * - Use a cryptographically random secret of at least 32 bytes\n * - Store the secret securely (environment variable, secrets manager)\n * - Never expose the secret to clients\n * - The signature covers all snapshot fields for integrity\n *\n * @example\n * ```typescript\n * const snapshot = system.getDistributableSnapshot({\n *   includeDerivations: ['canUseFeature', 'limits'],\n *   ttlSeconds: 3600,\n * });\n *\n * // Sign the snapshot (server-side only)\n * const signed = await signSnapshot(snapshot, process.env.SNAPSHOT_SECRET);\n *\n * // Store in JWT, Redis, or send to client\n * const jwt = createJWT({ snapshot: signed });\n *\n * // Later, verify the signature\n * const isValid = await verifySnapshotSignature(signed, process.env.SNAPSHOT_SECRET);\n * if (!isValid) {\n *   throw new Error('Snapshot has been tampered with');\n * }\n * ```\n *\n * @param snapshot - The snapshot to sign\n * @param secret - The HMAC secret (string or Uint8Array)\n * @returns A signed snapshot with the signature attached\n */\nexport async function signSnapshot<T>(\n\tsnapshot: DistributableSnapshotLike<T>,\n\tsecret: string | Uint8Array,\n): Promise<SignedSnapshot<T>> {\n\t// Create a canonical representation for signing\n\tconst payload = stableStringify({\n\t\tdata: snapshot.data,\n\t\tcreatedAt: snapshot.createdAt,\n\t\texpiresAt: snapshot.expiresAt,\n\t\tversion: snapshot.version,\n\t\tmetadata: snapshot.metadata,\n\t});\n\n\tconst signature = await hmacSha256(payload, secret);\n\n\treturn {\n\t\t...snapshot,\n\t\tsignature,\n\t\talgorithm: \"hmac-sha256\",\n\t};\n}\n\n/**\n * Verify the signature of a signed snapshot.\n * Returns true if the signature is valid, false otherwise.\n *\n * **Important:** Always verify signatures before trusting snapshot data,\n * especially if the snapshot was received from an untrusted source (client, cache).\n *\n * @example\n * ```typescript\n * // Receive signed snapshot from client or cache\n * const snapshot = JSON.parse(cachedData);\n *\n * // Verify before using\n * const isValid = await verifySnapshotSignature(snapshot, process.env.SNAPSHOT_SECRET);\n * if (!isValid) {\n *   throw new Error('Invalid snapshot signature - possible tampering');\n * }\n *\n * // Now safe to use snapshot.data\n * if (snapshot.data.canUseFeature.api) {\n *   // Grant access\n * }\n * ```\n *\n * @param signedSnapshot - The signed snapshot to verify\n * @param secret - The HMAC secret (must match the signing secret)\n * @returns True if signature is valid, false otherwise\n */\nexport async function verifySnapshotSignature<T>(\n\tsignedSnapshot: SignedSnapshot<T>,\n\tsecret: string | Uint8Array,\n): Promise<boolean> {\n\tif (!signedSnapshot.signature || signedSnapshot.algorithm !== \"hmac-sha256\") {\n\t\treturn false;\n\t}\n\n\t// Recreate the canonical payload (same as signing)\n\tconst payload = stableStringify({\n\t\tdata: signedSnapshot.data,\n\t\tcreatedAt: signedSnapshot.createdAt,\n\t\texpiresAt: signedSnapshot.expiresAt,\n\t\tversion: signedSnapshot.version,\n\t\tmetadata: signedSnapshot.metadata,\n\t});\n\n\tconst expectedSignature = await hmacSha256(payload, secret);\n\n\t// Use timing-safe comparison\n\treturn timingSafeEqual(signedSnapshot.signature, expectedSignature);\n}\n\n/**\n * Create HMAC-SHA256 signature of a message.\n * Uses Web Crypto API for cross-platform support (Node.js, browsers, Deno, Bun).\n */\nasync function hmacSha256(\n\tmessage: string,\n\tsecret: string | Uint8Array,\n): Promise<string> {\n\t// Convert secret to Uint8Array if string\n\tconst secretBytes: Uint8Array =\n\t\ttypeof secret === \"string\" ? new TextEncoder().encode(secret) : secret;\n\n\t// Import key for HMAC\n\tconst algorithm: HmacImportParams = { name: \"HMAC\", hash: { name: \"SHA-256\" } };\n\tconst key = await crypto.subtle.importKey(\n\t\t\"raw\",\n\t\tsecretBytes as unknown as ArrayBuffer,\n\t\talgorithm,\n\t\tfalse,\n\t\t[\"sign\"],\n\t);\n\n\t// Sign the message\n\tconst messageBytes = new TextEncoder().encode(message);\n\tconst signature = await crypto.subtle.sign(\"HMAC\", key, messageBytes);\n\n\t// Convert to hex string\n\treturn Array.from(new Uint8Array(signature))\n\t\t.map((b) => b.toString(16).padStart(2, \"0\"))\n\t\t.join(\"\");\n}\n\n/**\n * Timing-safe string comparison to prevent timing attacks.\n * Both strings should be the same length (hex signatures from same algorithm).\n */\nfunction timingSafeEqual(a: string, b: string): boolean {\n\tif (a.length !== b.length) {\n\t\treturn false;\n\t}\n\n\tlet result = 0;\n\tfor (let i = 0; i < a.length; i++) {\n\t\tresult |= a.charCodeAt(i) ^ b.charCodeAt(i);\n\t}\n\treturn result === 0;\n}\n","/**\n * Shared Adapter Utilities\n *\n * Common types and helper functions used across all framework adapters.\n * @internal\n */\n\nimport type { TimeTravelState, TimeTravelAPI, SystemInspection, SnapshotMeta } from \"./core/types.js\";\nimport { withTracking } from \"./core/tracking.js\";\n\n// ============================================================================\n// SystemLike — structural type satisfied by both System and SingleModuleSystem\n// ============================================================================\n\n/**\n * Minimal structural type for shared adapter helpers.\n * Both `System<any>` and `SingleModuleSystem<any>` satisfy this interface,\n * eliminating the need for `as unknown as System<any>` casts in adapters.\n * @internal\n */\nexport interface SystemLike {\n\treadonly isSettled: boolean;\n\treadonly debug: TimeTravelAPI | null;\n\treadonly facts: {\n\t\t$store: {\n\t\t\tget(key: string): unknown;\n\t\t\thas(key: string): boolean;\n\t\t\ttoObject(): Record<string, unknown>;\n\t\t};\n\t};\n\treadonly derive?: Record<string, unknown>;\n\tread(key: string): unknown;\n\tinspect(): SystemInspection;\n}\n\n// ============================================================================\n// Requirements State\n// ============================================================================\n\n/**\n * Requirements state returned by useRequirements hooks.\n * Provides a focused view of just requirements without full inspection overhead.\n */\nexport interface RequirementsState {\n\t/** Array of unmet requirements waiting to be resolved */\n\tunmet: Array<{\n\t\tid: string;\n\t\trequirement: { type: string; [key: string]: unknown };\n\t\tfromConstraint: string;\n\t}>;\n\t/** Array of requirements currently being resolved */\n\tinflight: Array<{ id: string; resolverId: string; startedAt: number }>;\n\t/** Whether there are any unmet requirements */\n\thasUnmet: boolean;\n\t/** Whether there are any inflight requirements */\n\thasInflight: boolean;\n\t/** Whether the system is actively working (has unmet or inflight requirements) */\n\tisWorking: boolean;\n}\n\n// ============================================================================\n// Inspect State (shared across all adapters)\n// ============================================================================\n\n/**\n * Consolidated inspection state returned by useInspect hooks.\n * Identical shape across React, Vue, Svelte, Solid, and Lit adapters.\n */\nexport interface InspectState {\n\t/** Whether the system has settled (no pending operations) */\n\tisSettled: boolean;\n\t/** Array of unmet requirements */\n\tunmet: RequirementsState[\"unmet\"];\n\t/** Array of inflight requirements */\n\tinflight: RequirementsState[\"inflight\"];\n\t/** Whether the system is actively working */\n\tisWorking: boolean;\n\t/** Whether there are any unmet requirements */\n\thasUnmet: boolean;\n\t/** Whether there are any inflight requirements */\n\thasInflight: boolean;\n}\n\n/**\n * Information about a single constraint.\n */\nexport interface ConstraintInfo {\n\tid: string;\n\tactive: boolean;\n\tpriority: number;\n}\n\n/**\n * Compute InspectState from a system instance.\n * Centralizes the logic currently duplicated across adapters.\n * @internal\n */\nexport function computeInspectState(system: SystemLike): InspectState {\n\tconst inspection = system.inspect();\n\treturn {\n\t\tisSettled: system.isSettled,\n\t\tunmet: inspection.unmet,\n\t\tinflight: inspection.inflight,\n\t\tisWorking: inspection.unmet.length > 0 || inspection.inflight.length > 0,\n\t\thasUnmet: inspection.unmet.length > 0,\n\t\thasInflight: inspection.inflight.length > 0,\n\t};\n}\n\n// ============================================================================\n// Throttled Hook Options\n// ============================================================================\n\n/**\n * Options for throttled hooks.\n * Used by useInspectThrottled, useRequirementsThrottled, etc.\n */\nexport interface ThrottledHookOptions {\n\t/**\n\t * Minimum time between updates in milliseconds.\n\t * @default 100\n\t */\n\tthrottleMs?: number;\n}\n\n// ============================================================================\n// Throttle Utility\n// ============================================================================\n\n/**\n * Create a throttled version of a callback function.\n * Uses trailing-edge throttling: the callback will be called at most once per interval,\n * with the latest arguments from the most recent call.\n *\n * @param callback - The function to throttle\n * @param ms - The minimum time between calls in milliseconds\n * @returns A throttled version of the callback and a cleanup function\n * @internal\n */\nexport function createThrottle<T extends (...args: unknown[]) => void>(\n\tcallback: T,\n\tms: number,\n): { throttled: T; cleanup: () => void } {\n\tlet timeoutId: ReturnType<typeof setTimeout> | null = null;\n\tlet lastArgs: Parameters<T> | null = null;\n\tlet lastCallTime = 0;\n\n\tconst throttled = ((...args: Parameters<T>) => {\n\t\tconst now = Date.now();\n\t\tconst timeSinceLastCall = now - lastCallTime;\n\n\t\tif (timeSinceLastCall >= ms) {\n\t\t\t// Enough time has passed, call immediately\n\t\t\tlastCallTime = now;\n\t\t\tcallback(...args);\n\t\t} else {\n\t\t\t// Schedule for later, keeping latest args\n\t\t\tlastArgs = args;\n\t\t\tif (!timeoutId) {\n\t\t\t\ttimeoutId = setTimeout(() => {\n\t\t\t\t\ttimeoutId = null;\n\t\t\t\t\tlastCallTime = Date.now();\n\t\t\t\t\tif (lastArgs) {\n\t\t\t\t\t\tcallback(...lastArgs);\n\t\t\t\t\t\tlastArgs = null;\n\t\t\t\t\t}\n\t\t\t\t}, ms - timeSinceLastCall);\n\t\t\t}\n\t\t}\n\t}) as T;\n\n\tconst cleanup = () => {\n\t\tif (timeoutId) {\n\t\t\tclearTimeout(timeoutId);\n\t\t\ttimeoutId = null;\n\t\t}\n\t\tlastArgs = null;\n\t};\n\n\treturn { throttled, cleanup };\n}\n\n// ============================================================================\n// Shared Adapter Helpers\n// ============================================================================\n\n/**\n * Dev-mode assertion that the system parameter is non-null.\n * Tree-shaken in production builds.\n * @internal\n */\nexport function assertSystem(hookName: string, system: unknown): void {\n\tif (process.env.NODE_ENV !== \"production\" && system == null) {\n\t\tthrow new Error(\n\t\t\t`[Directive] ${hookName}() requires a system instance as the first argument. Received ${system}.`,\n\t\t);\n\t}\n}\n\n/** Default equality function using Object.is */\nexport function defaultEquality<T>(a: T, b: T): boolean {\n\treturn Object.is(a, b);\n}\n\n/**\n * Build a TimeTravelState object from a system's debug instance.\n * Returns null when time-travel is disabled.\n * @internal\n */\nexport function buildTimeTravelState(system: SystemLike): TimeTravelState | null {\n\tconst debug = system.debug;\n\tif (!debug) return null;\n\n\t// Build lightweight metadata array (no facts data)\n\tconst snapshots: SnapshotMeta[] = debug.snapshots.map((s) => ({\n\t\tid: s.id,\n\t\ttimestamp: s.timestamp,\n\t\ttrigger: s.trigger,\n\t}));\n\n\treturn {\n\t\t// Existing\n\t\tcanUndo: debug.currentIndex > 0,\n\t\tcanRedo: debug.currentIndex < debug.snapshots.length - 1,\n\t\tundo: () => debug.goBack(),\n\t\tredo: () => debug.goForward(),\n\t\tcurrentIndex: debug.currentIndex,\n\t\ttotalSnapshots: debug.snapshots.length,\n\n\t\t// Snapshot access\n\t\tsnapshots,\n\t\tgetSnapshotFacts: (id: number): Record<string, unknown> | null => {\n\t\t\tconst snap = debug.snapshots.find((s) => s.id === id);\n\t\t\treturn snap ? snap.facts : null;\n\t\t},\n\n\t\t// Navigation\n\t\tgoTo: (snapshotId: number) => debug.goTo(snapshotId),\n\t\tgoBack: (steps: number) => debug.goBack(steps),\n\t\tgoForward: (steps: number) => debug.goForward(steps),\n\t\treplay: () => debug.replay(),\n\n\t\t// Session persistence\n\t\texportSession: () => debug.export(),\n\t\timportSession: (json: string) => debug.import(json),\n\n\t\t// Changesets\n\t\tbeginChangeset: (label: string) => debug.beginChangeset(label),\n\t\tendChangeset: () => debug.endChangeset(),\n\n\t\t// Recording control\n\t\tisPaused: debug.isPaused,\n\t\tpause: () => debug.pause(),\n\t\tresume: () => debug.resume(),\n\t};\n}\n\n/**\n * Pick specific fact values from a system's store.\n * @internal\n */\nexport function pickFacts(system: SystemLike, keys: string[]): Record<string, unknown> {\n\tconst result: Record<string, unknown> = {};\n\tfor (const key of keys) {\n\t\tresult[key] = system.facts.$store.get(key);\n\t}\n\treturn result;\n}\n\n// ============================================================================\n// Tracked Selector\n// ============================================================================\n\n/** Result of running a selector with tracking. @internal */\nexport interface TrackedSelectorResult<R> {\n\tvalue: R;\n\tfactKeys: string[];\n\tderiveKeys: string[];\n}\n\n/**\n * Run a selector against a system with automatic dependency tracking.\n * Creates a Proxy that intercepts property access to distinguish between\n * fact reads (tracked via withTracking) and derivation reads (tracked manually).\n *\n * Used by useSelector in all framework adapters.\n * @internal\n */\nexport function runTrackedSelector<R>(\n\tsystem: SystemLike,\n\tderiveKeySet: Set<string>,\n\tselector: (state: Record<string, unknown>) => R,\n): TrackedSelectorResult<R> {\n\tconst accessedDeriveKeys: string[] = [];\n\n\tconst stateProxy = new Proxy(\n\t\t{},\n\t\t{\n\t\t\tget(_, prop: string | symbol) {\n\t\t\t\tif (typeof prop !== \"string\") return undefined;\n\t\t\t\tif (deriveKeySet.has(prop)) {\n\t\t\t\t\taccessedDeriveKeys.push(prop);\n\t\t\t\t\treturn system.read(prop);\n\t\t\t\t}\n\t\t\t\treturn system.facts.$store.get(prop);\n\t\t\t},\n\t\t\thas(_, prop: string | symbol) {\n\t\t\t\tif (typeof prop !== \"string\") return false;\n\t\t\t\treturn deriveKeySet.has(prop) || system.facts.$store.has(prop);\n\t\t\t},\n\t\t\townKeys() {\n\t\t\t\tconst factKeys = Object.keys(system.facts.$store.toObject());\n\t\t\t\tconst combined = new Set(factKeys);\n\t\t\t\tfor (const k of deriveKeySet) combined.add(k);\n\t\t\t\treturn [...combined];\n\t\t\t},\n\t\t\tgetOwnPropertyDescriptor() {\n\t\t\t\treturn { configurable: true, enumerable: true, writable: true };\n\t\t\t},\n\t\t},\n\t);\n\n\tconst { value, deps } = withTracking(() => selector(stateProxy as Record<string, unknown>));\n\treturn { value, factKeys: Array.from(deps) as string[], deriveKeys: accessedDeriveKeys };\n}\n\n/**\n * Check if tracked dependency keys have changed.\n * @internal\n */\nexport function depsChanged(\n\tprevFacts: string[],\n\tnewFacts: string[],\n\tprevDerived: string[],\n\tnewDerived: string[],\n): boolean {\n\tconst factsChanged =\n\t\tnewFacts.length !== prevFacts.length ||\n\t\tnewFacts.some((k, i) => k !== prevFacts[i]);\n\tconst derivedChanged =\n\t\tnewDerived.length !== prevDerived.length ||\n\t\tnewDerived.some((k, i) => k !== prevDerived[i]);\n\treturn factsChanged || derivedChanged;\n}\n\n// ============================================================================\n// Re-exports from core/types/adapter-utils and utils/utils\n// ============================================================================\n\nexport {\n\tsetBridgeFact,\n\tgetBridgeFact,\n\tcreateCallbackPlugin,\n\trequirementGuard,\n\trequirementGuardMultiple,\n} from \"./core/types/adapter-utils.js\";\n\n\nexport { shallowEqual } from \"./utils/utils.js\";\n"]}

package/dist/adapter-utils.d.cts

@@ -0,0 +1,230 @@
+import { R as Requirement, P as Plugin, F as Facts, S as Schema, Y as TimeTravelAPI, aE as SystemInspection, aH as TimeTravelState } from './plugins-CcwEXXMS.cjs';
+export { s as shallowEqual } from './utils-4JrY5fk9.cjs';
+
+/**
+ * Adapter Type Utilities - Shared types and helpers for framework adapters
+ *
+ * These utilities reduce type assertions in adapters by providing:
+ * - Schema composition types
+ * - Constraint/resolver converters
+ * - Plugin factory helpers
+ */
+
+/**
+ * Set a bridge fact without strict typing.
+ * Use for adapter-internal bridge fields like `__adapterState`.
+ *
+ * @example
+ * ```typescript
+ * setBridgeFact(facts, "__adapterState", currentState);
+ * ```
+ */
+declare function setBridgeFact<V>(facts: Facts<Schema>, key: string, value: V): void;
+/**
+ * Get a bridge fact without strict typing.
+ * Use for adapter-internal bridge fields.
+ *
+ * @example
+ * ```typescript
+ * const state = getBridgeFact<MyState>(facts, "__adapterState");
+ * ```
+ */
+declare function getBridgeFact<V>(facts: Facts<Schema>, key: string): V;
+/**
+ * Callback definitions for adapter plugins.
+ */
+interface AdapterCallbacks {
+    onRequirementCreated?: (req: Requirement) => void;
+    onRequirementResolved?: (req: Requirement) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a callback plugin for adapter events.
+ * Wraps adapter callbacks in a Directive plugin.
+ *
+ * @param name - Plugin name (for debugging)
+ * @param callbacks - Callback functions to invoke
+ *
+ * @example
+ * ```typescript
+ * const callbackPlugin = createCallbackPlugin("adapter-callbacks", {
+ *   onRequirementCreated: (req) => console.log("Created:", req),
+ *   onRequirementResolved: (req) => console.log("Resolved:", req),
+ * });
+ * ```
+ */
+declare function createCallbackPlugin(name: string, callbacks: AdapterCallbacks): Plugin<any>;
+/**
+ * Create a type guard for a specific requirement type.
+ * Simplifies the common pattern of checking req.type.
+ *
+ * @example
+ * ```typescript
+ * const isResetReq = requirementGuard<ResetReq>("RESET");
+ * // Use in resolver:
+ * { requirement: isResetReq, resolve: ... }
+ * ```
+ */
+declare function requirementGuard<R extends Requirement>(type: R["type"]): (req: Requirement) => req is R;
+/**
+ * Create a type guard that matches multiple requirement types.
+ *
+ * @example
+ * ```typescript
+ * const isDataReq = requirementGuardMultiple<FetchReq | RefreshReq>(["FETCH", "REFRESH"]);
+ * ```
+ */
+declare function requirementGuardMultiple<R extends Requirement>(types: Array<R["type"]>): (req: Requirement) => req is R;
+
+/**
+ * Shared Adapter Utilities
+ *
+ * Common types and helper functions used across all framework adapters.
+ * @internal
+ */
+
+/**
+ * Minimal structural type for shared adapter helpers.
+ * Both `System<any>` and `SingleModuleSystem<any>` satisfy this interface,
+ * eliminating the need for `as unknown as System<any>` casts in adapters.
+ * @internal
+ */
+interface SystemLike {
+    readonly isSettled: boolean;
+    readonly debug: TimeTravelAPI | null;
+    readonly facts: {
+        $store: {
+            get(key: string): unknown;
+            has(key: string): boolean;
+            toObject(): Record<string, unknown>;
+        };
+    };
+    readonly derive?: Record<string, unknown>;
+    read(key: string): unknown;
+    inspect(): SystemInspection;
+}
+/**
+ * Requirements state returned by useRequirements hooks.
+ * Provides a focused view of just requirements without full inspection overhead.
+ */
+interface RequirementsState {
+    /** Array of unmet requirements waiting to be resolved */
+    unmet: Array<{
+        id: string;
+        requirement: {
+            type: string;
+            [key: string]: unknown;
+        };
+        fromConstraint: string;
+    }>;
+    /** Array of requirements currently being resolved */
+    inflight: Array<{
+        id: string;
+        resolverId: string;
+        startedAt: number;
+    }>;
+    /** Whether there are any unmet requirements */
+    hasUnmet: boolean;
+    /** Whether there are any inflight requirements */
+    hasInflight: boolean;
+    /** Whether the system is actively working (has unmet or inflight requirements) */
+    isWorking: boolean;
+}
+/**
+ * Consolidated inspection state returned by useInspect hooks.
+ * Identical shape across React, Vue, Svelte, Solid, and Lit adapters.
+ */
+interface InspectState {
+    /** Whether the system has settled (no pending operations) */
+    isSettled: boolean;
+    /** Array of unmet requirements */
+    unmet: RequirementsState["unmet"];
+    /** Array of inflight requirements */
+    inflight: RequirementsState["inflight"];
+    /** Whether the system is actively working */
+    isWorking: boolean;
+    /** Whether there are any unmet requirements */
+    hasUnmet: boolean;
+    /** Whether there are any inflight requirements */
+    hasInflight: boolean;
+}
+/**
+ * Information about a single constraint.
+ */
+interface ConstraintInfo {
+    id: string;
+    active: boolean;
+    priority: number;
+}
+/**
+ * Compute InspectState from a system instance.
+ * Centralizes the logic currently duplicated across adapters.
+ * @internal
+ */
+declare function computeInspectState(system: SystemLike): InspectState;
+/**
+ * Options for throttled hooks.
+ * Used by useInspectThrottled, useRequirementsThrottled, etc.
+ */
+interface ThrottledHookOptions {
+    /**
+     * Minimum time between updates in milliseconds.
+     * @default 100
+     */
+    throttleMs?: number;
+}
+/**
+ * Create a throttled version of a callback function.
+ * Uses trailing-edge throttling: the callback will be called at most once per interval,
+ * with the latest arguments from the most recent call.
+ *
+ * @param callback - The function to throttle
+ * @param ms - The minimum time between calls in milliseconds
+ * @returns A throttled version of the callback and a cleanup function
+ * @internal
+ */
+declare function createThrottle<T extends (...args: unknown[]) => void>(callback: T, ms: number): {
+    throttled: T;
+    cleanup: () => void;
+};
+/**
+ * Dev-mode assertion that the system parameter is non-null.
+ * Tree-shaken in production builds.
+ * @internal
+ */
+declare function assertSystem(hookName: string, system: unknown): void;
+/** Default equality function using Object.is */
+declare function defaultEquality<T>(a: T, b: T): boolean;
+/**
+ * Build a TimeTravelState object from a system's debug instance.
+ * Returns null when time-travel is disabled.
+ * @internal
+ */
+declare function buildTimeTravelState(system: SystemLike): TimeTravelState | null;
+/**
+ * Pick specific fact values from a system's store.
+ * @internal
+ */
+declare function pickFacts(system: SystemLike, keys: string[]): Record<string, unknown>;
+/** Result of running a selector with tracking. @internal */
+interface TrackedSelectorResult<R> {
+    value: R;
+    factKeys: string[];
+    deriveKeys: string[];
+}
+/**
+ * Run a selector against a system with automatic dependency tracking.
+ * Creates a Proxy that intercepts property access to distinguish between
+ * fact reads (tracked via withTracking) and derivation reads (tracked manually).
+ *
+ * Used by useSelector in all framework adapters.
+ * @internal
+ */
+declare function runTrackedSelector<R>(system: SystemLike, deriveKeySet: Set<string>, selector: (state: Record<string, unknown>) => R): TrackedSelectorResult<R>;
+/**
+ * Check if tracked dependency keys have changed.
+ * @internal
+ */
+declare function depsChanged(prevFacts: string[], newFacts: string[], prevDerived: string[], newDerived: string[]): boolean;
+
+export { type ConstraintInfo, type InspectState, type RequirementsState, type SystemLike, type ThrottledHookOptions, type TrackedSelectorResult, assertSystem, buildTimeTravelState, computeInspectState, createCallbackPlugin, createThrottle, defaultEquality, depsChanged, getBridgeFact, pickFacts, requirementGuard, requirementGuardMultiple, runTrackedSelector, setBridgeFact };

package/dist/adapter-utils.d.ts

@@ -0,0 +1,230 @@
+import { R as Requirement, P as Plugin, F as Facts, S as Schema, Y as TimeTravelAPI, aE as SystemInspection, aH as TimeTravelState } from './plugins-CcwEXXMS.js';
+export { s as shallowEqual } from './utils-4JrY5fk9.js';
+
+/**
+ * Adapter Type Utilities - Shared types and helpers for framework adapters
+ *
+ * These utilities reduce type assertions in adapters by providing:
+ * - Schema composition types
+ * - Constraint/resolver converters
+ * - Plugin factory helpers
+ */
+
+/**
+ * Set a bridge fact without strict typing.
+ * Use for adapter-internal bridge fields like `__adapterState`.
+ *
+ * @example
+ * ```typescript
+ * setBridgeFact(facts, "__adapterState", currentState);
+ * ```
+ */
+declare function setBridgeFact<V>(facts: Facts<Schema>, key: string, value: V): void;
+/**
+ * Get a bridge fact without strict typing.
+ * Use for adapter-internal bridge fields.
+ *
+ * @example
+ * ```typescript
+ * const state = getBridgeFact<MyState>(facts, "__adapterState");
+ * ```
+ */
+declare function getBridgeFact<V>(facts: Facts<Schema>, key: string): V;
+/**
+ * Callback definitions for adapter plugins.
+ */
+interface AdapterCallbacks {
+    onRequirementCreated?: (req: Requirement) => void;
+    onRequirementResolved?: (req: Requirement) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a callback plugin for adapter events.
+ * Wraps adapter callbacks in a Directive plugin.
+ *
+ * @param name - Plugin name (for debugging)
+ * @param callbacks - Callback functions to invoke
+ *
+ * @example
+ * ```typescript
+ * const callbackPlugin = createCallbackPlugin("adapter-callbacks", {
+ *   onRequirementCreated: (req) => console.log("Created:", req),
+ *   onRequirementResolved: (req) => console.log("Resolved:", req),
+ * });
+ * ```
+ */
+declare function createCallbackPlugin(name: string, callbacks: AdapterCallbacks): Plugin<any>;
+/**
+ * Create a type guard for a specific requirement type.
+ * Simplifies the common pattern of checking req.type.
+ *
+ * @example
+ * ```typescript
+ * const isResetReq = requirementGuard<ResetReq>("RESET");
+ * // Use in resolver:
+ * { requirement: isResetReq, resolve: ... }
+ * ```
+ */
+declare function requirementGuard<R extends Requirement>(type: R["type"]): (req: Requirement) => req is R;
+/**
+ * Create a type guard that matches multiple requirement types.
+ *
+ * @example
+ * ```typescript
+ * const isDataReq = requirementGuardMultiple<FetchReq | RefreshReq>(["FETCH", "REFRESH"]);
+ * ```
+ */
+declare function requirementGuardMultiple<R extends Requirement>(types: Array<R["type"]>): (req: Requirement) => req is R;
+
+/**
+ * Shared Adapter Utilities
+ *
+ * Common types and helper functions used across all framework adapters.
+ * @internal
+ */
+
+/**
+ * Minimal structural type for shared adapter helpers.
+ * Both `System<any>` and `SingleModuleSystem<any>` satisfy this interface,
+ * eliminating the need for `as unknown as System<any>` casts in adapters.
+ * @internal
+ */
+interface SystemLike {
+    readonly isSettled: boolean;
+    readonly debug: TimeTravelAPI | null;
+    readonly facts: {
+        $store: {
+            get(key: string): unknown;
+            has(key: string): boolean;
+            toObject(): Record<string, unknown>;
+        };
+    };
+    readonly derive?: Record<string, unknown>;
+    read(key: string): unknown;
+    inspect(): SystemInspection;
+}
+/**
+ * Requirements state returned by useRequirements hooks.
+ * Provides a focused view of just requirements without full inspection overhead.
+ */
+interface RequirementsState {
+    /** Array of unmet requirements waiting to be resolved */
+    unmet: Array<{
+        id: string;
+        requirement: {
+            type: string;
+            [key: string]: unknown;
+        };
+        fromConstraint: string;
+    }>;
+    /** Array of requirements currently being resolved */
+    inflight: Array<{
+        id: string;
+        resolverId: string;
+        startedAt: number;
+    }>;
+    /** Whether there are any unmet requirements */
+    hasUnmet: boolean;
+    /** Whether there are any inflight requirements */
+    hasInflight: boolean;
+    /** Whether the system is actively working (has unmet or inflight requirements) */
+    isWorking: boolean;
+}
+/**
+ * Consolidated inspection state returned by useInspect hooks.
+ * Identical shape across React, Vue, Svelte, Solid, and Lit adapters.
+ */
+interface InspectState {
+    /** Whether the system has settled (no pending operations) */
+    isSettled: boolean;
+    /** Array of unmet requirements */
+    unmet: RequirementsState["unmet"];
+    /** Array of inflight requirements */
+    inflight: RequirementsState["inflight"];
+    /** Whether the system is actively working */
+    isWorking: boolean;
+    /** Whether there are any unmet requirements */
+    hasUnmet: boolean;
+    /** Whether there are any inflight requirements */
+    hasInflight: boolean;
+}
+/**
+ * Information about a single constraint.
+ */
+interface ConstraintInfo {
+    id: string;
+    active: boolean;
+    priority: number;
+}
+/**
+ * Compute InspectState from a system instance.
+ * Centralizes the logic currently duplicated across adapters.
+ * @internal
+ */
+declare function computeInspectState(system: SystemLike): InspectState;
+/**
+ * Options for throttled hooks.
+ * Used by useInspectThrottled, useRequirementsThrottled, etc.
+ */
+interface ThrottledHookOptions {
+    /**
+     * Minimum time between updates in milliseconds.
+     * @default 100
+     */
+    throttleMs?: number;
+}
+/**
+ * Create a throttled version of a callback function.
+ * Uses trailing-edge throttling: the callback will be called at most once per interval,
+ * with the latest arguments from the most recent call.
+ *
+ * @param callback - The function to throttle
+ * @param ms - The minimum time between calls in milliseconds
+ * @returns A throttled version of the callback and a cleanup function
+ * @internal
+ */
+declare function createThrottle<T extends (...args: unknown[]) => void>(callback: T, ms: number): {
+    throttled: T;
+    cleanup: () => void;
+};
+/**
+ * Dev-mode assertion that the system parameter is non-null.
+ * Tree-shaken in production builds.
+ * @internal
+ */
+declare function assertSystem(hookName: string, system: unknown): void;
+/** Default equality function using Object.is */
+declare function defaultEquality<T>(a: T, b: T): boolean;
+/**
+ * Build a TimeTravelState object from a system's debug instance.
+ * Returns null when time-travel is disabled.
+ * @internal
+ */
+declare function buildTimeTravelState(system: SystemLike): TimeTravelState | null;
+/**
+ * Pick specific fact values from a system's store.
+ * @internal
+ */
+declare function pickFacts(system: SystemLike, keys: string[]): Record<string, unknown>;
+/** Result of running a selector with tracking. @internal */
+interface TrackedSelectorResult<R> {
+    value: R;
+    factKeys: string[];
+    deriveKeys: string[];
+}
+/**
+ * Run a selector against a system with automatic dependency tracking.
+ * Creates a Proxy that intercepts property access to distinguish between
+ * fact reads (tracked via withTracking) and derivation reads (tracked manually).
+ *
+ * Used by useSelector in all framework adapters.
+ * @internal
+ */
+declare function runTrackedSelector<R>(system: SystemLike, deriveKeySet: Set<string>, selector: (state: Record<string, unknown>) => R): TrackedSelectorResult<R>;
+/**
+ * Check if tracked dependency keys have changed.
+ * @internal
+ */
+declare function depsChanged(prevFacts: string[], newFacts: string[], prevDerived: string[], newDerived: string[]): boolean;
+
+export { type ConstraintInfo, type InspectState, type RequirementsState, type SystemLike, type ThrottledHookOptions, type TrackedSelectorResult, assertSystem, buildTimeTravelState, computeInspectState, createCallbackPlugin, createThrottle, defaultEquality, depsChanged, getBridgeFact, pickFacts, requirementGuard, requirementGuardMultiple, runTrackedSelector, setBridgeFact };