fix(core): spell the plugin startup elapsed time durationMs, the unit-bearing name its spec contract declares

Discharges contract review 5555409410 on PR #16057 (head 4d20aa7): the new
published member was spelled `duration`, a key `packages/spec` has since
retired. Measured on origin/main f377394:
`packages/spec/src/kernel/startup-orchestrator.zod.ts:173` declares
`durationMs`; `:176` tombstones `duration` with `retiredKey()` ("Rename the
key to `durationMs`"); the gate
`packages/spec/scripts/check-duration-unit-keys.ts` is in the tree (landed
e9fcd6b). Two maintainer rulings make the rule govern every runtime-emitted
duration, and a per-plugin startup elapsed time on a public result type is one.

- `PluginStartupResult.durationMs?: number` replaces the never-released
  `duration?: number`; both emit sites in `kernel.ts` follow; `startTime`
  keeps its deprecated-alias treatment exactly as before.
- The provenance sentence in the interface JSDoc (which ships in the published
  `dist/index.d.ts`), in `kernel.ts`'s `{@link}` and in the changeset cited
  the retired `PluginStartupResultSchema.duration`; all three now cite
  `durationMs` and say the bare spelling is retired.
- The two pin tests read `.durationMs`; their ceiling assertion is unchanged.

No ADR-0087 treatment on the core side: the spec tombstone entry
(`packages/spec/src/migrations/entries/retired-keys/18.kernel__PluginStartupResult__duration.ts`)
records that core's interface is a different type and not a reader of the
schema; core simply does not adopt the retired spelling.

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

Author: claude

.changeset/core-plugin-startup-duration-name.md

@@ -2,18 +2,18 @@
 "@objectstack/core": minor
 ---
 
-Plugin startup elapsed time is now reported as `duration` — the name the spec contract for the same result already declares. `startTime`, which never held a start time, is deprecated and still populated.
+Plugin startup elapsed time is now reported as `durationMs` — the unit-bearing name the spec contract for the same result declares. `startTime`, which never held a start time, is deprecated and still populated.
 
 `PluginStartupResult.startTime` (`packages/core/src/plugin-loader.ts`) has always been assigned `Date.now() - startTime`, an elapsed duration, on both the success and the failure path. The name therefore asserts the opposite of the value: a reader who correctly takes `startTime` for an instant and writes `Date.now() - result.startTime` gets an age near the epoch rather than a wait. That is the one failure mode a unit convention cannot rescue — an ambiguous name makes someone stop and check, this one lets them proceed confidently wrong.
 
-This is not a naming preference but a divergence between what is declared and what is enforced. `packages/spec/src/kernel/startup-orchestrator.zod.ts` declares `duration: z.number().min(0)` — "Time taken to start the plugin in milliseconds" — for the same measure on the same result, the outcome of starting one plugin. The contract surface was already correct and `packages/core` had drifted away from it. The right spelling is also twelve lines above the defect in the same file: `PluginLoadResult.loadTime` carries the identical `Date.now() - startTime` computation under a name that does not lie.
+This is not a naming preference but a divergence between what is declared and what is enforced. `packages/spec/src/kernel/startup-orchestrator.zod.ts` declares `durationMs: z.number().min(0)` — "Time taken to start the plugin in milliseconds" — for the same measure on the same result, the outcome of starting one plugin; the bare `duration` spelling is retired there with a `retiredKey()` tombstone whose prescription is "Rename the key to `durationMs`", because a duration-shaped number carries its unit in its key name, never only in describe prose. The contract surface was already correct and `packages/core` had drifted away from it. The same computation already has an honest name twelve lines above the defect in the same file: `PluginLoadResult.loadTime` carries the identical `Date.now() - startTime` under a name that does not lie.
 
 Three sites move, and every one of them is additive — nothing is removed, so no consumer has to change anything on this release:
 
-- `PluginStartupResult` gains `duration?: number`. `startTime?: number` stays, still carrying the same value, marked `@deprecated` with a doc comment that states plainly it is elapsed milliseconds and not an instant.
+- `PluginStartupResult` gains `durationMs?: number`. `startTime?: number` stays, still carrying the same value, marked `@deprecated` with a doc comment that states plainly it is elapsed milliseconds and not an instant.
 - `ObjectKernel.getPluginStartupDurations()` is added; `getPluginMetrics()` becomes a `@deprecated` delegating alias returning the same map.
 - The private `pluginStartTimes` map is renamed `pluginStartupDurations` (private; no reader outside `kernel.ts` in this repo or in the pinned `objectui` sibling).
 
-Migration, where you want it: read `result.duration` where you read `result.startTime`, and `kernel.getPluginStartupDurations()` where you called `kernel.getPluginMetrics()`. The values are identical, so the change can be made at leisure; both old spellings keep working until they are removed.
+Migration, where you want it: read `result.durationMs` where you read `result.startTime`, and `kernel.getPluginStartupDurations()` where you called `kernel.getPluginMetrics()`. The values are identical, so the change can be made at leisure; both old spellings keep working until they are removed.
 
-ADR-0087 disposition: no migration-ledger entry, and none is required. Nothing is retired by this release — the old member and the old method both remain, populated and callable, which is ADR-0087's L1 outcome (the old shape keeps loading while the fleet moves) rather than a retirement. There is also nothing for `objectstack migrate meta` to rewrite: `packages/core/src/plugin-loader.ts#PluginStartupResult` is a runtime TypeScript interface with no Zod schema, no `packages/spec` declaration and no stored representation — the `PluginStartupResult` in `packages/spec/src/kernel/startup-orchestrator.zod.ts` is a separate, differently-shaped declaration that this change does not touch. When the deprecated spellings are removed, that removal is the change that carries the ledger disposition.
+ADR-0087 disposition: no migration-ledger entry, and none is required. Nothing is retired by this release — the old member and the old method both remain, populated and callable, which is ADR-0087's L1 outcome (the old shape keeps loading while the fleet moves) rather than a retirement. There is also nothing for `objectstack migrate meta` to rewrite: `packages/core/src/plugin-loader.ts#PluginStartupResult` is a runtime TypeScript interface with no Zod schema, no `packages/spec` declaration and no stored representation — the `PluginStartupResult` in `packages/spec/src/kernel/startup-orchestrator.zod.ts` is a separate, differently-shaped declaration that this change does not touch, and that schema's own `duration` tombstone entry (`packages/spec/src/migrations/entries/retired-keys/18.kernel__PluginStartupResult__duration.ts`) records that core's interface is not a reader of it. Core simply does not adopt the retired spelling. When the deprecated spellings are removed, that removal is the change that carries the ledger disposition.

packages/core/src/kernel.test.ts

@@ -617,7 +617,7 @@ describe('ObjectKernel', () => {
             await kernel.shutdown();
         });
 
-        it('PluginStartupResult.duration is an elapsed duration on both the success and the failure path', async () => {
+        it('PluginStartupResult.durationMs 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>;
@@ -634,10 +634,10 @@ describe('ObjectKernel', () => {
             const ok = await callStart(okMeta);
 
             expect(ok.success).toBe(true);
-            expect(ok.duration).toBeGreaterThan(0);
-            expect(ok.duration).toBeLessThan(INSTANT_FLOOR_MS);
+            expect(ok.durationMs).toBeGreaterThan(0);
+            expect(ok.durationMs).toBeLessThan(INSTANT_FLOOR_MS);
             // The deprecated alias carries the same elapsed value, not an instant.
-            expect(ok.startTime).toBe(ok.duration);
+            expect(ok.startTime).toBe(ok.durationMs);
 
             const failingMeta: PluginMetadata = {
                 name: 'failing-plugin',
@@ -650,9 +650,9 @@ describe('ObjectKernel', () => {
             const failed = await callStart(failingMeta);
 
             expect(failed.success).toBe(false);
-            expect(failed.duration).toBeGreaterThanOrEqual(0);
-            expect(failed.duration).toBeLessThan(INSTANT_FLOOR_MS);
-            expect(failed.startTime).toBe(failed.duration);
+            expect(failed.durationMs).toBeGreaterThanOrEqual(0);
+            expect(failed.durationMs).toBeLessThan(INSTANT_FLOOR_MS);
+            expect(failed.startTime).toBe(failed.durationMs);
         });
     });
 

packages/core/src/kernel.ts

@@ -541,7 +541,7 @@ export class ObjectKernel {
     /**
      * Per-plugin startup durations: plugin name -> elapsed milliseconds that
      * plugin's `start()` took. Not start instants -- see
-     * {@link PluginStartupResult.duration}.
+     * {@link PluginStartupResult.durationMs}.
      */
     getPluginStartupDurations(): Map<string, number> {
         return new Map(this.pluginStartupDurations);
@@ -709,7 +709,7 @@ export class ObjectKernel {
             return {
                 success: true,
                 pluginName: plugin.name,
-                duration,
+                durationMs: duration,
                 // Deprecated alias carrying the same elapsed value; see
                 // PluginStartupResult.startTime.
                 startTime: duration,
@@ -722,7 +722,7 @@ export class ObjectKernel {
                 success: false,
                 pluginName: plugin.name,
                 error: error as Error,
-                duration,
+                durationMs: duration,
                 // Deprecated alias carrying the same elapsed value; see
                 // PluginStartupResult.startTime.
                 startTime: duration,

packages/core/src/plugin-loader.ts

@@ -94,20 +94,21 @@ export interface PluginStartupResult {
     /**
      * Elapsed milliseconds the plugin's `start()` took.
      *
-     * Named for the member `packages/spec` already declares for the same
-     * measure -- `PluginStartupResultSchema.duration` in
+     * Named for the member `packages/spec` declares for the same measure --
+     * `PluginStartupResultSchema.durationMs` 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.
+     * start the plugin in milliseconds"), where the bare `duration` spelling is
+     * retired: a duration-shaped number carries its unit in its key name. Like
+     * `PluginLoadResult.loadTime` above, it is the same `Date.now() - startTime`
+     * computation under a name that does not lie.
      */
-    duration?: number;
+    durationMs?: number;
     /**
-     * The same elapsed milliseconds as {@link PluginStartupResult.duration}.
+     * The same elapsed milliseconds as {@link PluginStartupResult.durationMs}.
      *
      * @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.
+     * gets an age near the epoch instead of a wait. Read `durationMs` 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.
      */