Establish Phase 19 core services skeleton including registry, lifecycle hooks, and baseline wiring for the next runtime layer

PR: BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

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

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,3 @@
-Establish Phase 19 foundation structure and minimal wiring
+Establish Phase 19 core services skeleton including registry, lifecycle hooks, and baseline wiring for the next runtime layer
 
-PR: BUILD_PR_LEVEL_19_2_PHASE19_FOUNDATION
+PR: BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES

docs/dev/reports/validation_checklist.txt

@@ -1,2 +1,3 @@
-- [ ] structure created
-- [ ] no errors
+- [ ] services initialize
+- [ ] no runtime errors
+- [ ] baseline wiring loads

docs/pr/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md

@@ -0,0 +1,40 @@
+# BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES
+
+## Purpose
+Implement a minimal Phase 19 core-services skeleton and wire it into the existing `1901` foundation sample.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md`
+- `docs/pr/BUILD_PR_LEVEL_19_2_PHASE19_FOUNDATION.md`
+
+## Exact Build Target
+1. Add a Phase 19 shared core-services skeleton under:
+   - `samples/phase-19/shared/coreServices/`
+2. Include:
+   - one service contract validator
+   - one service registry with lifecycle hooks (`start`, `update`, `stop`)
+   - one communication service (channel/event bus wrapper)
+   - one baseline heartbeat service
+   - one bootstrap factory that registers baseline services
+3. Wire sample `1901` to use the core-services skeleton:
+   - initialize services in `main.js`
+   - start/update/stop via scene lifecycle hooks
+   - render minimal service status in sample panel
+4. Add targeted runtime validation:
+   - core-service lifecycle + communication path
+   - sample `1901` service-status rendering path
+
+## Non-Goals
+- no engine core modifications
+- no gameplay/system feature implementation
+- no runtime-layer or integration-flow implementation
+- no additional Phase 19 samples
+- no roadmap status updates
+
+## Validation
+- targeted runtime test for service registry lifecycle + communication path passes
+- sample `1901` still renders and surfaces heartbeat/service status without errors
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.zip`

docs/pr/PLAN_PR_LEVEL_19_3_PHASE19_CORE_SERVICES.md

@@ -0,0 +1,26 @@
+# PLAN_PR_LEVEL_19_3_PHASE19_CORE_SERVICES
+
+## Purpose
+Define and implement a minimal Phase 19 core-services skeleton and wire it into sample `1901`.
+
+## Source of Truth
+- `docs/pr/BUILD_PR_LEVEL_19_2_PHASE19_FOUNDATION.md`
+- `docs/pr/PLAN_PR_LEVEL_19_2_PHASE19_FOUNDATION.md`
+
+## Scope
+- add Phase 19 shared core-services modules under `samples/phase-19/shared/coreServices/`
+- include a service contract validator, service registry, channel service, and heartbeat service
+- add one bootstrap factory that registers baseline services
+- wire sample `1901` to start/update/stop core services and render minimal service status
+- add targeted runtime validation for core-service lifecycle + communication path
+
+## Out of Scope
+- no runtime-layer implementation
+- no integration-flow abstraction
+- no additional Phase 19 samples
+- no roadmap status updates
+
+## Exit Criteria
+- core-services skeleton exists and is wired into `1901`
+- lifecycle and communication path are validated with targeted test coverage
+- scoped delta is ready for repo-structured packaging

samples/phase-19/1901/Phase19FoundationScene.js

@@ -11,20 +11,45 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 const theme = new Theme(ThemeTokens);
 
 export default class Phase19FoundationScene extends Scene {
-  constructor() {
+  constructor({ coreServices = null } = {}) {
     super();
     this.elapsed = 0;
+    this.coreServices = coreServices;
+    this.lastHeartbeatTick = 0;
+    this.lastHeartbeatTime = 0;
+    this.unsubscribeHeartbeat = null;
+  }
+
+  enter(engine) {
+    if (!this.coreServices) return;
+    const channel = this.coreServices.get('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 });
   }
 
   update(dtSeconds) {
     this.elapsed += dtSeconds;
+    this.coreServices?.update(dtSeconds, { scene: this });
+  }
+
+  exit() {
+    if (typeof this.unsubscribeHeartbeat === 'function') {
+      this.unsubscribeHeartbeat();
+      this.unsubscribeHeartbeat = null;
+    }
+    this.coreServices?.stop({ scene: this });
   }
 
   render(renderer) {
     drawFrame(renderer, theme, [
-      'Sample 1901 - Phase 19 Foundation',
-      'Minimal Phase 19 scaffold with launcher wiring.',
-      'No feature implementation in this foundation slice.',
+      'Sample 1901 - Phase 19 Core Services',
+      'Minimal Phase 19 core-services skeleton wired into foundation sample.',
+      'No feature implementation in this core-services slice.',
     ]);
 
     renderer.drawRect(120, 212, 720, 200, '#0f172a');
@@ -38,12 +63,22 @@ export default class Phase19FoundationScene extends Scene {
       font: '16px monospace',
     });
 
+    const lifecycle = this.coreServices?.getLifecycleState?.() || {
+      running: false,
+      serviceCount: 0,
+    };
+    const channelSnapshot = this.coreServices?.get?.('phase19.channel')?.getSnapshot?.() || {
+      publishedCount: 0,
+      lastChannel: 'none',
+    };
     drawPanel(renderer, 620, 34, 300, 140, 'Phase 19 Bootstrap', [
-      'Status: initialized',
+      'Status: initialized (core services)',
       'Folder: samples/phase-19',
       'Entry sample: 1901',
-      'Scope: structure + wiring only',
-      'Features: deferred',
+      `Running: ${lifecycle.running ? 'yes' : 'no'}`,
+      `Services: ${lifecycle.serviceCount}`,
+      `Published: ${channelSnapshot.publishedCount} (${channelSnapshot.lastChannel})`,
+      `Heartbeat tick: ${this.lastHeartbeatTick} @ ${this.lastHeartbeatTime.toFixed(2)}s`,
     ]);
   }
 }

samples/phase-19/1901/main.js

@@ -7,6 +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 Phase19FoundationScene from './Phase19FoundationScene.js';
 
 const theme = new Theme(ThemeTokens);
@@ -23,5 +24,6 @@ const engine = new Engine({
   input,
 });
 
-engine.setScene(new Phase19FoundationScene());
+const coreServices = createPhase19CoreServices();
+engine.setScene(new Phase19FoundationScene({ coreServices }));
 engine.start();

samples/phase-19/shared/coreServices/createPhase19ChannelService.js

@@ -0,0 +1,47 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19ChannelService.js
+*/
+import EventBus from '/src/engine/events/EventBus.js';
+
+export default function createPhase19ChannelService() {
+  const bus = new EventBus();
+  let running = false;
+  let publishedCount = 0;
+  let lastChannel = 'none';
+
+  function publish(channel, payload = {}) {
+    if (!running || typeof channel !== 'string' || channel.length === 0) {
+      return 0;
+    }
+    lastChannel = channel;
+    publishedCount += 1;
+    return bus.emit(channel, payload);
+  }
+
+  function subscribe(channel, handler) {
+    return bus.on(channel, handler);
+  }
+
+  return {
+    id: 'phase19.channel',
+    publish,
+    subscribe,
+    getSnapshot() {
+      return {
+        running,
+        publishedCount,
+        lastChannel,
+      };
+    },
+    onStart() {
+      running = true;
+    },
+    onStop() {
+      running = false;
+      bus.clear();
+    },
+  };
+}

samples/phase-19/shared/coreServices/createPhase19CoreServices.js

@@ -0,0 +1,16 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19CoreServices.js
+*/
+import createPhase19ServiceRegistry from './createPhase19ServiceRegistry.js';
+import createPhase19ChannelService from './createPhase19ChannelService.js';
+import createPhase19HeartbeatService from './createPhase19HeartbeatService.js';
+
+export default function createPhase19CoreServices() {
+  const registry = createPhase19ServiceRegistry();
+  registry.register(createPhase19ChannelService());
+  registry.register(createPhase19HeartbeatService());
+  return registry;
+}

samples/phase-19/shared/coreServices/createPhase19HeartbeatService.js

@@ -0,0 +1,51 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase19HeartbeatService.js
+*/
+export default function createPhase19HeartbeatService({ intervalSeconds = 0.5 } = {}) {
+  const safeInterval = Math.max(0.05, Number(intervalSeconds) || 0.5);
+  let running = false;
+  let elapsed = 0;
+  let ticks = 0;
+  let lastBeatSeconds = 0;
+
+  return {
+    id: 'phase19.heartbeat',
+    onStart() {
+      running = true;
+      elapsed = 0;
+      ticks = 0;
+      lastBeatSeconds = 0;
+    },
+    onUpdate(dtSeconds, context = {}) {
+      if (!running) return;
+      const dt = Math.max(0, Number(dtSeconds) || 0);
+      elapsed += dt;
+      while (elapsed >= safeInterval) {
+        elapsed -= safeInterval;
+        ticks += 1;
+        lastBeatSeconds += safeInterval;
+        const channel = context.getService?.('phase19.channel');
+        if (channel && typeof channel.publish === 'function') {
+          channel.publish('phase19.heartbeat', {
+            tick: ticks,
+            t: Number(lastBeatSeconds.toFixed(3)),
+          });
+        }
+      }
+    },
+    onStop() {
+      running = false;
+    },
+    getSnapshot() {
+      return {
+        running,
+        intervalSeconds: safeInterval,
+        ticks,
+        lastBeatSeconds: Number(lastBeatSeconds.toFixed(3)),
+      };
+    },
+  };
+}