feat(observability): ObservabilityServicePlugin + wire service plugins (PR #3)

Resolves the gap left by PR #2: cache + storage adapters accepted an
optional MetricsRegistry but their respective Plugin classes never
forwarded one, so any host that registered observability via the
dispatcher saw zero cache/storage data.

Adds:

  packages/observability/src/service-names.ts
    OBSERVABILITY_METRICS_SERVICE = 'observability:metrics'
    OBSERVABILITY_ERRORS_SERVICE  = 'observability:errors'

  packages/runtime/src/observability/observability-service-plugin.ts
    ObservabilityServicePlugin — registers the host's MetricsRegistry
    and ErrorReporter under the canonical names. Defaults each to its
    respective Noop exporter so the services are always present.
    Also exports resolveMetrics() / resolveErrorReporter() helpers for
    consumers inside the runtime package.

CacheServicePlugin + StorageServicePlugin:
  - new `metrics?: MetricsRegistry` option (escape hatch for tests)
  - canonical resolution chain at init():
      option override → observability:metrics service → NoopMetricsRegistry
  - StorageServicePlugin's `buildAdapterFromValues` (the settings
    live-rebuild path) now also threads metrics into the freshly built
    adapter, so adapter swaps don't drop instrumentation
  - log line now reports the resolved registry class name for diagnostics

Helpers (resolveMetrics) are inlined as private functions in each
service to avoid a circular dep (services must not depend on runtime).
Constants live in @objectstack/observability which both services
already depend on.

New tests:
  - cache-service-plugin.metrics.test.ts (4 tests, resolution chain + override precedence)
  - storage-service-plugin.metrics.test.ts (4 tests, incl. settings-rebuild path)
  - observability-service-plugin.test.ts  (3 tests, registration + defaults)

All 22 service-cache + 48 service-storage + 282 runtime tests pass
(2 pre-existing i18n failures in app-plugin.test.ts on main unchanged).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: os-zhuang

packages/observability/src/index.ts

@@ -10,6 +10,9 @@
 // Contracts
 export type { MetricsRegistry, MetricSample, ErrorReporter, CapturedError, Logger } from './contracts.js';
 
+// Service-registry names (consumed by runtime's ObservabilityServicePlugin and lookup sites)
+export { OBSERVABILITY_METRICS_SERVICE, OBSERVABILITY_ERRORS_SERVICE } from './service-names.js';
+
 // Semantic conventions
 export { SEMCONV, RUNTIME_METRICS } from './semconv.js';
 

packages/observability/src/service-names.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Canonical service-registry names for the host's observability
+ * backends. Plugins look these up to discover the configured
+ * {@link MetricsRegistry} / {@link ErrorReporter} without each host
+ * having to thread observability config through every plugin
+ * constructor.
+ *
+ * See `@objectstack/runtime` → `ObservabilityServicePlugin` for the
+ * registration side.
+ */
+export const OBSERVABILITY_METRICS_SERVICE = 'observability:metrics';
+export const OBSERVABILITY_ERRORS_SERVICE = 'observability:errors';

packages/runtime/src/index.ts

@@ -68,6 +68,12 @@ export {
     InMemoryErrorReporter,
     type ErrorReporter,
     type CapturedError,
+    ObservabilityServicePlugin,
+    OBSERVABILITY_METRICS_SERVICE,
+    OBSERVABILITY_ERRORS_SERVICE,
+    resolveMetrics,
+    resolveErrorReporter,
+    type ObservabilityServicePluginOptions,
 } from './observability/index.js';
 
 // Export Artifact Loader

packages/runtime/src/observability/index.ts

@@ -28,3 +28,12 @@ export {
     instrumentRouteHandler,
     type InstrumentOptions,
 } from './instrument.js';
+
+export {
+    ObservabilityServicePlugin,
+    OBSERVABILITY_METRICS_SERVICE,
+    OBSERVABILITY_ERRORS_SERVICE,
+    resolveMetrics,
+    resolveErrorReporter,
+    type ObservabilityServicePluginOptions,
+} from './observability-service-plugin.js';

packages/runtime/src/observability/observability-service-plugin.test.ts

@@ -0,0 +1,62 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+    InMemoryMetricsRegistry,
+    InMemoryErrorReporter,
+    NoopMetricsRegistry,
+    NoopErrorReporter,
+    OBSERVABILITY_METRICS_SERVICE,
+    OBSERVABILITY_ERRORS_SERVICE,
+} from '@objectstack/observability';
+import { ObservabilityServicePlugin } from './observability-service-plugin';
+
+/**
+ * The plugin's only job is to register the host's metrics + error
+ * backends under canonical service names so other plugins can resolve
+ * them without each host threading config through every constructor.
+ */
+
+function makeCtx() {
+    const services = new Map<string, any>();
+    return {
+        logger: { info: () => {}, warn: () => {}, error: () => {} },
+        registerService: (name: string, svc: any) => { services.set(name, svc); },
+        getService: <T>(name: string): T => {
+            const s = services.get(name);
+            if (!s) throw new Error(`service '${name}' not registered`);
+            return s as T;
+        },
+        _services: services,
+    } as any;
+}
+
+describe('ObservabilityServicePlugin', () => {
+    it('registers explicit metrics + error backends under canonical names', async () => {
+        const metrics = new InMemoryMetricsRegistry();
+        const errors = new InMemoryErrorReporter();
+        const ctx = makeCtx();
+
+        await new ObservabilityServicePlugin({ metrics, errors }).init(ctx);
+
+        expect(ctx._services.get(OBSERVABILITY_METRICS_SERVICE)).toBe(metrics);
+        expect(ctx._services.get(OBSERVABILITY_ERRORS_SERVICE)).toBe(errors);
+    });
+
+    it('defaults to noop backends when no options provided', async () => {
+        const ctx = makeCtx();
+        await new ObservabilityServicePlugin().init(ctx);
+
+        expect(ctx._services.get(OBSERVABILITY_METRICS_SERVICE)).toBeInstanceOf(NoopMetricsRegistry);
+        expect(ctx._services.get(OBSERVABILITY_ERRORS_SERVICE)).toBeInstanceOf(NoopErrorReporter);
+    });
+
+    it('lets one backend be set while the other defaults to noop', async () => {
+        const metrics = new InMemoryMetricsRegistry();
+        const ctx = makeCtx();
+        await new ObservabilityServicePlugin({ metrics }).init(ctx);
+
+        expect(ctx._services.get(OBSERVABILITY_METRICS_SERVICE)).toBe(metrics);
+        expect(ctx._services.get(OBSERVABILITY_ERRORS_SERVICE)).toBeInstanceOf(NoopErrorReporter);
+    });
+});

packages/runtime/src/observability/observability-service-plugin.ts

@@ -0,0 +1,130 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import {
+    OBSERVABILITY_METRICS_SERVICE,
+    OBSERVABILITY_ERRORS_SERVICE,
+} from '@objectstack/observability';
+import {
+    NoopMetricsRegistry,
+    NoopErrorReporter,
+    type MetricsRegistry,
+    type ErrorReporter,
+} from './index.js';
+
+/**
+ * Canonical service names other plugins look up to find the host's
+ * configured observability backends. Re-exported from
+ * `@objectstack/observability` so callers can grab them alongside the
+ * plugin without straddling two packages.
+ */
+export { OBSERVABILITY_METRICS_SERVICE, OBSERVABILITY_ERRORS_SERVICE };
+
+/**
+ * Options for {@link ObservabilityServicePlugin}.
+ *
+ * Either or both backends can be omitted; the omitted one resolves to
+ * the corresponding no-op exporter so consumers can always rely on the
+ * service being present.
+ */
+export interface ObservabilityServicePluginOptions {
+    /** Metrics backend (e.g. `ConsoleMetricsRegistry`, `OtlpHttpMetricsRegistry`). */
+    metrics?: MetricsRegistry;
+    /** Error reporter backend (e.g. Sentry adapter). */
+    errors?: ErrorReporter;
+}
+
+/**
+ * `ObservabilityServicePlugin` — registers the host's
+ * {@link MetricsRegistry} and {@link ErrorReporter} in the kernel
+ * service registry under the canonical names so any other plugin can
+ * look them up without each host having to thread observability config
+ * through every plugin constructor.
+ *
+ * Resolution chain other plugins should follow:
+ *
+ *   1. Explicit option on the plugin's own options object (escape
+ *      hatch for tests / explicit wiring).
+ *   2. `ctx.getService(OBSERVABILITY_METRICS_SERVICE)`.
+ *   3. `NoopMetricsRegistry()` — never null.
+ *
+ * Register this plugin **before** any plugin that wants to consume the
+ * services (cache, storage, dispatcher), otherwise the consumer's
+ * `init` will fall through to the no-op default.
+ *
+ * @example
+ * ```ts
+ * import { ObjectKernel } from '@objectstack/core';
+ * import {
+ *   ObservabilityServicePlugin,
+ *   CacheServicePlugin,
+ * } from '@objectstack/runtime';
+ * import { ConsoleMetricsRegistry } from '@objectstack/observability';
+ *
+ * const kernel = new ObjectKernel();
+ * kernel.use(new ObservabilityServicePlugin({
+ *   metrics: new ConsoleMetricsRegistry(),
+ * }));
+ * kernel.use(new CacheServicePlugin()); // picks metrics up automatically
+ * ```
+ */
+export class ObservabilityServicePlugin implements Plugin {
+    name = 'com.objectstack.observability.service';
+    version = '1.0.0';
+    type = 'standard';
+
+    private readonly options: ObservabilityServicePluginOptions;
+
+    constructor(options: ObservabilityServicePluginOptions = {}) {
+        this.options = options;
+    }
+
+    async init(ctx: PluginContext): Promise<void> {
+        const metrics = this.options.metrics ?? new NoopMetricsRegistry();
+        const errors = this.options.errors ?? new NoopErrorReporter();
+        ctx.registerService(OBSERVABILITY_METRICS_SERVICE, metrics);
+        ctx.registerService(OBSERVABILITY_ERRORS_SERVICE, errors);
+        ctx.logger.info(
+            `ObservabilityServicePlugin: registered metrics=${(metrics as any).constructor?.name ?? 'unknown'} errors=${(errors as any).constructor?.name ?? 'unknown'}`,
+        );
+    }
+}
+
+/**
+ * Helper used by consumer plugins to resolve a metrics backend with
+ * the canonical fallback chain. Never throws; always returns a usable
+ * `MetricsRegistry`.
+ *
+ * @param ctx        the consuming plugin's `PluginContext`
+ * @param override   explicit option set on the consuming plugin (wins)
+ */
+export function resolveMetrics(
+    ctx: PluginContext,
+    override?: MetricsRegistry,
+): MetricsRegistry {
+    if (override) return override;
+    try {
+        const m = ctx.getService<MetricsRegistry | undefined>(OBSERVABILITY_METRICS_SERVICE);
+        if (m) return m;
+    } catch {
+        // Service not registered — fall through to the noop default.
+    }
+    return new NoopMetricsRegistry();
+}
+
+/**
+ * Sibling of {@link resolveMetrics} for {@link ErrorReporter}.
+ */
+export function resolveErrorReporter(
+    ctx: PluginContext,
+    override?: ErrorReporter,
+): ErrorReporter {
+    if (override) return override;
+    try {
+        const e = ctx.getService<ErrorReporter | undefined>(OBSERVABILITY_ERRORS_SERVICE);
+        if (e) return e;
+    } catch {
+        // Service not registered — fall through to the noop default.
+    }
+    return new NoopErrorReporter();
+}

packages/services/service-cache/src/cache-service-plugin.metrics.test.ts

@@ -0,0 +1,83 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+  InMemoryMetricsRegistry,
+  OBSERVABILITY_METRICS_SERVICE,
+  SEMCONV,
+} from '@objectstack/observability';
+import { CacheServicePlugin } from './cache-service-plugin';
+
+/**
+ * Verifies the metrics resolution chain wired in PR #3:
+ *   option override → service-registry lookup → noop fallback
+ *
+ * Without these tests it's easy to silently regress to the pre-PR-3
+ * behaviour where the plugin built an unmetered adapter and OTLP saw
+ * zero cache traffic.
+ */
+
+function makeCtx() {
+  const services = new Map<string, any>();
+  return {
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+    registerService: (name: string, svc: any) => { services.set(name, svc); },
+    getService: <T>(name: string): T => {
+      const s = services.get(name);
+      if (!s) throw new Error(`service '${name}' not registered`);
+      return s as T;
+    },
+    _services: services,
+  } as any;
+}
+
+describe('CacheServicePlugin observability wiring', () => {
+  it('uses an explicit metrics option when provided', async () => {
+    const metrics = new InMemoryMetricsRegistry();
+    const ctx = makeCtx();
+    await new CacheServicePlugin({ metrics }).init(ctx);
+
+    const cache = ctx._services.get('cache');
+    await cache.set('k', 'v', 60);
+    await cache.get('k');
+
+    expect(metrics.samples.length).toBeGreaterThan(0);
+    expect(metrics.samples.some((s) => s.name === SEMCONV.cacheLookupsTotal)).toBe(true);
+  });
+
+  it('falls back to the metrics service registered under observability:metrics', async () => {
+    const metrics = new InMemoryMetricsRegistry();
+    const ctx = makeCtx();
+    ctx._services.set(OBSERVABILITY_METRICS_SERVICE, metrics);
+
+    await new CacheServicePlugin().init(ctx);
+    const cache = ctx._services.get('cache');
+    await cache.set('k', 'v', 60);
+    await cache.get('k');
+
+    expect(metrics.samples.some((s) => s.name === SEMCONV.cacheLookupsTotal)).toBe(true);
+  });
+
+  it('uses a noop registry when neither option nor service is present', async () => {
+    const ctx = makeCtx();
+    await new CacheServicePlugin().init(ctx);
+    const cache = ctx._services.get('cache');
+    // Should not throw — proves the adapter got *something*.
+    await cache.set('k', 'v', 60);
+    expect(await cache.get('k')).toBe('v');
+  });
+
+  it('explicit option wins over a registered service', async () => {
+    const fromOption = new InMemoryMetricsRegistry();
+    const fromService = new InMemoryMetricsRegistry();
+    const ctx = makeCtx();
+    ctx._services.set(OBSERVABILITY_METRICS_SERVICE, fromService);
+
+    await new CacheServicePlugin({ metrics: fromOption }).init(ctx);
+    const cache = ctx._services.get('cache');
+    await cache.set('k', 'v', 60);
+
+    expect(fromOption.samples.length).toBeGreaterThan(0);
+    expect(fromService.samples.length).toBe(0);
+  });
+});