Phase 18 integration pass

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-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
+COMMAND: Integrate Phase 18 services and runtime layer, validate flow, package to <project folder>/tmp/BUILD_PR_LEVEL_18_5_PHASE18_INTEGRATION_PASS.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Phase 18 runtime layer scaffolding
+Phase 18 integration pass

docs/dev/reports/validation_checklist.txt

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

docs/pr/BUILD_PR_LEVEL_18_5_PHASE18_INTEGRATION_PASS.md

@@ -0,0 +1,36 @@
+# BUILD_PR_LEVEL_18_5_PHASE18_INTEGRATION_PASS
+
+## Purpose
+Integrate Phase 18 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_18_5_PHASE18_INTEGRATION_PASS.md`
+- `docs/pr/BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md`
+- `docs/pr/BUILD_PR_LEVEL_18_4_PHASE18_RUNTIME_LAYER.md`
+
+## Exact Build Target
+1. Add a Phase 18 integration-flow module that composes:
+   - core services registry
+   - runtime layer
+   - flow-level event subscriptions and snapshots
+2. Rewire sample `1801` 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 18 sample entries
+- no roadmap status changes
+
+## Validation
+- targeted integration flow test passes
+- existing runtime/core service targeted tests still pass
+- sample `1801` renders integration flow status without errors
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_18_5_PHASE18_INTEGRATION_PASS.zip`

docs/pr/PLAN_PR_LEVEL_18_5_PHASE18_INTEGRATION_PASS.md

@@ -0,0 +1,8 @@
+# PLAN_PR_LEVEL_18_5_PHASE18_INTEGRATION_PASS
+
+Purpose:
+Integrate Phase 18 layers into cohesive flow.
+
+Scope:
+- connect services + runtime
+- validate data flow

samples/phase-18/1801/Phase18FoundationScene.js

@@ -11,47 +11,40 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 const theme = new Theme(ThemeTokens);
 
 export default class Phase18FoundationScene extends Scene {
-  constructor({ runtimeLayer = null } = {}) {
+  constructor({ phase18Flow = null } = {}) {
     super();
     this.elapsed = 0;
-    this.runtimeLayer = runtimeLayer;
+    this.phase18Flow = phase18Flow;
     this.lastHeartbeatTick = 0;
     this.lastHeartbeatTime = 0;
     this.lastRuntimeTransition = 'idle';
-    this.unsubscribeHeartbeat = null;
     this.unsubscribeRuntimeState = null;
   }
 
   enter(engine) {
-    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.unsubscribeRuntimeState = this.runtimeLayer.onStateChange(({ previous, next }) => {
+    if (!this.phase18Flow) return;
+    this.unsubscribeRuntimeState = this.phase18Flow.onStateChange(({ previous, next }) => {
       this.lastRuntimeTransition = `${previous} -> ${next}`;
     });
-    this.runtimeLayer.start({ engine, scene: this });
+    this.phase18Flow.start({ engine, scene: this });
   }
 
   update(dtSeconds) {
     this.elapsed += dtSeconds;
-    this.runtimeLayer?.update(dtSeconds, { scene: this });
+    this.phase18Flow?.update(dtSeconds, { scene: this });
+    const snapshot = this.phase18Flow?.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.phase18Flow?.stop({ scene: this });
   }
 
   render(renderer) {
@@ -72,17 +65,29 @@ export default class Phase18FoundationScene extends Scene {
       font: '16px monospace',
     });
 
-    const runtimeSnapshot = this.runtimeLayer?.getSnapshot?.() || {
+    const phase18Snapshot = this.phase18Flow?.getSnapshot?.() || {
+      runtime: {
+        state: 'idle',
+        tickCount: 0,
+        serviceIds: [],
+      },
+      flow: {
+        runtimeStateEvents: 0,
+      },
+    };
+    const runtimeSnapshot = phase18Snapshot.runtime || {
       state: 'idle',
       tickCount: 0,
       serviceIds: [],
     };
+    const flowSnapshot = phase18Snapshot.flow || { runtimeStateEvents: 0 };
     drawPanel(renderer, 620, 34, 300, 160, 'Phase 18 Bootstrap', [
       'Status: initialized',
       'Folder: samples/phase-18',
       'Entry sample: 1801',
       `Runtime: ${runtimeSnapshot.state} | tick ${runtimeSnapshot.tickCount}`,
       `Transition: ${this.lastRuntimeTransition}`,
+      `Flow events: ${flowSnapshot.runtimeStateEvents}`,
       `Services: ${runtimeSnapshot.serviceIds.length}`,
       `Heartbeat tick: ${this.lastHeartbeatTick} @ ${this.lastHeartbeatTime.toFixed(2)}s`,
     ]);

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

samples/phase-18/shared/integration/createPhase18IntegrationFlow.js

@@ -0,0 +1,96 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18IntegrationFlow.js
+*/
+import createPhase18CoreServices from '../coreServices/createPhase18CoreServices.js';
+import createPhase18RuntimeLayer from '../runtimeLayer/createPhase18RuntimeLayer.js';
+
+export default function createPhase18IntegrationFlow({
+  coreServices = createPhase18CoreServices(),
+  runtimeLayer = createPhase18RuntimeLayer({ 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('phase18.channel');
+    if (!channel || typeof channel.subscribe !== 'function') return;
+
+    heartbeatUnsubscribe = channel.subscribe('phase18.heartbeat', (payload) => {
+      heartbeatEvents += 1;
+      lastHeartbeatTick = Number(payload?.tick) || 0;
+      lastHeartbeatSeconds = Number(payload?.t) || 0;
+    });
+    runtimeStateUnsubscribe = channel.subscribe('phase18.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/Phase18CoreServicesSkeleton.test.mjs

@@ -7,6 +7,7 @@ Phase18CoreServicesSkeleton.test.mjs
 import assert from 'node:assert/strict';
 import createPhase18CoreServices from '../../samples/phase-18/shared/coreServices/createPhase18CoreServices.js';
 import createPhase18RuntimeLayer from '../../samples/phase-18/shared/runtimeLayer/createPhase18RuntimeLayer.js';
+import createPhase18IntegrationFlow from '../../samples/phase-18/shared/integration/createPhase18IntegrationFlow.js';
 import Phase18FoundationScene from '../../samples/phase-18/1801/Phase18FoundationScene.js';
 
 function createRendererProbe(width = 960, height = 540) {
@@ -57,9 +58,8 @@ function assertCoreServiceLifecycleAndCommunication() {
 }
 
 function assertPhase18SampleWiring() {
-  const services = createPhase18CoreServices();
-  const runtimeLayer = createPhase18RuntimeLayer({ coreServices: services });
-  const scene = new Phase18FoundationScene({ runtimeLayer });
+  const phase18Flow = createPhase18IntegrationFlow();
+  const scene = new Phase18FoundationScene({ phase18Flow });
 
   scene.enter({});
   scene.update(0.55);
@@ -74,7 +74,11 @@ function assertPhase18SampleWiring() {
   );
 
   scene.exit();
-  assert.equal(services.getLifecycleState().running, false, 'Scene exit should stop core services through runtime integration.');
+  assert.equal(
+    phase18Flow.getCoreServices().getLifecycleState().running,
+    false,
+    'Scene exit should stop core services through integration flow.'
+  );
 }
 
 export function run() {

tests/runtime/Phase18IntegrationFlowPass.test.mjs

@@ -0,0 +1,40 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase18IntegrationFlowPass.test.mjs
+*/
+import assert from 'node:assert/strict';
+import createPhase18IntegrationFlow from '../../samples/phase-18/shared/integration/createPhase18IntegrationFlow.js';
+
+function assertIntegrationFlowLifecycleAndDataFlow() {
+  const flow = createPhase18IntegrationFlow();
+
+  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();
+}