Merge branch 'main' of https://github.com/objectstack-ai/framework

Author: hotlong

packages/metadata/src/metadata-manager.ts

@@ -137,6 +137,13 @@ export class MetadataManager implements IMetadataService {
    * @param environmentId - Environment ID (undefined = platform-global)
    */
   setDatabaseDriver(driver: IDataDriver, organizationId?: string, environmentId?: string): void {
+    if (environmentId !== undefined) {
+      this.logger.info('Project kernel — skipping DatabaseLoader for sys_metadata (control-plane only)', {
+        organizationId,
+        environmentId,
+      });
+      return;
+    }
     const tableName = this.config.tableName ?? 'sys_metadata';
     const dbLoader = new DatabaseLoader({
       driver,
@@ -159,6 +166,13 @@ export class MetadataManager implements IMetadataService {
    * @param environmentId - Environment ID (undefined = platform-global)
    */
   setDataEngine(engine: IDataEngine, organizationId?: string, environmentId?: string): void {
+    if (environmentId !== undefined) {
+      this.logger.info('Project kernel — skipping DatabaseLoader for sys_metadata (control-plane only)', {
+        organizationId,
+        environmentId,
+      });
+      return;
+    }
     const tableName = this.config.tableName ?? 'sys_metadata';
     const dbLoader = new DatabaseLoader({
       engine,

packages/objectql/src/plugin.ts

@@ -166,7 +166,15 @@ export class ObjectQLPlugin implements Plugin {
     await this.syncRegisteredSchemas(ctx);
 
     // Phase 2: Hydrate SchemaRegistry from sys_metadata (loads custom/template objects).
-    await this.restoreMetadataFromDb(ctx);
+    // Project kernels (environmentId set) never persist sys_metadata locally —
+    // metadata is sourced from the artifact (MetadataPlugin) or routed to the
+    // control plane via ControlPlaneProxyDriver. Skip to avoid querying a table
+    // that does not exist on local project DBs.
+    if (this.environmentId === undefined) {
+        await this.restoreMetadataFromDb(ctx);
+    } else {
+        ctx.logger.info('Project kernel — skipping sys_metadata hydration (metadata sourced from artifact)');
+    }
 
     // Phase 3: Sync any new schemas that were just hydrated from the DB
     // (e.g. CRM objects seeded via template — they must have tables before use).
@@ -176,12 +184,12 @@ export class ObjectQLPlugin implements Plugin {
     //
     // `SchemaRegistry` is a process-wide singleton, so project kernels in a
     // multi-project server would otherwise inherit every object ever
-    // registered by any sibling project (`saveMetaItem` writes to it).
-    // When this plugin was constructed with an `environmentId`, the kernel
-    // is project-scoped — its own ObjectQL.start already hydrated the
-    // project-owned schemas from sys_metadata (env_id-filtered), and the
-    // bridge would only pollute its metadata service with cross-project
-    // leakage. Skip it in that case.
+    // registered by any sibling project. When this plugin was constructed
+    // with an `environmentId`, the kernel is project-scoped — its
+    // metadata comes from the artifact (MetadataPlugin) or the
+    // control-plane proxy, not from local sys_metadata. The bridge would
+    // only pollute its metadata service with cross-project leakage, so
+    // skip it in that case.
     if (this.environmentId === undefined) {
         await this.bridgeObjectsToMetadataService(ctx);
     }

packages/objectql/src/protocol.ts

@@ -263,7 +263,8 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         // entries (the previous fallback-only logic meant project metadata
         // was never surfaced whenever system-bridged items populated the
         // registry). Deduplicate against whatever the registry returned.
-        try {
+        // Skip on project kernels — sys_metadata is control-plane only.
+        if (this.environmentId === undefined) try {
             const whereClause: Record<string, unknown> = {
                 type: request.type,
                 state: 'active',
@@ -367,8 +368,10 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             }
         }
 
-        // Fallback to database if not in registry
-        if (item === undefined) {
+        // Fallback to database if not in registry.
+        // Skip on project kernels — sys_metadata is control-plane only;
+        // project kernels source metadata from the artifact via MetadataService below.
+        if (item === undefined && this.environmentId === undefined) {
             try {
                 const scopedWhere: Record<string, unknown> = {
                     type: request.type,
@@ -1085,6 +1088,26 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             throw new Error('Item data is required');
         }
 
+        // Project kernels (environmentId set) never persist to sys_metadata
+        // locally — runtime metadata is sourced from the artifact and writes
+        // belong to the control plane. Update the in-memory registry only.
+        if (this.environmentId !== undefined) {
+            this.engine.registry.registerItem(request.type, request.item, 'name');
+            if (request.type === 'object' || request.type === 'objects') {
+                try {
+                    this.engine.registry.registerObject(request.item as any, 'sys_metadata');
+                } catch (err: any) {
+                    console.warn(
+                        `[Protocol] registerObject failed for ${request.name}: ${err?.message ?? err}`,
+                    );
+                }
+            }
+            return {
+                success: true,
+                message: 'Saved to memory registry (project kernel — sys_metadata is control-plane only)',
+            };
+        }
+
         // 1. Always update the in-memory registry (runtime cache).
         //    For `type === 'object'` we additionally register in the
         //    dedicated objects map so that downstream calls (e.g.
@@ -1176,6 +1199,12 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * Safe to call repeatedly — idempotent (latest DB record wins).
      */
     async loadMetaFromDb(): Promise<{ loaded: number; errors: number }> {
+        // Project kernels never read sys_metadata locally — the table only
+        // exists on the control plane. Metadata is sourced from the artifact
+        // (MetadataPlugin) or routed via ControlPlaneProxyDriver.
+        if (this.environmentId !== undefined) {
+            return { loaded: 0, errors: 0 };
+        }
         let loaded = 0;
         let errors = 0;
         try {