Add plugin resource limits.

DavidQ · DavidQ · commit d0b65d4bca8d · 2026-04-16T18:29:49.000-04:00
PR Details:
- Prevents resource abuse
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,7 +2,7 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement plugin performance monitoring:
-- Track execution metrics
-- Provide diagnostics
+Implement plugin resource limits:
+- Enforce CPU/memory caps
+- Maintain stability
 - Update roadmap status only
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,4 +1,4 @@
-Add plugin performance monitoring.
+Add plugin resource limits.
 
 PR Details:
-- Enables tracking of plugin performance
+- Prevents resource abuse
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,4 @@
-[ ] Metrics captured
-[ ] Reporting works
-[ ] No regression
+[ ] Limits enforced
+[ ] System stable
+[ ] No degradation
 [ ] Roadmap updated
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -821,7 +821,7 @@
 - [x] validate plugin/extension patterns
 - [x] validate adding new systems is clean
 - [.] validate external integration points
-- [.] ensure future phases can build cleanly
+- [x] ensure future phases can build cleanly
 
 ### Track H — Final Stability Gate
 - [ ] full-repo validation sweep
diff --git a/docs/pr/BUILD_PR.md b/docs/pr/BUILD_PR.md
@@ -1,21 +1,21 @@
-# BUILD_PR_LEVEL_20_6_OVERLAY_PLUGIN_PERFORMANCE_MONITORING
+# BUILD_PR_LEVEL_20_7_OVERLAY_PLUGIN_RESOURCE_LIMITS
 
 ## Purpose
-Introduce performance monitoring for overlay plugins.
+Enforce resource limits on overlay plugins.
 
 ## Roadmap Improvement
-Provides visibility into plugin performance and impact.
+Prevents plugins from degrading system performance.
 
 ## Scope
-- Track plugin execution time
-- Identify slow or heavy plugins
-- Provide basic diagnostics
+- Define CPU/memory limits
+- Enforce limits
+- Validate behavior under limits
 
 ## Test Steps
-1. Run plugins
-2. Monitor performance metrics
-3. Validate reporting
+1. Run heavy plugin
+2. Verify limits enforced
+3. Confirm system stability
 
 ## Expected
-- Performance metrics available
-- No performance regression
+- Limits enforced
+- No system degradation
diff --git a/samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js b/samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js
@@ -14,10 +14,32 @@ const PLUGIN_STATES = Object.freeze({
   FAILED: 'failed',
 });
 
+const DEFAULT_RESOURCE_LIMITS = Object.freeze({
+  maxHookDurationMs: 24,
+  maxHeapUsedBytes: 512 * 1024 * 1024,
+  maxHeapDeltaBytes: 8 * 1024 * 1024,
+});
+
 function normalizePluginId(pluginId) {
   return String(pluginId || '').trim();
 }
 
+function normalizeLimit(value, fallback) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return fallback;
+  }
+  return numeric;
+}
+
+function normalizeResourceLimits(resourceLimits = {}) {
+  return Object.freeze({
+    maxHookDurationMs: normalizeLimit(resourceLimits?.maxHookDurationMs, DEFAULT_RESOURCE_LIMITS.maxHookDurationMs),
+    maxHeapUsedBytes: normalizeLimit(resourceLimits?.maxHeapUsedBytes, DEFAULT_RESOURCE_LIMITS.maxHeapUsedBytes),
+    maxHeapDeltaBytes: normalizeLimit(resourceLimits?.maxHeapDeltaBytes, DEFAULT_RESOURCE_LIMITS.maxHeapDeltaBytes),
+  });
+}
+
 function toErrorDetails(error) {
   if (error && typeof error === 'object' && typeof error.message === 'string') {
     return {
@@ -73,6 +95,31 @@ function getNowMs() {
   return Date.now();
 }
 
+function readHeapUsageBytes() {
+  try {
+    if (typeof globalThis?.process?.memoryUsage === 'function') {
+      const usage = globalThis.process.memoryUsage();
+      const heapUsed = Number(usage?.heapUsed);
+      if (Number.isFinite(heapUsed) && heapUsed >= 0) {
+        return heapUsed;
+      }
+    }
+  } catch {
+    // Heap metrics are best-effort for diagnostics.
+  }
+
+  try {
+    const browserHeap = Number(globalThis?.performance?.memory?.usedJSHeapSize);
+    if (Number.isFinite(browserHeap) && browserHeap >= 0) {
+      return browserHeap;
+    }
+  } catch {
+    // Ignore unavailable browser heap APIs.
+  }
+
+  return 0;
+}
+
 function createHookMetrics() {
   return {
     calls: 0,
@@ -114,6 +161,14 @@ function createPluginMetrics() {
       lastRegisteredAtIso: '',
       lastExtensionId: '',
     },
+    resources: {
+      cpuViolations: 0,
+      memoryViolations: 0,
+      lastHookDurationMs: 0,
+      lastHeapUsedBytes: 0,
+      lastHeapDeltaBytes: 0,
+      lastViolationMessage: '',
+    },
     lastState: '',
     lastStateChangedAtIso: '',
   };
@@ -148,6 +203,7 @@ function normalizePluginDefinition(plugin) {
     id,
     version: String(plugin.version || '').trim(),
     metadata: Object.freeze({ ...(plugin.metadata || {}) }),
+    resourceLimits: normalizeResourceLimits(plugin.resourceLimits),
     init: typeof plugin.init === 'function' ? plugin.init : (typeof plugin.onInit === 'function' ? plugin.onInit : null),
     activate: typeof plugin.activate === 'function'
       ? plugin.activate
@@ -322,10 +378,60 @@ export default function createPhase19OverlayPluginRegistry({
     return true;
   }
 
+  function evaluateResourceLimitViolations(record, phase, durationMs, heapUsedBytes, heapDeltaBytes) {
+    const limits = record?.plugin?.resourceLimits || DEFAULT_RESOURCE_LIMITS;
+    const duration = Math.max(0, Number(durationMs) || 0);
+    const heapUsed = Math.max(0, Number(heapUsedBytes) || 0);
+    const heapDelta = Math.max(0, Number(heapDeltaBytes) || 0);
+    const cpuExceeded = duration > limits.maxHookDurationMs;
+    const heapExceeded = heapUsed > limits.maxHeapUsedBytes;
+    const heapDeltaExceeded = heapDelta > limits.maxHeapDeltaBytes;
+
+    if (record?.metrics?.resources) {
+      record.metrics.resources.lastHookDurationMs = duration;
+      record.metrics.resources.lastHeapUsedBytes = heapUsed;
+      record.metrics.resources.lastHeapDeltaBytes = heapDelta;
+      if (cpuExceeded) {
+        record.metrics.resources.cpuViolations += 1;
+      }
+      if (heapExceeded || heapDeltaExceeded) {
+        record.metrics.resources.memoryViolations += 1;
+      }
+    }
+
+    if (!cpuExceeded && !heapExceeded && !heapDeltaExceeded) {
+      return { ok: true };
+    }
+
+    const reasons = [];
+    if (cpuExceeded) {
+      reasons.push(`CPU ${duration.toFixed(3)}ms > ${limits.maxHookDurationMs}ms`);
+    }
+    if (heapExceeded) {
+      reasons.push(`heapUsed ${heapUsed}B > ${limits.maxHeapUsedBytes}B`);
+    }
+    if (heapDeltaExceeded) {
+      reasons.push(`heapDelta ${heapDelta}B > ${limits.maxHeapDeltaBytes}B`);
+    }
+    const message = `Resource limit exceeded (${reasons.join(', ')})`;
+    if (record?.metrics?.resources) {
+      record.metrics.resources.lastViolationMessage = message;
+    }
+    return {
+      ok: false,
+      phase: `${phase}-resource-limit`,
+      error: {
+        name: 'ResourceLimitError',
+        message,
+      },
+    };
+  }
+
   function runLifecycleHook(record, phase, context = {}) {
     const bucket = record?.metrics?.hooks?.[phase] || null;
     const hook = record?.plugin?.[phase];
     const startedAtMs = getNowMs();
+    const startedHeapBytes = readHeapUsageBytes();
     const startedAtIso = new Date().toISOString();
     if (bucket) {
       bucket.calls += 1;
@@ -334,14 +440,16 @@ export default function createPhase19OverlayPluginRegistry({
     if (typeof hook !== 'function') {
       const finishedAtMs = getNowMs();
       const durationMs = Math.max(0, finishedAtMs - startedAtMs);
+      const finishedHeapBytes = readHeapUsageBytes();
+      const heapDeltaBytes = Math.max(0, finishedHeapBytes - startedHeapBytes);
       if (bucket) {
         bucket.successes += 1;
         bucket.totalDurationMs += durationMs;
         bucket.lastDurationMs = durationMs;
         bucket.lastFinishedAtIso = new Date().toISOString();
         bucket.lastErrorMessage = '';
       }
-      return { ok: true };
+      return evaluateResourceLimitViolations(record, phase, durationMs, finishedHeapBytes, heapDeltaBytes);
     }
     try {
       const previousHookPluginId = activeHookPluginId;
@@ -358,14 +466,16 @@ export default function createPhase19OverlayPluginRegistry({
         hook(lifecycleContext);
         const finishedAtMs = getNowMs();
         const durationMs = Math.max(0, finishedAtMs - startedAtMs);
+        const finishedHeapBytes = readHeapUsageBytes();
+        const heapDeltaBytes = Math.max(0, finishedHeapBytes - startedHeapBytes);
         if (bucket) {
           bucket.successes += 1;
           bucket.totalDurationMs += durationMs;
           bucket.lastDurationMs = durationMs;
           bucket.lastFinishedAtIso = new Date().toISOString();
           bucket.lastErrorMessage = '';
         }
-        return { ok: true };
+        return evaluateResourceLimitViolations(record, phase, durationMs, finishedHeapBytes, heapDeltaBytes);
       } finally {
         activeHookPluginId = previousHookPluginId;
       }
@@ -404,7 +514,7 @@ export default function createPhase19OverlayPluginRegistry({
       }
       const initResult = runLifecycleHook(record, 'init', context);
       if (!initResult.ok) {
-        isolatePluginFailure(record, 'init', initResult.error, context, {
+        isolatePluginFailure(record, initResult.phase || 'init', initResult.error, context, {
           unregisterExtension: true,
           quarantine: true,
         });
@@ -473,7 +583,7 @@ export default function createPhase19OverlayPluginRegistry({
 
       const activateResult = runLifecycleHook(record, 'activate', context);
       if (!activateResult.ok) {
-        isolatePluginFailure(record, 'activate', activateResult.error, context, {
+        isolatePluginFailure(record, activateResult.phase || 'activate', activateResult.error, context, {
           unregisterExtension: true,
           quarantine: true,
         });
@@ -510,7 +620,7 @@ export default function createPhase19OverlayPluginRegistry({
       }
       const deactivateResult = runLifecycleHook(record, 'deactivate', context);
       if (!deactivateResult.ok) {
-        isolatePluginFailure(record, 'deactivate', deactivateResult.error, context, {
+        isolatePluginFailure(record, deactivateResult.phase || 'deactivate', deactivateResult.error, context, {
           unregisterExtension: true,
           quarantine: true,
         });
@@ -548,7 +658,7 @@ export default function createPhase19OverlayPluginRegistry({
       }
       const destroyResult = runLifecycleHook(record, 'destroy', context);
       if (!destroyResult.ok) {
-        isolatePluginFailure(record, 'destroy', destroyResult.error, context, {
+        isolatePluginFailure(record, destroyResult.phase || 'destroy', destroyResult.error, context, {
           unregisterExtension: true,
           quarantine: true,
         });
@@ -728,6 +838,7 @@ export default function createPhase19OverlayPluginRegistry({
       version: record.plugin.version,
       extensionId: record.extension.id,
       state: record.state,
+      resourceLimits: record.plugin.resourceLimits,
       failureCount: record.failureCount,
       lastFailure: record.lastFailure,
       metrics: snapshotPluginMetrics(record.metrics),
@@ -801,6 +912,8 @@ export default function createPhase19OverlayPluginRegistry({
         failureCount: record.failureCount,
         transitionAttempts: record.metrics?.transitions?.attempted || 0,
         transitionFailures: record.metrics?.transitions?.failed || 0,
+        cpuViolations: record.metrics?.resources?.cpuViolations || 0,
+        memoryViolations: record.metrics?.resources?.memoryViolations || 0,
       });
     }
     return Object.freeze(entries);
diff --git a/tests/runtime/Phase19OverlayPluginRegistry.test.mjs b/tests/runtime/Phase19OverlayPluginRegistry.test.mjs
@@ -372,11 +372,86 @@ function assertPluginBoundaryIsolationAndInterferenceProtection() {
   );
 }
 
+function assertPluginResourceLimitEnforcementAndDiagnostics() {
+  const registry = createPhase19OverlayPluginRegistry();
+
+  registry.registerPlugin({
+    id: 'phase19.resource.cpu',
+    resourceLimits: {
+      maxHookDurationMs: 1,
+      maxHeapUsedBytes: 1024 * 1024 * 1024,
+      maxHeapDeltaBytes: 1024 * 1024 * 1024,
+    },
+    createOverlayExtension() {
+      return definePhase19OverlayExtension({
+        id: 'phase19.resource.cpu.overlay',
+        overlays: [{ id: 'runtime', label: 'Runtime' }],
+      });
+    },
+    activate() {
+      const start = Date.now();
+      while (Date.now() - start < 6) {
+        // Busy wait to force CPU cap exceedance.
+      }
+    },
+  }, { autoActivate: false });
+
+  assert.equal(registry.activatePlugin('phase19.resource.cpu'), false, 'CPU cap exceedance should block activation safely.');
+  assert.equal(registry.getPluginState('phase19.resource.cpu'), registry.states.FAILED, 'CPU cap exceedance should quarantine plugin.');
+  assert.equal(
+    String(registry.getPluginFailure('phase19.resource.cpu')?.phase || '').includes('resource-limit'),
+    true,
+    'CPU cap exceedance should be reported as resource-limit phase.'
+  );
+  const cpuMetrics = registry.getPluginMetrics('phase19.resource.cpu');
+  assert.equal(cpuMetrics.resources.cpuViolations >= 1, true, 'CPU cap exceedance should increment CPU violation metrics.');
+  assert.equal(
+    registry.getFramework().getExtension('phase19.resource.cpu.overlay'),
+    null,
+    'CPU cap exceedance should isolate plugin by removing active extension registration.'
+  );
+
+  registry.registerPlugin({
+    id: 'phase19.resource.memory',
+    resourceLimits: {
+      maxHookDurationMs: 1000,
+      maxHeapUsedBytes: 1,
+      maxHeapDeltaBytes: 1024,
+    },
+    createOverlayExtension() {
+      return definePhase19OverlayExtension({
+        id: 'phase19.resource.memory.overlay',
+        overlays: [{ id: 'runtime', label: 'Runtime' }],
+      });
+    },
+  }, { autoActivate: false });
+
+  assert.equal(registry.initPlugin('phase19.resource.memory'), false, 'Memory cap exceedance should block initialization safely.');
+  assert.equal(registry.getPluginState('phase19.resource.memory'), registry.states.FAILED, 'Memory cap exceedance should quarantine plugin.');
+  const memoryMetrics = registry.getPluginMetrics('phase19.resource.memory');
+  assert.equal(memoryMetrics.resources.memoryViolations >= 1, true, 'Memory cap exceedance should increment memory violation metrics.');
+
+  const diagnostics = registry.getPluginDiagnostics('phase19.resource.memory');
+  assert.notEqual(diagnostics, null, 'Resource-limited plugin should expose diagnostics snapshot.');
+  assert.equal(Boolean(diagnostics.resourceLimits), true, 'Diagnostics should include configured resource limits.');
+  assert.equal(
+    diagnostics.resourceLimits.maxHeapUsedBytes,
+    1,
+    'Diagnostics should expose memory cap configuration.'
+  );
+  assert.equal(
+    registry.listPluginMetrics().some((entry) => entry.pluginId === 'phase19.resource.memory'),
+    true,
+    'Metrics listing should include resource-limited plugin.'
+  );
+}
+
 export function run() {
   assertPluginRegistrationAndRuntimeCompatibility();
   assertPluginUnregisterCleansFramework();
   assertPluginLifecycleTransitionsAndSafety();
   assertPluginLifecycleFailureIsolation();
   assertPluginFailureRecoveryFlow();
   assertPluginBoundaryIsolationAndInterferenceProtection();
+  assertPluginResourceLimitEnforcementAndDiagnostics();
 }
