@signaltree/guardrails 4.1.1 → 4.1.2

package/LICENSE

@@ -0,0 +1,54 @@
+BUSINESS SOURCE LICENSE 1.1
+
+Copyright (c) 2025 Jonathan D Borgia
+
+This Business Source License 1.1 ("License") governs the use of the software and associated documentation files (the "Software"). You are granted a limited license to use the Software under the terms of this License.
+
+1. Definitions
+
+"Change Date" means the date on which the Change License set out in section 6 will apply to the Software. The Change Date for this release is 2028-09-05.
+
+"Change License" means the open source license that will apply to the Software on and after the Change Date. The Change License for this release is the MIT License.
+
+"Licensor" means the copyright owner granting rights under this License (Jonathan D Borgia).
+
+"You" ("Licensee") means an individual or legal entity exercising rights under this License who has not violated the terms of this License or had their rights terminated.
+
+2. License Grant
+
+Subject to the terms and conditions of this License, Licensor hereby grants You a non-exclusive, non-transferable, worldwide license to use, reproduce, display, perform, and distribute the Software, and to make modifications and derivative works for internal use, until the Change Date.
+
+3. Commercial Use
+
+You may use the Software in commercial applications, including for providing services, selling products that include the Software, or otherwise exploiting the Software commercially, subject to the other terms of this License.
+
+4. Limitations and Conditions
+
+a. You may not remove or alter this License, the copyright notice, or notices of the Change Date.
+
+b. You may not publicly offer a modified version of the Software that would directly compete with Licensor's public offering of the Software if doing so would circumvent the intent of this License.
+
+c. Except as expressly provided in this License, no rights are granted to You under any patent or trademark of Licensor.
+
+5. Disclaimer and Limitation of Liability
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATING TO THE SOFTWARE.
+
+6. Change License
+
+On and after the Change Date specified above, the Software will be licensed under the Change License (MIT License) on the same terms and conditions as set forth by that Change License.
+
+7. Governing Law
+
+This License will be governed by and construed in accordance with the laws of the State of New York, USA, without regard to conflict of law principles.
+
+8. Accepting this License
+
+You accept this License by copying, modifying, or distributing the Software or any portion thereof.
+
+---
+
+LICENSE NOTE
+
+- Original license file replaced on 2025-09-05 to Business Source License 1.1. Change Date: 2028-09-05. Change License: MIT.
+  or standard modifications for your own applications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/guardrails",
-  "version": "4.1.1",
+  "version": "4.1.2",
   "description": "Development-only performance monitoring and anti-pattern detection for SignalTree",
   "type": "module",
   "sideEffects": false,
@@ -48,22 +48,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "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.1.1",
+    "@signaltree/core": "4.1.2",
     "tslib": "^2.0.0"
   },
   "devDependencies": {
-    "@signaltree/core": "workspace:*",
-    "@signaltree/shared": "workspace:*",
-    "@signaltree/types": "workspace:*"
+    "@signaltree/core": "4.1.0",
+    "@signaltree/shared": "0.0.1",
+    "@signaltree/types": "4.1.2"
   },
   "keywords": [
     "signaltree",
@@ -81,5 +73,13 @@
     "type": "git",
     "url": "https://github.com/signaltree/signaltree.git",
     "directory": "packages/guardrails"
+  },
+  "scripts": {
+    "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"
   }
-}
+}

package/dist/factories/index.js

@@ -1,119 +0,0 @@
-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

@@ -1,612 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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.js

@@ -1,21 +0,0 @@
-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/src/factories/index.d.ts

@@ -1,20 +0,0 @@
-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

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

package/src/lib/guardrails.d.ts

@@ -1,3 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,138 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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';