Phase 18 runtime layer scaffolding

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

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

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Phase 18 core services skeleton
+Phase 18 runtime layer scaffolding

docs/dev/reports/validation_checklist.txt

@@ -1,2 +1,3 @@
-- [ ] services initialize
-- [ ] no runtime errors
+- [ ] runtime initializes
+- [ ] loop executes
+- [ ] no errors

docs/pr/BUILD_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER.md

@@ -0,0 +1,34 @@
+# BUILD_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER
+
+## Purpose
+Implement a minimal Phase 18 runtime-layer scaffold and integrate it with the existing Phase 18 core-services skeleton.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER.md`
+- `docs/pr/BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md`
+
+## Exact Build Target
+1. Add runtime-layer scaffolding under:
+   - `samples/phase-18/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 18 core services:
+   - runtime layer starts/updates/stops service registry
+   - `samples/phase-18/1801` uses runtime layer instead of directly driving services
+
+## Non-Goals
+- no engine-core changes
+- no gameplay/system feature logic
+- no additional Phase 18 sample entries
+- no roadmap status updates
+
+## Validation
+- targeted runtime test for runtime state transitions + scheduler hooks + service integration
+- existing Phase 18 core-service skeleton test still passes
+- sample `1801` renders runtime/service status without errors
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER.zip`

docs/pr/PLAN_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER.md

@@ -0,0 +1,9 @@
+# PLAN_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER
+
+Purpose:
+Introduce runtime orchestration layer.
+
+Scope:
+- update loop
+- scheduling hooks
+- state transitions

samples/phase-18/1801/Phase18FoundationScene.js

@@ -11,44 +11,53 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 const theme = new Theme(ThemeTokens);
 
 export default class Phase18FoundationScene 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('phase18.channel');
+    if (!this.runtimeLayer) return;
+    const channel = this.runtimeLayer.getService('phase18.channel');
     if (channel && typeof channel.subscribe === 'function') {
       this.unsubscribeHeartbeat = channel.subscribe('phase18.heartbeat', (payload) => {
         this.lastHeartbeatTick = Number(payload?.tick) || 0;
         this.lastHeartbeatTime = Number(payload?.t) || 0;
       });
     }
-    this.coreServices.start({ engine, scene: this });
+    this.unsubscribeRuntimeState = this.runtimeLayer.onStateChange(({ previous, next }) => {
+      this.lastRuntimeTransition = `${previous} -> ${next}`;
+    });
+    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) {
     drawFrame(renderer, theme, [
       'Sample 1801 - Phase 18 Foundation',
-      'Minimal Phase 18 structure bootstrap and launcher wiring.',
+      'Minimal Phase 18 runtime-layer scaffolding integrated with core services.',
       'No feature implementation in this scaffold.',
     ]);
 
@@ -63,11 +72,18 @@ export default class Phase18FoundationScene extends Scene {
       font: '16px monospace',
     });
 
+    const runtimeSnapshot = this.runtimeLayer?.getSnapshot?.() || {
+      state: 'idle',
+      tickCount: 0,
+      serviceIds: [],
+    };
     drawPanel(renderer, 620, 34, 300, 160, 'Phase 18 Bootstrap', [
       'Status: initialized',
       'Folder: samples/phase-18',
       'Entry sample: 1801',
-      `Services: ${this.coreServices?.listServiceIds().length ?? 0}`,
+      `Runtime: ${runtimeSnapshot.state} | tick ${runtimeSnapshot.tickCount}`,
+      `Transition: ${this.lastRuntimeTransition}`,
+      `Services: ${runtimeSnapshot.serviceIds.length}`,
       `Heartbeat tick: ${this.lastHeartbeatTick} @ ${this.lastHeartbeatTime.toFixed(2)}s`,
     ]);
   }

samples/phase-18/1801/index.html

@@ -14,7 +14,7 @@
 <body>
   <main>
     <h1>Sample 1801 - Phase 18 Foundation</h1>
-    <p>Bootstrap scaffold for Phase 18 with minimal core-service lifecycle wiring and no feature logic.</p>
+    <p>Bootstrap scaffold for Phase 18 with minimal runtime-layer and core-service wiring, without feature logic.</p>
     <canvas id="game" width="960" height="540"></canvas>
 
     <section>

samples/phase-18/1801/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 createPhase18CoreServices from '/samples/phase-18/shared/coreServices/createPhase18CoreServices.js';
+import createPhase18RuntimeLayer from '/samples/phase-18/shared/runtimeLayer/createPhase18RuntimeLayer.js';
 import Phase18FoundationScene from './Phase18FoundationScene.js';
 
 const theme = new Theme(ThemeTokens);
@@ -25,5 +26,6 @@ const engine = new Engine({
 });
 
 const coreServices = createPhase18CoreServices();
-engine.setScene(new Phase18FoundationScene({ coreServices }));
+const runtimeLayer = createPhase18RuntimeLayer({ coreServices });
+engine.setScene(new Phase18FoundationScene({ runtimeLayer }));
 engine.start();

samples/phase-18/shared/runtimeLayer/createPhase18RuntimeLayer.js

@@ -0,0 +1,101 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18RuntimeLayer.js
+*/
+import createPhase18SchedulerHooks from './createPhase18SchedulerHooks.js';
+
+const RUNTIME_STATES = {
+  IDLE: 'idle',
+  RUNNING: 'running',
+  STOPPED: 'stopped',
+};
+
+export default function createPhase18RuntimeLayer({ coreServices } = {}) {
+  const schedulerHooks = createPhase18SchedulerHooks();
+  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?.('phase18.channel');
+    if (channel && typeof channel.publish === 'function') {
+      channel.publish('phase18.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-18/shared/runtimeLayer/createPhase18SchedulerHooks.js

@@ -0,0 +1,53 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18SchedulerHooks.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 createPhase18SchedulerHooks() {
+  const beforeUpdate = createHookChannel();
+  const afterUpdate = createHookChannel();
+  const stateChange = createHookChannel();
+
+  return {
+    beforeUpdate,
+    afterUpdate,
+    stateChange,
+    snapshot() {
+      return {
+        beforeUpdate: beforeUpdate.count(),
+        afterUpdate: afterUpdate.count(),
+        stateChange: stateChange.count(),
+      };
+    },
+  };
+}