Phase 18 core services skeleton

DavidQ · DavidQ · commit a81b181e194d · 2026-04-16T12:31:40.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Create Phase 18 foundation structure and minimal wiring, package to <project folder>/tmp/BUILD_PR_LEVEL_18_2_PHASE18_FOUNDATION.zip
+COMMAND: Implement Phase 18 core services skeleton and wiring, package to <project folder>/tmp/BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-Phase 18 foundation structure and minimal wiring
+Phase 18 core services skeleton
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,3 +1,2 @@
-- [ ] folders created
+- [ ] services initialize
 - [ ] no runtime errors
-- [ ] index/registry loads
diff --git a/docs/pr/BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md b/docs/pr/BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md
@@ -0,0 +1,36 @@
+# BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES
+
+## Purpose
+Implement a minimal Phase 18 core-services skeleton and wire it into the existing `1801` foundation sample.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md`
+- `docs/pr/BUILD_PR_LEVEL_18_2_PHASE18_FOUNDATION.md`
+
+## Exact Build Target
+1. Add a Phase 18 shared core-services skeleton under:
+   - `samples/phase-18/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 `1801` 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
+
+## Non-Goals
+- no engine core modifications
+- no gameplay/system feature implementation
+- no additional Phase 18 samples
+- no roadmap status updates
+
+## Validation
+- targeted runtime test for service registry lifecycle + communication path
+- sample `1801` still renders with service status
+
+## Packaging Rule
+Package only this PR's created/modified files into:
+`tmp/BUILD_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.zip`
diff --git a/docs/pr/PLAN_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md b/docs/pr/PLAN_PR_LEVEL_18_3_PHASE18_CORE_SERVICES.md
@@ -0,0 +1,9 @@
+# PLAN_PR_LEVEL_18_3_PHASE18_CORE_SERVICES
+
+Purpose:
+Define core services for Phase 18.
+
+Scope:
+- service registry
+- lifecycle hooks
+- communication patterns
diff --git a/samples/phase-18/1801/Phase18FoundationScene.js b/samples/phase-18/1801/Phase18FoundationScene.js
@@ -11,13 +11,38 @@ import { drawFrame, drawPanel } from '/src/engine/debug/index.js';
 const theme = new Theme(ThemeTokens);
 
 export default class Phase18FoundationScene 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('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 });
   }
 
   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) {
@@ -42,7 +67,8 @@ export default class Phase18FoundationScene extends Scene {
       'Status: initialized',
       'Folder: samples/phase-18',
       'Entry sample: 1801',
-      'Next: scoped Level 18 slices',
+      `Services: ${this.coreServices?.listServiceIds().length ?? 0}`,
+      `Heartbeat tick: ${this.lastHeartbeatTick} @ ${this.lastHeartbeatTime.toFixed(2)}s`,
     ]);
   }
 }
diff --git a/samples/phase-18/1801/index.html b/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 wiring and no feature implementation.</p>
+    <p>Bootstrap scaffold for Phase 18 with minimal core-service lifecycle wiring and no feature logic.</p>
     <canvas id="game" width="960" height="540"></canvas>
 
     <section>
diff --git a/samples/phase-18/1801/main.js b/samples/phase-18/1801/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 createPhase18CoreServices from '/samples/phase-18/shared/coreServices/createPhase18CoreServices.js';
 import Phase18FoundationScene from './Phase18FoundationScene.js';
 
 const theme = new Theme(ThemeTokens);
@@ -23,5 +24,6 @@ const engine = new Engine({
   input,
 });
 
-engine.setScene(new Phase18FoundationScene());
+const coreServices = createPhase18CoreServices();
+engine.setScene(new Phase18FoundationScene({ coreServices }));
 engine.start();
diff --git a/samples/phase-18/shared/coreServices/createPhase18ChannelService.js b/samples/phase-18/shared/coreServices/createPhase18ChannelService.js
@@ -0,0 +1,47 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18ChannelService.js
+*/
+import EventBus from '/src/engine/events/EventBus.js';
+
+export default function createPhase18ChannelService() {
+  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: 'phase18.channel',
+    publish,
+    subscribe,
+    getSnapshot() {
+      return {
+        running,
+        publishedCount,
+        lastChannel,
+      };
+    },
+    onStart() {
+      running = true;
+    },
+    onStop() {
+      running = false;
+      bus.clear();
+    },
+  };
+}
diff --git a/samples/phase-18/shared/coreServices/createPhase18CoreServices.js b/samples/phase-18/shared/coreServices/createPhase18CoreServices.js
@@ -0,0 +1,16 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18CoreServices.js
+*/
+import createPhase18ServiceRegistry from './createPhase18ServiceRegistry.js';
+import createPhase18ChannelService from './createPhase18ChannelService.js';
+import createPhase18HeartbeatService from './createPhase18HeartbeatService.js';
+
+export default function createPhase18CoreServices() {
+  const registry = createPhase18ServiceRegistry();
+  registry.register(createPhase18ChannelService());
+  registry.register(createPhase18HeartbeatService());
+  return registry;
+}
diff --git a/samples/phase-18/shared/coreServices/createPhase18HeartbeatService.js b/samples/phase-18/shared/coreServices/createPhase18HeartbeatService.js
@@ -0,0 +1,51 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18HeartbeatService.js
+*/
+export default function createPhase18HeartbeatService({ 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: 'phase18.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?.('phase18.channel');
+        if (channel && typeof channel.publish === 'function') {
+          channel.publish('phase18.heartbeat', {
+            tick: ticks,
+            t: Number(lastBeatSeconds.toFixed(3)),
+          });
+        }
+      }
+    },
+    onStop() {
+      running = false;
+    },
+    getSnapshot() {
+      return {
+        running,
+        intervalSeconds: safeInterval,
+        ticks,
+        lastBeatSeconds: Number(lastBeatSeconds.toFixed(3)),
+      };
+    },
+  };
+}
diff --git a/samples/phase-18/shared/coreServices/createPhase18ServiceRegistry.js b/samples/phase-18/shared/coreServices/createPhase18ServiceRegistry.js
@@ -0,0 +1,102 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+createPhase18ServiceRegistry.js
+*/
+import { assertValidPhase18Service } from './phase18ServiceContract.js';
+
+export default function createPhase18ServiceRegistry() {
+  const servicesById = new Map();
+  const serviceOrder = [];
+  let running = false;
+
+  function withContext(context = {}) {
+    return {
+      ...context,
+      serviceRegistry: api,
+      getService: get,
+      listServiceIds,
+    };
+  }
+
+  function register(service) {
+    assertValidPhase18Service(service);
+    if (servicesById.has(service.id)) {
+      throw new Error(`Duplicate service id: ${service.id}`);
+    }
+    servicesById.set(service.id, service);
+    serviceOrder.push(service.id);
+    if (typeof service.onRegister === 'function') {
+      service.onRegister(withContext());
+    }
+    return service;
+  }
+
+  function get(serviceId) {
+    return servicesById.get(serviceId) || null;
+  }
+
+  function listServiceIds() {
+    return [...serviceOrder];
+  }
+
+  function start(context = {}) {
+    if (running) return false;
+    running = true;
+    const ctx = withContext(context);
+    for (let i = 0; i < serviceOrder.length; i += 1) {
+      const service = servicesById.get(serviceOrder[i]);
+      if (service && typeof service.onStart === 'function') {
+        service.onStart(ctx);
+      }
+    }
+    return true;
+  }
+
+  function update(dtSeconds, context = {}) {
+    if (!running) return 0;
+    const ctx = withContext(context);
+    let updated = 0;
+    for (let i = 0; i < serviceOrder.length; i += 1) {
+      const service = servicesById.get(serviceOrder[i]);
+      if (service && typeof service.onUpdate === 'function') {
+        service.onUpdate(dtSeconds, ctx);
+        updated += 1;
+      }
+    }
+    return updated;
+  }
+
+  function stop(context = {}) {
+    if (!running) return false;
+    const ctx = withContext(context);
+    for (let i = serviceOrder.length - 1; i >= 0; i -= 1) {
+      const service = servicesById.get(serviceOrder[i]);
+      if (service && typeof service.onStop === 'function') {
+        service.onStop(ctx);
+      }
+    }
+    running = false;
+    return true;
+  }
+
+  function getLifecycleState() {
+    return {
+      running,
+      serviceCount: serviceOrder.length,
+      serviceIds: listServiceIds(),
+    };
+  }
+
+  const api = {
+    register,
+    get,
+    listServiceIds,
+    start,
+    update,
+    stop,
+    getLifecycleState,
+  };
+  return api;
+}
diff --git a/samples/phase-18/shared/coreServices/phase18ServiceContract.js b/samples/phase-18/shared/coreServices/phase18ServiceContract.js
@@ -0,0 +1,25 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+phase18ServiceContract.js
+*/
+export function isValidPhase18Service(service) {
+  if (!service || typeof service !== 'object') return false;
+  if (typeof service.id !== 'string' || service.id.trim().length === 0) return false;
+
+  const hookNames = ['onRegister', 'onStart', 'onUpdate', 'onStop'];
+  for (let i = 0; i < hookNames.length; i += 1) {
+    const hook = service[hookNames[i]];
+    if (hook !== undefined && typeof hook !== 'function') {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function assertValidPhase18Service(service) {
+  if (!isValidPhase18Service(service)) {
+    throw new Error('Invalid Phase 18 service contract.');
+  }
+}
diff --git a/tests/runtime/Phase18CoreServicesSkeleton.test.mjs b/tests/runtime/Phase18CoreServicesSkeleton.test.mjs

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Phase 18 foundation structure and minimal wiring`
	`1`	`+Phase 18 core services skeleton`