fix(core): plugin startup elapsed time is duration, the name its spec contract already uses

`PluginStartupResult.startTime` has always carried `Date.now() - startTime`, an
elapsed duration, so the name asserts the opposite of the value: a reader who
correctly takes it for an instant and writes `Date.now() - result.startTime`
gets an age near the epoch. `packages/spec/src/kernel/startup-orchestrator.zod.ts`
already declares the correct name for the same measure (`duration`, "Time taken
to start the plugin in milliseconds"), and `PluginLoadResult.loadTime` twelve
lines above the defect already spells the identical computation truthfully -- so
this is a declared-vs-enforced divergence between `packages/core` and the spec
contract it implements, not a naming preference.

Three sites, all additive (nothing is removed, so no consumer changes):
  - `PluginStartupResult` gains `duration?: number`; `startTime` stays,
    populated with the same value, marked `@deprecated` with a doc comment that
    states plainly what it holds (ADR-0087 L1 -- the old shape keeps working).
  - the private `pluginStartTimes` map is renamed `pluginStartupDurations`
    (private; measured zero readers outside `kernel.ts`).
  - `getPluginStartupDurations()` is added and `getPluginMetrics()` becomes a
    deprecated delegating alias.

Pin tests assert the value is a bounded elapsed duration rather than an
epoch-millisecond instant, on the success and the failure path -- the assertion
`toBeGreaterThan(0)` could never make.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ARYe3yQTQCUFm5qPYNgKaJ

Author: claude[bot]

packages/core/ADVANCED_FEATURES.md

@@ -223,14 +223,15 @@ for (const [pluginName, health] of allHealth) {
 
 ### 7. Performance Metrics
 
-Track plugin startup times:
+Track plugin startup durations -- the map values are elapsed milliseconds,
+not start instants:
 
 ```typescript
 await kernel.bootstrap();
 
-const metrics = kernel.getPluginMetrics();
-for (const [pluginName, startTime] of metrics) {
-  console.log(`${pluginName}: ${startTime}ms`);
+const durations = kernel.getPluginStartupDurations();
+for (const [pluginName, duration] of durations) {
+  console.log(`${pluginName}: ${duration}ms`);
 }
 // plugin-1: 150ms
 // plugin-2: 320ms
@@ -327,7 +328,8 @@ Both kernels adhere to the same `Plugin` interface, but `ObjectKernel` supports
 - `async shutdown(): Promise<void>`
 - `async checkPluginHealth(pluginName: string): Promise<PluginHealthStatus>`
 - `async checkAllPluginsHealth(): Promise<Map<string, PluginHealthStatus>>`
-- `getPluginMetrics(): Map<string, number>`
+- `getPluginStartupDurations(): Map<string, number>`
+- `getPluginMetrics(): Map<string, number>` *(deprecated alias of the above)*
 - `async getServiceAsync<T>(name: string, scopeId?: string): Promise<T>`
 - `onShutdown(handler: () => Promise<void>): void`
 - `getState(): string`

packages/core/examples/kernel-features-example.ts

@@ -232,11 +232,11 @@ async function main() {
 
   console.log('\n✅ Kernel started successfully!\n');
 
-  // Show plugin metrics
-  console.log('📊 Plugin Startup Metrics:');
-  const metrics = kernel.getPluginMetrics();
-  for (const [name, time] of metrics) {
-    console.log(`   ${name}: ${time}ms`);
+  // Show plugin startup durations (elapsed ms, not start instants)
+  console.log('📊 Plugin Startup Durations:');
+  const durations = kernel.getPluginStartupDurations();
+  for (const [name, duration] of durations) {
+    console.log(`   ${name}: ${duration}ms`);
   }
   console.log('');
 

packages/core/src/kernel.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { ObjectKernel } from './kernel';
 import { ServiceLifecycle, PluginMetadata } from './plugin-loader';
+import type { PluginStartupResult } from './plugin-loader';
 import type { Plugin, PluginContext } from './types';
 import { recordGuards, stillPinningTheLoop } from '@objectstack/refd-timer-testkit';
 
@@ -582,6 +583,73 @@ describe('ObjectKernel', () => {
 
             await kernel.shutdown();
         });
+
+        // These two pin the MEANING of the number, not merely that one is
+        // present. The result member carrying it was spelled `startTime` while
+        // holding `Date.now() - start`, so a reader who correctly took it for an
+        // instant and wrote `Date.now() - result.startTime` got an age near the
+        // epoch. `toBeGreaterThan(0)` cannot tell the two readings apart -- an
+        // epoch-millisecond instant passes it too. A ceiling can: any instant
+        // today is ~1.7e12, orders of magnitude above any plugin's start().
+        const INSTANT_FLOOR_MS = 1_000_000_000; // ~11.5 days as a duration; well below any real epoch-ms instant
+
+        it('getPluginStartupDurations reports elapsed durations, not start instants', async () => {
+            const plugin: Plugin = {
+                name: 'timed-plugin',
+                version: '1.0.0',
+                init: async () => {},
+                start: async () => {
+                    await new Promise(resolve => setTimeout(resolve, 20));
+                },
+            };
+
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+
+            const durations = kernel.getPluginStartupDurations();
+            const value = durations.get('timed-plugin');
+
+            expect(value).toBeGreaterThan(0);
+            expect(value).toBeLessThan(INSTANT_FLOOR_MS);
+            // The deprecated alias is the same map, so it must agree.
+            expect(kernel.getPluginMetrics().get('timed-plugin')).toBe(value);
+
+            await kernel.shutdown();
+        });
+
+        it('PluginStartupResult.duration is an elapsed duration on both the success and the failure path', async () => {
+            const callStart = (meta: PluginMetadata): Promise<PluginStartupResult> =>
+                (kernel as unknown as {
+                    startPluginWithTimeout(p: PluginMetadata): Promise<PluginStartupResult>;
+                }).startPluginWithTimeout(meta);
+
+            const ok = await callStart({
+                name: 'ok-plugin',
+                version: '1.0.0',
+                start: async () => {
+                    await new Promise(resolve => setTimeout(resolve, 20));
+                },
+            } as PluginMetadata);
+
+            expect(ok.success).toBe(true);
+            expect(ok.duration).toBeGreaterThan(0);
+            expect(ok.duration).toBeLessThan(INSTANT_FLOOR_MS);
+            // The deprecated alias carries the same elapsed value, not an instant.
+            expect(ok.startTime).toBe(ok.duration);
+
+            const failed = await callStart({
+                name: 'failing-plugin',
+                version: '1.0.0',
+                start: async () => {
+                    throw new Error('boom');
+                },
+            } as PluginMetadata);
+
+            expect(failed.success).toBe(false);
+            expect(failed.duration).toBeGreaterThanOrEqual(0);
+            expect(failed.duration).toBeLessThan(INSTANT_FLOOR_MS);
+            expect(failed.startTime).toBe(failed.duration);
+        });
     });
 
     describe('Graceful Shutdown', () => {

packages/core/src/kernel.ts

@@ -66,7 +66,12 @@ export class ObjectKernel {
     private pluginLoader: PluginLoader;
     private config: ObjectKernelConfig;
     private startedPlugins: Set<string> = new Set();
-    private pluginStartTimes: Map<string, number> = new Map();
+    /**
+     * Plugin name -> elapsed milliseconds that plugin's `start()` took. These
+     * are DURATIONS, never start instants; the old spelling `pluginStartTimes`
+     * said the opposite of what it held.
+     */
+    private pluginStartupDurations: Map<string, number> = new Map();
     private shutdownHandlers: Array<() => Promise<void>> = [];
     /**
      * Name of the plugin whose init() is currently executing (Phase 1 is
@@ -533,11 +538,24 @@ export class ObjectKernel {
         return results;
     }
 
+    /**
+     * Per-plugin startup durations: plugin name -> elapsed milliseconds that
+     * plugin's `start()` took. Not start instants -- see
+     * {@link PluginStartupResult.duration}.
+     */
+    getPluginStartupDurations(): Map<string, number> {
+        return new Map(this.pluginStartupDurations);
+    }
+
     /**
      * Get plugin startup metrics
+     *
+     * @deprecated Renamed to {@link ObjectKernel.getPluginStartupDurations},
+     * which states what the values are. Retained as a delegating alias so
+     * nothing has to change on this release; slated for removal.
      */
     getPluginMetrics(): Map<string, number> {
-        return new Map(this.pluginStartTimes);
+        return this.getPluginStartupDurations();
     }
 
     /**
@@ -684,13 +702,16 @@ export class ObjectKernel {
 
             const duration = Date.now() - startTime;
             this.startedPlugins.add(plugin.name);
-            this.pluginStartTimes.set(plugin.name, duration);
+            this.pluginStartupDurations.set(plugin.name, duration);
 
             this.logger.debug(`Plugin started: ${plugin.name} (${duration}ms)`);
 
             return {
                 success: true,
                 pluginName: plugin.name,
+                duration,
+                // Deprecated alias carrying the same elapsed value; see
+                // PluginStartupResult.startTime.
                 startTime: duration,
             };
         } catch (error) {
@@ -701,6 +722,9 @@ export class ObjectKernel {
                 success: false,
                 pluginName: plugin.name,
                 error: error as Error,
+                duration,
+                // Deprecated alias carrying the same elapsed value; see
+                // PluginStartupResult.startTime.
                 startTime: duration,
                 timedOut: isTimeout,
             };

packages/core/src/plugin-loader.ts

@@ -91,6 +91,26 @@ export interface PluginLoadResult {
 export interface PluginStartupResult {
     success: boolean;
     pluginName: string;
+    /**
+     * Elapsed milliseconds the plugin's `start()` took.
+     *
+     * Named for the member the spec contract this result implements already
+     * declares -- `PluginStartupResultSchema.duration` in
+     * `packages/spec/src/kernel/startup-orchestrator.zod.ts` ("Time taken to
+     * start the plugin in milliseconds") -- and matching `PluginLoadResult.loadTime`
+     * above: the same `Date.now() - startTime` computation under a name that
+     * does not lie.
+     */
+    duration?: number;
+    /**
+     * The same elapsed milliseconds as {@link PluginStartupResult.duration}.
+     *
+     * @deprecated Misnamed: this has never held an instant, so a reader who
+     * correctly takes `startTime` for one and writes `Date.now() - result.startTime`
+     * gets an age near the epoch instead of a wait. Read `duration` instead.
+     * Still populated so nothing has to change on this release (ADR-0087 L1 --
+     * the old shape keeps working while the fleet moves); slated for removal.
+     */
     startTime?: number;
     error?: Error;
     timedOut?: boolean;