@signaltree/guardrails 4.0.15 → 4.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @signaltree/guardrails Changelog
+
+## 1.1.0 (2025-11-12)
+
+- Added recomputation tracking, percentile reporting, and diff ratio analysis
+- Implemented memory-leak heuristics, hot-path sampling, and guardrails disposal API
+- Introduced factory helpers (`createFeatureTree`, `createPerformanceTree`, etc.)
+- Integrated guardrails into release automation, bundle analysis, and coverage scripts
+- Published comprehensive documentation set (migration guide, troubleshooting, limitations)
+
+## 1.0.0 (2025-10-??)
+
+- Initial release with core budgets, hot-path detection, and custom rule engine
+- Dev-only exports to guarantee zero production overhead
+

package/README.md

@@ -0,0 +1,51 @@
+# @signaltree/guardrails
+
+> Development-only performance monitoring and anti-pattern detection for SignalTree
+
+## Features
+
+- ✅ **Zero production cost** - Dev-only via conditional exports
+- ✅ **Performance budgets** - Update time, memory, recomputations
+- ✅ **Hot path analysis** - Automatic detection with heat scores
+- ✅ **Memory leak detection** - Retention and growth tracking
+- ✅ **Custom rules engine** - Team-specific policies
+- ✅ **Intent-aware suppression** - Smart noise reduction
+- ✅ **Percentile reporting** - P50/P95/P99 metrics
+
+## Installation
+
+```bash
+npm install --save-dev @signaltree/guardrails
+```
+
+## Quick Start
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { withGuardrails } from '@signaltree/guardrails';
+
+const tree = signalTree({ count: 0 }).with(withGuardrails({
+  budgets: { maxUpdateTime: 16 },
+  hotPaths: { threshold: 10 },
+}));
+```
+
+## Using Factories
+
+```typescript
+import { signalTree } from '@signaltree/core';
+import { createFeatureTree } from '@signaltree/guardrails/factories';
+
+const tree = createFeatureTree(signalTree, { data: [] }, {
+  name: 'dashboard',
+  guardrails: true,
+});
+```
+
+## Configuration
+
+See [docs/guardrails](../../docs/guardrails) for complete documentation.
+
+## License
+
+MIT

package/dist/factories/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/factories/index";

package/dist/factories/index.js

@@ -0,0 +1,119 @@
+import { withGuardrails } from '../lib/guardrails.js';
+import { rules } from '../lib/rules.js';
+
+function isGuardrailsConfig(value) {
+  return Boolean(value) && typeof value === 'object';
+}
+function resolveGuardrailsConfig(guardrails) {
+  if (guardrails === false) {
+    return undefined;
+  }
+  if (isGuardrailsConfig(guardrails)) {
+    return guardrails;
+  }
+  return {
+    budgets: {
+      maxUpdateTime: 16,
+      maxRecomputations: 100
+    },
+    hotPaths: {
+      enabled: true,
+      threshold: 10
+    },
+    reporting: {
+      console: true
+    }
+  };
+}
+function createFeatureTree(signalTree, initial, options) {
+  const env = options.env ?? process?.env?.['NODE_ENV'] ?? 'production';
+  const isDev = env === 'development';
+  const isTest = env === 'test';
+  const enhancers = [];
+  if (isDev || isTest) {
+    const guardrailsConfig = resolveGuardrailsConfig(options.guardrails);
+    if (guardrailsConfig) {
+      enhancers.push(withGuardrails(guardrailsConfig));
+    }
+  }
+  if (options.enhancers?.length) {
+    enhancers.push(...options.enhancers);
+  }
+  let tree = signalTree(initial);
+  for (const enhancer of enhancers) {
+    tree = tree.with(enhancer);
+  }
+  return tree;
+}
+function createAngularFeatureTree(signalTree, initial, options) {
+  const isDev = Boolean(ngDevMode);
+  return createFeatureTree(signalTree, initial, {
+    ...options,
+    env: isDev ? 'development' : 'production'
+  });
+}
+function createAppShellTree(signalTree, initial) {
+  return createFeatureTree(signalTree, initial, {
+    guardrails: {
+      budgets: {
+        maxUpdateTime: 4,
+        maxMemory: 20
+      },
+      hotPaths: {
+        threshold: 5
+      },
+      customRules: [rules.noDeepNesting(3)]
+    }
+  });
+}
+function createPerformanceTree(signalTree, initial, name) {
+  return createFeatureTree(signalTree, initial, {
+    guardrails: {
+      budgets: {
+        maxUpdateTime: 8,
+        maxRecomputations: 200
+      },
+      hotPaths: {
+        threshold: 50
+      },
+      memoryLeaks: {
+        enabled: false
+      },
+      reporting: {
+        interval: 10000
+      }
+    }
+  });
+}
+function createFormTree(signalTree, initial, formName) {
+  return createFeatureTree(signalTree, initial, {
+    guardrails: {
+      customRules: [rules.noDeepNesting(4), rules.maxPayloadSize(50), rules.noSensitiveData()]
+    }
+  });
+}
+function createCacheTree(signalTree, initial) {
+  return createFeatureTree(signalTree, initial, {
+    guardrails: {
+      mode: 'silent',
+      memoryLeaks: {
+        enabled: false
+      }
+    }});
+}
+function createTestTree(signalTree, initial, overrides) {
+  return createFeatureTree(signalTree, initial, {
+    env: 'test',
+    guardrails: {
+      mode: 'throw',
+      budgets: {
+        maxUpdateTime: 5,
+        maxRecomputations: 50
+      },
+      customRules: [rules.noFunctionsInState(), rules.noDeepNesting(4)],
+      ...overrides
+    }
+  });
+}
+
+export { createAngularFeatureTree, createAppShellTree, createCacheTree, createFeatureTree, createFormTree, createPerformanceTree, createTestTree };

package/dist/lib/guardrails.js

@@ -0,0 +1,612 @@
+function isFunction(value) {
+  return typeof value === 'function';
+}
+function isString(value) {
+  return typeof value === 'string';
+}
+function isObjectLike(value) {
+  return typeof value === 'object' && value !== null;
+}
+function resolveEnabledFlag(option) {
+  if (option === undefined) {
+    return true;
+  }
+  if (isFunction(option)) {
+    try {
+      return option();
+    } catch {
+      return true;
+    }
+  }
+  return option;
+}
+function supportsMiddleware(tree) {
+  const candidate = tree;
+  return isFunction(candidate.addTap) && isFunction(candidate.removeTap);
+}
+function tryStructuredClone(value) {
+  const cloneFn = globalThis.structuredClone;
+  if (isFunction(cloneFn)) {
+    try {
+      return cloneFn(value);
+    } catch {}
+  }
+  return value;
+}
+function isDevEnvironment() {
+  if (__DEV__ !== undefined) return __DEV__;
+  if (process?.env?.['NODE_ENV'] === 'production') return false;
+  if (ngDevMode != null) return Boolean(ngDevMode);
+  return true;
+}
+const MAX_TIMING_SAMPLES = 1000;
+const RECOMPUTATION_WINDOW_MS = 1000;
+function withGuardrails(config = {}) {
+  return tree => {
+    const enabled = resolveEnabledFlag(config.enabled);
+    if (!isDevEnvironment() || !enabled) {
+      return tree;
+    }
+    if (!supportsMiddleware(tree)) {
+      console.warn('[Guardrails] Tree does not expose middleware hooks; guardrails disabled.');
+      return tree;
+    }
+    const stats = createRuntimeStats();
+    const context = {
+      tree,
+      config,
+      stats,
+      issues: [],
+      hotPaths: [],
+      currentUpdate: null,
+      suppressed: false,
+      timings: [],
+      hotPathData: new Map(),
+      issueMap: new Map(),
+      signalUsage: new Map(),
+      memoryHistory: [],
+      recomputationLog: [],
+      disposed: false
+    };
+    const middlewareId = `guardrails:${config.treeId ?? 'tree'}:${Math.random().toString(36).slice(2)}`;
+    context.middlewareId = middlewareId;
+    const middleware = createGuardrailsMiddleware(context);
+    tree.addTap(middleware);
+    const stopMonitoring = startMonitoring(context);
+    const teardown = () => {
+      if (context.disposed) return;
+      context.disposed = true;
+      stopMonitoring();
+      try {
+        tree.removeTap(middlewareId);
+      } catch {}
+    };
+    const originalDestroy = tree.destroy?.bind(tree);
+    tree.destroy = () => {
+      teardown();
+      if (originalDestroy) {
+        originalDestroy();
+      }
+    };
+    tree['__guardrails'] = createAPI(context, teardown);
+    return tree;
+  };
+}
+function createRuntimeStats() {
+  return {
+    updateCount: 0,
+    totalUpdateTime: 0,
+    avgUpdateTime: 0,
+    p50UpdateTime: 0,
+    p95UpdateTime: 0,
+    p99UpdateTime: 0,
+    maxUpdateTime: 0,
+    recomputationCount: 0,
+    recomputationsPerSecond: 0,
+    signalCount: 0,
+    signalRetention: 0,
+    unreadSignalCount: 0,
+    memoryGrowthRate: 0,
+    hotPathCount: 0,
+    violationCount: 0
+  };
+}
+function createGuardrailsMiddleware(context) {
+  return {
+    id: context.middlewareId ?? 'guardrails',
+    before: (action, payload, state) => {
+      if (context.suppressed) {
+        context.currentUpdate = null;
+        return !context.disposed;
+      }
+      const metadata = extractMetadata(payload);
+      if (shouldSuppressUpdate(context, metadata)) {
+        context.currentUpdate = null;
+        return !context.disposed;
+      }
+      const details = collectUpdateDetails(payload, state);
+      context.currentUpdate = {
+        action,
+        startTime: performance.now(),
+        metadata,
+        details
+      };
+      for (const detail of details) {
+        analyzePreUpdate(context, detail, metadata);
+      }
+      return !context.disposed;
+    },
+    after: (_action, _payload, _previousState, newState) => {
+      const pending = context.currentUpdate;
+      if (!pending) return;
+      const duration = Math.max(0, performance.now() - pending.startTime);
+      const timestamp = Date.now();
+      const recomputations = Math.max(0, pending.details.length - 1);
+      updateTimingStats(context, duration);
+      for (const [index, detail] of pending.details.entries()) {
+        const latest = getValueAtPath(newState, detail.segments);
+        const diffRatio = calculateDiffRatio(detail.oldValue, latest);
+        analyzePostUpdate(context, detail, duration, diffRatio, index === 0);
+        trackHotPath(context, detail.path, duration);
+        trackSignalUsage(context, detail.path, timestamp);
+      }
+      updateSignalStats(context, timestamp);
+      recordRecomputations(context, recomputations, timestamp);
+      context.currentUpdate = null;
+    }
+  };
+}
+function updatePercentiles(context) {
+  if (context.timings.length === 0) return;
+  const sorted = [...context.timings].sort((a, b) => a - b);
+  context.stats.p50UpdateTime = sorted[Math.floor(sorted.length * 0.5)] || 0;
+  context.stats.p95UpdateTime = sorted[Math.floor(sorted.length * 0.95)] || 0;
+  context.stats.p99UpdateTime = sorted[Math.floor(sorted.length * 0.99)] || 0;
+}
+function calculateDiffRatio(oldValue, newValue) {
+  if (!isComparableRecord(oldValue) || !isComparableRecord(newValue)) {
+    return Object.is(oldValue, newValue) ? 0 : 1;
+  }
+  if (oldValue === newValue) return 0;
+  const oldKeys = new Set(Object.keys(oldValue));
+  const newKeys = new Set(Object.keys(newValue));
+  const allKeys = new Set([...oldKeys, ...newKeys]);
+  let changed = 0;
+  for (const key of allKeys) {
+    if (!oldKeys.has(key) || !newKeys.has(key) || oldValue[key] !== newValue[key]) {
+      changed++;
+    }
+  }
+  return allKeys.size === 0 ? 0 : changed / allKeys.size;
+}
+function analyzePreUpdate(context, detail, metadata) {
+  if (!context.config.customRules) return;
+  for (const rule of context.config.customRules) {
+    evaluateRule(context, rule, {
+      path: detail.segments,
+      value: detail.newValue,
+      oldValue: detail.oldValue,
+      metadata,
+      tree: context.tree,
+      stats: context.stats
+    });
+  }
+}
+function analyzePostUpdate(context, detail, duration, diffRatio, isPrimary) {
+  if (isPrimary && context.config.budgets?.maxUpdateTime && duration > context.config.budgets.maxUpdateTime) {
+    addIssue(context, {
+      type: 'budget',
+      severity: 'error',
+      message: `Update took ${duration.toFixed(2)}ms (budget: ${context.config.budgets.maxUpdateTime}ms)`,
+      path: detail.path,
+      count: 1
+    });
+  }
+  const minDiff = context.config.analysis?.minDiffForParentReplace ?? 0.8;
+  if (context.config.analysis?.warnParentReplace && diffRatio > minDiff) {
+    addIssue(context, {
+      type: 'analysis',
+      severity: 'warning',
+      message: `High diff ratio (${(diffRatio * 100).toFixed(0)}%) - consider scoped updates`,
+      path: detail.path,
+      count: 1,
+      diffRatio
+    });
+  }
+}
+function trackHotPath(context, path, duration) {
+  if (!context.config.hotPaths?.enabled) return;
+  const pathKey = Array.isArray(path) ? path.join('.') : path;
+  const now = Date.now();
+  const windowMs = context.config.hotPaths.windowMs || 1000;
+  let data = context.hotPathData.get(pathKey);
+  if (!data) {
+    data = {
+      count: 0,
+      lastUpdate: now,
+      durations: []
+    };
+    context.hotPathData.set(pathKey, data);
+  }
+  if (now - data.lastUpdate > windowMs) {
+    data.count = 0;
+    data.durations = [];
+  }
+  data.count++;
+  data.durations.push(duration);
+  data.lastUpdate = now;
+  const threshold = context.config.hotPaths.threshold || 10;
+  const updatesPerSecond = data.count / windowMs * 1000;
+  if (updatesPerSecond > threshold) {
+    const sorted = [...data.durations].sort((a, b) => a - b);
+    const p95 = sorted[Math.floor(sorted.length * 0.95)] || 0;
+    const avg = data.durations.reduce((sum, d) => sum + d, 0) / data.durations.length;
+    updateHotPath(context, {
+      path: pathKey,
+      updatesPerSecond,
+      heatScore: Math.min(100, updatesPerSecond / threshold * 50),
+      downstreamEffects: 0,
+      avgDuration: avg,
+      p95Duration: p95
+    });
+  }
+}
+function trackSignalUsage(context, path, timestamp) {
+  const key = Array.isArray(path) ? path.join('.') : path;
+  const entry = context.signalUsage.get(key) ?? {
+    updates: 0,
+    lastSeen: timestamp
+  };
+  entry.updates += 1;
+  entry.lastSeen = timestamp;
+  context.signalUsage.set(key, entry);
+}
+function updateSignalStats(context, timestamp) {
+  const retentionWindow = context.config.memoryLeaks?.checkInterval ?? 5000;
+  const historyWindow = Math.max(retentionWindow, 1000);
+  const signalCount = context.signalUsage.size;
+  context.stats.signalCount = signalCount;
+  const staleCount = [...context.signalUsage.values()].filter(entry => timestamp - entry.lastSeen > retentionWindow).length;
+  context.stats.signalRetention = staleCount;
+  context.stats.unreadSignalCount = 0;
+  context.memoryHistory.push({
+    timestamp,
+    count: signalCount
+  });
+  context.memoryHistory = context.memoryHistory.filter(entry => timestamp - entry.timestamp <= historyWindow);
+  const baseline = context.memoryHistory[0]?.count ?? signalCount;
+  const growth = baseline === 0 ? 0 : (signalCount - baseline) / Math.max(1, baseline);
+  context.stats.memoryGrowthRate = growth;
+}
+function recordRecomputations(context, count, timestamp) {
+  if (count > 0) {
+    context.stats.recomputationCount += count;
+    for (let i = 0; i < count; i++) {
+      context.recomputationLog.push(timestamp);
+    }
+  }
+  if (context.recomputationLog.length) {
+    context.recomputationLog = context.recomputationLog.filter(value => timestamp - value <= RECOMPUTATION_WINDOW_MS);
+  }
+  context.stats.recomputationsPerSecond = context.recomputationLog.length;
+}
+function updateHotPath(context, hotPath) {
+  const existing = context.hotPaths.find(h => h.path === hotPath.path);
+  if (existing) {
+    Object.assign(existing, hotPath);
+  } else {
+    context.hotPaths.push(hotPath);
+    const topN = context.config.hotPaths?.topN || 5;
+    if (context.hotPaths.length > topN) {
+      context.hotPaths.sort((a, b) => b.heatScore - a.heatScore);
+      context.hotPaths.length = topN;
+    }
+  }
+  context.stats.hotPathCount = context.hotPaths.length;
+}
+function evaluateRule(context, rule, ruleContext) {
+  const handleFailure = () => {
+    const message = typeof rule.message === 'function' ? rule.message(ruleContext) : rule.message;
+    addIssue(context, {
+      type: 'rule',
+      severity: rule.severity || 'warning',
+      message,
+      path: ruleContext.path.join('.'),
+      count: 1,
+      metadata: {
+        rule: rule.name
+      }
+    });
+  };
+  try {
+    const result = rule.test(ruleContext);
+    if (result instanceof Promise) {
+      result.then(outcome => {
+        if (!outcome) {
+          handleFailure();
+        }
+      }).catch(error => {
+        console.warn(`[Guardrails] Rule ${rule.name} rejected:`, error);
+      });
+      return;
+    }
+    if (!result) {
+      handleFailure();
+    }
+  } catch (error) {
+    console.warn(`[Guardrails] Rule ${rule.name} threw error:`, error);
+  }
+}
+function addIssue(context, issue) {
+  if (context.suppressed) return;
+  if (context.config.reporting?.aggregateWarnings !== false) {
+    const key = `${issue.type}:${issue.path}:${issue.message}`;
+    const existing = context.issueMap.get(key);
+    if (existing) {
+      existing.count++;
+      return;
+    }
+    context.issueMap.set(key, issue);
+  }
+  context.issues.push(issue);
+  context.stats.violationCount++;
+  if (context.config.mode === 'throw') {
+    throw new Error(`[Guardrails] ${issue.message}`);
+  }
+}
+function shouldSuppressUpdate(context, metadata) {
+  if (context.suppressed) return true;
+  if (!metadata) return false;
+  if (metadata.suppressGuardrails && context.config.suppression?.respectMetadata !== false) {
+    return true;
+  }
+  const autoSuppress = new Set(context.config.suppression?.autoSuppress ?? []);
+  return [metadata.intent, metadata.source].some(value => isString(value) && autoSuppress.has(value));
+}
+function startMonitoring(context) {
+  const interval = setInterval(() => {
+    if (context.disposed) {
+      clearInterval(interval);
+      return;
+    }
+    checkMemory(context);
+    maybeReport(context);
+  }, context.config.reporting?.interval || 5000);
+  return () => clearInterval(interval);
+}
+function checkMemory(context) {
+  if (!context.config.memoryLeaks?.enabled) return;
+  const now = Date.now();
+  const retentionWindow = context.config.memoryLeaks?.checkInterval ?? 5000;
+  const retentionThreshold = context.config.memoryLeaks?.retentionThreshold ?? 100;
+  const growthThreshold = context.config.memoryLeaks?.growthRate ?? 0.2;
+  const staleCount = [...context.signalUsage.values()].filter(entry => now - entry.lastSeen > retentionWindow).length;
+  context.stats.signalRetention = staleCount;
+  const exceedsRetention = context.stats.signalRetention > retentionThreshold;
+  const exceedsGrowth = context.stats.memoryGrowthRate > growthThreshold;
+  if (exceedsRetention || exceedsGrowth) {
+    addIssue(context, {
+      type: 'memory',
+      severity: 'warning',
+      message: `Potential memory leak detected (signals: ${context.stats.signalCount}, growth ${(context.stats.memoryGrowthRate * 100).toFixed(1)}%)`,
+      path: 'root',
+      count: 1,
+      metadata: {
+        signalCount: context.stats.signalCount,
+        growth: context.stats.memoryGrowthRate
+      }
+    });
+  }
+}
+function maybeReport(context) {
+  if (context.config.reporting?.console === false) return;
+  const report = generateReport(context);
+  if (context.config.reporting?.customReporter) {
+    context.config.reporting.customReporter(report);
+  }
+  if (context.config.reporting?.console && context.issues.length > 0) {
+    reportToConsole(report, context.config.reporting.console === 'verbose');
+  }
+  context.issues = [];
+  context.issueMap.clear();
+}
+function reportToConsole(report, verbose) {
+  console.group('[Guardrails] Performance Report');
+  logIssues(report.issues);
+  logHotPaths(report.hotPaths);
+  if (verbose) {
+    logVerboseStats(report);
+  }
+  console.groupEnd();
+}
+function logIssues(issues) {
+  if (issues.length === 0) return;
+  console.warn(`${issues.length} issues detected:`);
+  for (const issue of issues) {
+    const prefix = getSeverityPrefix(issue.severity);
+    const countSuffix = issue.count > 1 ? ` (x${issue.count})` : '';
+    const message = `${prefix} [${issue.type}] ${issue.message}${countSuffix}`;
+    console.log(`  ${message}`);
+  }
+}
+function logHotPaths(hotPaths) {
+  if (hotPaths.length === 0) return;
+  console.log(`\nHot Paths (${hotPaths.length}):`);
+  for (const hp of hotPaths) {
+    const entry = `  🔥 ${hp.path}: ${hp.updatesPerSecond.toFixed(1)}/s (heat: ${hp.heatScore.toFixed(0)})`;
+    console.log(entry);
+  }
+}
+function logVerboseStats(report) {
+  console.log('\nStats:', report.stats);
+  console.log('Budgets:', report.budgets);
+}
+function getSeverityPrefix(severity) {
+  if (severity === 'error') return '❌';
+  if (severity === 'warning') return '⚠️';
+  return 'ℹ️';
+}
+function generateReport(context) {
+  const memoryCurrent = context.stats.signalCount;
+  const memoryLimit = context.config.budgets?.maxMemory ?? 50;
+  const recomputationCurrent = context.stats.recomputationsPerSecond;
+  const recomputationLimit = context.config.budgets?.maxRecomputations ?? 100;
+  const budgets = {
+    updateTime: createBudgetItem(context.stats.avgUpdateTime, context.config.budgets?.maxUpdateTime || 16),
+    memory: createBudgetItem(memoryCurrent, memoryLimit),
+    recomputations: createBudgetItem(recomputationCurrent, recomputationLimit)
+  };
+  return {
+    timestamp: Date.now(),
+    treeId: context.config.treeId,
+    issues: Array.from(context.issueMap.values()),
+    hotPaths: context.hotPaths,
+    budgets,
+    stats: context.stats,
+    recommendations: generateRecommendations(context)
+  };
+}
+function createBudgetItem(current, limit) {
+  if (limit <= 0) {
+    return {
+      current,
+      limit,
+      usage: 0,
+      status: 'ok'
+    };
+  }
+  const usage = current / limit * 100;
+  const threshold = 80;
+  let status;
+  if (usage > 100) {
+    status = 'exceeded';
+  } else if (usage > threshold) {
+    status = 'warning';
+  } else {
+    status = 'ok';
+  }
+  return {
+    current,
+    limit,
+    usage,
+    status
+  };
+}
+function generateRecommendations(context) {
+  const recommendations = [];
+  if (context.hotPaths.length > 0) {
+    recommendations.push('Consider batching or debouncing updates to hot paths');
+  }
+  if (context.stats.avgUpdateTime > 10) {
+    recommendations.push('Average update time is high - review update logic');
+  }
+  return recommendations;
+}
+function createAPI(context, teardown) {
+  return {
+    getReport: () => generateReport(context),
+    getStats: () => context.stats,
+    suppress: fn => {
+      const was = context.suppressed;
+      context.suppressed = true;
+      try {
+        fn();
+      } finally {
+        context.suppressed = was;
+      }
+    },
+    dispose: () => {
+      teardown();
+      const finalReport = generateReport(context);
+      if (context.config.reporting?.console !== false) {
+        console.log('[Guardrails] Final report on disposal:', finalReport);
+      }
+      if (context.config.reporting?.customReporter) {
+        context.config.reporting.customReporter(finalReport);
+      }
+    }
+  };
+}
+function extractMetadata(payload) {
+  if (!isObjectLike(payload)) return undefined;
+  const candidate = payload['metadata'];
+  return isObjectLike(candidate) ? candidate : undefined;
+}
+function collectUpdateDetails(payload, stateSnapshot) {
+  const details = [];
+  const visit = (value, segments, currentState) => {
+    const path = segments.length ? segments.join('.') : 'root';
+    const oldValue = captureValue(currentState);
+    if (isObjectLike(value)) {
+      details.push({
+        path,
+        segments: [...segments],
+        newValue: value,
+        oldValue
+      });
+      for (const [key, child] of Object.entries(value)) {
+        visit(child, [...segments, key], isObjectLike(currentState) ? currentState[key] : undefined);
+      }
+      return;
+    }
+    details.push({
+      path,
+      segments: [...segments],
+      newValue: value,
+      oldValue
+    });
+  };
+  if (isObjectLike(payload)) {
+    visit(payload, [], stateSnapshot);
+  } else {
+    details.push({
+      path: 'root',
+      segments: [],
+      newValue: payload,
+      oldValue: captureValue(stateSnapshot)
+    });
+  }
+  if (details.length === 0) {
+    details.push({
+      path: 'root',
+      segments: [],
+      newValue: payload,
+      oldValue: captureValue(stateSnapshot)
+    });
+  }
+  return details;
+}
+function getValueAtPath(source, segments) {
+  let current = source;
+  for (const segment of segments) {
+    if (!isObjectLike(current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function captureValue(value) {
+  return tryStructuredClone(value);
+}
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function updateTimingStats(context, duration) {
+  context.timings.push(duration);
+  if (context.timings.length > MAX_TIMING_SAMPLES) {
+    context.timings.shift();
+  }
+  context.stats.updateCount++;
+  context.stats.totalUpdateTime += duration;
+  context.stats.avgUpdateTime = context.stats.totalUpdateTime / context.stats.updateCount;
+  context.stats.maxUpdateTime = Math.max(context.stats.maxUpdateTime, duration);
+  updatePercentiles(context);
+}
+function isComparableRecord(value) {
+  return isPlainObject(value);
+}
+
+export { withGuardrails };

package/dist/lib/rules.js

@@ -0,0 +1,62 @@
+const rules = {
+  noDeepNesting: (maxDepth = 5) => ({
+    name: 'no-deep-nesting',
+    description: `Prevents nesting deeper than ${maxDepth} levels`,
+    test: ctx => ctx.path.length <= maxDepth,
+    message: ctx => `Path too deep: ${ctx.path.join('.')} (${ctx.path.length} levels, max: ${maxDepth})`,
+    severity: 'warning',
+    tags: ['architecture', 'complexity']
+  }),
+  noFunctionsInState: () => ({
+    name: 'no-functions',
+    description: 'Functions break serialization',
+    test: ctx => typeof ctx.value !== 'function',
+    message: 'Functions cannot be stored in state (breaks serialization)',
+    severity: 'error',
+    tags: ['serialization', 'data']
+  }),
+  noCacheInPersistence: () => ({
+    name: 'no-cache-persistence',
+    description: 'Prevent cache from being persisted',
+    test: ctx => {
+      if (ctx.metadata?.source === 'serialization' && ctx.path.includes('cache')) {
+        return false;
+      }
+      return true;
+    },
+    message: 'Cache should not be persisted',
+    severity: 'warning',
+    tags: ['persistence', 'cache']
+  }),
+  maxPayloadSize: (maxKB = 100) => ({
+    name: 'max-payload-size',
+    description: `Limit payload size to ${maxKB}KB`,
+    test: ctx => {
+      try {
+        const size = JSON.stringify(ctx.value).length;
+        return size < maxKB * 1024;
+      } catch {
+        return true;
+      }
+    },
+    message: ctx => {
+      const size = JSON.stringify(ctx.value).length;
+      const kb = (size / 1024).toFixed(1);
+      return `Payload size ${kb}KB exceeds limit of ${maxKB}KB`;
+    },
+    severity: 'warning',
+    tags: ['performance', 'data']
+  }),
+  noSensitiveData: (sensitiveKeys = ['password', 'token', 'secret', 'apiKey']) => ({
+    name: 'no-sensitive-data',
+    description: 'Prevents storing sensitive data',
+    test: ctx => {
+      return !ctx.path.some(segment => sensitiveKeys.some(key => typeof segment === 'string' && segment.toLowerCase().includes(key.toLowerCase())));
+    },
+    message: ctx => `Sensitive data detected in path: ${ctx.path.join('.')}`,
+    severity: 'error',
+    tags: ['security', 'data']
+  })
+};
+
+export { rules };

package/dist/noop.d.ts

@@ -0,0 +1 @@
+export * from "./src/noop";

package/dist/noop.js

@@ -0,0 +1,21 @@
+const noopRule = name => ({
+  name,
+  description: 'No-op guardrail',
+  test: () => true,
+  message: '',
+  severity: 'info'
+});
+function withGuardrails(config) {
+  return tree => {
+    return tree;
+  };
+}
+const rules = {
+  noDeepNesting: () => noopRule('noop'),
+  noFunctionsInState: () => noopRule('noop'),
+  noCacheInPersistence: () => noopRule('noop'),
+  maxPayloadSize: () => noopRule('noop'),
+  noSensitiveData: () => noopRule('noop')
+};
+
+export { rules, withGuardrails };

package/package.json

@@ -1,60 +1,69 @@
 {
   "name": "@signaltree/guardrails",
-  "version": "4.0.15",
+  "version": "4.1.0",
   "description": "Development-only performance monitoring and anti-pattern detection for SignalTree",
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/lib/guardrails.js",
+  "module": "./dist/lib/guardrails.js",
+  "types": "./src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./src/index.d.ts",
       "development": {
-        "import": "./dist/index.js",
-        "require": "./dist/index.cjs"
+        "import": "./dist/lib/guardrails.js",
+        "default": "./dist/lib/guardrails.js"
       },
       "production": {
         "import": "./dist/noop.js",
-        "require": "./dist/noop.cjs"
+        "default": "./dist/noop.js"
       },
       "default": "./dist/noop.js"
     },
     "./factories": {
-      "types": "./dist/factories/index.d.ts",
+      "types": "./src/factories/index.d.ts",
       "development": {
         "import": "./dist/factories/index.js",
-        "require": "./dist/factories/index.cjs"
+        "default": "./dist/factories/index.js"
       },
       "production": {
         "import": "./dist/noop.js",
-        "require": "./dist/noop.cjs"
+        "default": "./dist/noop.js"
       },
       "default": "./dist/noop.js"
     },
+    "./noop": {
+      "types": "./src/noop.d.ts",
+      "import": "./dist/noop.js",
+      "default": "./dist/noop.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsup",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint src --ext .ts",
-    "type-check": "tsc --noEmit"
+    "build": "nx build guardrails",
+    "test": "nx test guardrails",
+    "lint": "nx lint guardrails",
+    "test:watch": "nx test guardrails --watch",
+    "test:coverage": "nx test guardrails --coverage",
+    "type-check": "tsc --project tsconfig.lib.json --noEmit"
   },
   "peerDependencies": {
-    "@signaltree/core": "^4.0.0"
+    "@signaltree/core": "^4.1.0",
+    "tslib": "^2.0.0"
   },
   "devDependencies": {
     "@signaltree/core": "workspace:*",
     "@signaltree/shared": "workspace:*",
-    "@signaltree/types": "workspace:*",
-    "tsup": "^8.0.0"
+    "@signaltree/types": "workspace:*"
   },
   "keywords": [
     "signaltree",

package/src/factories/index.d.ts

@@ -0,0 +1,20 @@
+import type { SignalTree, TreeConfig } from '@signaltree/core';
+import type { GuardrailsConfig } from '../lib/types';
+type SignalTreeFactory<T extends Record<string, unknown>> = (initial: T, config?: TreeConfig) => SignalTree<T>;
+type EnhancerFn<T extends Record<string, unknown>> = (tree: SignalTree<T>) => SignalTree<T>;
+interface FeatureTreeOptions<T extends Record<string, unknown>> {
+    name: string;
+    env?: 'development' | 'test' | 'staging' | 'production';
+    persistence?: boolean | Record<string, unknown>;
+    guardrails?: boolean | GuardrailsConfig;
+    devtools?: boolean;
+    enhancers?: EnhancerFn<T>[];
+}
+export declare function createFeatureTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T, options: FeatureTreeOptions<T>): SignalTree<T>;
+export declare function createAngularFeatureTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T, options: Omit<FeatureTreeOptions<T>, 'env'>): SignalTree<T>;
+export declare function createAppShellTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T): SignalTree<T>;
+export declare function createPerformanceTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T, name: string): SignalTree<T>;
+export declare function createFormTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T, formName: string): SignalTree<T>;
+export declare function createCacheTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T): SignalTree<T>;
+export declare function createTestTree<T extends Record<string, unknown>>(signalTree: SignalTreeFactory<T>, initial: T, overrides?: Partial<GuardrailsConfig>): SignalTree<T>;
+export {};

package/src/index.d.ts

@@ -0,0 +1,4 @@
+import { withGuardrails } from './lib/guardrails';
+import { rules } from './lib/rules';
+export { withGuardrails, rules };
+export type * from './lib/types';

package/src/lib/guardrails.d.ts

@@ -0,0 +1,3 @@
+import type { SignalTree } from '@signaltree/core';
+import type { GuardrailsConfig } from './types';
+export declare function withGuardrails<T extends Record<string, unknown>>(config?: GuardrailsConfig<T>): (tree: SignalTree<T>) => SignalTree<T>;

package/src/lib/rules.d.ts

@@ -0,0 +1,8 @@
+import type { GuardrailRule } from './types';
+export declare const rules: {
+    noDeepNesting: (maxDepth?: number) => GuardrailRule;
+    noFunctionsInState: () => GuardrailRule;
+    noCacheInPersistence: () => GuardrailRule;
+    maxPayloadSize: (maxKB?: number) => GuardrailRule;
+    noSensitiveData: (sensitiveKeys?: string[]) => GuardrailRule;
+};

package/src/lib/types.d.ts

@@ -0,0 +1,138 @@
+import type { SignalTree } from '@signaltree/core';
+export interface GuardrailsConfig<T extends Record<string, unknown> = Record<string, unknown>> {
+    mode?: 'warn' | 'throw' | 'silent';
+    enabled?: boolean | (() => boolean);
+    budgets?: {
+        maxUpdateTime?: number;
+        maxMemory?: number;
+        maxRecomputations?: number;
+        maxTreeDepth?: number;
+        alertThreshold?: number;
+    };
+    hotPaths?: {
+        enabled?: boolean;
+        threshold?: number;
+        topN?: number;
+        trackDownstream?: boolean;
+        windowMs?: number;
+    };
+    memoryLeaks?: {
+        enabled?: boolean;
+        checkInterval?: number;
+        retentionThreshold?: number;
+        growthRate?: number;
+        trackUnread?: boolean;
+    };
+    customRules?: GuardrailRule<T>[];
+    suppression?: {
+        autoSuppress?: Array<'hydrate' | 'reset' | 'bulk' | 'migration' | 'time-travel' | 'serialization'>;
+        respectMetadata?: boolean;
+    };
+    analysis?: {
+        forbidRootRead?: boolean;
+        forbidSliceRootRead?: boolean | string[];
+        maxDepsPerComputed?: number;
+        warnParentReplace?: boolean;
+        minDiffForParentReplace?: number;
+        detectThrashing?: boolean;
+        maxRerunsPerSecond?: number;
+    };
+    reporting?: {
+        interval?: number;
+        console?: boolean | 'verbose';
+        customReporter?: (report: GuardrailsReport) => void;
+        aggregateWarnings?: boolean;
+        maxIssuesPerReport?: number;
+    };
+    treeId?: string;
+}
+export interface UpdateMetadata {
+    intent?: 'hydrate' | 'reset' | 'bulk' | 'migration' | 'user' | 'system';
+    source?: 'serialization' | 'time-travel' | 'devtools' | 'user' | 'system';
+    suppressGuardrails?: boolean;
+    timestamp?: number;
+    correlationId?: string;
+    [key: string]: unknown;
+}
+export interface GuardrailRule<T extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    test: (context: RuleContext<T>) => boolean | Promise<boolean>;
+    message: string | ((context: RuleContext<T>) => string);
+    severity?: 'error' | 'warning' | 'info';
+    fix?: (context: RuleContext<T>) => void;
+    tags?: string[];
+}
+export interface RuleContext<T extends Record<string, unknown> = Record<string, unknown>> {
+    path: string[];
+    value: unknown;
+    oldValue?: unknown;
+    metadata?: UpdateMetadata;
+    tree: SignalTree<T>;
+    duration?: number;
+    diffRatio?: number;
+    recomputeCount?: number;
+    downstreamEffects?: number;
+    isUnread?: boolean;
+    stats: RuntimeStats;
+}
+export interface RuntimeStats {
+    updateCount: number;
+    totalUpdateTime: number;
+    avgUpdateTime: number;
+    p50UpdateTime: number;
+    p95UpdateTime: number;
+    p99UpdateTime: number;
+    maxUpdateTime: number;
+    recomputationCount: number;
+    recomputationsPerSecond: number;
+    signalCount: number;
+    signalRetention: number;
+    unreadSignalCount: number;
+    memoryGrowthRate: number;
+    hotPathCount: number;
+    violationCount: number;
+}
+export interface GuardrailIssue {
+    type: 'budget' | 'hot-path' | 'memory' | 'rule' | 'analysis';
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    path?: string;
+    count: number;
+    diffRatio?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface HotPath {
+    path: string;
+    updatesPerSecond: number;
+    heatScore: number;
+    downstreamEffects: number;
+    avgDuration: number;
+    p95Duration: number;
+}
+export interface BudgetStatus {
+    updateTime: BudgetItem;
+    memory: BudgetItem;
+    recomputations: BudgetItem;
+}
+export interface BudgetItem {
+    current: number;
+    limit: number;
+    usage: number;
+    status: 'ok' | 'warning' | 'exceeded';
+}
+export interface GuardrailsReport {
+    timestamp: number;
+    treeId?: string;
+    issues: GuardrailIssue[];
+    hotPaths: HotPath[];
+    budgets: BudgetStatus;
+    stats: RuntimeStats;
+    recommendations: string[];
+}
+export interface GuardrailsAPI {
+    getReport(): GuardrailsReport;
+    getStats(): RuntimeStats;
+    suppress(fn: () => void): void;
+    dispose(): void;
+}

package/src/noop.d.ts

@@ -0,0 +1,11 @@
+import type { SignalTree } from '@signaltree/core';
+import type { GuardrailsConfig, GuardrailRule } from './lib/types';
+export declare function withGuardrails<T extends Record<string, unknown>>(config?: GuardrailsConfig): (tree: SignalTree<T>) => SignalTree<T>;
+export declare const rules: {
+    noDeepNesting: () => GuardrailRule<Record<string, unknown>>;
+    noFunctionsInState: () => GuardrailRule<Record<string, unknown>>;
+    noCacheInPersistence: () => GuardrailRule<Record<string, unknown>>;
+    maxPayloadSize: () => GuardrailRule<Record<string, unknown>>;
+    noSensitiveData: () => GuardrailRule<Record<string, unknown>>;
+};
+export type * from './lib/types';