Integrate Phase 19 core services with runtime layer ensuring data flow and lifecycle coherence

PR: BUILD_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

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

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-Introduce Phase 19 runtime layer including update loop, scheduling hooks, and integration with core services
+Integrate Phase 19 core services with runtime layer ensuring data flow and lifecycle coherence
 
-PR: BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER
+PR: BUILD_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS

docs/dev/reports/validation_checklist.txt

@@ -1,2 +1,2 @@
-- [ ] runtime initializes
-- [ ] loop runs
+- [ ] integration works
+- [ ] no errors

docs/pr/BUILD_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS.md

@@ -0,0 +1,36 @@
+# BUILD_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS
+
+## Purpose
+Integrate Phase 19 core services and runtime layer through a single flow entry point and validate end-to-end interaction behavior.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS.md`
+- `docs/pr/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md`
+- `docs/pr/BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.md`
+
+## Exact Build Target
+1. Add a Phase 19 integration-flow module that composes:
+   - core services registry
+   - runtime layer
+   - flow-level event subscriptions and snapshots
+2. Rewire sample `1901` to use the integration-flow module instead of directly composing runtime/core services.
+3. Keep runtime and service modules unchanged except as needed for integration wiring.
+4. Add targeted runtime integration validation for:
+   - start/update/stop flow path
+   - runtime state event flow
+   - heartbeat flow through integration snapshot
+
+## Non-Goals
+- no engine-core changes
+- no gameplay feature implementation
+- no additional Phase 19 sample entries
+- no roadmap status changes
+
+## Validation
+- targeted integration flow test passes
+- existing runtime/core service targeted tests still pass
+- sample `1901` renders integration flow status without errors
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS.zip`

docs/pr/PLAN_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS.md

@@ -0,0 +1,25 @@
+# PLAN_PR_LEVEL_19_5_PHASE19_INTEGRATION_PASS
+
+## Purpose
+Integrate Phase 19 core services and runtime layer through a single flow entry point, with targeted end-to-end validation.
+
+## Source of Truth
+- `docs/pr/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md`
+- `docs/pr/BUILD_PR_LEVEL_19_4_PHASE19_RUNTIME_LAYER.md`
+
+## Scope
+- add one Phase 19 integration-flow module that composes core services + runtime layer
+- rewire sample `1901` to use the integration-flow entry point
+- keep existing core-services and runtime-layer modules unchanged except as needed for integration wiring
+- add targeted integration runtime validation
+
+## Out of Scope
+- no engine-core changes
+- no gameplay feature logic
+- no additional Phase 19 samples
+- no roadmap status updates
+
+## Exit Criteria
+- integration-flow module exists and drives start/update/stop through `1901`
+- targeted integration test coverage passes
+- existing runtime/core tests remain passing

samples/phase-19/1901/Phase19FoundationScene.js

@@ -11,54 +11,47 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 const theme = new Theme(ThemeTokens);
 
 export default class Phase19FoundationScene extends Scene {
-  constructor({ runtimeLayer = null } = {}) {
+  constructor({ phase19Flow = null } = {}) {
     super();
     this.elapsed = 0;
-    this.runtimeLayer = runtimeLayer;
+    this.phase19Flow = phase19Flow;
     this.lastHeartbeatTick = 0;
     this.lastHeartbeatTime = 0;
     this.lastRuntimeTransition = 'idle';
-    this.unsubscribeHeartbeat = null;
     this.unsubscribeRuntimeState = null;
   }
 
   enter(engine) {
-    if (!this.runtimeLayer) return;
-    this.unsubscribeRuntimeState = this.runtimeLayer.onStateChange(({ previous, next }) => {
+    if (!this.phase19Flow) return;
+    this.unsubscribeRuntimeState = this.phase19Flow.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.runtimeLayer.start({ engine, scene: this });
+    this.phase19Flow.start({ engine, scene: this });
   }
 
   update(dtSeconds) {
     this.elapsed += dtSeconds;
-    this.runtimeLayer?.update(dtSeconds, { scene: this });
+    this.phase19Flow?.update(dtSeconds, { scene: this });
+    const snapshot = this.phase19Flow?.getSnapshot?.();
+    if (snapshot?.flow) {
+      this.lastHeartbeatTick = Number(snapshot.flow.lastHeartbeatTick) || 0;
+      this.lastHeartbeatTime = Number(snapshot.flow.lastHeartbeatSeconds) || 0;
+    }
   }
 
   exit() {
-    if (typeof this.unsubscribeHeartbeat === 'function') {
-      this.unsubscribeHeartbeat();
-      this.unsubscribeHeartbeat = null;
-    }
     if (typeof this.unsubscribeRuntimeState === 'function') {
       this.unsubscribeRuntimeState();
       this.unsubscribeRuntimeState = null;
     }
-    this.runtimeLayer?.stop({ scene: this });
+    this.phase19Flow?.stop({ scene: this });
   }
 
   render(renderer) {
     drawFrame(renderer, theme, [
-      'Sample 1901 - Phase 19 Core Services',
-      'Minimal Phase 19 core-services skeleton wired into foundation sample.',
-      'No feature implementation in this core-services slice.',
+      'Sample 1901 - Phase 19 Integration Flow',
+      'Minimal Phase 19 integration flow wired over runtime layer + core services.',
+      'No feature implementation in this integration slice.',
     ]);
 
     renderer.drawRect(120, 212, 720, 200, '#0f172a');
@@ -72,23 +65,30 @@ export default class Phase19FoundationScene extends Scene {
       font: '16px monospace',
     });
 
-    const runtimeSnapshot = this.runtimeLayer?.getSnapshot?.() || {
+    const phase19Snapshot = this.phase19Flow?.getSnapshot?.() || {
+      runtime: {
+        state: 'idle',
+        tickCount: 0,
+        serviceIds: [],
+      },
+      flow: {
+        runtimeStateEvents: 0,
+      },
+    };
+    const runtimeSnapshot = phase19Snapshot.runtime || {
       state: 'idle',
       tickCount: 0,
       serviceIds: [],
     };
-    const channelSnapshot = this.runtimeLayer?.getService?.('phase19.channel')?.getSnapshot?.() || {
-      publishedCount: 0,
-      lastChannel: 'none',
-    };
+    const flowSnapshot = phase19Snapshot.flow || { runtimeStateEvents: 0 };
     drawPanel(renderer, 620, 34, 300, 160, 'Phase 19 Bootstrap', [
-      'Status: initialized (runtime layer)',
+      'Status: initialized',
       'Folder: samples/phase-19',
       'Entry sample: 1901',
       `Runtime: ${runtimeSnapshot.state} | tick ${runtimeSnapshot.tickCount}`,
       `Transition: ${this.lastRuntimeTransition}`,
+      `Flow events: ${flowSnapshot.runtimeStateEvents}`,
       `Services: ${runtimeSnapshot.serviceIds.length}`,
-      `Published: ${channelSnapshot.publishedCount} (${channelSnapshot.lastChannel})`,
       `Heartbeat tick: ${this.lastHeartbeatTick} @ ${this.lastHeartbeatTime.toFixed(2)}s`,
     ]);
   }

samples/phase-19/1901/main.js

@@ -7,8 +7,7 @@ main.js
 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 createPhase19IntegrationFlow from '/samples/phase-19/shared/integration/createPhase19IntegrationFlow.js';
 import Phase19FoundationScene from './Phase19FoundationScene.js';
 
 const theme = new Theme(ThemeTokens);
@@ -25,7 +24,6 @@ const engine = new Engine({
   input,
 });
 
-const coreServices = createPhase19CoreServices();
-const runtimeLayer = createPhase19RuntimeLayer({ coreServices });
-engine.setScene(new Phase19FoundationScene({ runtimeLayer }));
+const phase19Flow = createPhase19IntegrationFlow();
+engine.setScene(new Phase19FoundationScene({ phase19Flow }));
 engine.start();

samples/phase-19/shared/integration/createPhase19IntegrationFlow.js

@@ -0,0 +1,96 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19IntegrationFlow.js
+*/
+import createPhase19CoreServices from '../coreServices/createPhase19CoreServices.js';
+import createPhase19RuntimeLayer from '../runtimeLayer/createPhase19RuntimeLayer.js';
+
+export default function createPhase19IntegrationFlow({
+  coreServices = createPhase19CoreServices(),
+  runtimeLayer = createPhase19RuntimeLayer({ coreServices }),
+} = {}) {
+  let heartbeatEvents = 0;
+  let runtimeStateEvents = 0;
+  let lastHeartbeatTick = 0;
+  let lastHeartbeatSeconds = 0;
+  let lastRuntimeState = 'idle';
+  let heartbeatUnsubscribe = null;
+  let runtimeStateUnsubscribe = null;
+
+  function attachChannels() {
+    if (heartbeatUnsubscribe || runtimeStateUnsubscribe) return;
+    const channel = runtimeLayer.getService('phase19.channel');
+    if (!channel || typeof channel.subscribe !== 'function') return;
+
+    heartbeatUnsubscribe = channel.subscribe('phase19.heartbeat', (payload) => {
+      heartbeatEvents += 1;
+      lastHeartbeatTick = Number(payload?.tick) || 0;
+      lastHeartbeatSeconds = Number(payload?.t) || 0;
+    });
+    runtimeStateUnsubscribe = channel.subscribe('phase19.runtime.state', (payload) => {
+      runtimeStateEvents += 1;
+      lastRuntimeState = String(payload?.next || lastRuntimeState);
+    });
+  }
+
+  function detachChannels() {
+    if (typeof heartbeatUnsubscribe === 'function') {
+      heartbeatUnsubscribe();
+    }
+    if (typeof runtimeStateUnsubscribe === 'function') {
+      runtimeStateUnsubscribe();
+    }
+    heartbeatUnsubscribe = null;
+    runtimeStateUnsubscribe = null;
+  }
+
+  function start(context = {}) {
+    attachChannels();
+    return runtimeLayer.start(context);
+  }
+
+  function update(dtSeconds, context = {}) {
+    return runtimeLayer.update(dtSeconds, context);
+  }
+
+  function stop(context = {}) {
+    const stopped = runtimeLayer.stop(context);
+    detachChannels();
+    return stopped;
+  }
+
+  function getSnapshot() {
+    return {
+      runtime: runtimeLayer.getSnapshot(),
+      flow: {
+        heartbeatEvents,
+        runtimeStateEvents,
+        lastHeartbeatTick,
+        lastHeartbeatSeconds,
+        lastRuntimeState,
+        subscriptionsActive: Boolean(heartbeatUnsubscribe || runtimeStateUnsubscribe),
+      },
+    };
+  }
+
+  return {
+    start,
+    update,
+    stop,
+    getSnapshot,
+    getService: runtimeLayer.getService,
+    getState: runtimeLayer.getState,
+    states: runtimeLayer.states,
+    onBeforeUpdate: runtimeLayer.onBeforeUpdate,
+    onAfterUpdate: runtimeLayer.onAfterUpdate,
+    onStateChange: runtimeLayer.onStateChange,
+    getCoreServices() {
+      return coreServices;
+    },
+    getRuntimeLayer() {
+      return runtimeLayer;
+    },
+  };
+}

tests/runtime/Phase19CoreServicesSkeleton.test.mjs

@@ -6,7 +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 createPhase19IntegrationFlow from '../../samples/phase-19/shared/integration/createPhase19IntegrationFlow.js';
 import Phase19FoundationScene from '../../samples/phase-19/1901/Phase19FoundationScene.js';
 
 function createRendererProbe(width = 960, height = 540) {
@@ -57,9 +57,8 @@ function assertCoreServiceLifecycleAndCommunication() {
 }
 
 function assertPhase19SampleWiring() {
-  const coreServices = createPhase19CoreServices();
-  const runtimeLayer = createPhase19RuntimeLayer({ coreServices });
-  const scene = new Phase19FoundationScene({ runtimeLayer });
+  const phase19Flow = createPhase19IntegrationFlow();
+  const scene = new Phase19FoundationScene({ phase19Flow });
 
   scene.enter({});
   scene.update(0.55);
@@ -75,9 +74,9 @@ function assertPhase19SampleWiring() {
 
   scene.exit();
   assert.equal(
-    coreServices.getLifecycleState().running,
+    phase19Flow.getCoreServices().getLifecycleState().running,
     false,
-    'Scene exit should stop core services through runtime layer.'
+    'Scene exit should stop core services through integration flow.'
   );
 }
 

tests/runtime/Phase19IntegrationFlowPass.test.mjs

@@ -0,0 +1,40 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase19IntegrationFlowPass.test.mjs
+*/
+import assert from 'node:assert/strict';
+import createPhase19IntegrationFlow from '../../samples/phase-19/shared/integration/createPhase19IntegrationFlow.js';
+
+function assertIntegrationFlowLifecycleAndDataFlow() {
+  const flow = createPhase19IntegrationFlow();
+
+  assert.equal(flow.getState(), flow.states.IDLE, 'Integration flow should start in idle state.');
+  assert.equal(flow.start({ source: 'integration-test' }), true, 'Integration flow should start once.');
+
+  flow.update(0.25, { source: 'integration-test' });
+  flow.update(0.25, { source: 'integration-test' });
+  flow.update(0.5, { source: 'integration-test' });
+
+  const runningSnapshot = flow.getSnapshot();
+  assert.equal(runningSnapshot.runtime.state, flow.states.RUNNING, 'Runtime state should be running after start.');
+  assert.equal(runningSnapshot.runtime.tickCount >= 3, true, 'Runtime tick count should advance through updates.');
+  assert.equal(runningSnapshot.flow.heartbeatEvents >= 1, true, 'Heartbeat events should flow through integration layer.');
+  assert.equal(runningSnapshot.flow.runtimeStateEvents >= 1, true, 'Runtime state events should flow through integration layer.');
+  assert.equal(runningSnapshot.flow.lastRuntimeState, flow.states.RUNNING, 'Last runtime state should reflect running during active updates.');
+
+  assert.equal(flow.stop({ source: 'integration-test' }), true, 'Integration flow should stop cleanly.');
+  const stoppedSnapshot = flow.getSnapshot();
+  assert.equal(stoppedSnapshot.runtime.state, flow.states.STOPPED, 'Runtime state should be stopped after stop.');
+  assert.equal(stoppedSnapshot.flow.subscriptionsActive, false, 'Integration flow subscriptions should detach after stop.');
+  assert.equal(
+    flow.getCoreServices().getLifecycleState().running,
+    false,
+    'Core services should be stopped when integration flow stops.'
+  );
+}
+
+export function run() {
+  assertIntegrationFlowLifecycleAndDataFlow();
+}