Complete Track 20B Stability & Monitoring

- added runtime error tracking
- added performance monitoring hooks
- standardized logging

Roadmap:
Track B [ ] -> [x]

Author: DavidQ

docs/dev/reports/validation_checklist.txt

@@ -1,11 +1,3 @@
-- [ ] confirmed Track 20A docs already exist and are not re-done here
-- [ ] duplicate/superseded doc surfaces identified
-- [ ] authoritative current docs selected
-- [ ] unique content preserved before any deletion
-- [ ] duplicate/superseded docs removed safely
-- [ ] empty documentation directories removed safely
-- [ ] active references updated
-- [ ] onboarding flow validated end-to-end
-- [ ] no start_of_day changes
-- [ ] unrelated working-tree changes preserved
-- [ ] roadmap updated by status-only transitions only after successful validation
+- error tracking observable
+- performance metrics captured
+- logs consistent across modules

docs/pr/BUILD_PR_LEVEL_20_3_TRACK_B_STABILITY_MONITORING_EXECUTION.md

@@ -0,0 +1,21 @@
+# BUILD PR LEVEL 20.3
+
+## Purpose
+Execute Track 20B Stability & Monitoring with real, testable work.
+
+## Scope
+- runtime error tracking
+- performance monitoring hooks
+- logging standardization
+
+## Acceptance
+- error tracking implemented and observable
+- performance hooks integrated
+- logging standardized across modules
+
+## Roadmap
+This PR may advance:
+- runtime error tracking [ ] -> [x]
+- performance monitoring hooks [ ] -> [x]
+- logging standardization [ ] -> [x]
+- Track B [ ] -> [x]

docs/reports/BUILD_PR_LEVEL_20_3_TRACK_B_STABILITY_MONITORING_EXECUTION_validation.md

@@ -0,0 +1,27 @@
+# BUILD_PR_LEVEL_20_3_TRACK_B_STABILITY_MONITORING_EXECUTION Validation
+
+## Scope
+- runtime error tracking hooks
+- performance monitoring hooks
+- standardized logging format and usage
+
+## Implementation summary
+1. Engine runtime monitoring hooks:
+   - added error-tracking hook path with event emission (`engine:runtime-error`)
+   - added performance hook path with frame payload emission (`engine:performance-frame`)
+2. Logging standardization:
+   - standardized logger entry envelope to `engine.log.v1`
+   - added explicit `event` field support for structured logging usage
+3. Logging usage normalization:
+   - runtime hook and recovery/error-boundary logging now emits structured event metadata
+
+## Runtime tests executed
+1. `node -e "import('./tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs').then((m)=>m.run())"`
+   - result: PASS
+2. `node --input-type=module -e "<alias-hook bootstrap>; import('./tests/runtime/Phase19IntegrationFlowPass.test.mjs').then((m)=>m.run())"`
+   - result: PASS
+
+## Track 20B status promotion backing
+- runtime error tracking: validated by runtime error hook assertions and event emission assertions
+- performance monitoring hooks: validated by performance payload and snapshot assertions
+- logging standardization: validated by logger format/event assertions

docs/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -850,9 +850,9 @@
 - [x] validate deployment flow
 
 ### Track B ? Stability & Monitoring
-- [ ] runtime error tracking
-- [ ] performance monitoring hooks
-- [ ] logging standardization
+- [x] runtime error tracking
+- [x] performance monitoring hooks
+- [x] logging standardization
 
 ### Track C ? Documentation Completeness
 - [x] finalize developer docs

src/engine/core/Engine.js

@@ -32,6 +32,7 @@ export default class Engine {
     audio = null,
     logger = null,
     camera3D = null,
+    runtimeHooks = null,
   } = {}) {
     if (!canvas) {
       throw new Error('Engine requires a canvas.');
@@ -70,6 +71,10 @@ export default class Engine {
     });
     this.audio = audio || new AudioService();
     this.logger = logger || new Logger({ channel: 'engine' });
+    this.runtimeHooks = {
+      onError: typeof runtimeHooks?.onError === 'function' ? runtimeHooks.onError : null,
+      onPerformance: typeof runtimeHooks?.onPerformance === 'function' ? runtimeHooks.onPerformance : null,
+    };
     this.camera3D = camera3D || new Camera3D();
     this.settings = new SettingsSystem({
       namespace: 'toolboxaid:engine-settings',
@@ -116,8 +121,10 @@ export default class Engine {
       try {
         scene.setCamera3D(this.camera3D, this);
       } catch (error) {
-        this.logger?.warn?.('Engine scene setCamera3D hook failed.', {
-          error: error?.message || String(error),
+        this.trackRuntimeError('scene.setCamera3D', error, {
+          severity: 'warn',
+          isolated: true,
+          message: 'Engine scene setCamera3D hook failed.',
         });
       }
       return;
@@ -130,12 +137,50 @@ export default class Engine {
     try {
       scene.camera3D = this.camera3D;
     } catch (error) {
-      this.logger?.warn?.('Engine scene camera3D assignment failed.', {
-        error: error?.message || String(error),
+      this.trackRuntimeError('scene.camera3D.assign', error, {
+        severity: 'warn',
+        isolated: true,
+        message: 'Engine scene camera3D assignment failed.',
       });
     }
   }
 
+  trackRuntimeError(stage, error, { severity = 'error', isolated = false, context = {}, message = null } = {}) {
+    const payload = {
+      stage,
+      isolated: isolated === true,
+      severity,
+      error: error?.message || String(error),
+      timestamp: new Date().toISOString(),
+      context: { ...context },
+    };
+
+    const loggerMethod = severity === 'warn' ? 'warn' : 'error';
+    this.logger?.[loggerMethod]?.(message || 'Engine runtime issue tracked.', {
+      event: 'engine.runtime.error',
+      stage: payload.stage,
+      isolated: payload.isolated,
+      error: payload.error,
+      ...payload.context,
+    });
+
+    this.events?.emit?.('engine:runtime-error', payload);
+    this.runtimeHooks.onError?.(payload);
+    return payload;
+  }
+
+  publishPerformanceFrame(frameData) {
+    const snapshot = typeof this.metrics?.getSnapshot === 'function' ? this.metrics.getSnapshot() : null;
+    const payload = {
+      ...frameData,
+      snapshot: snapshot ? { ...snapshot } : null,
+      timestamp: new Date().toISOString(),
+    };
+    this.events?.emit?.('engine:performance-frame', payload);
+    this.runtimeHooks.onPerformance?.(payload);
+    return payload;
+  }
+
   start() {
     if (this.input && typeof this.input.attach === 'function') {
       this.input.attach();
@@ -188,10 +233,20 @@ export default class Engine {
     let fixedUpdates = 0;
 
     if (this.input && typeof this.input.update === 'function') {
-      this.input.update(deltaSeconds);
+      try {
+        this.input.update(deltaSeconds);
+      } catch (error) {
+        this.trackRuntimeError('input.update', error, { severity: 'error' });
+        throw error;
+      }
     }
     if (this.audio && typeof this.audio.update === 'function') {
-      this.audio.update(deltaSeconds);
+      try {
+        this.audio.update(deltaSeconds);
+      } catch (error) {
+        this.trackRuntimeError('audio.update', error, { severity: 'error' });
+        throw error;
+      }
     }
 
     const updateStart = performance.now();
@@ -200,14 +255,21 @@ export default class Engine {
         try {
           this.scene.step3DPhysics(stepSeconds, this);
         } catch (error) {
-          this.logger?.warn?.('Engine scene step3DPhysics hook failed.', {
-            error: error?.message || String(error),
+          this.trackRuntimeError('scene.step3DPhysics', error, {
+            severity: 'warn',
+            isolated: true,
+            message: 'Engine scene step3DPhysics hook failed.',
           });
         }
       }
 
       if (this.scene && typeof this.scene.update === 'function') {
-        this.scene.update(stepSeconds, this);
+        try {
+          this.scene.update(stepSeconds, this);
+        } catch (error) {
+          this.trackRuntimeError('scene.update', error, { severity: 'error' });
+          throw error;
+        }
       }
     });
     fixedUpdates = tickerResult.steps;
@@ -217,7 +279,12 @@ export default class Engine {
     this.renderer.clear();
     this.backgroundImageLayer?.render?.(this.renderer, { scene: this.scene, engine: this });
     if (this.scene && typeof this.scene.render === 'function') {
-      this.scene.render(this.renderer, this);
+      try {
+        this.scene.render(this.renderer, this);
+      } catch (error) {
+        this.trackRuntimeError('scene.render', error, { severity: 'error' });
+        throw error;
+      }
     }
     const fullscreenActive = this.fullscreen?.getState?.().active === true;
     const fullscreenElement = this.fullscreen?.documentRef?.fullscreenElement
@@ -226,13 +293,15 @@ export default class Engine {
     this.fullscreenBezelLayer?.sync?.({ fullscreenActive, fullscreenElement });
     renderDurationMs = performance.now() - renderStart;
 
-    this.metrics.recordFrame({
+    const frameData = {
       dtSeconds: deltaSeconds,
       frameMs: performance.now() - frameStart,
       updateMs: updateDurationMs,
       renderMs: renderDurationMs,
       fixedUpdates,
-    });
+    };
+    this.metrics.recordFrame(frameData);
+    this.publishPerformanceFrame(frameData);
 
     this.rafId = requestAnimationFrame(this.tick);
   }

src/engine/logging/ErrorBoundary.js

@@ -14,6 +14,7 @@ export default class ErrorBoundary {
       return operation();
     } catch (error) {
       this.logger?.error('Operation failed gracefully.', {
+        event: 'engine.error-boundary.operation-failed',
         error: error?.message || 'Unknown error',
       });
       return fallback;

src/engine/logging/Logger.js

@@ -22,11 +22,16 @@ export default class Logger {
       return null;
     }
 
+    const normalizedMessage = typeof message === 'string' ? message : String(message);
+    const metaSource = (meta && typeof meta === 'object') ? meta : { value: meta };
+    const { event = `${this.channel}.${level}`, ...normalizedMeta } = metaSource;
     const entry = {
+      format: 'engine.log.v1',
       level,
       channel: this.channel,
-      message,
-      meta: { ...meta },
+      event,
+      message: normalizedMessage,
+      meta: { ...normalizedMeta },
       timestamp: new Date().toISOString(),
     };
 

src/engine/release/CrashRecoveryManager.js

@@ -32,6 +32,7 @@ export default class CrashRecoveryManager {
       };
     } catch (error) {
       this.logger?.error('Operation failed gracefully.', {
+        event: 'engine.crash-recovery.operation-failed',
         error: error?.message || 'Unknown error',
         label,
       });

tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs

@@ -6,6 +6,7 @@ Phase19RuntimeLifecycleValidation.test.mjs
 */
 import assert from 'node:assert/strict';
 import Engine from '../../src/engine/core/Engine.js';
+import { Logger } from '../../src/engine/logging/index.js';
 
 function createCanvas() {
   const canvas = {
@@ -76,6 +77,8 @@ function createHarness({
   fixedStepMs = 16,
   scene = null,
   logger = null,
+  events = null,
+  runtimeHooks = null,
 } = {}) {
   const attachCounts = {
     input: 0,
@@ -135,6 +138,10 @@ function createHarness({
       recordFrame(frame) {
         metrics.push(frame);
       },
+      getSnapshot() {
+        const latest = metrics.length > 0 ? metrics[metrics.length - 1] : null;
+        return latest ? { ...latest } : { frameMs: 0, updateMs: 0, renderMs: 0, fixedUpdates: 0 };
+      },
     },
     input: {
       attach() {
@@ -171,6 +178,8 @@ function createHarness({
       warn() {},
       error() {},
     },
+    events,
+    runtimeHooks,
   });
 
   if (scene) {
@@ -350,9 +359,82 @@ function assertLongRunningStability() {
   }
 }
 
+function assertRuntimeMonitoringHooksAndLoggingFormat() {
+  const animationFrame = createAnimationFrameStub();
+  try {
+    const runtimeErrors = [];
+    const performanceFrames = [];
+    const emittedEvents = [];
+    const logger = new Logger({ channel: 'runtime-test', level: 'debug' });
+
+    const harness = createHarness({
+      logger,
+      runtimeHooks: {
+        onError(payload) {
+          runtimeErrors.push(payload);
+        },
+        onPerformance(payload) {
+          performanceFrames.push(payload);
+        },
+      },
+      events: {
+        emit(name, payload) {
+          emittedEvents.push({ name, payload });
+          return 0;
+        },
+      },
+      scene: {
+        step3DPhysics() {
+          throw new Error('monitoring-hook-physics-failure');
+        },
+        update() {},
+        render() {},
+      },
+    });
+
+    harness.engine.start();
+    harness.engine.tick(1016);
+    harness.engine.stop();
+
+    assert.equal(runtimeErrors.length >= 1, true, 'Runtime error hook should receive isolated runtime error payloads.');
+    assert.equal(
+      runtimeErrors.some((entry) => entry.stage === 'scene.step3DPhysics' && entry.isolated === true),
+      true,
+      'Runtime error hook should include scene.step3DPhysics stage metadata.'
+    );
+    assert.equal(performanceFrames.length >= 1, true, 'Performance monitoring hook should receive frame payloads.');
+    assert.equal(
+      performanceFrames.some((entry) => typeof entry.snapshot === 'object' && entry.snapshot !== null),
+      true,
+      'Performance monitoring hook payload should include metrics snapshot.'
+    );
+    assert.equal(
+      emittedEvents.some((entry) => entry.name === 'engine:runtime-error'),
+      true,
+      'Engine should emit engine:runtime-error event when runtime errors are tracked.'
+    );
+    assert.equal(
+      emittedEvents.some((entry) => entry.name === 'engine:performance-frame'),
+      true,
+      'Engine should emit engine:performance-frame event for monitoring consumers.'
+    );
+
+    const entries = logger.getEntries();
+    assert.equal(entries.length >= 1, true, 'Standardized logger should capture runtime monitoring logs.');
+    assert.equal(
+      entries.every((entry) => entry.format === 'engine.log.v1' && typeof entry.event === 'string' && entry.event.length > 0),
+      true,
+      'Logger entries should use the standardized log format and include event codes.'
+    );
+  } finally {
+    animationFrame.restore();
+  }
+}
+
 export function run() {
   assertBootRunShutdownLifecycle();
   assertHotReloadAndResetFlows();
   assertErrorHandlingPaths();
   assertLongRunningStability();
+  assertRuntimeMonitoringHooksAndLoggingFormat();
 }