Merge pull request #739 from objectstack-ai/copilot/update-object-naming-prefix

Author: hotlong

ROADMAP.md

@@ -138,6 +138,32 @@ The following renames are planned for packages that implement core service contr
 > The existing `plugin-auth` package will be preserved with a deprecation notice and re-export shim
 > until v4.0 removes the old name.
 
+### System Object Naming Convention (`sys_` Prefix)
+
+> **Adopted:** 2026-02-19  
+> **Scope:** All system kernel objects in `SystemObjectName` constants.
+
+All system kernel objects use the `sys_` prefix to clearly distinguish platform-internal objects from
+business/custom objects, aligning with industry best practices (e.g., ServiceNow `sys_user`, `sys_audit`).
+
+| Constant Key | Protocol Name | Description |
+|:---|:---|:---|
+| `SystemObjectName.USER` | `sys_user` | Authentication: user identity |
+| `SystemObjectName.SESSION` | `sys_session` | Authentication: active session |
+| `SystemObjectName.ACCOUNT` | `sys_account` | Authentication: OAuth / credential account |
+| `SystemObjectName.VERIFICATION` | `sys_verification` | Authentication: email / phone verification |
+| `SystemObjectName.METADATA` | `sys_metadata` | System metadata storage |
+
+**Rationale:**
+- Prevents naming collisions between system objects and business objects (e.g., a CRM `account` vs. `sys_account`)
+- Aligns with ServiceNow and similar platforms that use `sys_` as a reserved namespace
+- ObjectStack already uses namespace + FQN for business object isolation; the `sys_` prefix completes the picture for kernel-level objects
+- Physical storage table names can differ via `ObjectSchema.tableName` + `StorageNameMapping.resolveTableName()` for backward compatibility
+
+**Migration (v3.x → v4.0):**
+- v3.x: The `SystemObjectName` constants now emit `sys_`-prefixed names. Implementations using `StorageNameMapping.resolveTableName()` can set `tableName` to preserve legacy physical table names during the transition.
+- v4.0: Legacy un-prefixed aliases will be fully removed.
+
 ---
 
 ## Phase 1: Protocol Specification (✅ Complete)

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

@@ -10,18 +10,18 @@ import {
 // ============================================================================
 
 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');
+  it('should expose all expected object names with sys_ prefix', () => {
+    expect(SystemObjectName.USER).toBe('sys_user');
+    expect(SystemObjectName.SESSION).toBe('sys_session');
+    expect(SystemObjectName.ACCOUNT).toBe('sys_account');
+    expect(SystemObjectName.VERIFICATION).toBe('sys_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');
+    expect(names).toContain('sys_user');
+    expect(names).toContain('sys_session');
   });
 });
 

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

@@ -21,13 +21,13 @@
  */
 export const SystemObjectName = {
   /** Authentication: user identity */
-  USER: 'user',
+  USER: 'sys_user',
   /** Authentication: active session */
-  SESSION: 'session',
+  SESSION: 'sys_session',
   /** Authentication: OAuth / credential account */
-  ACCOUNT: 'account',
+  ACCOUNT: 'sys_account',
   /** Authentication: email / phone verification */
-  VERIFICATION: 'verification',
+  VERIFICATION: 'sys_verification',
   /** System metadata storage */
   METADATA: 'sys_metadata',
 } as const;