Introduce Phase 19 runtime layer including update loop, scheduling hooks, and integration with core services

PR: BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Implement Phase 19 core services skeleton and wiring, package to <project folder>/tmp/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.zip
+COMMAND: Implement Phase 19 runtime layer scaffolding and package to <project folder>/tmp/BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-Establish Phase 19 core services skeleton including registry, lifecycle hooks, and baseline wiring for the next runtime layer
+Introduce Phase 19 runtime layer including update loop, scheduling hooks, and integration with core services
 
-PR: BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES
+PR: BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,2 @@
-- [ ] services initialize
-- [ ] no runtime errors
-- [ ] baseline wiring loads
+- [ ] runtime initializes
+- [ ] loop runs

docs/pr/BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.md

@@ -0,0 +1,38 @@
+# BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER
+
+## Purpose
+Implement a minimal Phase 19 runtime-layer scaffold and integrate it with the existing Phase 19 core-services skeleton.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.md`
+- `docs/pr/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md`
+
+## Exact Build Target
+1. Add runtime-layer scaffolding under:
+   - `samples/phase-19/shared/runtimeLayer/`
+2. Include:
+   - runtime loop orchestration (`start`, `update`, `stop`)
+   - scheduler hooks (before/after update and state-change hook channels)
+   - explicit runtime state transitions
+3. Integrate runtime layer with Phase 19 core services:
+   - runtime layer starts/updates/stops service registry
+   - `samples/phase-19/1901` uses runtime layer instead of directly driving services
+4. Add targeted runtime validation for:
+   - runtime state transitions + scheduler hooks + service integration
+   - sample `1901` runtime/service status rendering path
+
+## Non-Goals
+- no engine-core changes
+- no gameplay/system feature logic
+- no integration-flow implementation
+- no additional Phase 19 sample entries
+- no roadmap status updates
+
+## Validation
+- targeted runtime test for runtime state transitions + scheduler hooks + service integration passes
+- existing Phase 19 core-service skeleton test still passes
+- sample `1901` renders runtime/service status without errors
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.zip`

docs/pr/PLAN_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.md

@@ -0,0 +1,26 @@
+# PLAN_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER
+
+## Purpose
+Implement a minimal Phase 19 runtime-layer scaffold and wire it into sample `1901`.
+
+## Source of Truth
+- `docs/pr/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md`
+- `docs/pr/PLAN_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md`
+
+## Scope
+- add runtime-layer scaffolding under `samples/phase-19/shared/runtimeLayer/`
+- include runtime loop orchestration, scheduler hooks, and explicit runtime state transitions
+- integrate runtime layer with Phase 19 core services (`start`, `update`, `stop`)
+- rewire sample `1901` to use runtime layer instead of directly driving core services
+- add targeted runtime validation for transitions/hooks/service integration
+
+## Out of Scope
+- no integration-flow abstraction
+- no gameplay/feature systems
+- no additional Phase 19 samples
+- no roadmap status updates
+
+## Exit Criteria
+- runtime layer exists and drives core services through `1901`
+- targeted runtime validation passes
+- scoped delta is ready for repo-structured packaging

samples/phase-19/1901/Phase19FoundationScene.js

@@ -11,38 +11,47 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 const theme = new Theme(ThemeTokens);
 
 export default class Phase19FoundationScene extends Scene {
-  constructor({ coreServices = null } = {}) {
+  constructor({ runtimeLayer = null } = {}) {
     super();
     this.elapsed = 0;
-    this.coreServices = coreServices;
+    this.runtimeLayer = runtimeLayer;
     this.lastHeartbeatTick = 0;
     this.lastHeartbeatTime = 0;
+    this.lastRuntimeTransition = 'idle';
     this.unsubscribeHeartbeat = null;
+    this.unsubscribeRuntimeState = null;
   }
 
   enter(engine) {
-    if (!this.coreServices) return;
-    const channel = this.coreServices.get('phase19.channel');
+    if (!this.runtimeLayer) return;
+    this.unsubscribeRuntimeState = this.runtimeLayer.onStateChange(({ previous, next }) => {
+      this.lastRuntimeTransition = `${previous} -> ${next}`;
+    });
+    const channel = this.runtimeLayer.getService('phase19.channel');
     if (channel && typeof channel.subscribe === 'function') {
       this.unsubscribeHeartbeat = channel.subscribe('phase19.heartbeat', (payload) => {
         this.lastHeartbeatTick = Number(payload?.tick) || 0;
         this.lastHeartbeatTime = Number(payload?.t) || 0;
       });
     }
-    this.coreServices.start({ engine, scene: this });
+    this.runtimeLayer.start({ engine, scene: this });
   }
 
   update(dtSeconds) {
     this.elapsed += dtSeconds;
-    this.coreServices?.update(dtSeconds, { scene: this });
+    this.runtimeLayer?.update(dtSeconds, { scene: this });
   }
 
   exit() {
     if (typeof this.unsubscribeHeartbeat === 'function') {
       this.unsubscribeHeartbeat();
       this.unsubscribeHeartbeat = null;
     }
-    this.coreServices?.stop({ scene: this });
+    if (typeof this.unsubscribeRuntimeState === 'function') {
+      this.unsubscribeRuntimeState();
+      this.unsubscribeRuntimeState = null;
+    }
+    this.runtimeLayer?.stop({ scene: this });
   }
 
   render(renderer) {
@@ -63,20 +72,22 @@ export default class Phase19FoundationScene extends Scene {
       font: '16px monospace',
     });
 
-    const lifecycle = this.coreServices?.getLifecycleState?.() || {
-      running: false,
-      serviceCount: 0,
+    const runtimeSnapshot = this.runtimeLayer?.getSnapshot?.() || {
+      state: 'idle',
+      tickCount: 0,
+      serviceIds: [],
     };
-    const channelSnapshot = this.coreServices?.get?.('phase19.channel')?.getSnapshot?.() || {
+    const channelSnapshot = this.runtimeLayer?.getService?.('phase19.channel')?.getSnapshot?.() || {
       publishedCount: 0,
       lastChannel: 'none',
     };
-    drawPanel(renderer, 620, 34, 300, 140, 'Phase 19 Bootstrap', [
-      'Status: initialized (core services)',
+    drawPanel(renderer, 620, 34, 300, 160, 'Phase 19 Bootstrap', [
+      'Status: initialized (runtime layer)',
       'Folder: samples/phase-19',
       'Entry sample: 1901',
-      `Running: ${lifecycle.running ? 'yes' : 'no'}`,
-      `Services: ${lifecycle.serviceCount}`,
+      `Runtime: ${runtimeSnapshot.state} | tick ${runtimeSnapshot.tickCount}`,
+      `Transition: ${this.lastRuntimeTransition}`,
+      `Services: ${runtimeSnapshot.serviceIds.length}`,
       `Published: ${channelSnapshot.publishedCount} (${channelSnapshot.lastChannel})`,
       `Heartbeat tick: ${this.lastHeartbeatTick} @ ${this.lastHeartbeatTime.toFixed(2)}s`,
     ]);

samples/phase-19/1901/main.js

@@ -8,6 +8,7 @@ import Engine from '/src/engine/core/Engine.js';
 import { InputService } from '/src/engine/input/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import createPhase19CoreServices from '/samples/phase-19/shared/coreServices/createPhase19CoreServices.js';
+import createPhase19RuntimeLayer from '/samples/phase-19/shared/runtimeLayer/createPhase19RuntimeLayer.js';
 import Phase19FoundationScene from './Phase19FoundationScene.js';
 
 const theme = new Theme(ThemeTokens);
@@ -25,5 +26,6 @@ const engine = new Engine({
 });
 
 const coreServices = createPhase19CoreServices();
-engine.setScene(new Phase19FoundationScene({ coreServices }));
+const runtimeLayer = createPhase19RuntimeLayer({ coreServices });
+engine.setScene(new Phase19FoundationScene({ runtimeLayer }));
 engine.start();

samples/phase-19/shared/runtimeLayer/createPhase19RuntimeLayer.js

@@ -0,0 +1,101 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19RuntimeLayer.js
+*/
+import createPhase19SchedulerHooks from './createPhase19SchedulerHooks.js';
+
+const RUNTIME_STATES = {
+  IDLE: 'idle',
+  RUNNING: 'running',
+  STOPPED: 'stopped',
+};
+
+export default function createPhase19RuntimeLayer({ coreServices } = {}) {
+  const schedulerHooks = createPhase19SchedulerHooks();
+  let runtimeState = RUNTIME_STATES.IDLE;
+  let tickCount = 0;
+  let lastDtSeconds = 0;
+
+  function notifyStateChange(previous, next, context = {}) {
+    schedulerHooks.stateChange.run({ previous, next, context });
+    const channel = coreServices?.get?.('phase19.channel');
+    if (channel && typeof channel.publish === 'function') {
+      channel.publish('phase19.runtime.state', { previous, next });
+    }
+  }
+
+  function transitionTo(nextState, context = {}) {
+    if (runtimeState === nextState) return false;
+    const previous = runtimeState;
+    runtimeState = nextState;
+    notifyStateChange(previous, nextState, context);
+    return true;
+  }
+
+  function start(context = {}) {
+    if (runtimeState === RUNTIME_STATES.RUNNING) return false;
+    coreServices?.start?.({ ...context, runtimeLayer: api });
+    transitionTo(RUNTIME_STATES.RUNNING, context);
+    return true;
+  }
+
+  function update(dtSeconds, context = {}) {
+    if (runtimeState !== RUNTIME_STATES.RUNNING) return 0;
+    const dt = Math.max(0, Number(dtSeconds) || 0);
+    lastDtSeconds = dt;
+    tickCount += 1;
+
+    const payload = { dtSeconds: dt, tick: tickCount, context };
+    schedulerHooks.beforeUpdate.run(payload);
+    coreServices?.update?.(dt, { ...context, runtimeLayer: api, tick: tickCount });
+    schedulerHooks.afterUpdate.run(payload);
+    return tickCount;
+  }
+
+  function stop(context = {}) {
+    if (runtimeState !== RUNTIME_STATES.RUNNING) return false;
+    transitionTo(RUNTIME_STATES.STOPPED, context);
+    coreServices?.stop?.({ ...context, runtimeLayer: api });
+    return true;
+  }
+
+  function getSnapshot() {
+    return {
+      state: runtimeState,
+      tickCount,
+      lastDtSeconds,
+      hookCounts: schedulerHooks.snapshot(),
+      serviceIds: coreServices?.listServiceIds?.() || [],
+    };
+  }
+
+  const api = {
+    start,
+    update,
+    stop,
+    getSnapshot,
+    getState() {
+      return runtimeState;
+    },
+    getService(serviceId) {
+      return coreServices?.get?.(serviceId) || null;
+    },
+    listServiceIds() {
+      return coreServices?.listServiceIds?.() || [];
+    },
+    onBeforeUpdate(handler) {
+      return schedulerHooks.beforeUpdate.register(handler);
+    },
+    onAfterUpdate(handler) {
+      return schedulerHooks.afterUpdate.register(handler);
+    },
+    onStateChange(handler) {
+      return schedulerHooks.stateChange.register(handler);
+    },
+    states: RUNTIME_STATES,
+  };
+
+  return api;
+}

samples/phase-19/shared/runtimeLayer/createPhase19SchedulerHooks.js

@@ -0,0 +1,53 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19SchedulerHooks.js
+*/
+function createHookChannel() {
+  const handlers = new Set();
+
+  function register(handler) {
+    if (typeof handler !== 'function') return () => {};
+    handlers.add(handler);
+    return () => handlers.delete(handler);
+  }
+
+  function run(payload) {
+    let executed = 0;
+    for (const handler of handlers) {
+      handler(payload);
+      executed += 1;
+    }
+    return executed;
+  }
+
+  function count() {
+    return handlers.size;
+  }
+
+  return {
+    register,
+    run,
+    count,
+  };
+}
+
+export default function createPhase19SchedulerHooks() {
+  const beforeUpdate = createHookChannel();
+  const afterUpdate = createHookChannel();
+  const stateChange = createHookChannel();
+
+  return {
+    beforeUpdate,
+    afterUpdate,
+    stateChange,
+    snapshot() {
+      return {
+        beforeUpdate: beforeUpdate.count(),
+        afterUpdate: afterUpdate.count(),
+        stateChange: stateChange.count(),
+      };
+    },
+  };
+}

tests/runtime/Phase19CoreServicesSkeleton.test.mjs

@@ -6,6 +6,7 @@ Phase19CoreServicesSkeleton.test.mjs
 */
 import assert from 'node:assert/strict';
 import createPhase19CoreServices from '../../samples/phase-19/shared/coreServices/createPhase19CoreServices.js';
+import createPhase19RuntimeLayer from '../../samples/phase-19/shared/runtimeLayer/createPhase19RuntimeLayer.js';
 import Phase19FoundationScene from '../../samples/phase-19/1901/Phase19FoundationScene.js';
 
 function createRendererProbe(width = 960, height = 540) {
@@ -57,7 +58,8 @@ function assertCoreServiceLifecycleAndCommunication() {
 
 function assertPhase19SampleWiring() {
   const coreServices = createPhase19CoreServices();
-  const scene = new Phase19FoundationScene({ coreServices });
+  const runtimeLayer = createPhase19RuntimeLayer({ coreServices });
+  const scene = new Phase19FoundationScene({ runtimeLayer });
 
   scene.enter({});
   scene.update(0.55);
@@ -75,7 +77,7 @@ function assertPhase19SampleWiring() {
   assert.equal(
     coreServices.getLifecycleState().running,
     false,
-    'Scene exit should stop core services.'
+    'Scene exit should stop core services through runtime layer.'
   );
 }