Skip to content

Commit 8d767a5

Browse files
Copilothotlong
andcommitted
feat: unify system kernel object naming with sys_ prefix
BREAKING CHANGE: All system kernel objects now use sys_ prefix: - user → sys_user - session → sys_session - account → sys_account - verification → sys_verification - metadata remains sys_metadata (unchanged) Constant keys (SystemObjectName.USER etc.) remain the same. Use StorageNameMapping.resolveTableName() for backward compatibility. Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 72f169e commit 8d767a5

3 files changed

Lines changed: 37 additions & 11 deletions

File tree

ROADMAP.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,32 @@ The following renames are planned for packages that implement core service contr
138138
> The existing `plugin-auth` package will be preserved with a deprecation notice and re-export shim
139139
> until v4.0 removes the old name.
140140
141+
### System Object Naming Convention (`sys_` Prefix)
142+
143+
> **Adopted:** 2026-02-19
144+
> **Scope:** All system kernel objects in `SystemObjectName` constants.
145+
146+
All system kernel objects use the `sys_` prefix to clearly distinguish platform-internal objects from
147+
business/custom objects, aligning with industry best practices (e.g., ServiceNow `sys_user`, `sys_audit`).
148+
149+
| Constant Key | Protocol Name | Description |
150+
|:---|:---|:---|
151+
| `SystemObjectName.USER` | `sys_user` | Authentication: user identity |
152+
| `SystemObjectName.SESSION` | `sys_session` | Authentication: active session |
153+
| `SystemObjectName.ACCOUNT` | `sys_account` | Authentication: OAuth / credential account |
154+
| `SystemObjectName.VERIFICATION` | `sys_verification` | Authentication: email / phone verification |
155+
| `SystemObjectName.METADATA` | `sys_metadata` | System metadata storage |
156+
157+
**Rationale:**
158+
- Prevents naming collisions between system objects and business objects (e.g., a CRM `account` vs. `sys_account`)
159+
- Aligns with ServiceNow and similar platforms that use `sys_` as a reserved namespace
160+
- ObjectStack already uses namespace + FQN for business object isolation; the `sys_` prefix completes the picture for kernel-level objects
161+
- Physical storage table names can differ via `ObjectSchema.tableName` + `StorageNameMapping.resolveTableName()` for backward compatibility
162+
163+
**Migration (v3.x → v4.0):**
164+
- 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.
165+
- v4.0: Legacy un-prefixed aliases will be fully removed.
166+
141167
---
142168

143169
## Phase 1: Protocol Specification (✅ Complete)

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,18 @@ import {
1010
// ============================================================================
1111

1212
describe('SystemObjectName', () => {
13-
it('should expose all expected object names', () => {
14-
expect(SystemObjectName.USER).toBe('user');
15-
expect(SystemObjectName.SESSION).toBe('session');
16-
expect(SystemObjectName.ACCOUNT).toBe('account');
17-
expect(SystemObjectName.VERIFICATION).toBe('verification');
13+
it('should expose all expected object names with sys_ prefix', () => {
14+
expect(SystemObjectName.USER).toBe('sys_user');
15+
expect(SystemObjectName.SESSION).toBe('sys_session');
16+
expect(SystemObjectName.ACCOUNT).toBe('sys_account');
17+
expect(SystemObjectName.VERIFICATION).toBe('sys_verification');
1818
expect(SystemObjectName.METADATA).toBe('sys_metadata');
1919
});
2020

2121
it('should be readonly (const assertion)', () => {
2222
const names: readonly string[] = Object.values(SystemObjectName);
23-
expect(names).toContain('user');
24-
expect(names).toContain('session');
23+
expect(names).toContain('sys_user');
24+
expect(names).toContain('sys_session');
2525
});
2626
});
2727

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@
2121
*/
2222
export const SystemObjectName = {
2323
/** Authentication: user identity */
24-
USER: 'user',
24+
USER: 'sys_user',
2525
/** Authentication: active session */
26-
SESSION: 'session',
26+
SESSION: 'sys_session',
2727
/** Authentication: OAuth / credential account */
28-
ACCOUNT: 'account',
28+
ACCOUNT: 'sys_account',
2929
/** Authentication: email / phone verification */
30-
VERIFICATION: 'verification',
30+
VERIFICATION: 'sys_verification',
3131
/** System metadata storage */
3232
METADATA: 'sys_metadata',
3333
} as const;

0 commit comments

Comments
 (0)