@objectstack/objectql 4.0.1 → 4.0.3

package/dist/index.mjs

@@ -53,36 +53,45 @@ var SchemaRegistry = class {
   // ==========================================
   /**
    * Register a namespace for a package.
-   * Enforces namespace uniqueness within the instance.
-   * 
-   * @throws Error if namespace is already registered to a different package
+   * Multiple packages can share the same namespace (e.g. 'sys').
    */
   static registerNamespace(namespace, packageId) {
     if (!namespace) return;
-    const existing = this.namespaceRegistry.get(namespace);
-    if (existing && existing !== packageId) {
-      throw new Error(
-        `Namespace "${namespace}" is already registered to package "${existing}". Package "${packageId}" cannot use the same namespace.`
-      );
+    let owners = this.namespaceRegistry.get(namespace);
+    if (!owners) {
+      owners = /* @__PURE__ */ new Set();
+      this.namespaceRegistry.set(namespace, owners);
     }
-    this.namespaceRegistry.set(namespace, packageId);
+    owners.add(packageId);
     this.log(`[Registry] Registered namespace: ${namespace} \u2192 ${packageId}`);
   }
   /**
    * Unregister a namespace when a package is uninstalled.
    */
   static unregisterNamespace(namespace, packageId) {
-    const existing = this.namespaceRegistry.get(namespace);
-    if (existing === packageId) {
-      this.namespaceRegistry.delete(namespace);
-      this.log(`[Registry] Unregistered namespace: ${namespace}`);
+    const owners = this.namespaceRegistry.get(namespace);
+    if (owners) {
+      owners.delete(packageId);
+      if (owners.size === 0) {
+        this.namespaceRegistry.delete(namespace);
+      }
+      this.log(`[Registry] Unregistered namespace: ${namespace} \u2190 ${packageId}`);
     }
   }
   /**
-   * Get the package that owns a namespace.
+   * Get the packages that use a namespace.
    */
   static getNamespaceOwner(namespace) {
-    return this.namespaceRegistry.get(namespace);
+    const owners = this.namespaceRegistry.get(namespace);
+    if (!owners || owners.size === 0) return void 0;
+    return owners.values().next().value;
+  }
+  /**
+   * Get all packages that share a namespace.
+   */
+  static getNamespaceOwners(namespace) {
+    const owners = this.namespaceRegistry.get(namespace);
+    return owners ? Array.from(owners) : [];
   }
   // ==========================================
   // Object Registration (Ownership Model)
@@ -292,7 +301,7 @@ var SchemaRegistry = class {
     if (type === "object") {
       return ObjectSchema.parse(item);
     }
-    if (type === "apps") {
+    if (type === "app") {
       return AppSchema.parse(item);
     }
     if (type === "package") {
@@ -442,13 +451,13 @@ var SchemaRegistry = class {
   // App Helpers
   // ==========================================
   static registerApp(app, packageId) {
-    this.registerItem("apps", app, "name", packageId);
+    this.registerItem("app", app, "name", packageId);
   }
   static getApp(name) {
-    return this.getItem("apps", name);
+    return this.getItem("app", name);
   }
   static getAllApps() {
-    return this.listItems("apps");
+    return this.listItems("app");
   }
   // ==========================================
   // Plugin Helpers
@@ -494,7 +503,7 @@ SchemaRegistry._logLevel = "info";
 SchemaRegistry.objectContributors = /* @__PURE__ */ new Map();
 /** FQN → Merged ServiceObject (cached, invalidated on changes) */
 SchemaRegistry.mergedObjectCache = /* @__PURE__ */ new Map();
-/** Namespace → PackageId (ensures namespace uniqueness) */
+/** Namespace → Set<PackageId> (multiple packages can share a namespace) */
 SchemaRegistry.namespaceRegistry = /* @__PURE__ */ new Map();
 // ==========================================
 // Generic metadata storage (non-object types)
@@ -504,6 +513,7 @@ SchemaRegistry.metadata = /* @__PURE__ */ new Map();
 
 // src/protocol.ts
 import { parseFilterAST, isFilterAST } from "@objectstack/spec/data";
+import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from "@objectstack/spec/shared";
 function simpleHash(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -631,20 +641,32 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getMetaTypes() {
-    return {
-      types: SchemaRegistry.getRegisteredTypes()
-    };
+    const schemaTypes = SchemaRegistry.getRegisteredTypes();
+    let runtimeTypes = [];
+    try {
+      const services = this.getServicesRegistry?.();
+      const metadataService = services?.get("metadata");
+      if (metadataService && typeof metadataService.getRegisteredTypes === "function") {
+        runtimeTypes = await metadataService.getRegisteredTypes();
+      }
+    } catch {
+    }
+    const allTypes = Array.from(/* @__PURE__ */ new Set([...schemaTypes, ...runtimeTypes]));
+    return { types: allTypes };
   }
   async getMetaItems(request) {
-    let items = SchemaRegistry.listItems(request.type);
+    const { packageId } = request;
+    let items = SchemaRegistry.listItems(request.type, packageId);
     if (items.length === 0) {
-      const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-      items = SchemaRegistry.listItems(alt);
+      const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+      if (alt) items = SchemaRegistry.listItems(alt, packageId);
     }
     if (items.length === 0) {
       try {
+        const whereClause = { type: request.type, state: "active" };
+        if (packageId) whereClause._packageId = packageId;
         const allRecords = await this.engine.find("sys_metadata", {
-          where: { type: request.type, state: "active" }
+          where: whereClause
         });
         if (allRecords && allRecords.length > 0) {
           items = allRecords.map((record) => {
@@ -653,21 +675,47 @@ var ObjectStackProtocolImplementation = class {
             return data;
           });
         } else {
-          const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-          const altRecords = await this.engine.find("sys_metadata", {
-            where: { type: alt, state: "active" }
-          });
-          if (altRecords && altRecords.length > 0) {
-            items = altRecords.map((record) => {
-              const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-              SchemaRegistry.registerItem(request.type, data, "name");
-              return data;
+          const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+          if (alt) {
+            const altRecords = await this.engine.find("sys_metadata", {
+              where: { type: alt, state: "active" }
             });
+            if (altRecords && altRecords.length > 0) {
+              items = altRecords.map((record) => {
+                const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
+                SchemaRegistry.registerItem(request.type, data, "name");
+                return data;
+              });
+            }
           }
         }
       } catch {
       }
     }
+    try {
+      const services = this.getServicesRegistry?.();
+      const metadataService = services?.get("metadata");
+      if (metadataService && typeof metadataService.list === "function") {
+        const runtimeItems = await metadataService.list(request.type);
+        if (runtimeItems && runtimeItems.length > 0) {
+          const itemMap = /* @__PURE__ */ new Map();
+          for (const item of items) {
+            const entry = item;
+            if (entry && typeof entry === "object" && "name" in entry) {
+              itemMap.set(entry.name, entry);
+            }
+          }
+          for (const item of runtimeItems) {
+            const entry = item;
+            if (entry && typeof entry === "object" && "name" in entry) {
+              itemMap.set(entry.name, entry);
+            }
+          }
+          items = Array.from(itemMap.values());
+        }
+      }
+    } catch {
+    }
     return {
       type: request.type,
       items
@@ -676,8 +724,8 @@ var ObjectStackProtocolImplementation = class {
   async getMetaItem(request) {
     let item = SchemaRegistry.getItem(request.type, request.name);
     if (item === void 0) {
-      const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-      item = SchemaRegistry.getItem(alt, request.name);
+      const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+      if (alt) item = SchemaRegistry.getItem(alt, request.name);
     }
     if (item === void 0) {
       try {
@@ -688,18 +736,30 @@ var ObjectStackProtocolImplementation = class {
           item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
           SchemaRegistry.registerItem(request.type, item, "name");
         } else {
-          const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-          const altRecord = await this.engine.findOne("sys_metadata", {
-            where: { type: alt, name: request.name, state: "active" }
-          });
-          if (altRecord) {
-            item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
-            SchemaRegistry.registerItem(request.type, item, "name");
+          const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+          if (alt) {
+            const altRecord = await this.engine.findOne("sys_metadata", {
+              where: { type: alt, name: request.name, state: "active" }
+            });
+            if (altRecord) {
+              item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
+              SchemaRegistry.registerItem(request.type, item, "name");
+            }
           }
         }
       } catch {
       }
     }
+    if (item === void 0) {
+      try {
+        const services = this.getServicesRegistry?.();
+        const metadataService = services?.get("metadata");
+        if (metadataService && typeof metadataService.get === "function") {
+          item = await metadataService.get(request.type, request.name);
+        }
+      } catch {
+      }
+    }
     return {
       type: request.type,
       name: request.name,
@@ -872,10 +932,7 @@ var ObjectStackProtocolImplementation = class {
     const records = await this.engine.find(request.object, options);
     return {
       object: request.object,
-      value: records,
-      // OData compatibility
       records,
-      // Legacy
       total: records.length,
       hasMore: false
     };
@@ -933,7 +990,21 @@ var ObjectStackProtocolImplementation = class {
   // ==========================================
   async getMetaItemCached(request) {
     try {
-      const item = SchemaRegistry.getItem(request.type, request.name);
+      let item = SchemaRegistry.getItem(request.type, request.name);
+      if (!item) {
+        const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+        if (alt) item = SchemaRegistry.getItem(alt, request.name);
+      }
+      if (!item) {
+        try {
+          const services = this.getServicesRegistry?.();
+          const metadataService = services?.get("metadata");
+          if (metadataService && typeof metadataService.get === "function") {
+            item = await metadataService.get(request.type, request.name);
+          }
+        } catch {
+        }
+      }
       if (!item) {
         throw new Error(`Metadata item ${request.type}/${request.name} not found`);
       }
@@ -1285,10 +1356,11 @@ var ObjectStackProtocolImplementation = class {
       for (const record of records) {
         try {
           const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-          if (record.type === "object") {
+          const normalizedType = PLURAL_TO_SINGULAR[record.type] ?? record.type;
+          if (normalizedType === "object") {
             SchemaRegistry.registerObject(data, record.packageId || "sys_metadata");
           } else {
-            SchemaRegistry.registerItem(record.type, data, "name");
+            SchemaRegistry.registerItem(normalizedType, data, "name");
           }
           loaded++;
         } catch (e) {
@@ -1438,6 +1510,7 @@ var ObjectStackProtocolImplementation = class {
 import { ExecutionContextSchema } from "@objectstack/spec/kernel";
 import { createLogger } from "@objectstack/core";
 import { CoreServiceName } from "@objectstack/spec/system";
+import { pluralToSingular } from "@objectstack/spec/shared";
 var _ObjectQL = class _ObjectQL {
   constructor(hostContext = {}) {
     this.drivers = /* @__PURE__ */ new Map();
@@ -1728,7 +1801,7 @@ var _ObjectQL = class _ObjectQL {
         for (const item of items) {
           const itemName = item.name || item.id;
           if (itemName) {
-            SchemaRegistry.registerItem(key, item, "name", id);
+            SchemaRegistry.registerItem(pluralToSingular(key), item, "name", id);
           }
         }
       }
@@ -1834,7 +1907,7 @@ var _ObjectQL = class _ObjectQL {
         for (const item of items) {
           const itemName = item.name || item.id;
           if (itemName) {
-            SchemaRegistry.registerItem(key, item, "name", ownerId);
+            SchemaRegistry.registerItem(pluralToSingular(key), item, "name", ownerId);
           }
         }
       }
@@ -1858,6 +1931,16 @@ var _ObjectQL = class _ObjectQL {
       this.logger.info("Set default driver", { driverName: driver.name });
     }
   }
+  /**
+   * Set the realtime service for publishing data change events.
+   * Should be called after kernel resolves the realtime service.
+   *
+   * @param service - An IRealtimeService instance for event publishing
+   */
+  setRealtimeService(service) {
+    this.realtimeService = service;
+    this.logger.info("RealtimeService configured for data events");
+  }
   /**
    * Helper to get object definition
    */
@@ -1912,14 +1995,22 @@ var _ObjectQL = class _ObjectQL {
       driverCount: this.drivers.size,
       drivers: Array.from(this.drivers.keys())
     });
+    const failedDrivers = [];
     for (const [name, driver] of this.drivers) {
       try {
         await driver.connect();
         this.logger.info("Driver connected successfully", { driverName: name });
       } catch (e) {
+        failedDrivers.push(name);
         this.logger.error("Failed to connect driver", e, { driverName: name });
       }
     }
+    if (failedDrivers.length > 0) {
+      this.logger.warn(
+        `${failedDrivers.length} of ${this.drivers.size} driver(s) failed initial connect. Operations may recover via lazy reconnection or fail at query time.`,
+        { failedDrivers }
+      );
+    }
     this.logger.info("ObjectQL engine initialization complete");
   }
   async destroy() {
@@ -2121,6 +2212,39 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterInsert";
         hookContext.result = result;
         await this.triggerHooks("afterInsert", hookContext);
+        if (this.realtimeService) {
+          try {
+            if (Array.isArray(result)) {
+              for (const record of result) {
+                const event = {
+                  type: "data.record.created",
+                  object,
+                  payload: {
+                    recordId: record.id,
+                    after: record
+                  },
+                  timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                };
+                await this.realtimeService.publish(event);
+              }
+              this.logger.debug(`Published ${result.length} data.record.created events`, { object });
+            } else {
+              const event = {
+                type: "data.record.created",
+                object,
+                payload: {
+                  recordId: result.id,
+                  after: result
+                },
+                timestamp: (/* @__PURE__ */ new Date()).toISOString()
+              };
+              await this.realtimeService.publish(event);
+              this.logger.debug("Published data.record.created event", { object, recordId: result.id });
+            }
+          } catch (error) {
+            this.logger.warn("Failed to publish data event", { object, error });
+          }
+        }
         return hookContext.result;
       } catch (e) {
         this.logger.error("Insert operation failed", e, { object });
@@ -2167,6 +2291,26 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterUpdate";
         hookContext.result = result;
         await this.triggerHooks("afterUpdate", hookContext);
+        if (this.realtimeService) {
+          try {
+            const resultId = typeof result === "object" && result && "id" in result ? result.id : void 0;
+            const recordId = String(hookContext.input.id || resultId || "");
+            const event = {
+              type: "data.record.updated",
+              object,
+              payload: {
+                recordId,
+                changes: hookContext.input.data,
+                after: result
+              },
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            };
+            await this.realtimeService.publish(event);
+            this.logger.debug("Published data.record.updated event", { object, recordId });
+          } catch (error) {
+            this.logger.warn("Failed to publish data event", { object, error });
+          }
+        }
         return hookContext.result;
       } catch (e) {
         this.logger.error("Update operation failed", e, { object });
@@ -2212,6 +2356,24 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterDelete";
         hookContext.result = result;
         await this.triggerHooks("afterDelete", hookContext);
+        if (this.realtimeService) {
+          try {
+            const resultId = typeof result === "object" && result && "id" in result ? result.id : void 0;
+            const recordId = String(hookContext.input.id || resultId || "");
+            const event = {
+              type: "data.record.deleted",
+              object,
+              payload: {
+                recordId
+              },
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            };
+            await this.realtimeService.publish(event);
+            this.logger.debug("Published data.record.deleted event", { object, recordId });
+          } catch (error) {
+            this.logger.warn("Failed to publish data event", { object, error });
+          }
+        }
         return hookContext.result;
       } catch (e) {
         this.logger.error("Delete operation failed", e, { object });
@@ -2669,6 +2831,9 @@ var MetadataFacade = class {
 };
 
 // src/plugin.ts
+function hasLoadMetaFromDb(service) {
+  return typeof service === "object" && service !== null && typeof service["loadMetaFromDb"] === "function";
+}
 var ObjectQLPlugin = class {
   constructor(ql, hostContext) {
     this.name = "com.objectstack.engine.objectql";
@@ -2680,38 +2845,18 @@ var ObjectQLPlugin = class {
         this.ql = new ObjectQL(hostCtx);
       }
       ctx.registerService("objectql", this.ql);
-      let hasMetadata = false;
-      let metadataProvider = "objectql";
-      try {
-        if (ctx.getService("metadata")) {
-          hasMetadata = true;
-          metadataProvider = "external";
-        }
-      } catch (e) {
-      }
-      if (!hasMetadata) {
-        try {
-          const metadataFacade = new MetadataFacade();
-          ctx.registerService("metadata", metadataFacade);
-          ctx.logger.info("MetadataFacade registered as metadata service", {
-            mode: "in-memory",
-            features: ["registry", "fast-lookup"]
+      ctx.registerService("data", this.ql);
+      const ql = this.ql;
+      ctx.registerService("manifest", {
+        register: (manifest) => {
+          ql.registerApp(manifest);
+          ctx.logger.debug("Manifest registered via manifest service", {
+            id: manifest.id || manifest.name
           });
-        } catch (e) {
-          if (!e.message?.includes("already registered")) {
-            throw e;
-          }
         }
-      } else {
-        ctx.logger.info("External metadata service detected", {
-          provider: metadataProvider,
-          mode: "will-sync-in-start-phase"
-        });
-      }
-      ctx.registerService("data", this.ql);
+      });
       ctx.logger.info("ObjectQL engine registered", {
-        services: ["objectql", "data"],
-        metadataProvider
+        services: ["objectql", "data", "manifest"]
       });
       const protocolShim = new ObjectStackProtocolImplementation(
         this.ql,
@@ -2724,7 +2869,7 @@ var ObjectQLPlugin = class {
       ctx.logger.info("ObjectQL engine starting...");
       try {
         const metadataService = ctx.getService("metadata");
-        if (metadataService && !(metadataService instanceof MetadataFacade) && this.ql) {
+        if (metadataService && typeof metadataService.loadMany === "function" && this.ql) {
           await this.loadMetadataFromService(metadataService, ctx);
         }
       } catch (e) {
@@ -2738,13 +2883,29 @@ var ObjectQLPlugin = class {
             ctx.logger.debug("Discovered and registered driver service", { serviceName: name });
           }
           if (name.startsWith("app.")) {
+            ctx.logger.warn(
+              `[DEPRECATED] Service "${name}" uses legacy app.* convention. Migrate to ctx.getService('manifest').register(data).`
+            );
             this.ql.registerApp(service);
-            ctx.logger.debug("Discovered and registered app service", { serviceName: name });
+            ctx.logger.debug("Discovered and registered app service (legacy)", { serviceName: name });
+          }
+        }
+        try {
+          const realtimeService = ctx.getService("realtime");
+          if (realtimeService && typeof realtimeService === "object" && "publish" in realtimeService) {
+            ctx.logger.info("[ObjectQLPlugin] Bridging realtime service to ObjectQL for event publishing");
+            this.ql.setRealtimeService(realtimeService);
           }
+        } catch (e) {
+          ctx.logger.debug("[ObjectQLPlugin] No realtime service found \u2014 data events will not be published", {
+            error: e.message
+          });
         }
       }
       await this.ql?.init();
+      await this.restoreMetadataFromDb(ctx);
       await this.syncRegisteredSchemas(ctx);
+      await this.bridgeObjectsToMetadataService(ctx);
       this.registerAuditHooks(ctx);
       this.registerTenantMiddleware(ctx);
       ctx.logger.info("ObjectQL engine started", {
@@ -2937,6 +3098,97 @@ var ObjectQLPlugin = class {
       ctx.logger.info("Schema sync complete", { synced, skipped, total: allObjects.length });
     }
   }
+  /**
+   * Restore persisted metadata from the database (sys_metadata) on startup.
+   *
+   * Calls `protocol.loadMetaFromDb()` to bulk-load all active metadata
+   * records (objects, views, apps, etc.) into the in-memory SchemaRegistry.
+   * This closes the persistence loop so that user-created schemas survive
+   * kernel cold starts and redeployments.
+   *
+   * Gracefully degrades when:
+   * - The protocol service is unavailable (e.g., in-memory-only mode).
+   * - `loadMetaFromDb` is not implemented by the protocol shim.
+   * - The underlying driver/table does not exist yet (first-run scenario).
+   */
+  async restoreMetadataFromDb(ctx) {
+    let protocol;
+    try {
+      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) {
+      ctx.logger.debug("Protocol service unavailable, skipping DB restore", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+      return;
+    }
+    try {
+      const { loaded, errors } = await protocol.loadMetaFromDb();
+      if (loaded > 0 || errors > 0) {
+        ctx.logger.info("Metadata restored from database to SchemaRegistry", { loaded, errors });
+      } else {
+        ctx.logger.debug("No persisted metadata found in database");
+      }
+    } catch (e) {
+      ctx.logger.debug("DB metadata restore failed (non-fatal)", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+    }
+  }
+  /**
+   * Bridge all SchemaRegistry objects to the metadata service.
+   *
+   * This ensures objects registered by plugins and loaded from sys_metadata
+   * are visible to AI tools and other consumers that query IMetadataService.
+   *
+   * Runs after both restoreMetadataFromDb() and syncRegisteredSchemas() to
+   * catch all objects in the SchemaRegistry regardless of their source.
+   */
+  async bridgeObjectsToMetadataService(ctx) {
+    try {
+      const metadataService = ctx.getService("metadata");
+      if (!metadataService || typeof metadataService.register !== "function") {
+        ctx.logger.debug("Metadata service unavailable for bridging, skipping");
+        return;
+      }
+      if (!this.ql?.registry) {
+        ctx.logger.debug("SchemaRegistry unavailable for bridging, skipping");
+        return;
+      }
+      const objects = this.ql.registry.getAllObjects();
+      let bridged = 0;
+      for (const obj of objects) {
+        try {
+          const existing = await metadataService.getObject(obj.name);
+          if (!existing) {
+            await metadataService.register("object", obj.name, obj);
+            bridged++;
+          }
+        } catch (e) {
+          ctx.logger.debug("Failed to bridge object to metadata service", {
+            object: obj.name,
+            error: e instanceof Error ? e.message : String(e)
+          });
+        }
+      }
+      if (bridged > 0) {
+        ctx.logger.info("Bridged objects from SchemaRegistry to metadata service", {
+          count: bridged,
+          total: objects.length
+        });
+      } else {
+        ctx.logger.debug("No objects needed bridging (all already in metadata service)");
+      }
+    } catch (e) {
+      ctx.logger.debug("Failed to bridge objects to metadata service", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+    }
+  }
   /**
    * Load metadata from external metadata service into ObjectQL registry
    * This enables ObjectQL to use file-based or remote metadata