fix: address PR review — type-safe protocol access, narrower error handling, canonical app type in tests

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/0c3ad9ed-acb5-48f4-a9c5-c81bde62ed87

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/objectql/src/plugin.integration.test.ts

@@ -838,7 +838,7 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
             return [
               {
                 id: '1',
-                type: 'app',
+                type: 'apps',
                 name: 'custom_crm',
                 state: 'active',
                 metadata: JSON.stringify({ name: 'custom_crm', label: 'Custom CRM' }),
@@ -888,7 +888,7 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
 
       // Assert — items should be restored into the registry
       const registry = (kernel.getService('objectql') as any).registry;
-      expect(registry.getItem('app', 'custom_crm')).toEqual({
+      expect(registry.getAllApps()).toContainEqual({
         name: 'custom_crm',
         label: 'Custom CRM',
       });

packages/objectql/src/plugin.ts

@@ -6,6 +6,25 @@ import { Plugin, PluginContext } from '@objectstack/core';
 
 export type { Plugin, PluginContext };
 
+/**
+ * Protocol extension for DB-based metadata hydration.
+ * `loadMetaFromDb` is implemented by ObjectStackProtocolImplementation but
+ * is NOT (yet) part of the canonical ObjectStackProtocol wire-contract in
+ * `@objectstack/spec`, since it is a server-side bootstrap concern only.
+ */
+interface ProtocolWithDbRestore {
+  loadMetaFromDb(): Promise<{ loaded: number; errors: number }>;
+}
+
+/** Type guard — checks whether the service exposes `loadMetaFromDb`. */
+function hasLoadMetaFromDb(service: unknown): service is ProtocolWithDbRestore {
+  return (
+    typeof service === 'object' &&
+    service !== null &&
+    typeof (service as Record<string, unknown>)['loadMetaFromDb'] === 'function'
+  );
+}
+
 export class ObjectQLPlugin implements Plugin {
   name = 'com.objectstack.engine.objectql';
   type = 'objectql';
@@ -352,13 +371,24 @@ export class ObjectQLPlugin implements Plugin {
    * - The underlying driver/table does not exist yet (first-run scenario).
    */
   private async restoreMetadataFromDb(ctx: PluginContext): Promise<void> {
+    // Phase 1: Resolve protocol service (separate from DB I/O for clearer diagnostics)
+    let protocol: ProtocolWithDbRestore;
     try {
-      const protocol = ctx.getService('protocol') as any;
-      if (!protocol || typeof protocol.loadMetaFromDb !== 'function') {
+      const service = ctx.getService('protocol');
+      if (!service || !hasLoadMetaFromDb(service)) {
         ctx.logger.debug('Protocol service does not support loadMetaFromDb, skipping DB restore');
         return;
       }
+      protocol = service;
+    } catch (e: unknown) {
+      ctx.logger.debug('Protocol service unavailable, skipping DB restore', {
+        error: e instanceof Error ? e.message : String(e),
+      });
+      return;
+    }
 
+    // Phase 2: DB hydration
+    try {
       const { loaded, errors } = await protocol.loadMetaFromDb();
 
       if (loaded > 0 || errors > 0) {
@@ -368,7 +398,7 @@ export class ObjectQLPlugin implements Plugin {
       }
     } catch (e: unknown) {
       // Non-fatal: first-run or in-memory driver may not have sys_metadata yet
-      ctx.logger.debug('DB metadata restore skipped (non-fatal)', {
+      ctx.logger.debug('DB metadata restore failed (non-fatal)', {
         error: e instanceof Error ? e.message : String(e),
       });
     }