Merge pull request #730 from objectstack-ai/copilot/support-object-name-decoupling

Author: hotlong

ROADMAP.md

@@ -146,10 +146,10 @@ The following renames are planned for packages that implement core service contr
 
 ### Deliverables — All Completed
 
-- [x] **Data Protocol** — Object, Field (35+ types), Query, Filter, Validation, Hook, Datasource, Dataset, Analytics, Document
+- [x] **Data Protocol** — Object, Field (35+ types), Query, Filter, Validation, Hook, Datasource, Dataset, Analytics, Document, Storage Name Mapping (`tableName`/`columnName`)
 - [x] **Driver Specifications** — Memory, PostgreSQL, MongoDB driver schemas + SQL/NoSQL abstractions
 - [x] **UI Protocol** — View (List/Form/Kanban/Calendar/Gantt), App, Dashboard, Report, Action, Page (16 types), Chart, Widget, Theme, Animation, DnD, Touch, Keyboard, Responsive, Offline, Notification, i18n, Content Elements
-- [x] **System Protocol** — Manifest, Auth Config, Cache, Logging, Metrics, Tracing, Audit, Encryption, Masking, Migration, Tenant, Translation, Search Engine, HTTP Server, Worker, Job, Object Storage, Notification, Message Queue, Registry Config, Collaboration, Compliance, Change Management, Disaster Recovery, License, Security Context, Core Services
+- [x] **System Protocol** — Manifest, Auth Config, Cache, Logging, Metrics, Tracing, Audit, Encryption, Masking, Migration, Tenant, Translation, Search Engine, HTTP Server, Worker, Job, Object Storage, Notification, Message Queue, Registry Config, Collaboration, Compliance, Change Management, Disaster Recovery, License, Security Context, Core Services, SystemObjectName/SystemFieldName Constants, StorageNameMapping Utilities
 - [x] **Automation Protocol** — Flow (autolaunched/screen/schedule), Workflow, State Machine, Trigger Registry, Approval, ETL, Sync, Webhook
 - [x] **AI Protocol** — Agent, Agent Action, Conversation, Cost, MCP, Model Registry, NLQ, Orchestration, Predictive, RAG Pipeline, Runtime Ops, Feedback Loop, DevOps Agent, Plugin Development
 - [x] **API Protocol** — Protocol (104 schemas), Endpoint, Contract, Router, Dispatcher, REST Server, GraphQL, OData, WebSocket, Realtime, Batch, Versioning, HTTP Cache, Documentation, Discovery, Registry, Errors, Auth, Auth Endpoints, Metadata, Analytics, Query Adapter, Storage, Plugin REST API

packages/spec/src/data/field.test.ts

@@ -1433,3 +1433,32 @@ describe('FieldSchema - conditionalRequired property', () => {
     expect(result.conditionalRequired).toBe('amount > 1000');
   });
 });
+
+// ============================================================================
+// columnName — Storage Layer Mapping
+// ============================================================================
+
+describe('FieldSchema - columnName', () => {
+  it('should accept columnName for storage layer mapping', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+      columnName: 'user_email',
+    });
+    expect(result.columnName).toBe('user_email');
+  });
+
+  it('should accept field without columnName (optional, defaults to key)', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+    });
+    expect(result.columnName).toBeUndefined();
+  });
+
+  it('should accept camelCase columnName for legacy DB compatibility', () => {
+    const result = FieldSchema.parse({
+      type: 'datetime',
+      columnName: 'expiresAt',
+    });
+    expect(result.columnName).toBe('expiresAt');
+  });
+});

packages/spec/src/data/field.zod.ts

@@ -349,6 +349,9 @@ export const FieldSchema = z.object({
   description: z.string().optional().describe('Tooltip/Help text'),
   format: z.string().optional().describe('Format string (e.g. email, phone)'),
 
+  /** Storage Layer Mapping */
+  columnName: z.string().optional().describe('Physical column name in the target datasource. Defaults to the field key when not set.'),
+
   /** Database Constraints */
   required: z.boolean().default(false).describe('Is required'),
   searchable: z.boolean().default(false).describe('Is searchable'),

packages/spec/src/data/object.test.ts

@@ -283,6 +283,28 @@ describe('ObjectSchema', () => {
 
       expect(() => ObjectSchema.parse(fullObject)).not.toThrow();
     });
+
+    it('should accept object with tableName and field-level columnName for storage decoupling', () => {
+      const object = ObjectSchema.parse({
+        name: 'user',
+        tableName: 'ba_users',
+        fields: {
+          email: {
+            type: 'email',
+            columnName: 'email_address',
+          },
+          created_at: {
+            type: 'datetime',
+            columnName: 'createdAt',
+          },
+        },
+      });
+
+      expect(object.name).toBe('user');
+      expect(object.tableName).toBe('ba_users');
+      expect(object.fields.email.columnName).toBe('email_address');
+      expect(object.fields.created_at.columnName).toBe('createdAt');
+    });
   });
 
   describe('Object with Indexes', () => {

packages/spec/src/system/constants/index.ts

@@ -11,3 +11,4 @@
  */
 
 export * from './paths';
+export * from './system-names';

packages/spec/src/system/constants/system-names.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from 'vitest';
+import {
+  SystemObjectName,
+  SystemFieldName,
+  StorageNameMapping,
+} from './system-names';
+
+// ============================================================================
+// SystemObjectName
+// ============================================================================
+
+describe('SystemObjectName', () => {
+  it('should expose all expected object names', () => {
+    expect(SystemObjectName.USER).toBe('user');
+    expect(SystemObjectName.SESSION).toBe('session');
+    expect(SystemObjectName.ACCOUNT).toBe('account');
+    expect(SystemObjectName.VERIFICATION).toBe('verification');
+    expect(SystemObjectName.METADATA).toBe('sys_metadata');
+  });
+
+  it('should be readonly (const assertion)', () => {
+    const names: readonly string[] = Object.values(SystemObjectName);
+    expect(names).toContain('user');
+    expect(names).toContain('session');
+  });
+});
+
+// ============================================================================
+// SystemFieldName
+// ============================================================================
+
+describe('SystemFieldName', () => {
+  it('should expose all expected field names', () => {
+    expect(SystemFieldName.ID).toBe('id');
+    expect(SystemFieldName.CREATED_AT).toBe('created_at');
+    expect(SystemFieldName.UPDATED_AT).toBe('updated_at');
+    expect(SystemFieldName.OWNER_ID).toBe('owner_id');
+    expect(SystemFieldName.TENANT_ID).toBe('tenant_id');
+    expect(SystemFieldName.USER_ID).toBe('user_id');
+    expect(SystemFieldName.DELETED_AT).toBe('deleted_at');
+  });
+
+  it('should be readonly (const assertion)', () => {
+    const names: readonly string[] = Object.values(SystemFieldName);
+    expect(names).toContain('id');
+    expect(names).toContain('owner_id');
+  });
+});
+
+// ============================================================================
+// StorageNameMapping
+// ============================================================================
+
+describe('StorageNameMapping', () => {
+  describe('resolveTableName', () => {
+    it('should return tableName when specified', () => {
+      expect(StorageNameMapping.resolveTableName({ name: 'user', tableName: 'ba_users' })).toBe('ba_users');
+    });
+
+    it('should fall back to name when tableName is not set', () => {
+      expect(StorageNameMapping.resolveTableName({ name: 'user' })).toBe('user');
+    });
+
+    it('should fall back to name when tableName is undefined', () => {
+      expect(StorageNameMapping.resolveTableName({ name: 'session', tableName: undefined })).toBe('session');
+    });
+  });
+
+  describe('resolveColumnName', () => {
+    it('should return columnName when specified', () => {
+      expect(StorageNameMapping.resolveColumnName('user_id', { columnName: 'userId' })).toBe('userId');
+    });
+
+    it('should fall back to fieldKey when columnName is not set', () => {
+      expect(StorageNameMapping.resolveColumnName('user_id', {})).toBe('user_id');
+    });
+
+    it('should fall back to fieldKey when columnName is undefined', () => {
+      expect(StorageNameMapping.resolveColumnName('email', { columnName: undefined })).toBe('email');
+    });
+  });
+
+  describe('buildColumnMap', () => {
+    it('should build a complete field-key → column-name map', () => {
+      const fields = {
+        user_id: { columnName: 'userId' },
+        email: {},
+        expires_at: { columnName: 'expiresAt' },
+      };
+
+      const map = StorageNameMapping.buildColumnMap(fields);
+
+      expect(map).toEqual({
+        user_id: 'userId',
+        email: 'email',
+        expires_at: 'expiresAt',
+      });
+    });
+
+    it('should return empty map for empty fields', () => {
+      expect(StorageNameMapping.buildColumnMap({})).toEqual({});
+    });
+  });
+
+  describe('buildReverseColumnMap', () => {
+    it('should build a reverse column-name → field-key map', () => {
+      const fields = {
+        user_id: { columnName: 'userId' },
+        email: {},
+        expires_at: { columnName: 'expiresAt' },
+      };
+
+      const reverseMap = StorageNameMapping.buildReverseColumnMap(fields);
+
+      expect(reverseMap).toEqual({
+        userId: 'user_id',
+        email: 'email',
+        expiresAt: 'expires_at',
+      });
+    });
+
+    it('should return empty map for empty fields', () => {
+      expect(StorageNameMapping.buildReverseColumnMap({})).toEqual({});
+    });
+
+    it('should handle all fields without columnName (identity mapping)', () => {
+      const fields = {
+        name: {},
+        status: {},
+      };
+
+      const reverseMap = StorageNameMapping.buildReverseColumnMap(fields);
+
+      expect(reverseMap).toEqual({
+        name: 'name',
+        status: 'status',
+      });
+    });
+  });
+});

packages/spec/src/system/constants/system-names.ts

@@ -0,0 +1,140 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * System Object Names — Protocol Layer Constants
+ *
+ * These constants define the canonical, protocol-level names for system objects.
+ * All API calls, SDK references, permissions checks, and metadata lookups MUST use
+ * these names instead of hardcoded strings or physical table names.
+ *
+ * The actual storage table name may differ via `ObjectSchema.tableName`.
+ * The mapping between protocol name and storage name is handled by the
+ * ObjectQL Engine / Driver layer.
+ *
+ * @example
+ * ```ts
+ * import { SystemObjectName } from '@objectstack/spec/system';
+ *
+ * // Always use the constant for API / SDK / permission references
+ * const users = await engine.find(SystemObjectName.USER, { ... });
+ * ```
+ */
+export const SystemObjectName = {
+  /** Authentication: user identity */
+  USER: 'user',
+  /** Authentication: active session */
+  SESSION: 'session',
+  /** Authentication: OAuth / credential account */
+  ACCOUNT: 'account',
+  /** Authentication: email / phone verification */
+  VERIFICATION: 'verification',
+  /** System metadata storage */
+  METADATA: 'sys_metadata',
+} as const;
+
+/** Union type of all system object names */
+export type SystemObjectName = typeof SystemObjectName[keyof typeof SystemObjectName];
+
+/**
+ * System Field Names — Protocol Layer Constants
+ *
+ * These constants define the canonical, protocol-level names for common system fields.
+ * All API calls, SDK references, and permission checks MUST use these constants
+ * instead of hardcoded strings or physical column names.
+ *
+ * The actual storage column name may differ via `FieldSchema.columnName`.
+ *
+ * @example
+ * ```ts
+ * import { SystemFieldName } from '@objectstack/spec/system';
+ *
+ * // Use the constant to reference the owner field in queries
+ * const myRecords = await engine.find('project', {
+ *   filters: [SystemFieldName.OWNER_ID, '=', currentUserId],
+ * });
+ * ```
+ */
+export const SystemFieldName = {
+  /** Primary key */
+  ID: 'id',
+  /** Record creation timestamp */
+  CREATED_AT: 'created_at',
+  /** Record last-updated timestamp */
+  UPDATED_AT: 'updated_at',
+  /** Record owner (lookup to user) */
+  OWNER_ID: 'owner_id',
+  /** Tenant isolation key */
+  TENANT_ID: 'tenant_id',
+  /** Foreign key to user on session / account objects */
+  USER_ID: 'user_id',
+  /** Soft-delete timestamp */
+  DELETED_AT: 'deleted_at',
+} as const;
+
+/** Union type of all system field names */
+export type SystemFieldName = typeof SystemFieldName[keyof typeof SystemFieldName];
+
+/**
+ * Storage Name Mapping — Protocol ↔ Physical Name Resolution
+ *
+ * Provides pure utility functions for resolving protocol-level names to
+ * physical storage names and vice-versa.
+ *
+ * These helpers are intended for use inside the ObjectQL Engine and Driver layers.
+ * They are intentionally stateless — they receive the object definition and return
+ * the resolved name.
+ */
+export const StorageNameMapping = {
+  /**
+   * Resolve the physical table name for an object.
+   * Falls back to `object.name` when `tableName` is not set.
+   *
+   * @param object - Object definition (at minimum `{ name: string; tableName?: string }`)
+   * @returns The physical table / collection name to use in storage operations.
+   */
+  resolveTableName(object: { name: string; tableName?: string }): string {
+    return object.tableName ?? object.name;
+  },
+
+  /**
+   * Resolve the physical column name for a field.
+   * Falls back to `fieldKey` when `columnName` is not set on the field.
+   *
+   * @param fieldKey - The protocol-level field key (snake_case identifier).
+   * @param field    - Field definition (at minimum `{ columnName?: string }`).
+   * @returns The physical column name to use in storage operations.
+   */
+  resolveColumnName(fieldKey: string, field: { columnName?: string }): string {
+    return field.columnName ?? fieldKey;
+  },
+
+  /**
+   * Build a complete field-key → column-name map for an entire object.
+   *
+   * @param fields - The fields record from an ObjectSchema.
+   * @returns A record mapping every protocol field key to its physical column name.
+   */
+  buildColumnMap(fields: Record<string, { columnName?: string }>): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const key of Object.keys(fields)) {
+      map[key] = fields[key].columnName ?? key;
+    }
+    return map;
+  },
+
+  /**
+   * Build a reverse column-name → field-key map for an entire object.
+   * Useful for translating storage-layer results back to protocol-level field keys.
+   *
+   * @param fields - The fields record from an ObjectSchema.
+   * @returns A record mapping every physical column name back to its protocol field key.
+   */
+  buildReverseColumnMap(fields: Record<string, { columnName?: string }>): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const key of Object.keys(fields)) {
+      const col = fields[key].columnName ?? key;
+      map[col] = key;
+    }
+    return map;
+  },
+} as const;

packages/spec/src/system/index.ts

@@ -47,5 +47,8 @@ export * from './tenant.zod';
 export * from './license.zod';
 export * from './registry-config.zod';
 
+// Constants
+export * from './constants';
+
 // Types
 export * from './types';