fix(spec,core): tombstone the startTime alias the duration-unit rule refuses

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KB5PFtxuy1x3dcR5gxudx6

Author: claude

.changeset/16059-startup-orchestrator-shipped-shape.md

@@ -47,14 +47,24 @@ cannot drift again.
 | `pluginName` | absent | `string`, required |
 | `success` | `boolean`, required | unchanged |
 | `durationMs` | `number`, **required** | `number`, **optional** (absent when the plugin declares no `start()`) |
-| `startTime` | absent | `number`, optional — deprecated alias of `durationMs`, mirrored because the kernel still populates it |
+| `startTime` | absent (it was core's own deprecated alias) | **removed** — read `durationMs`, which always carried the same value |
 | `error` | serializable projection | unchanged (a thrown `Error` satisfies it) |
 | `timedOut` | absent | `boolean`, optional — set when the failure was the timeout |
 | `health: HealthStatus` | optional | **removed** — no probe ever filled it |
 
-**The one-line fix:** rename `plugin: { name }` to `pluginName`, and delete `health`. Both
-old spellings are `retiredKey()` tombstones on the surviving schema, so each is a `tsc`
-error at the construction site and a parse error carrying the prescription.
+**The one-line fix:** rename `plugin: { name }` to `pluginName`, delete `health`, and read
+`durationMs` wherever you read `startTime`. All three old spellings are `retiredKey()`
+tombstones on the surviving schema, so each is a `tsc` error at the construction site and a
+parse error carrying the prescription.
+
+`startTime` is the one member whose removal a reader can OBSERVE: `@objectstack/core`
+populated it beside `durationMs` with the identical elapsed value, under its own ADR-0087
+L1 deprecation, and `ObjectKernel.startPluginWithTimeout()` stops setting it here. Mirroring
+it on the contract was the alternative and the tree refuses it — `check:duration-unit-keys`
+(ruling B on #14478) fails an elapsed number whose key name carries no unit, and neither of
+that rule's two schema-declared exemptions fits: it is not an `EpochMs` instant and it
+mirrors no external standard. Renaming it to `startTimeMs` would mint a spelling nothing has
+ever produced, for a member already documented as slated for removal.
 
 For `@objectstack/core` consumers the members are unchanged; the one narrowing is that
 `PluginStartupResult.error` is now typed as the serializable projection

content/docs/references/kernel/startup-orchestrator.mdx

@@ -34,7 +34,12 @@ What each member means, and when it is present:
   TIMEOUT rather than a throw from inside `start()`: the kernel sets it from
   the raced rejection's message. Absent on the success path; absent, not
   `false`, when a plugin's own `start()` threw.
-- `startTime` — deprecated; see its own note below.
+
+The deprecated `startTime` alias the kernel used to set beside `durationMs`
+ends here: it never held an instant, and a member whose name promises one
+while carrying an elapsed duration is the confusion the duration-unit rule
+exists to stop. It is a tombstone on this schema and the kernel no longer
+populates it.
 
 ── [#16059] What this module used to declare, and why it no longer does ────
 
@@ -98,9 +103,9 @@ const result = PluginStartupResultSchema.parse(data);
 | **pluginName** | `string` | ✅ | Name of the plugin that was started |
 | **success** | `boolean` | ✅ | Whether the plugin started successfully |
 | **durationMs** | `number` | optional | Time taken to start the plugin in milliseconds; absent when the plugin declares no start() |
-| **startTime** | `number` | optional | [DEPRECATED] The same elapsed milliseconds as durationMs — read durationMs instead |
 | **error** | `{ name: string; message: string; stack?: string; code?: string }` | optional | Serializable error representation if startup failed |
 | **timedOut** | `boolean` | optional | Whether startup failed because the startup timeout fired, rather than start() throwing |
+| **startTime** | `never` | optional | [REMOVED] `PluginStartupResult.startTime` was removed in @objectstack/spec 18 (ADR-0049) — it never held an instant: the kernel filled it with the SAME elapsed milliseconds as `durationMs`, so a reader who took the name at its word and computed `Date.now() - startTime` got an age near the epoch instead of a wait. Delete the key and read `durationMs`, which has always carried the same value. |
 | **duration** | `never` | optional | [REMOVED] `PluginStartupResult.duration` was renamed to `durationMs` in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to `durationMs`; the value (milliseconds) is unchanged. |
 | **plugin** | `never` | optional | [REMOVED] `PluginStartupResult.plugin` was removed in @objectstack/spec 18 (ADR-0049) — the kernel has never put a plugin OBJECT in this result, so the nested `{ name, version }` shape described a value nothing ever built. Replace the key with `pluginName` and carry the plugin name string. |
 | **health** | `never` | optional | [REMOVED] `PluginStartupResult.health` was removed in @objectstack/spec 18 (ADR-0049) — it carried a `HealthStatus`, and that vocabulary is retired with the startup orchestrator that declared it: no probe system ever ran a health check at startup, so nothing ever filled the key. Delete the key; a plugin that reports health does it through a service it registers, not through this result. |

packages/core/src/kernel.test.ts

@@ -585,10 +585,12 @@ describe('ObjectKernel', () => {
         });
 
         // 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
+        // present. The result member carrying it was once ALSO spelled
+        // `startTime` while holding `Date.now() - start`, so a reader who
+        // correctly took that name for an instant and wrote
+        // `Date.now() - result.startTime` got an age near the epoch. #16059
+        // removed that alias; `durationMs` is the only spelling left, and
+        // `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
@@ -636,8 +638,13 @@ describe('ObjectKernel', () => {
             expect(ok.success).toBe(true);
             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.durationMs);
+            // [#16059] The `startTime` alias that used to carry the same value is
+            // GONE, not merely deprecated: a member whose name promises an
+            // instant while holding an elapsed duration is the confusion this
+            // case exists to pin, and the spec now tombstones it. Asserting its
+            // absence here is what keeps a later "restore the alias" from
+            // passing quietly.
+            expect(ok).not.toHaveProperty('startTime');
 
             const failingMeta: PluginMetadata = {
                 name: 'failing-plugin',
@@ -652,7 +659,7 @@ describe('ObjectKernel', () => {
             expect(failed.success).toBe(false);
             expect(failed.durationMs).toBeGreaterThanOrEqual(0);
             expect(failed.durationMs).toBeLessThan(INSTANT_FLOOR_MS);
-            expect(failed.startTime).toBe(failed.durationMs);
+            expect(failed).not.toHaveProperty('startTime');
         });
     });
 

packages/core/src/kernel.ts

@@ -792,9 +792,6 @@ export class ObjectKernel {
                 success: true,
                 pluginName: plugin.name,
                 durationMs: duration,
-                // Deprecated alias carrying the same elapsed value; see
-                // PluginStartupResult.startTime.
-                startTime: duration,
             };
         } catch (error) {
             const duration = Date.now() - startTime;
@@ -805,9 +802,6 @@ export class ObjectKernel {
                 pluginName: plugin.name,
                 error: error as Error,
                 durationMs: duration,
-                // Deprecated alias carrying the same elapsed value; see
-                // PluginStartupResult.startTime.
-                startTime: duration,
                 timedOut: isTimeout,
             };
         }

packages/core/src/plugin-loader.ts

@@ -99,12 +99,18 @@ export interface PluginLoadResult {
  * SCHEMA against what this package actually ships and made the type flow one
  * way — spec to core — so the two cannot drift apart again.
  *
- * The shape is unchanged for every producer and reader here: `pluginName`,
- * `success`, optional `durationMs`, the deprecated `startTime` alias,
- * `timedOut`, and `error` — declared by the spec as the serializable projection
- * (`name` / `message` / `stack` / `code`) that a thrown `Error` satisfies
- * structurally, so `ObjectKernel` keeps handing the live instance through and
- * `instanceof Error` keeps narrowing at the read site.
+ * The members carry over unchanged — `pluginName`, `success`, optional
+ * `durationMs`, `timedOut`, and `error`, which the spec declares as the
+ * serializable projection (`name` / `message` / `stack` / `code`) that a thrown
+ * `Error` satisfies structurally, so `ObjectKernel` keeps handing the live
+ * instance through and `instanceof Error` keeps narrowing at the read site.
+ *
+ * One member does NOT carry over: the deprecated `startTime` alias, which held
+ * the same elapsed milliseconds as `durationMs` under a name that promises an
+ * instant. The spec tombstones it rather than mirroring it —
+ * `check:duration-unit-keys` refuses an elapsed number whose key name carries
+ * no unit, and neither of that rule's schema-declared exemptions fits — so the
+ * L1 window closes here and `ObjectKernel` no longer populates it.
  */
 export type { PluginStartupResult } from '@objectstack/spec/kernel';
 

packages/spec/authorable-surface/kernel.json

@@ -583,7 +583,7 @@
     "kernel/PluginStartupResult:health [RETIRED]",
     "kernel/PluginStartupResult:plugin [RETIRED]",
     "kernel/PluginStartupResult:pluginName",
-    "kernel/PluginStartupResult:startTime",
+    "kernel/PluginStartupResult:startTime [RETIRED]",
     "kernel/PluginStartupResult:success",
     "kernel/PluginStartupResult:timedOut",
     "kernel/PluginStateSnapshot:metadata",

packages/spec/src/kernel/startup-orchestrator-retirement.test.ts

@@ -117,12 +117,14 @@ describe('[#16059] startup orchestrator retirement', () => {
     // asserts the shape here too, so the reason is named at the spec end.
     const { PluginStartupResultSchema } = await import('./startup-orchestrator.zod');
     const shape = (PluginStartupResultSchema as unknown as { shape: Record<string, unknown> }).shape;
-    for (const member of ['pluginName', 'success', 'durationMs', 'startTime', 'error', 'timedOut']) {
+    for (const member of ['pluginName', 'success', 'durationMs', 'error', 'timedOut']) {
       expect(Object.keys(shape), `${member} must be declared`).toContain(member);
     }
-    // The two members that left the surviving def are tombstones, not
-    // deletions — present in the shape, refusing with a prescription.
-    for (const member of ['plugin', 'health', 'duration']) {
+    // The members that left the surviving def are tombstones, not deletions —
+    // present in the shape, refusing with a prescription. `startTime` is here
+    // rather than above on purpose: mirroring the deprecated alias is what
+    // `check:duration-unit-keys` refuses, so the contract ends it instead.
+    for (const member of ['plugin', 'health', 'startTime', 'duration']) {
       expect(Object.keys(shape), `${member} must remain as a tombstone`).toContain(member);
     }
   });

packages/spec/src/kernel/startup-orchestrator.test.ts

@@ -17,21 +17,14 @@ describe('PluginStartupResultSchema — the shape the kernel produces', () => {
     expect(result.success).toBe(true);
   });
 
-  it('accepts the success path: durationMs plus the deprecated startTime alias', () => {
+  it('accepts the success path: durationMs alone', () => {
     const result = PluginStartupResultSchema.safeParse({
       pluginName: 'crm-plugin',
       success: true,
       durationMs: 1250,
-      startTime: 1250,
     });
     expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data.durationMs).toBe(1250);
-      // The kernel populates both with the SAME elapsed value under its
-      // ADR-0087 L1 disposition; the contract mirrors that rather than
-      // declaring `never` for a member the kernel emits.
-      expect(result.data.startTime).toBe(result.data.durationMs);
-    }
+    if (result.success) expect(result.data.durationMs).toBe(1250);
   });
 
   it('accepts the failure path: the serializable error projection', () => {
@@ -112,6 +105,22 @@ describe('[#16059] the re-declared result refuses the members it dropped', () =>
     expect(issue!.message).toContain('Replace the key with `pluginName`');
   });
 
+  it('REFUSES the deprecated `startTime` alias and prescribes `durationMs`', () => {
+    const result = PluginStartupResultSchema.safeParse({
+      pluginName: 'crm-plugin',
+      success: true,
+      durationMs: 1250,
+      startTime: 1250,
+    });
+    expect(result.success).toBe(false);
+    const issue = result.error!.issues.find((i) => i.path.join('.') === 'startTime');
+    expect(issue).toBeDefined();
+    expect(issue!.code).not.toBe('unrecognized_keys');
+    // The prescription is the payload: the name promised an instant and the
+    // value was always an elapsed duration.
+    expect(issue!.message).toMatch(/startTime.*removed.*read `durationMs`/s);
+  });
+
   it('REFUSES `health` and says no startup probe system exists', () => {
     const result = PluginStartupResultSchema.safeParse({
       pluginName: 'crm-plugin',

packages/spec/src/kernel/startup-orchestrator.zod.ts

@@ -35,7 +35,12 @@ import { retiredKey } from '../shared/retired-key';
  *   TIMEOUT rather than a throw from inside `start()`: the kernel sets it from
  *   the raced rejection's message. Absent on the success path; absent, not
  *   `false`, when a plugin's own `start()` threw.
- * - `startTime` — deprecated; see its own note below.
+ *
+ * The deprecated `startTime` alias the kernel used to set beside `durationMs`
+ * ends here: it never held an instant, and a member whose name promises one
+ * while carrying an elapsed duration is the confusion the duration-unit rule
+ * exists to stop. It is a tombstone on this schema and the kernel no longer
+ * populates it.
  *
  * ── [#16059] What this module used to declare, and why it no longer does ────
  *
@@ -121,21 +126,6 @@ export const PluginStartupResultSchema = lazySchema(() => z.object({
   durationMs: z.number().min(0).optional()
     .describe('Time taken to start the plugin in milliseconds; absent when the plugin declares no start()'),
 
-  /**
-   * The same elapsed milliseconds as `durationMs`.
-   *
-   * @deprecated Misnamed: it has never held an instant, so a reader who
-   * correctly takes `startTime` for one and computes `Date.now() - startTime`
-   * gets an age near the epoch instead of a wait. Read `durationMs` instead.
-   * Mirrored here because `@objectstack/core` still POPULATES it under its
-   * ADR-0087 L1 disposition — the old shape keeps working while the fleet
-   * moves — and a contract that declared `never` for a member the kernel emits
-   * would be the very drift #16059 closed. It leaves this schema in the same
-   * change that stops the kernel emitting it.
-   */
-  startTime: z.number().min(0).optional()
-    .describe('[DEPRECATED] The same elapsed milliseconds as durationMs — read durationMs instead'),
-
   /**
    * Error if startup failed
    */
@@ -153,6 +143,25 @@ export const PluginStartupResultSchema = lazySchema(() => z.object({
   timedOut: z.boolean().optional()
     .describe('Whether startup failed because the startup timeout fired, rather than start() throwing'),
 
+  /**
+   * Tombstone for the deprecated `startTime` alias core carried (#16059).
+   *
+   * Mirroring it was the other candidate and the tree refuses it: the member
+   * holds elapsed milliseconds under a name that carries no unit, which is
+   * exactly what `check:duration-unit-keys` (ruling B on #14478) fails, and
+   * neither of that rule's two schema-declared exemptions applies — it is not
+   * an `EpochMs` instant and it mirrors no external standard. Renaming it to
+   * `startTimeMs` would mint a spelling nothing has ever produced, for a member
+   * already slated for removal. So the L1 alias ends here, audibly.
+   */
+  startTime: retiredKey(
+    '`PluginStartupResult.startTime` was removed in @objectstack/spec 18 (ADR-0049) — '
+    + 'it never held an instant: the kernel filled it with the SAME elapsed milliseconds as '
+    + '`durationMs`, so a reader who took the name at its word and computed '
+    + '`Date.now() - startTime` got an age near the epoch instead of a wait. Delete the key '
+    + 'and read `durationMs`, which has always carried the same value.',
+  ),
+
   /** Tombstone for the `duration` → `durationMs` rename (#15678, ruling B on #14478). */
   duration: retiredKey(
     '`PluginStartupResult.duration` was renamed to `durationMs` in @objectstack/spec 17 — '

packages/spec/src/migrations/entries/retired-keys/18.kernel__PluginStartupResult__startTime.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+// #16059 — `PluginStartupResult.startTime` was `@objectstack/core`'s own
+// ADR-0087 L1 alias: the kernel set it to the SAME elapsed milliseconds as
+// `durationMs`, under a name that promises an instant. It arrives on the spec's
+// surface only to leave it, because the re-declaration of this schema against
+// the shipped shape had to choose between mirroring the member and tombstoning
+// it, and mirroring is refused by `check:duration-unit-keys` (ruling B on
+// #14478): an elapsed number whose key name carries no unit, matching neither
+// of that rule's two schema-declared exemptions — not an `EpochMs` instant, not
+// an external-standard mirror. Renaming it to `startTimeMs` would mint a
+// spelling nothing ever produced for a member already slated for removal, so
+// the alias ends here and the kernel stops populating it in the same change.
+export const entry = 'kernel/PluginStartupResult:startTime';