feat(runtime,cli)!: retire the inert DriverPluginOptions (#4320)

new DriverPlugin(driver, { datasourceName, registerAsDefault }) never did
what it promised: both options configured the start() datasource block that
probed metadata.addDatasource — a method no metadata service implements —
so they were dead weight on every boot since inception. Routing to a named
auxiliary driver never came from the option: it keys off the DRIVER name
(init registers driver.<name>, ObjectQL's discovery loop adopts it, the
engine's lifecycle resolution looks the name up — engine.ts
LIFECYCLE_DATASOURCE), which is why serve's telemetry split worked all
along despite the option doing nothing.

- DriverPlugin constructor narrowed to (driver, driverName?); the options
  interface (module-local, never exported from the package root) is gone.
- serve.ts drops the options argument; the telemetry wiring comment now
  states the driver-name mechanism explicitly.
- Major changeset for @objectstack/runtime carries the FROM -> TO
  migration; behavior is unchanged by construction (the code the options
  configured never ran).

Verified: full turbo build green (71 packages); runtime 954/67 and cli
628/64 tests pass; pnpm lint clean.

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

Author: claude

.changeset/retire-inert-driver-plugin-options.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/runtime": major
+"@objectstack/cli": patch
+---
+
+feat(runtime)!: retire the inert `DriverPluginOptions` — `DriverPlugin` takes `(driver, driverName?)` (#4320)
+
+`new DriverPlugin(driver, { datasourceName, registerAsDefault })` never did
+what it promised: both options configured a datasource-registration block in
+`start()` gated on `metadata.addDatasource`, a method **no metadata service
+implements** — so the block early-returned on every boot since inception and
+the options were dead weight (found while typing service lookups for #4251).
+
+**Migration** — delete the options argument; nothing changes at runtime
+because nothing ever happened:
+
+- FROM `new DriverPlugin(driver, { datasourceName: 'x', registerAsDefault: false })`
+  TO `new DriverPlugin(driver)`
+- FROM `new DriverPlugin(driver, 'name', options)` TO `new DriverPlugin(driver, 'name')`
+- The string second argument (`new DriverPlugin(driver, 'memory')`) is unchanged.
+
+If you passed `datasourceName` expecting routing to a named auxiliary driver:
+that routing never came from the option. It keys off the **driver name** —
+`DriverPlugin.init()` registers `driver.<name>`, ObjectQL's discovery loop
+adopts it, and the engine's lifecycle/datasource resolution looks the name up
+(see the telemetry provision in `os serve` for the pattern: stamp
+`driver.name`, register the plugin, done). For Setup → Datasources visibility,
+declare the datasource through `DatasourceConnectionService` /
+`registerInMemory('datasource', …)` (ADR-0062).
+
+The `DriverPluginOptions` interface was module-local (never exported from the
+package root), so the only public break is the constructor's second/third
+argument shape.

packages/cli/src/commands/serve.ts

@@ -1003,9 +1003,15 @@ export default class Serve extends Command {
                    });
                    if (telemetry.engine !== 'memory') {
                      // The engine keys datasources by driver name — the
-                     // lifecycle router looks this exact name up.
+                     // lifecycle router looks this exact name up. The driver
+                     // name is the WHOLE wiring: DriverPlugin.init registers
+                     // `driver.telemetry`, ObjectQL's discovery loop adopts
+                     // it, and lifecycle-classed objects route to it. (An
+                     // options bag once also asked for `datasourceName:
+                     // 'telemetry'` metadata registration — inert since
+                     // inception, retired in #4320.)
                      Object.defineProperty(telemetry.driver, 'name', { value: 'telemetry' });
-                     await kernel.use(new DriverPlugin(telemetry.driver, { datasourceName: 'telemetry', registerAsDefault: false }));
+                     await kernel.use(new DriverPlugin(telemetry.driver));
                      trackPlugin('TelemetryDatasource');
                      console.log(chalk.dim(`  telemetry datasource: ${telemetryPath} (lifecycle-classed system data; OS_TELEMETRY_DB=0 to disable)`));
                    }

packages/runtime/src/driver-plugin.ts

@@ -16,42 +16,24 @@ import { Plugin, PluginContext } from '@objectstack/core';
  * const driverPlugin = new DriverPlugin(memoryDriver, 'memory');
  * kernel.use(driverPlugin);
  */
-/**
- * ⚠️ Both options are INERT. They configured start()'s datasource
- * registration, which probed `metadata.addDatasource` — a method no metadata
- * service implements — so the guarded block never ran on any boot and was
- * removed when typing the lookup surfaced it (#4251). The one live caller
- * that passes them (`serve.ts`, `datasourceName: 'telemetry'`) has never
- * gotten the registration it asks for. Kept only for source compatibility;
- * revive-or-remove is tracked in #4320.
- */
-export interface DriverPluginOptions {
-    /**
-     * If set, registers a named datasource so packages declaring
-     * `defaultDatasource: '<name>'` resolve to this driver.
-     */
-    datasourceName?: string;
-    /**
-     * If `true` (default), registers this driver as the `default` datasource
-     * when none exists. Set to `false` for proxy drivers (e.g. cloud proxy)
-     * that should never become the default.
-     */
-    registerAsDefault?: boolean;
-}
-
 export class DriverPlugin implements Plugin {
     name: string;
     type = 'driver';
     version = '1.0.0';
 
     private driver: any;
 
-    // Options are accepted (source compatibility for existing callers) but no
-    // longer stored — nothing reads them since the dead datasource block left
-    // start(); see the DriverPluginOptions doc.
-    constructor(driver: any, driverNameOrOptions?: string | DriverPluginOptions, _options?: DriverPluginOptions) {
+    // A `DriverPluginOptions` bag (`datasourceName` / `registerAsDefault`)
+    // used to be accepted here. Both options configured start()'s datasource
+    // registration, which probed `metadata.addDatasource` — a method no
+    // metadata service implements — so they were inert on every boot since
+    // inception; retired via #4320 (found by #4251). Routing to a named
+    // auxiliary driver needs only the DRIVER name: init() registers
+    // `driver.<name>`, ObjectQL's discovery loop adopts it, and the engine's
+    // lifecycle/datasource resolution keys off that name (see serve.ts's
+    // telemetry provision for the pattern).
+    constructor(driver: any, driverName?: string) {
         this.driver = driver;
-        const driverName = typeof driverNameOrOptions === 'string' ? driverNameOrOptions : undefined;
         this.name = `com.objectstack.driver.${driverName || driver.name || 'unknown'}`;
     }
 
@@ -68,10 +50,11 @@ export class DriverPlugin implements Plugin {
     // start() used to hold a named/default datasource registration block,
     // gated on `metadata.addDatasource` — a method no metadata service
     // implements, here or anywhere in the repo — so the guard's early return
-    // made every line behind it (and the options above) unreachable on every
-    // boot. Typing the lookup (#4251) surfaced that; the dead block is gone
-    // rather than typed against a phantom shape. Datasource declaration and
-    // visibility live in ADR-0062's DatasourceConnectionService +
+    // made every line behind it (and the options that configured it)
+    // unreachable on every boot. Typing the lookup (#4251) surfaced that; the
+    // dead block is gone rather than typed against a phantom shape, and the
+    // options followed it (#4320). Datasource declaration and visibility live
+    // in ADR-0062's DatasourceConnectionService +
     // `registerInMemory('datasource', …)` path — see DefaultDatasourcePlugin.
     start = async (ctx: PluginContext) => {
         ctx.logger.debug('Driver plugin started', { driverName: this.driver.name || 'unknown' });