@directive-run/core 0.5.0 → 0.8.0

package/dist/adapter-utils.js.map

@@ -1 +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.js","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  const dependencies = new Set<string>();\n\n  return {\n    get isTracking() {\n      return true;\n    },\n    track(key: string) {\n      dependencies.add(key);\n    },\n    getDependencies() {\n      return dependencies;\n    },\n  };\n}\n\n/** Null tracking context when not tracking */\nconst nullContext: TrackingContext = {\n  isTracking: false,\n  track() {},\n  getDependencies() {\n    return new Set();\n  },\n};\n\n/**\n * Get the current tracking context.\n * Returns null context if no tracking is active.\n */\nexport function getCurrentTracker(): TrackingContext {\n  return trackingStack[trackingStack.length - 1] ?? nullContext;\n}\n\n/**\n * Check if we're currently tracking dependencies.\n */\nexport function isTracking(): boolean {\n  return 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  const context = createTrackingContext();\n  trackingStack.push(context);\n\n  try {\n    const value = fn();\n    return { value, deps: context.getDependencies() };\n  } finally {\n    trackingStack.pop();\n  }\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  // Temporarily clear the stack\n  const saved = trackingStack.splice(0, trackingStack.length);\n\n  try {\n    return fn();\n  } finally {\n    // Restore the stack (loop avoids spread overflow with deep stacks)\n    for (const ctx of saved) {\n      trackingStack.push(ctx);\n    }\n  }\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  getCurrentTracker().track(key);\n}\n\n/** Prototype pollution guard — shared across all proxy handlers */\nexport const BLOCKED_PROPS: ReadonlySet<string> = Object.freeze(\n  new Set([\"__proto__\", \"constructor\", \"prototype\"]),\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 { Facts } from \"./facts.js\";\nimport type { Plugin } from \"./plugins.js\";\nimport type { ConstraintDef, Requirement } from \"./requirements.js\";\nimport type { ResolverContext, ResolverDef } from \"./resolvers.js\";\nimport type { InferSchema, Schema } from \"./schema.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<Base extends Schema, Extra extends Schema> = Base &\n  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  return 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  facts: Facts<S>,\n  key: K,\n  value: InferSchema<S>[K],\n): void {\n  (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  facts: Facts<Schema>,\n  key: string,\n  value: V,\n): void {\n  (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>(facts: Facts<Schema>, key: string): V {\n  return (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  when: (state: TState) => boolean | Promise<boolean>;\n  require: Requirement | ((state: TState) => Requirement | null);\n  priority?: 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  constraints: Record<string, AdapterConstraint<TState>>,\n  extractState: (facts: Facts<S>) => TState,\n): Record<string, ConstraintDef<S, Requirement>> {\n  const result: Record<string, ConstraintDef<S, Requirement>> = {};\n\n  for (const [id, constraint] of Object.entries(constraints)) {\n    result[id] = {\n      priority: constraint.priority ?? 0,\n      when: (facts) => constraint.when(extractState(facts)),\n      require: (facts) => {\n        const req =\n          typeof constraint.require === \"function\"\n            ? constraint.require(extractState(facts))\n            : constraint.require;\n        return req;\n      },\n    };\n  }\n\n  return 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  context: TContext;\n  signal: AbortSignal;\n}\n\n/**\n * Adapter resolver definition (generic form used by adapters).\n */\nexport interface AdapterResolver<\n  TContext,\n  R extends Requirement = Requirement,\n> {\n  requirement: (req: Requirement) => req is R;\n  key?: (req: R) => string;\n  resolve: (\n    req: R,\n    ctx: AdapterResolverContext<TContext>,\n  ) => 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  resolvers: Record<string, AdapterResolver<TContext, Requirement>>,\n  createContext: (ctx: ResolverContext<S>) => TContext,\n): Record<string, ResolverDef<S, Requirement>> {\n  const result: Record<string, ResolverDef<S, Requirement>> = {};\n\n  for (const [id, resolver] of Object.entries(resolvers)) {\n    result[id] = {\n      requirement: resolver.requirement,\n      key: resolver.key,\n      resolve: async (req, ctx) => {\n        const adapterCtx = createContext(ctx);\n        await resolver.resolve(req, {\n          context: adapterCtx,\n          signal: ctx.signal,\n        });\n      },\n    };\n  }\n\n  return result;\n}\n\n// ============================================================================\n// Plugin Factory\n// ============================================================================\n\n/**\n * Callback definitions for adapter plugins.\n */\nexport interface AdapterCallbacks {\n  onRequirementCreated?: (req: Requirement) => void;\n  onRequirementResolved?: (req: Requirement) => void;\n  onError?: (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  name: string,\n  callbacks: AdapterCallbacks,\n): Plugin<any> {\n  return {\n    name,\n    onRequirementCreated: callbacks.onRequirementCreated\n      ? (req) => callbacks.onRequirementCreated!(req.requirement)\n      : undefined,\n    onRequirementMet: callbacks.onRequirementResolved\n      ? (req) => callbacks.onRequirementResolved!(req.requirement)\n      : undefined,\n    onError: callbacks.onError,\n  };\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  constraints: Record<string, ConstraintDef<S, Requirement>>,\n): Record<string, ConstraintDef<S, Requirement>> {\n  return 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  resolvers: Record<string, ResolverDef<S, Requirement>>,\n): Record<string, ResolverDef<S, Requirement>> {\n  return 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  type: R[\"type\"],\n): (req: Requirement) => req is R {\n  return (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  types: Array<R[\"type\"]>,\n): (req: Requirement) => req is R {\n  const typeSet = new Set(types);\n  return (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  promise: Promise<T>,\n  ms: number,\n  errorMessage: string,\n): Promise<T> {\n  let timeoutId: ReturnType<typeof setTimeout>;\n\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeoutId = setTimeout(() => reject(new Error(errorMessage)), ms);\n  });\n\n  try {\n    return await Promise.race([promise, timeoutPromise]);\n  } finally {\n    clearTimeout(timeoutId!);\n  }\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  if (error instanceof Error) {\n    return error;\n  }\n  return 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  const seen = new WeakSet();\n\n  function stringify(val: unknown, depth: number): string {\n    if (depth > maxDepth) {\n      return '\"[max depth exceeded]\"';\n    }\n\n    if (val === null) return \"null\";\n    if (val === undefined) return \"undefined\";\n\n    const type = typeof val;\n\n    if (type === \"string\") return JSON.stringify(val);\n    if (type === \"number\" || type === \"boolean\") return String(val);\n    if (type === \"function\") return '\"[function]\"';\n    if (type === \"symbol\") return '\"[symbol]\"';\n\n    if (Array.isArray(val)) {\n      // Check for circular reference\n      if (seen.has(val)) {\n        return '\"[circular]\"';\n      }\n      seen.add(val);\n      const result = `[${val.map((v) => stringify(v, depth + 1)).join(\",\")}]`;\n      seen.delete(val);\n      return result;\n    }\n\n    if (type === \"object\") {\n      const obj = val as Record<string, unknown>;\n      // Check for circular reference\n      if (seen.has(obj)) {\n        return '\"[circular]\"';\n      }\n      seen.add(obj);\n      const keys = Object.keys(obj).sort();\n      const pairs = keys.map(\n        (k) => `${JSON.stringify(k)}:${stringify(obj[k], depth + 1)}`,\n      );\n      const result = `{${pairs.join(\",\")}}`;\n      seen.delete(obj);\n      return result;\n    }\n\n    return '\"[unknown]\"';\n  }\n\n  return 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  const dangerousKeys = new Set([\"__proto__\", \"constructor\", \"prototype\"]);\n  const seen = new WeakSet();\n\n  function check(val: unknown, depth: number): boolean {\n    if (depth > maxDepth) return false; // Fail safe at max depth - don't assume safety\n    if (val === null || val === undefined) return true;\n    if (typeof val !== \"object\") return true;\n\n    const objVal = val as Record<string, unknown>;\n\n    // Check for circular reference\n    if (seen.has(objVal)) return true;\n    seen.add(objVal);\n\n    // Check array elements\n    if (Array.isArray(objVal)) {\n      for (const item of objVal) {\n        if (!check(item, depth + 1)) {\n          seen.delete(objVal);\n          return false;\n        }\n      }\n      seen.delete(objVal);\n      return true;\n    }\n\n    // Check object keys and values\n    for (const key of Object.keys(objVal)) {\n      if (dangerousKeys.has(key)) {\n        seen.delete(objVal);\n        return false;\n      }\n      if (!check(objVal[key], depth + 1)) {\n        seen.delete(objVal);\n        return false;\n      }\n    }\n\n    seen.delete(objVal);\n    return true;\n  }\n\n  return 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>>(\n  a: T,\n  b: T,\n): boolean {\n  if (a === b) return true;\n  if (!a || !b) return false;\n\n  const keysA = Object.keys(a);\n  const keysB = Object.keys(b);\n\n  if (keysA.length !== keysB.length) return false;\n\n  for (const key of keysA) {\n    if (a[key] !== b[key]) return false;\n  }\n\n  return 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  const str = stableStringify(value);\n  let hash = 5381;\n  for (let i = 0; i < str.length; i++) {\n    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);\n  }\n  // Convert to unsigned 32-bit and then to hex\n  return (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  data: T;\n  createdAt: number;\n  expiresAt?: number;\n  version?: string;\n  metadata?: 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  snapshot: DistributableSnapshotLike<T>,\n  now: number = Date.now(),\n): boolean {\n  return 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  snapshot: DistributableSnapshotLike<T>,\n  now: number = Date.now(),\n): T {\n  // Structural validation\n  if (!snapshot || typeof snapshot !== \"object\") {\n    throw new Error(\n      \"[Directive] Invalid snapshot: expected an object with 'data' and 'createdAt' properties.\",\n    );\n  }\n  if (!(\"data\" in snapshot)) {\n    throw new Error(\n      \"[Directive] Invalid snapshot: missing required 'data' property.\",\n    );\n  }\n  if (!(\"createdAt\" in snapshot) || typeof snapshot.createdAt !== \"number\") {\n    throw new Error(\n      \"[Directive] Invalid snapshot: missing or invalid 'createdAt' property (expected number).\",\n    );\n  }\n\n  // Expiration validation\n  if (isSnapshotExpired(snapshot, now)) {\n    const expiredAt = new Date(snapshot.expiresAt!).toISOString();\n    throw new Error(\n      `[Directive] Snapshot expired at ${expiredAt}. Obtain a fresh snapshot from the source.`,\n    );\n  }\n  return snapshot.data;\n}\n\n/**\n * Diff result for a single changed value.\n */\nexport interface SnapshotDiffEntry {\n  /** The key path that changed (e.g., \"canUseApi\" or \"limits.apiCalls\") */\n  path: string;\n  /** The value in the old snapshot */\n  oldValue: unknown;\n  /** The value in the new snapshot */\n  newValue: unknown;\n  /** Type of change: \"added\", \"removed\", or \"changed\" */\n  type: \"added\" | \"removed\" | \"changed\";\n}\n\n/**\n * Result of diffing two snapshots.\n */\nexport interface SnapshotDiff {\n  /** Whether the snapshots are identical */\n  identical: boolean;\n  /** List of changes between snapshots */\n  changes: SnapshotDiffEntry[];\n  /** Whether the version changed (if both have versions) */\n  versionChanged: boolean;\n  /** Old version (if available) */\n  oldVersion?: string;\n  /** New version (if available) */\n  newVersion?: 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  oldSnapshot: DistributableSnapshotLike<T>,\n  newSnapshot: DistributableSnapshotLike<T>,\n): SnapshotDiff {\n  const changes: SnapshotDiffEntry[] = [];\n\n  // Deep compare function\n  function compare(oldObj: unknown, newObj: unknown, path: string): void {\n    // Handle null/undefined\n    if (oldObj === null || oldObj === undefined) {\n      if (newObj !== null && newObj !== undefined) {\n        changes.push({\n          path,\n          oldValue: oldObj,\n          newValue: newObj,\n          type: \"added\",\n        });\n      }\n      return;\n    }\n    if (newObj === null || newObj === undefined) {\n      changes.push({\n        path,\n        oldValue: oldObj,\n        newValue: newObj,\n        type: \"removed\",\n      });\n      return;\n    }\n\n    // Handle primitives\n    if (typeof oldObj !== \"object\" || typeof newObj !== \"object\") {\n      if (!Object.is(oldObj, newObj)) {\n        changes.push({\n          path,\n          oldValue: oldObj,\n          newValue: newObj,\n          type: \"changed\",\n        });\n      }\n      return;\n    }\n\n    // Handle arrays\n    if (Array.isArray(oldObj) && Array.isArray(newObj)) {\n      if (oldObj.length !== newObj.length) {\n        changes.push({\n          path,\n          oldValue: oldObj,\n          newValue: newObj,\n          type: \"changed\",\n        });\n        return;\n      }\n      for (let i = 0; i < oldObj.length; i++) {\n        compare(oldObj[i], newObj[i], `${path}[${i}]`);\n      }\n      return;\n    }\n\n    // Handle objects\n    const oldRecord = oldObj as Record<string, unknown>;\n    const newRecord = newObj as Record<string, unknown>;\n    const allKeys = new Set([\n      ...Object.keys(oldRecord),\n      ...Object.keys(newRecord),\n    ]);\n\n    for (const key of allKeys) {\n      const childPath = path ? `${path}.${key}` : key;\n      if (!(key in oldRecord)) {\n        changes.push({\n          path: childPath,\n          oldValue: undefined,\n          newValue: newRecord[key],\n          type: \"added\",\n        });\n      } else if (!(key in newRecord)) {\n        changes.push({\n          path: childPath,\n          oldValue: oldRecord[key],\n          newValue: undefined,\n          type: \"removed\",\n        });\n      } else {\n        compare(oldRecord[key], newRecord[key], childPath);\n      }\n    }\n  }\n\n  // Compare data\n  compare(oldSnapshot.data, newSnapshot.data, \"\");\n\n  // Check version change\n  const versionChanged =\n    oldSnapshot.version !== newSnapshot.version &&\n    (oldSnapshot.version !== undefined || newSnapshot.version !== undefined);\n\n  return {\n    identical: changes.length === 0,\n    changes,\n    versionChanged,\n    oldVersion: oldSnapshot.version,\n    newVersion: newSnapshot.version,\n  };\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  extends DistributableSnapshotLike<T> {\n  /** HMAC-SHA256 signature in hex format */\n  signature: string;\n  /** Signing algorithm used */\n  algorithm: \"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  snapshot: DistributableSnapshotLike<T> | SignedSnapshot<T>,\n): snapshot is SignedSnapshot<T> {\n  return \"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  snapshot: DistributableSnapshotLike<T>,\n  secret: string | Uint8Array,\n): Promise<SignedSnapshot<T>> {\n  // Create a canonical representation for signing\n  const payload = stableStringify({\n    data: snapshot.data,\n    createdAt: snapshot.createdAt,\n    expiresAt: snapshot.expiresAt,\n    version: snapshot.version,\n    metadata: snapshot.metadata,\n  });\n\n  const signature = await hmacSha256(payload, secret);\n\n  return {\n    ...snapshot,\n    signature,\n    algorithm: \"hmac-sha256\",\n  };\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  signedSnapshot: SignedSnapshot<T>,\n  secret: string | Uint8Array,\n): Promise<boolean> {\n  if (!signedSnapshot.signature || signedSnapshot.algorithm !== \"hmac-sha256\") {\n    return false;\n  }\n\n  // Recreate the canonical payload (same as signing)\n  const payload = stableStringify({\n    data: signedSnapshot.data,\n    createdAt: signedSnapshot.createdAt,\n    expiresAt: signedSnapshot.expiresAt,\n    version: signedSnapshot.version,\n    metadata: signedSnapshot.metadata,\n  });\n\n  const expectedSignature = await hmacSha256(payload, secret);\n\n  // Use timing-safe comparison\n  return 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  message: string,\n  secret: string | Uint8Array,\n): Promise<string> {\n  // Convert secret to Uint8Array if string\n  const secretBytes: Uint8Array =\n    typeof secret === \"string\" ? new TextEncoder().encode(secret) : secret;\n\n  // Import key for HMAC\n  const algorithm: HmacImportParams = {\n    name: \"HMAC\",\n    hash: { name: \"SHA-256\" },\n  };\n  const key = await crypto.subtle.importKey(\n    \"raw\",\n    secretBytes as unknown as ArrayBuffer,\n    algorithm,\n    false,\n    [\"sign\"],\n  );\n\n  // Sign the message\n  const messageBytes = new TextEncoder().encode(message);\n  const signature = await crypto.subtle.sign(\"HMAC\", key, messageBytes);\n\n  // Convert to hex string\n  return Array.from(new Uint8Array(signature))\n    .map((b) => b.toString(16).padStart(2, \"0\"))\n    .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  if (a.length !== b.length) {\n    return false;\n  }\n\n  let result = 0;\n  for (let i = 0; i < a.length; i++) {\n    result |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n  return 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 { withTracking } from \"./core/tracking.js\";\nimport type {\n  SnapshotMeta,\n  SystemInspection,\n  TimeTravelAPI,\n  TimeTravelState,\n} from \"./core/types.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  readonly isSettled: boolean;\n  readonly debug: TimeTravelAPI | null;\n  readonly facts: {\n    $store: {\n      get(key: string): unknown;\n      has(key: string): boolean;\n      toObject(): Record<string, unknown>;\n    };\n  };\n  readonly derive?: Record<string, unknown>;\n  read(key: string): unknown;\n  inspect(): 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  /** Array of unmet requirements waiting to be resolved */\n  unmet: Array<{\n    id: string;\n    requirement: { type: string; [key: string]: unknown };\n    fromConstraint: string;\n  }>;\n  /** Array of requirements currently being resolved */\n  inflight: Array<{ id: string; resolverId: string; startedAt: number }>;\n  /** Whether there are any unmet requirements */\n  hasUnmet: boolean;\n  /** Whether there are any inflight requirements */\n  hasInflight: boolean;\n  /** Whether the system is actively working (has unmet or inflight requirements) */\n  isWorking: 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  /** Whether the system has settled (no pending operations) */\n  isSettled: boolean;\n  /** Array of unmet requirements */\n  unmet: RequirementsState[\"unmet\"];\n  /** Array of inflight requirements */\n  inflight: RequirementsState[\"inflight\"];\n  /** Whether the system is actively working */\n  isWorking: boolean;\n  /** Whether there are any unmet requirements */\n  hasUnmet: boolean;\n  /** Whether there are any inflight requirements */\n  hasInflight: boolean;\n}\n\n/**\n * Information about a single constraint.\n */\nexport interface ConstraintInfo {\n  id: string;\n  active: boolean;\n  priority: 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  const inspection = system.inspect();\n  return {\n    isSettled: system.isSettled,\n    unmet: inspection.unmet,\n    inflight: inspection.inflight,\n    isWorking: inspection.unmet.length > 0 || inspection.inflight.length > 0,\n    hasUnmet: inspection.unmet.length > 0,\n    hasInflight: inspection.inflight.length > 0,\n  };\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  /**\n   * Minimum time between updates in milliseconds.\n   * @default 100\n   */\n  throttleMs?: 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  callback: T,\n  ms: number,\n): { throttled: T; cleanup: () => void } {\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  let lastArgs: Parameters<T> | null = null;\n  let lastCallTime = 0;\n\n  const throttled = ((...args: Parameters<T>) => {\n    const now = Date.now();\n    const timeSinceLastCall = now - lastCallTime;\n\n    if (timeSinceLastCall >= ms) {\n      // Enough time has passed, call immediately\n      lastCallTime = now;\n      callback(...args);\n    } else {\n      // Schedule for later, keeping latest args\n      lastArgs = args;\n      if (!timeoutId) {\n        timeoutId = setTimeout(() => {\n          timeoutId = null;\n          lastCallTime = Date.now();\n          if (lastArgs) {\n            callback(...lastArgs);\n            lastArgs = null;\n          }\n        }, ms - timeSinceLastCall);\n      }\n    }\n  }) as T;\n\n  const cleanup = () => {\n    if (timeoutId) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n    lastArgs = null;\n  };\n\n  return { 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  if (process.env.NODE_ENV !== \"production\" && system == null) {\n    throw new Error(\n      `[Directive] ${hookName}() requires a system instance as the first argument. Received ${system}.`,\n    );\n  }\n}\n\n/** Default equality function using Object.is */\nexport function defaultEquality<T>(a: T, b: T): boolean {\n  return 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(\n  system: SystemLike,\n): TimeTravelState | null {\n  const debug = system.debug;\n  if (!debug) return null;\n\n  // Build lightweight metadata array (no facts data)\n  const snapshots: SnapshotMeta[] = debug.snapshots.map((s) => ({\n    id: s.id,\n    timestamp: s.timestamp,\n    trigger: s.trigger,\n  }));\n\n  return {\n    // Existing\n    canUndo: debug.currentIndex > 0,\n    canRedo: debug.currentIndex < debug.snapshots.length - 1,\n    undo: () => debug.goBack(),\n    redo: () => debug.goForward(),\n    currentIndex: debug.currentIndex,\n    totalSnapshots: debug.snapshots.length,\n\n    // Snapshot access\n    snapshots,\n    getSnapshotFacts: (id: number): Record<string, unknown> | null => {\n      const snap = debug.snapshots.find((s) => s.id === id);\n      return snap ? snap.facts : null;\n    },\n\n    // Navigation\n    goTo: (snapshotId: number) => debug.goTo(snapshotId),\n    goBack: (steps: number) => debug.goBack(steps),\n    goForward: (steps: number) => debug.goForward(steps),\n    replay: () => debug.replay(),\n\n    // Session persistence\n    exportSession: () => debug.export(),\n    importSession: (json: string) => debug.import(json),\n\n    // Changesets\n    beginChangeset: (label: string) => debug.beginChangeset(label),\n    endChangeset: () => debug.endChangeset(),\n\n    // Recording control\n    isPaused: debug.isPaused,\n    pause: () => debug.pause(),\n    resume: () => debug.resume(),\n  };\n}\n\n/**\n * Pick specific fact values from a system's store.\n * @internal\n */\nexport function pickFacts(\n  system: SystemLike,\n  keys: string[],\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  for (const key of keys) {\n    result[key] = system.facts.$store.get(key);\n  }\n  return result;\n}\n\n// ============================================================================\n// Tracked Selector\n// ============================================================================\n\n/** Result of running a selector with tracking. @internal */\nexport interface TrackedSelectorResult<R> {\n  value: R;\n  factKeys: string[];\n  deriveKeys: 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  system: SystemLike,\n  deriveKeySet: Set<string>,\n  selector: (state: Record<string, unknown>) => R,\n): TrackedSelectorResult<R> {\n  const accessedDeriveKeys: string[] = [];\n\n  const stateProxy = new Proxy(\n    {},\n    {\n      get(_, prop: string | symbol) {\n        if (typeof prop !== \"string\") return undefined;\n        if (deriveKeySet.has(prop)) {\n          accessedDeriveKeys.push(prop);\n          return system.read(prop);\n        }\n        return system.facts.$store.get(prop);\n      },\n      has(_, prop: string | symbol) {\n        if (typeof prop !== \"string\") return false;\n        return deriveKeySet.has(prop) || system.facts.$store.has(prop);\n      },\n      ownKeys() {\n        const factKeys = Object.keys(system.facts.$store.toObject());\n        const combined = new Set(factKeys);\n        for (const k of deriveKeySet) combined.add(k);\n        return [...combined];\n      },\n      getOwnPropertyDescriptor() {\n        return { configurable: true, enumerable: true, writable: true };\n      },\n    },\n  );\n\n  const { value, deps } = withTracking(() =>\n    selector(stateProxy as Record<string, unknown>),\n  );\n  return {\n    value,\n    factKeys: Array.from(deps) as string[],\n    deriveKeys: accessedDeriveKeys,\n  };\n}\n\n/**\n * Check if tracked dependency keys have changed.\n * @internal\n */\nexport function depsChanged(\n  prevFacts: string[],\n  newFacts: string[],\n  prevDerived: string[],\n  newDerived: string[],\n): boolean {\n  const factsChanged =\n    newFacts.length !== prevFacts.length ||\n    newFacts.some((k, i) => k !== prevFacts[i]);\n  const derivedChanged =\n    newDerived.length !== prevDerived.length ||\n    newDerived.some((k, i) => k !== prevDerived[i]);\n  return factsChanged || derivedChanged;\n}\n\n// ============================================================================\n// Re-exports from core/types/adapter-utils and utils/utils\n// ============================================================================\n\nexport {\n  setBridgeFact,\n  getBridgeFact,\n  createCallbackPlugin,\n  requirementGuard,\n  requirementGuardMultiple,\n} from \"./core/types/adapter-utils.js\";\n\nexport { shallowEqual } from \"./utils/utils.js\";\n"]}
+{"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","buildHistoryState","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":"AAaA,SAASA,CAAAA,EAAyC,CAChD,IAAMC,CAAAA,CAAe,IAAI,GAAA,CAEzB,OAAO,CACL,IAAI,YAAa,CACf,OAAO,KACT,CAAA,CACA,KAAA,CAAMC,CAAAA,CAAa,CACjBD,EAAa,GAAA,CAAIC,CAAG,EACtB,CAAA,CACA,eAAA,EAAkB,CAChB,OAAOD,CACT,CACF,CACF,CAgDO,SAASE,CAAAA,CAAgBC,EAA8C,CAC5E,IAAMC,EAAUL,CAAAA,EAAsB,CAGtC,GAAI,CAEF,OAAO,CAAE,KAAA,CADKI,CAAAA,EAAG,CACD,IAAA,CAAMC,EAAQ,eAAA,EAAkB,CAClD,CAAA,OAAE,CAEF,CACF,CAsDkD,MAAA,CAAO,OACvD,IAAI,GAAA,CAAI,CAAC,WAAA,CAAa,aAAA,CAAe,WAAW,CAAC,CACnD,EC/CO,SAASC,EACdC,CAAAA,CACAL,CAAAA,CACAM,EACM,CACLD,CAAAA,CAAkCL,CAAG,CAAA,CAAIM,EAC5C,CAWO,SAASC,CAAAA,CAAiBF,CAAAA,CAAsBL,EAAgB,CACrE,OAAQK,CAAAA,CAAkCL,CAAG,CAC/C,CAyJO,SAASQ,EACdC,CAAAA,CACAC,CAAAA,CACa,CACb,OAAO,CACL,IAAA,CAAAD,CAAAA,CACA,qBAAsBC,CAAAA,CAAU,oBAAA,CAC3BC,GAAQD,CAAAA,CAAU,oBAAA,CAAsBC,EAAI,WAAW,CAAA,CACxD,MAAA,CACJ,gBAAA,CAAkBD,EAAU,qBAAA,CACvBC,CAAAA,EAAQD,EAAU,qBAAA,CAAuBC,CAAAA,CAAI,WAAW,CAAA,CACzD,MAAA,CACJ,OAAA,CAASD,CAAAA,CAAU,OACrB,CACF,CAyCO,SAASE,CAAAA,CACdC,EACgC,CAChC,OAAQF,CAAAA,EAAkBA,CAAAA,CAAI,OAASE,CACzC,CAUO,SAASC,CAAAA,CACdC,CAAAA,CACgC,CAChC,IAAMC,CAAAA,CAAU,IAAI,GAAA,CAAID,CAAK,CAAA,CAC7B,OAAQJ,GAAkBK,CAAAA,CAAQ,GAAA,CAAIL,EAAI,IAAI,CAChD,CC7KO,SAASM,EACdC,CAAAA,CACAC,CAAAA,CACS,CACT,GAAID,CAAAA,GAAMC,EAAG,OAAO,KAAA,CACpB,GAAI,CAACD,GAAK,CAACC,CAAAA,CAAG,OAAO,MAAA,CAErB,IAAMC,CAAAA,CAAQ,MAAA,CAAO,IAAA,CAAKF,CAAC,EACrBG,CAAAA,CAAQ,MAAA,CAAO,KAAKF,CAAC,CAAA,CAE3B,GAAIC,CAAAA,CAAM,MAAA,GAAWC,CAAAA,CAAM,MAAA,CAAQ,OAAO,MAAA,CAE1C,IAAA,IAAWrB,KAAOoB,CAAAA,CAChB,GAAIF,EAAElB,CAAG,CAAA,GAAMmB,CAAAA,CAAEnB,CAAG,EAAG,OAAO,MAAA,CAGhC,OAAO,KACT,CClFO,SAASsB,CAAAA,CAAoBC,CAAAA,CAAkC,CACpE,IAAMC,EAAaD,CAAAA,CAAO,OAAA,EAAQ,CAClC,OAAO,CACL,SAAA,CAAWA,CAAAA,CAAO,SAAA,CAClB,KAAA,CAAOC,EAAW,KAAA,CAClB,QAAA,CAAUA,EAAW,QAAA,CACrB,SAAA,CAAWA,EAAW,KAAA,CAAM,MAAA,CAAS,CAAA,EAAKA,CAAAA,CAAW,SAAS,MAAA,CAAS,CAAA,CACvE,SAAUA,CAAAA,CAAW,KAAA,CAAM,OAAS,CAAA,CACpC,WAAA,CAAaA,CAAAA,CAAW,QAAA,CAAS,OAAS,CAC5C,CACF,CAgCO,SAASC,CAAAA,CACdC,EACAC,CAAAA,CACuC,CACvC,IAAIC,CAAAA,CAAkD,KAClDC,CAAAA,CAAiC,IAAA,CACjCC,CAAAA,CAAe,CAAA,CAkCnB,OAAO,CAAE,SAAA,EAhCU,CAAA,GAAIC,CAAAA,GAAwB,CAC7C,IAAMC,CAAAA,CAAM,KAAK,GAAA,EAAI,CACfC,EAAoBD,CAAAA,CAAMF,CAAAA,CAE5BG,CAAAA,EAAqBN,CAAAA,EAEvBG,EAAeE,CAAAA,CACfN,CAAAA,CAAS,GAAGK,CAAI,CAAA,GAGhBF,EAAWE,CAAAA,CACNH,CAAAA,GACHA,CAAAA,CAAY,UAAA,CAAW,IAAM,CAC3BA,CAAAA,CAAY,KACZE,CAAAA,CAAe,IAAA,CAAK,KAAI,CACpBD,CAAAA,GACFH,CAAAA,CAAS,GAAGG,CAAQ,CAAA,CACpBA,CAAAA,CAAW,MAEf,CAAA,CAAGF,CAAAA,CAAKM,CAAiB,CAAA,CAAA,EAG/B,CAAA,CAAA,CAUoB,OAAA,CARJ,IAAM,CAChBL,CAAAA,GACF,YAAA,CAAaA,CAAS,CAAA,CACtBA,CAAAA,CAAY,MAEdC,CAAAA,CAAW,KACb,CAE4B,CAC9B,CAWO,SAASK,CAAAA,CAAaC,EAAkBZ,CAAAA,CAAuB,CACpE,GAAI,OAAA,CAAQ,GAAA,CAAI,QAAA,GAAa,YAAA,EAAgBA,GAAU,IAAA,CACrD,MAAM,IAAI,KAAA,CACR,CAAA,YAAA,EAAeY,CAAQ,CAAA,8DAAA,EAAiEZ,CAAM,CAAA,CAAA,CAChG,CAEJ,CAGO,SAASa,CAAAA,CAAmBlB,CAAAA,CAAMC,CAAAA,CAAe,CACtD,OAAO,MAAA,CAAO,EAAA,CAAGD,CAAAA,CAAGC,CAAC,CACvB,CAOO,SAASkB,CAAAA,CACdd,CAAAA,CACqB,CACrB,IAAMe,CAAAA,CAAQf,CAAAA,CAAO,OAAA,CACrB,GAAI,CAACe,CAAAA,CAAO,OAAO,IAAA,CAGnB,IAAMC,EAA4BD,CAAAA,CAAM,SAAA,CAAU,GAAA,CAAKE,CAAAA,GAAO,CAC5D,EAAA,CAAIA,CAAAA,CAAE,GACN,SAAA,CAAWA,CAAAA,CAAE,UACb,OAAA,CAASA,CAAAA,CAAE,OACb,CAAA,CAAE,EAEF,OAAO,CAEL,SAAA,CAAWF,CAAAA,CAAM,aAAe,CAAA,CAChC,YAAA,CAAcA,CAAAA,CAAM,YAAA,CAAeA,EAAM,SAAA,CAAU,MAAA,CAAS,EAC5D,YAAA,CAAcA,CAAAA,CAAM,aACpB,cAAA,CAAgBA,CAAAA,CAAM,SAAA,CAAU,MAAA,CAGhC,UAAAC,CAAAA,CACA,gBAAA,CAAmBE,GAA+C,CAChE,IAAMC,EAAOJ,CAAAA,CAAM,SAAA,CAAU,IAAA,CAAME,CAAAA,EAAMA,EAAE,EAAA,GAAOC,CAAE,EACpD,OAAOC,CAAAA,CAAOA,EAAK,KAAA,CAAQ,IAC7B,CAAA,CAGA,IAAA,CAAOC,GAAuBL,CAAAA,CAAM,IAAA,CAAKK,CAAU,CAAA,CACnD,OAASC,CAAAA,EAAmBN,CAAAA,CAAM,MAAA,CAAOM,CAAK,EAC9C,SAAA,CAAYA,CAAAA,EAAmBN,EAAM,SAAA,CAAUM,CAAK,EACpD,MAAA,CAAQ,IAAMN,CAAAA,CAAM,MAAA,GAGpB,aAAA,CAAe,IAAMA,EAAM,MAAA,EAAO,CAClC,cAAgBO,CAAAA,EAAiBP,CAAAA,CAAM,MAAA,CAAOO,CAAI,EAGlD,cAAA,CAAiBC,CAAAA,EAAkBR,EAAM,cAAA,CAAeQ,CAAK,EAC7D,YAAA,CAAc,IAAMR,CAAAA,CAAM,YAAA,GAG1B,QAAA,CAAUA,CAAAA,CAAM,SAChB,KAAA,CAAO,IAAMA,EAAM,KAAA,EAAM,CACzB,MAAA,CAAQ,IAAMA,EAAM,MAAA,EACtB,CACF,CAMO,SAASS,EACdxB,CAAAA,CACAyB,CAAAA,CACyB,CACzB,IAAMC,EAAkC,EAAC,CACzC,QAAWjD,CAAAA,IAAOgD,CAAAA,CAChBC,EAAOjD,CAAG,CAAA,CAAIuB,CAAAA,CAAO,KAAA,CAAM,OAAO,GAAA,CAAIvB,CAAG,EAE3C,OAAOiD,CACT,CAqBO,SAASC,CAAAA,CACd3B,CAAAA,CACA4B,CAAAA,CACAC,EAC0B,CAC1B,IAAMC,CAAAA,CAA+B,GAE/BC,CAAAA,CAAa,IAAI,KAAA,CACrB,GACA,CACE,GAAA,CAAIC,EAAGC,CAAAA,CAAuB,CAC5B,GAAI,OAAOA,CAAAA,EAAS,QAAA,CACpB,OAAIL,EAAa,GAAA,CAAIK,CAAI,GACvBH,CAAAA,CAAmB,IAAA,CAAKG,CAAI,CAAA,CACrBjC,CAAAA,CAAO,IAAA,CAAKiC,CAAI,GAElBjC,CAAAA,CAAO,KAAA,CAAM,OAAO,GAAA,CAAIiC,CAAI,CACrC,CAAA,CACA,GAAA,CAAID,CAAAA,CAAGC,CAAAA,CAAuB,CAC5B,OAAI,OAAOA,CAAAA,EAAS,QAAA,CAAiB,MAC9BL,CAAAA,CAAa,GAAA,CAAIK,CAAI,CAAA,EAAKjC,EAAO,KAAA,CAAM,MAAA,CAAO,IAAIiC,CAAI,CAC/D,EACA,OAAA,EAAU,CACR,IAAMC,CAAAA,CAAW,OAAO,IAAA,CAAKlC,CAAAA,CAAO,MAAM,MAAA,CAAO,QAAA,EAAU,CAAA,CACrDmC,CAAAA,CAAW,IAAI,GAAA,CAAID,CAAQ,CAAA,CACjC,IAAA,IAAWE,KAAKR,CAAAA,CAAcO,CAAAA,CAAS,IAAIC,CAAC,CAAA,CAC5C,OAAO,CAAC,GAAGD,CAAQ,CACrB,CAAA,CACA,wBAAA,EAA2B,CACzB,OAAO,CAAE,YAAA,CAAc,IAAA,CAAM,WAAY,IAAA,CAAM,QAAA,CAAU,IAAK,CAChE,CACF,CACF,CAAA,CAEM,CAAE,KAAA,CAAApD,CAAAA,CAAO,KAAAsD,CAAK,CAAA,CAAI3D,EAAa,IACnCmD,CAAAA,CAASE,CAAqC,CAChD,CAAA,CACA,OAAO,CACL,MAAAhD,CAAAA,CACA,QAAA,CAAU,MAAM,IAAA,CAAKsD,CAAI,EACzB,UAAA,CAAYP,CACd,CACF,CAMO,SAASQ,CAAAA,CACdC,CAAAA,CACAC,EACAC,CAAAA,CACAC,CAAAA,CACS,CACT,IAAMC,CAAAA,CACJH,CAAAA,CAAS,MAAA,GAAWD,EAAU,MAAA,EAC9BC,CAAAA,CAAS,KAAK,CAACJ,CAAAA,CAAGQ,IAAMR,CAAAA,GAAMG,CAAAA,CAAUK,CAAC,CAAC,EACtCC,CAAAA,CACJH,CAAAA,CAAW,SAAWD,CAAAA,CAAY,MAAA,EAClCC,EAAW,IAAA,CAAK,CAACN,CAAAA,CAAGQ,CAAAA,GAAMR,IAAMK,CAAAA,CAAYG,CAAC,CAAC,CAAA,CAChD,OAAOD,GAAgBE,CACzB","file":"adapter-utils.js","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  const dependencies = new Set<string>();\n\n  return {\n    get isTracking() {\n      return true;\n    },\n    track(key: string) {\n      dependencies.add(key);\n    },\n    getDependencies() {\n      return dependencies;\n    },\n  };\n}\n\n/** Null tracking context when not tracking */\nconst nullContext: TrackingContext = {\n  isTracking: false,\n  track() {},\n  getDependencies() {\n    return new Set();\n  },\n};\n\n/**\n * Get the current tracking context.\n *\n * @returns The active {@link TrackingContext}, or a null context (no-op) if\n *   no tracking is active.\n *\n * @internal\n */\nexport function getCurrentTracker(): TrackingContext {\n  return trackingStack[trackingStack.length - 1] ?? nullContext;\n}\n\n/**\n * Check if dependency tracking is currently active.\n *\n * @returns `true` if inside a {@link withTracking} call, `false` otherwise.\n *\n * @internal\n */\nexport function isTracking(): boolean {\n  return trackingStack.length > 0;\n}\n\n/**\n * Run a function with dependency tracking.\n *\n * @remarks\n * Pushes a fresh tracking context onto the stack, executes `fn`, then pops\n * the context. Any fact reads inside `fn` are recorded as dependencies.\n * Nesting is supported — inner calls get their own independent context.\n *\n * @param fn - The function to execute under tracking.\n * @returns An object with the computed `value` and a `deps` Set of accessed\n *   fact keys.\n *\n * @internal\n */\nexport function withTracking<T>(fn: () => T): { value: T; deps: Set<string> } {\n  const context = createTrackingContext();\n  trackingStack.push(context);\n\n  try {\n    const value = fn();\n    return { value, deps: context.getDependencies() };\n  } finally {\n    trackingStack.pop();\n  }\n}\n\n/**\n * Run a function without tracking.\n *\n * @remarks\n * Temporarily clears the tracking stack so that fact reads inside `fn` do\n * not register as dependencies. The stack is restored after `fn` returns\n * (even on error). Useful for side-effect reads that should not trigger\n * derivation invalidation.\n *\n * @param fn - The function to execute without tracking.\n * @returns The return value of `fn`.\n *\n * @internal\n */\nexport function withoutTracking<T>(fn: () => T): T {\n  // Temporarily clear the stack\n  const saved = trackingStack.splice(0, trackingStack.length);\n\n  try {\n    return fn();\n  } finally {\n    // Restore the stack (loop avoids spread overflow with deep stacks)\n    for (const ctx of saved) {\n      trackingStack.push(ctx);\n    }\n  }\n}\n\n/**\n * Track a specific key in the current context.\n *\n * @remarks\n * No-op if no tracking context is active.\n *\n * @param key - The fact key to record as a dependency.\n *\n * @internal\n */\nexport function trackAccess(key: string): void {\n  getCurrentTracker().track(key);\n}\n\n/**\n * Prototype pollution guard — shared across all proxy handlers.\n *\n * @remarks\n * Contains `__proto__`, `constructor`, and `prototype`. Every proxy `get`\n * and `has` trap checks this set and returns `undefined` / `false` for\n * matching keys, preventing prototype pollution via proxy-based objects.\n *\n * @internal\n */\nexport const BLOCKED_PROPS: ReadonlySet<string> = Object.freeze(\n  new Set([\"__proto__\", \"constructor\", \"prototype\"]),\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 { Facts } from \"./facts.js\";\nimport type { Plugin } from \"./plugins.js\";\nimport type { ConstraintDef, Requirement } from \"./requirements.js\";\nimport type { ResolverContext, ResolverDef } from \"./resolvers.js\";\nimport type { InferSchema, Schema } from \"./schema.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<Base extends Schema, Extra extends Schema> = Base &\n  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  return 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  facts: Facts<S>,\n  key: K,\n  value: InferSchema<S>[K],\n): void {\n  (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  facts: Facts<Schema>,\n  key: string,\n  value: V,\n): void {\n  (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>(facts: Facts<Schema>, key: string): V {\n  return (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  when: (state: TState) => boolean | Promise<boolean>;\n  require: Requirement | ((state: TState) => Requirement | null);\n  priority?: 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  constraints: Record<string, AdapterConstraint<TState>>,\n  extractState: (facts: Facts<S>) => TState,\n): Record<string, ConstraintDef<S, Requirement>> {\n  const result: Record<string, ConstraintDef<S, Requirement>> = {};\n\n  for (const [id, constraint] of Object.entries(constraints)) {\n    result[id] = {\n      priority: constraint.priority ?? 0,\n      when: (facts) => constraint.when(extractState(facts)),\n      require: (facts) => {\n        const req =\n          typeof constraint.require === \"function\"\n            ? constraint.require(extractState(facts))\n            : constraint.require;\n        return req;\n      },\n    };\n  }\n\n  return 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  context: TContext;\n  signal: AbortSignal;\n}\n\n/**\n * Adapter resolver definition (generic form used by adapters).\n */\nexport interface AdapterResolver<\n  TContext,\n  R extends Requirement = Requirement,\n> {\n  requirement: (req: Requirement) => req is R;\n  key?: (req: R) => string;\n  resolve: (\n    req: R,\n    ctx: AdapterResolverContext<TContext>,\n  ) => 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  resolvers: Record<string, AdapterResolver<TContext, Requirement>>,\n  createContext: (ctx: ResolverContext<S>) => TContext,\n): Record<string, ResolverDef<S, Requirement>> {\n  const result: Record<string, ResolverDef<S, Requirement>> = {};\n\n  for (const [id, resolver] of Object.entries(resolvers)) {\n    result[id] = {\n      requirement: resolver.requirement,\n      key: resolver.key,\n      resolve: async (req, ctx) => {\n        const adapterCtx = createContext(ctx);\n        await resolver.resolve(req, {\n          context: adapterCtx,\n          signal: ctx.signal,\n        });\n      },\n    };\n  }\n\n  return result;\n}\n\n// ============================================================================\n// Plugin Factory\n// ============================================================================\n\n/**\n * Callback definitions for adapter plugins.\n */\nexport interface AdapterCallbacks {\n  onRequirementCreated?: (req: Requirement) => void;\n  onRequirementResolved?: (req: Requirement) => void;\n  onError?: (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  name: string,\n  callbacks: AdapterCallbacks,\n): Plugin<any> {\n  return {\n    name,\n    onRequirementCreated: callbacks.onRequirementCreated\n      ? (req) => callbacks.onRequirementCreated!(req.requirement)\n      : undefined,\n    onRequirementMet: callbacks.onRequirementResolved\n      ? (req) => callbacks.onRequirementResolved!(req.requirement)\n      : undefined,\n    onError: callbacks.onError,\n  };\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  constraints: Record<string, ConstraintDef<S, Requirement>>,\n): Record<string, ConstraintDef<S, Requirement>> {\n  return 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  resolvers: Record<string, ResolverDef<S, Requirement>>,\n): Record<string, ResolverDef<S, Requirement>> {\n  return 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  type: R[\"type\"],\n): (req: Requirement) => req is R {\n  return (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  types: Array<R[\"type\"]>,\n): (req: Requirement) => req is R {\n  const typeSet = new Set(types);\n  return (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  promise: Promise<T>,\n  ms: number,\n  errorMessage: string,\n): Promise<T> {\n  let timeoutId: ReturnType<typeof setTimeout>;\n\n  const timeoutPromise = new Promise<never>((_, reject) => {\n    timeoutId = setTimeout(() => reject(new Error(errorMessage)), ms);\n  });\n\n  try {\n    return await Promise.race([promise, timeoutPromise]);\n  } finally {\n    clearTimeout(timeoutId!);\n  }\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  if (error instanceof Error) {\n    return error;\n  }\n  return 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  const seen = new WeakSet();\n\n  function stringify(val: unknown, depth: number): string {\n    if (depth > maxDepth) {\n      return '\"[max depth exceeded]\"';\n    }\n\n    if (val === null) return \"null\";\n    if (val === undefined) return \"undefined\";\n\n    const type = typeof val;\n\n    if (type === \"string\") return JSON.stringify(val);\n    if (type === \"number\" || type === \"boolean\") return String(val);\n    if (type === \"function\") return '\"[function]\"';\n    if (type === \"symbol\") return '\"[symbol]\"';\n\n    if (Array.isArray(val)) {\n      // Check for circular reference\n      if (seen.has(val)) {\n        return '\"[circular]\"';\n      }\n      seen.add(val);\n      const result = `[${val.map((v) => stringify(v, depth + 1)).join(\",\")}]`;\n      seen.delete(val);\n      return result;\n    }\n\n    if (type === \"object\") {\n      const obj = val as Record<string, unknown>;\n      // Check for circular reference\n      if (seen.has(obj)) {\n        return '\"[circular]\"';\n      }\n      seen.add(obj);\n      const keys = Object.keys(obj).sort();\n      const pairs = keys.map(\n        (k) => `${JSON.stringify(k)}:${stringify(obj[k], depth + 1)}`,\n      );\n      const result = `{${pairs.join(\",\")}}`;\n      seen.delete(obj);\n      return result;\n    }\n\n    return '\"[unknown]\"';\n  }\n\n  return 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  const dangerousKeys = new Set([\"__proto__\", \"constructor\", \"prototype\"]);\n  const seen = new WeakSet();\n\n  function check(val: unknown, depth: number): boolean {\n    if (depth > maxDepth) return false; // Fail safe at max depth - don't assume safety\n    if (val === null || val === undefined) return true;\n    if (typeof val !== \"object\") return true;\n\n    const objVal = val as Record<string, unknown>;\n\n    // Check for circular reference\n    if (seen.has(objVal)) return true;\n    seen.add(objVal);\n\n    // Check array elements\n    if (Array.isArray(objVal)) {\n      for (const item of objVal) {\n        if (!check(item, depth + 1)) {\n          seen.delete(objVal);\n          return false;\n        }\n      }\n      seen.delete(objVal);\n      return true;\n    }\n\n    // Check object keys and values\n    for (const key of Object.keys(objVal)) {\n      if (dangerousKeys.has(key)) {\n        seen.delete(objVal);\n        return false;\n      }\n      if (!check(objVal[key], depth + 1)) {\n        seen.delete(objVal);\n        return false;\n      }\n    }\n\n    seen.delete(objVal);\n    return true;\n  }\n\n  return 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>>(\n  a: T,\n  b: T,\n): boolean {\n  if (a === b) return true;\n  if (!a || !b) return false;\n\n  const keysA = Object.keys(a);\n  const keysB = Object.keys(b);\n\n  if (keysA.length !== keysB.length) return false;\n\n  for (const key of keysA) {\n    if (a[key] !== b[key]) return false;\n  }\n\n  return 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  const str = stableStringify(value);\n  let hash = 5381;\n  for (let i = 0; i < str.length; i++) {\n    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);\n  }\n  // Convert to unsigned 32-bit and then to hex\n  return (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  data: T;\n  createdAt: number;\n  expiresAt?: number;\n  version?: string;\n  metadata?: 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  snapshot: DistributableSnapshotLike<T>,\n  now: number = Date.now(),\n): boolean {\n  return 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  snapshot: DistributableSnapshotLike<T>,\n  now: number = Date.now(),\n): T {\n  // Structural validation\n  if (!snapshot || typeof snapshot !== \"object\") {\n    throw new Error(\n      \"[Directive] Invalid snapshot: expected an object with 'data' and 'createdAt' properties.\",\n    );\n  }\n  if (!(\"data\" in snapshot)) {\n    throw new Error(\n      \"[Directive] Invalid snapshot: missing required 'data' property.\",\n    );\n  }\n  if (!(\"createdAt\" in snapshot) || typeof snapshot.createdAt !== \"number\") {\n    throw new Error(\n      \"[Directive] Invalid snapshot: missing or invalid 'createdAt' property (expected number).\",\n    );\n  }\n\n  // Expiration validation\n  if (isSnapshotExpired(snapshot, now)) {\n    const expiredAt = new Date(snapshot.expiresAt!).toISOString();\n    throw new Error(\n      `[Directive] Snapshot expired at ${expiredAt}. Obtain a fresh snapshot from the source.`,\n    );\n  }\n  return snapshot.data;\n}\n\n/**\n * Diff result for a single changed value.\n */\nexport interface SnapshotDiffEntry {\n  /** The key path that changed (e.g., \"canUseApi\" or \"limits.apiCalls\") */\n  path: string;\n  /** The value in the old snapshot */\n  oldValue: unknown;\n  /** The value in the new snapshot */\n  newValue: unknown;\n  /** Type of change: \"added\", \"removed\", or \"changed\" */\n  type: \"added\" | \"removed\" | \"changed\";\n}\n\n/**\n * Result of diffing two snapshots.\n */\nexport interface SnapshotDiff {\n  /** Whether the snapshots are identical */\n  identical: boolean;\n  /** List of changes between snapshots */\n  changes: SnapshotDiffEntry[];\n  /** Whether the version changed (if both have versions) */\n  versionChanged: boolean;\n  /** Old version (if available) */\n  oldVersion?: string;\n  /** New version (if available) */\n  newVersion?: 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  oldSnapshot: DistributableSnapshotLike<T>,\n  newSnapshot: DistributableSnapshotLike<T>,\n): SnapshotDiff {\n  const changes: SnapshotDiffEntry[] = [];\n\n  // Deep compare function\n  function compare(oldObj: unknown, newObj: unknown, path: string): void {\n    // Handle null/undefined\n    if (oldObj === null || oldObj === undefined) {\n      if (newObj !== null && newObj !== undefined) {\n        changes.push({\n          path,\n          oldValue: oldObj,\n          newValue: newObj,\n          type: \"added\",\n        });\n      }\n      return;\n    }\n    if (newObj === null || newObj === undefined) {\n      changes.push({\n        path,\n        oldValue: oldObj,\n        newValue: newObj,\n        type: \"removed\",\n      });\n      return;\n    }\n\n    // Handle primitives\n    if (typeof oldObj !== \"object\" || typeof newObj !== \"object\") {\n      if (!Object.is(oldObj, newObj)) {\n        changes.push({\n          path,\n          oldValue: oldObj,\n          newValue: newObj,\n          type: \"changed\",\n        });\n      }\n      return;\n    }\n\n    // Handle arrays\n    if (Array.isArray(oldObj) && Array.isArray(newObj)) {\n      if (oldObj.length !== newObj.length) {\n        changes.push({\n          path,\n          oldValue: oldObj,\n          newValue: newObj,\n          type: \"changed\",\n        });\n        return;\n      }\n      for (let i = 0; i < oldObj.length; i++) {\n        compare(oldObj[i], newObj[i], `${path}[${i}]`);\n      }\n      return;\n    }\n\n    // Handle objects\n    const oldRecord = oldObj as Record<string, unknown>;\n    const newRecord = newObj as Record<string, unknown>;\n    const allKeys = new Set([\n      ...Object.keys(oldRecord),\n      ...Object.keys(newRecord),\n    ]);\n\n    for (const key of allKeys) {\n      const childPath = path ? `${path}.${key}` : key;\n      if (!(key in oldRecord)) {\n        changes.push({\n          path: childPath,\n          oldValue: undefined,\n          newValue: newRecord[key],\n          type: \"added\",\n        });\n      } else if (!(key in newRecord)) {\n        changes.push({\n          path: childPath,\n          oldValue: oldRecord[key],\n          newValue: undefined,\n          type: \"removed\",\n        });\n      } else {\n        compare(oldRecord[key], newRecord[key], childPath);\n      }\n    }\n  }\n\n  // Compare data\n  compare(oldSnapshot.data, newSnapshot.data, \"\");\n\n  // Check version change\n  const versionChanged =\n    oldSnapshot.version !== newSnapshot.version &&\n    (oldSnapshot.version !== undefined || newSnapshot.version !== undefined);\n\n  return {\n    identical: changes.length === 0,\n    changes,\n    versionChanged,\n    oldVersion: oldSnapshot.version,\n    newVersion: newSnapshot.version,\n  };\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  extends DistributableSnapshotLike<T> {\n  /** HMAC-SHA256 signature in hex format */\n  signature: string;\n  /** Signing algorithm used */\n  algorithm: \"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  snapshot: DistributableSnapshotLike<T> | SignedSnapshot<T>,\n): snapshot is SignedSnapshot<T> {\n  return \"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  snapshot: DistributableSnapshotLike<T>,\n  secret: string | Uint8Array,\n): Promise<SignedSnapshot<T>> {\n  // Create a canonical representation for signing\n  const payload = stableStringify({\n    data: snapshot.data,\n    createdAt: snapshot.createdAt,\n    expiresAt: snapshot.expiresAt,\n    version: snapshot.version,\n    metadata: snapshot.metadata,\n  });\n\n  const signature = await hmacSha256(payload, secret);\n\n  return {\n    ...snapshot,\n    signature,\n    algorithm: \"hmac-sha256\",\n  };\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  signedSnapshot: SignedSnapshot<T>,\n  secret: string | Uint8Array,\n): Promise<boolean> {\n  if (!signedSnapshot.signature || signedSnapshot.algorithm !== \"hmac-sha256\") {\n    return false;\n  }\n\n  // Recreate the canonical payload (same as signing)\n  const payload = stableStringify({\n    data: signedSnapshot.data,\n    createdAt: signedSnapshot.createdAt,\n    expiresAt: signedSnapshot.expiresAt,\n    version: signedSnapshot.version,\n    metadata: signedSnapshot.metadata,\n  });\n\n  const expectedSignature = await hmacSha256(payload, secret);\n\n  // Use timing-safe comparison\n  return 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  message: string,\n  secret: string | Uint8Array,\n): Promise<string> {\n  // Convert secret to Uint8Array if string\n  const secretBytes: Uint8Array =\n    typeof secret === \"string\" ? new TextEncoder().encode(secret) : secret;\n\n  // Import key for HMAC\n  const algorithm: HmacImportParams = {\n    name: \"HMAC\",\n    hash: { name: \"SHA-256\" },\n  };\n  const key = await crypto.subtle.importKey(\n    \"raw\",\n    secretBytes as unknown as ArrayBuffer,\n    algorithm,\n    false,\n    [\"sign\"],\n  );\n\n  // Sign the message\n  const messageBytes = new TextEncoder().encode(message);\n  const signature = await crypto.subtle.sign(\"HMAC\", key, messageBytes);\n\n  // Convert to hex string\n  return Array.from(new Uint8Array(signature))\n    .map((b) => b.toString(16).padStart(2, \"0\"))\n    .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  if (a.length !== b.length) {\n    return false;\n  }\n\n  let result = 0;\n  for (let i = 0; i < a.length; i++) {\n    result |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n  return 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 { withTracking } from \"./core/tracking.js\";\nimport type {\n  HistoryAPI,\n  HistoryState,\n  SnapshotMeta,\n  SystemInspection,\n} from \"./core/types.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  readonly isSettled: boolean;\n  readonly history: HistoryAPI | null;\n  readonly facts: {\n    $store: {\n      get(key: string): unknown;\n      has(key: string): boolean;\n      toObject(): Record<string, unknown>;\n    };\n  };\n  readonly derive?: Record<string, unknown>;\n  read(key: string): unknown;\n  inspect(): 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  /** Array of unmet requirements waiting to be resolved */\n  unmet: Array<{\n    id: string;\n    requirement: { type: string; [key: string]: unknown };\n    fromConstraint: string;\n  }>;\n  /** Array of requirements currently being resolved */\n  inflight: Array<{ id: string; resolverId: string; startedAt: number }>;\n  /** Whether there are any unmet requirements */\n  hasUnmet: boolean;\n  /** Whether there are any inflight requirements */\n  hasInflight: boolean;\n  /** Whether the system is actively working (has unmet or inflight requirements) */\n  isWorking: 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  /** Whether the system has settled (no pending operations) */\n  isSettled: boolean;\n  /** Array of unmet requirements */\n  unmet: RequirementsState[\"unmet\"];\n  /** Array of inflight requirements */\n  inflight: RequirementsState[\"inflight\"];\n  /** Whether the system is actively working */\n  isWorking: boolean;\n  /** Whether there are any unmet requirements */\n  hasUnmet: boolean;\n  /** Whether there are any inflight requirements */\n  hasInflight: boolean;\n}\n\n/**\n * Information about a single constraint.\n */\nexport interface ConstraintInfo {\n  id: string;\n  active: boolean;\n  priority: 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  const inspection = system.inspect();\n  return {\n    isSettled: system.isSettled,\n    unmet: inspection.unmet,\n    inflight: inspection.inflight,\n    isWorking: inspection.unmet.length > 0 || inspection.inflight.length > 0,\n    hasUnmet: inspection.unmet.length > 0,\n    hasInflight: inspection.inflight.length > 0,\n  };\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  /**\n   * Minimum time between updates in milliseconds.\n   * @default 100\n   */\n  throttleMs?: 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  callback: T,\n  ms: number,\n): { throttled: T; cleanup: () => void } {\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  let lastArgs: Parameters<T> | null = null;\n  let lastCallTime = 0;\n\n  const throttled = ((...args: Parameters<T>) => {\n    const now = Date.now();\n    const timeSinceLastCall = now - lastCallTime;\n\n    if (timeSinceLastCall >= ms) {\n      // Enough time has passed, call immediately\n      lastCallTime = now;\n      callback(...args);\n    } else {\n      // Schedule for later, keeping latest args\n      lastArgs = args;\n      if (!timeoutId) {\n        timeoutId = setTimeout(() => {\n          timeoutId = null;\n          lastCallTime = Date.now();\n          if (lastArgs) {\n            callback(...lastArgs);\n            lastArgs = null;\n          }\n        }, ms - timeSinceLastCall);\n      }\n    }\n  }) as T;\n\n  const cleanup = () => {\n    if (timeoutId) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n    lastArgs = null;\n  };\n\n  return { 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  if (process.env.NODE_ENV !== \"production\" && system == null) {\n    throw new Error(\n      `[Directive] ${hookName}() requires a system instance as the first argument. Received ${system}.`,\n    );\n  }\n}\n\n/** Default equality function using Object.is */\nexport function defaultEquality<T>(a: T, b: T): boolean {\n  return Object.is(a, b);\n}\n\n/**\n * Build a HistoryState object from a system's history instance.\n * Returns null when history is disabled.\n * @internal\n */\nexport function buildHistoryState(\n  system: SystemLike,\n): HistoryState | null {\n  const debug = system.history;\n  if (!debug) return null;\n\n  // Build lightweight metadata array (no facts data)\n  const snapshots: SnapshotMeta[] = debug.snapshots.map((s) => ({\n    id: s.id,\n    timestamp: s.timestamp,\n    trigger: s.trigger,\n  }));\n\n  return {\n    // Navigation state\n    canGoBack: debug.currentIndex > 0,\n    canGoForward: debug.currentIndex < debug.snapshots.length - 1,\n    currentIndex: debug.currentIndex,\n    totalSnapshots: debug.snapshots.length,\n\n    // Snapshot access\n    snapshots,\n    getSnapshotFacts: (id: number): Record<string, unknown> | null => {\n      const snap = debug.snapshots.find((s) => s.id === id);\n      return snap ? snap.facts : null;\n    },\n\n    // Navigation\n    goTo: (snapshotId: number) => debug.goTo(snapshotId),\n    goBack: (steps?: number) => debug.goBack(steps),\n    goForward: (steps?: number) => debug.goForward(steps),\n    replay: () => debug.replay(),\n\n    // Session persistence\n    exportSession: () => debug.export(),\n    importSession: (json: string) => debug.import(json),\n\n    // Changesets\n    beginChangeset: (label: string) => debug.beginChangeset(label),\n    endChangeset: () => debug.endChangeset(),\n\n    // Recording control\n    isPaused: debug.isPaused,\n    pause: () => debug.pause(),\n    resume: () => debug.resume(),\n  };\n}\n\n/**\n * Pick specific fact values from a system's store.\n * @internal\n */\nexport function pickFacts(\n  system: SystemLike,\n  keys: string[],\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  for (const key of keys) {\n    result[key] = system.facts.$store.get(key);\n  }\n  return result;\n}\n\n// ============================================================================\n// Tracked Selector\n// ============================================================================\n\n/** Result of running a selector with tracking. @internal */\nexport interface TrackedSelectorResult<R> {\n  value: R;\n  factKeys: string[];\n  deriveKeys: 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  system: SystemLike,\n  deriveKeySet: Set<string>,\n  selector: (state: Record<string, unknown>) => R,\n): TrackedSelectorResult<R> {\n  const accessedDeriveKeys: string[] = [];\n\n  const stateProxy = new Proxy(\n    {},\n    {\n      get(_, prop: string | symbol) {\n        if (typeof prop !== \"string\") return undefined;\n        if (deriveKeySet.has(prop)) {\n          accessedDeriveKeys.push(prop);\n          return system.read(prop);\n        }\n        return system.facts.$store.get(prop);\n      },\n      has(_, prop: string | symbol) {\n        if (typeof prop !== \"string\") return false;\n        return deriveKeySet.has(prop) || system.facts.$store.has(prop);\n      },\n      ownKeys() {\n        const factKeys = Object.keys(system.facts.$store.toObject());\n        const combined = new Set(factKeys);\n        for (const k of deriveKeySet) combined.add(k);\n        return [...combined];\n      },\n      getOwnPropertyDescriptor() {\n        return { configurable: true, enumerable: true, writable: true };\n      },\n    },\n  );\n\n  const { value, deps } = withTracking(() =>\n    selector(stateProxy as Record<string, unknown>),\n  );\n  return {\n    value,\n    factKeys: Array.from(deps) as string[],\n    deriveKeys: accessedDeriveKeys,\n  };\n}\n\n/**\n * Check if tracked dependency keys have changed.\n * @internal\n */\nexport function depsChanged(\n  prevFacts: string[],\n  newFacts: string[],\n  prevDerived: string[],\n  newDerived: string[],\n): boolean {\n  const factsChanged =\n    newFacts.length !== prevFacts.length ||\n    newFacts.some((k, i) => k !== prevFacts[i]);\n  const derivedChanged =\n    newDerived.length !== prevDerived.length ||\n    newDerived.some((k, i) => k !== prevDerived[i]);\n  return factsChanged || derivedChanged;\n}\n\n// ============================================================================\n// Re-exports from core/types/adapter-utils and utils/utils\n// ============================================================================\n\nexport {\n  setBridgeFact,\n  getBridgeFact,\n  createCallbackPlugin,\n  requirementGuard,\n  requirementGuardMultiple,\n} from \"./core/types/adapter-utils.js\";\n\nexport { shallowEqual } from \"./utils/utils.js\";\n"]}