Remove flat exports, enforce namespace-only imports

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

packages/spec/EXPORT_ORGANIZATION.md

@@ -7,26 +7,27 @@ The `@objectstack/spec` package exports many schemas and types. As the API surfa
 2. **Poor discoverability**: With 200+ exports in a flat namespace, it's hard to find what you need
 3. **Unclear domain boundaries**: Not obvious which exports belong to which protocol
 
-## Solution: Dual Export Strategy
+## Solution: Namespace-Only Exports
 
-We now support **both flat and namespaced imports** to give developers flexibility while preventing future naming conflicts.
+This package **does NOT export types at the root level** to prevent naming conflicts. All exports are organized by protocol domain using namespaces.
 
-### 1. Flat Exports (Backward Compatible)
+### Import Styles
 
-All existing imports continue to work:
+#### Style 1: Namespace Imports from Root
 
 ```typescript
-import { Field, User, App, Agent } from '@objectstack/spec';
+import { Data, UI, System, AI, API } from '@objectstack/spec';
+
+const field: Data.Field = { /* ... */ };
+const user: System.User = { /* ... */ };
 ```
 
 **When to use:**
-- Migrating existing code
-- Importing a few specific types
-- Quick prototyping
+- Need multiple protocols in one file
+- Want single import statement
+- Clear namespace boundaries
 
-### 2. Namespaced Exports (Recommended)
-
-Import by protocol domain for better organization:
+#### Style 2: Namespace Imports via Subpath
 
 ```typescript
 import * as Data from '@objectstack/spec/data';
@@ -40,10 +41,24 @@ const user: System.User = { /* ... */ };
 ```
 
 **When to use:**
-- New code
-- Working with many types from the same protocol
-- Want to avoid any risk of naming conflicts
-- Want clear domain boundaries in your code
+- Better tree-shaking (only imports needed protocols)
+- Explicit about which protocols are used
+- Working with many types from same protocol
+
+#### Style 3: Direct Subpath Imports
+
+```typescript
+import { Field, FieldType } from '@objectstack/spec/data';
+import { User, Session } from '@objectstack/spec/system';
+
+const field: Field = { /* ... */ };
+const user: User = { /* ... */ };
+```
+
+**When to use:**
+- Most concise syntax
+- Importing specific types only
+- No namespace prefix needed
 
 ## Protocol Domains
 
@@ -85,48 +100,51 @@ API contracts and envelopes:
 
 ## Migration Guide
 
-### For Library Maintainers
+### Breaking Change Notice
 
-You don't need to change anything! All existing exports remain available. However, you may want to adopt namespaced imports in new code:
+**This is a breaking change.** Flat imports are no longer supported.
 
-**Before:**
+**Before (v0.1.x):**
 ```typescript
 import { Field, User, App } from '@objectstack/spec';
 ```
 
-**After (optional):**
+**After (v0.2.x+):**
 ```typescript
+// Option 1: Namespace from root
+import { Data, System, UI } from '@objectstack/spec';
+const field: Data.Field = { /* ... */ };
+const user: System.User = { /* ... */ };
+
+// Option 2: Namespace via subpath
 import * as Data from '@objectstack/spec/data';
 import * as System from '@objectstack/spec/system';
-import * as UI from '@objectstack/spec/ui';
-
 const field: Data.Field = { /* ... */ };
 const user: System.User = { /* ... */ };
-const app: UI.App = { /* ... */ };
-```
 
-### For Application Developers
+// Option 3: Direct subpath imports
+import { Field } from '@objectstack/spec/data';
+import { User } from '@objectstack/spec/system';
+const field: Field = { /* ... */ };
+const user: User = { /* ... */ };
+```
 
-Choose the style that fits your needs:
+### Migration Steps
 
-```typescript
-// Option 1: Flat imports (quick and simple)
-import { ObjectSchema, Field } from '@objectstack/spec';
+1. **Find all imports from `@objectstack/spec`:**
+   ```bash
+   grep -r "from '@objectstack/spec'" src/
+   ```
 
-// Option 2: Namespaced imports (organized and safe)
-import * as Data from '@objectstack/spec/data';
-const result = Data.ObjectSchema.parse(config);
+2. **Replace with one of the three styles above**
 
-// Option 3: Mixed approach
-import { Field } from '@objectstack/spec';
-import * as System from '@objectstack/spec/system';
-```
+3. **Test your application** to ensure all types are accessible
 
 ## Implementation Details
 
 ### Package.json Exports
 
-The `package.json` now includes export mappings:
+The `package.json` includes export mappings:
 
 ```json
 {
@@ -151,22 +169,23 @@ Each protocol domain has an `index.ts` barrel file that re-exports all schemas a
 - `src/ai/index.ts` - AI Protocol
 - `src/api/index.ts` - API Protocol
 
-The root `src/index.ts` continues to re-export everything for backward compatibility.
+The root `src/index.ts` exports only protocol namespaces (no flat exports).
 
 ## Benefits
 
-1. **Zero Breaking Changes**: All existing code continues to work
-2. **Prevents Conflicts**: Clear namespace boundaries prevent naming collisions
+1. **Eliminates Naming Conflicts**: Namespace boundaries prevent all naming collisions
+2. **Clear Protocol Boundaries**: Immediately obvious which protocol a type belongs to
 3. **Better IDE Support**: Autocomplete shows all types in a namespace
 4. **Self-Documenting**: Code clearly shows which protocol is being used
 5. **Scalable**: Can easily add new protocols without conflict risk
+6. **Tree-Shakeable**: Modern bundlers can better optimize imports
 
 ## Future Considerations
 
 As the API grows, we can:
 1. Add sub-namespaces (e.g., `@objectstack/spec/data/query` for query-specific types)
-2. Mark certain flat exports as deprecated if conflicts arise
-3. Add convenience exports for commonly-used combinations
+2. Add convenience exports for commonly-used combinations
+3. Further organize large protocol domains into sub-categories
 
 ## Questions?
 

packages/spec/PR_SUMMARY.md

@@ -8,7 +8,7 @@
 
 ## Solution Overview
 
-Implemented a **dual export strategy** that prevents naming conflicts while maintaining 100% backward compatibility.
+Implemented a **namespace-only export strategy** that completely eliminates naming conflicts. This is a **breaking change** that enforces organized imports by protocol domain.
 
 ## Key Changes
 
@@ -25,7 +25,19 @@ packages/spec/src/
 └── api/index.ts         # API Protocol (Contracts, Requests, etc.)
 ```
 
-### 2. Updated package.json
+### 2. Updated Root Index
+
+**Removed all flat exports** from `src/index.ts` and replaced with namespace exports:
+
+```typescript
+export * as Data from './data';
+export * as UI from './ui';
+export * as System from './system';
+export * as AI from './ai';
+export * as API from './api';
+```
+
+### 3. Updated package.json
 
 Added export mappings for each namespace:
 
@@ -42,45 +54,73 @@ Added export mappings for each namespace:
 }
 ```
 
-### 3. Enhanced Documentation
+### 4. Enhanced Documentation
 
-- **README.md**: Added comprehensive section on import styles
-- **EXPORT_ORGANIZATION.md**: Detailed guide on the new organization
-- **examples/**: Code examples demonstrating both import styles
+- **README.md**: Updated with three supported import styles
+- **EXPORT_ORGANIZATION.md**: Detailed migration guide
+- **examples/**: Updated code examples
 
 ## Import Styles Supported
 
-### Style 1: Flat Imports (Backward Compatible)
+### Style 1: Namespace Imports from Root
 
 ```typescript
-import { Field, User, App, Agent } from '@objectstack/spec';
-```
+import { Data, UI, System, AI, API } from '@objectstack/spec';
 
-✅ All 36 existing imports in the codebase continue to work
+const field: Data.Field = { /* ... */ };
+const user: System.User = { /* ... */ };
+```
 
-### Style 2: Namespaced Imports (Recommended)
+### Style 2: Namespace Imports via Subpath
 
 ```typescript
 import * as Data from '@objectstack/spec/data';
 import * as UI from '@objectstack/spec/ui';
 import * as System from '@objectstack/spec/system';
-import * as AI from '@objectstack/spec/ai';
-import * as API from '@objectstack/spec/api';
 
 const field: Data.Field = { /* ... */ };
 const user: System.User = { /* ... */ };
 ```
 
+### Style 3: Direct Subpath Imports
+
+```typescript
+import { Field, FieldType } from '@objectstack/spec/data';
+import { User, Session } from '@objectstack/spec/system';
+
+const field: Field = { /* ... */ };
+const user: User = { /* ... */ };
+```
+
 ## Benefits
 
-1. **✅ Zero Breaking Changes**: All existing code continues to work without modification
-2. **✅ Prevents Future Conflicts**: Namespaces prevent naming collisions as API grows
+1. **✅ Eliminates All Naming Conflicts**: Namespace boundaries completely prevent collisions
+2. **✅ Clear Protocol Boundaries**: Immediately obvious which protocol a type belongs to
 3. **✅ Better Developer Experience**: 
    - Clear domain boundaries
    - Improved IDE autocomplete
    - Self-documenting code
 4. **✅ Scalable Architecture**: Easy to add new protocols without risk
-5. **✅ Flexible**: Developers can choose their preferred import style
+5. **✅ Tree-Shakeable**: Better optimization by modern bundlers
+
+## Breaking Change Notice
+
+**This is a breaking change.** Flat imports from the root are no longer supported.
+
+### Migration Required
+
+All imports like:
+```typescript
+import { Field, User, App } from '@objectstack/spec';
+```
+
+Must be changed to one of the three supported styles (see above).
+
+### Migration Steps
+
+1. Find all imports: `grep -r "from '@objectstack/spec'" src/`
+2. Replace with one of the three styles
+3. Test your application
 
 ## Verification Results
 
@@ -92,58 +132,35 @@ const user: System.User = { /* ... */ };
 - **Status**: ✅ Passed
 - **Vulnerabilities**: 0
 
-### Backward Compatibility
-- **Existing Imports Checked**: 36 files
-- **Breaking Changes**: 0
-- **Status**: ✅ 100% Compatible
-
 ### TypeScript Compilation
 - **Status**: ✅ No export errors
 - **Circular Dependencies**: None detected
 
 ## Files Changed
 
-- ✅ `packages/spec/src/index.ts` - Added documentation and reorganized exports
+- ✅ `packages/spec/src/index.ts` - Removed flat exports, added namespace exports
 - ✅ `packages/spec/src/data/index.ts` - New barrel export
 - ✅ `packages/spec/src/ui/index.ts` - New barrel export
 - ✅ `packages/spec/src/system/index.ts` - New barrel export
 - ✅ `packages/spec/src/ai/index.ts` - New barrel export
 - ✅ `packages/spec/src/api/index.ts` - New barrel export
 - ✅ `packages/spec/package.json` - Added export mappings
-- ✅ `packages/spec/README.md` - Enhanced documentation
-- ✅ `packages/spec/EXPORT_ORGANIZATION.md` - New comprehensive guide
-- ✅ `packages/spec/examples/namespaced-imports.example.ts` - Example code
+- ✅ `packages/spec/README.md` - Updated documentation
+- ✅ `packages/spec/EXPORT_ORGANIZATION.md` - Updated with migration guide
+- ✅ `packages/spec/examples/namespaced-imports.example.ts` - Updated examples
 - ✅ `packages/spec/examples/README.md` - Examples documentation
 
-## Migration Path
-
-### For Existing Code
-**No migration required!** All existing imports continue to work.
-
-### For New Code
-Recommended to use namespaced imports for better organization:
-
-```typescript
-// Before (still works)
-import { Field, User, App } from '@objectstack/spec';
-
-// After (recommended)
-import * as Data from '@objectstack/spec/data';
-import * as System from '@objectstack/spec/system';
-import * as UI from '@objectstack/spec/ui';
-```
-
 ## Future Considerations
 
 1. **Add Sub-namespaces**: Can create deeper organization (e.g., `@objectstack/spec/data/query`)
-2. **Deprecation Path**: If conflicts arise, can mark specific flat exports as deprecated
-3. **Convention Exports**: Can add convenience exports for commonly-used combinations
+2. **Convention Exports**: Can add convenience exports for commonly-used combinations
+3. **Further Categorization**: Organize large protocol domains into sub-categories
 
 ## Questions & Support
 
 See the following documentation for more details:
 - [README.md](README.md) - Quick start and usage examples
-- [EXPORT_ORGANIZATION.md](EXPORT_ORGANIZATION.md) - Comprehensive guide
+- [EXPORT_ORGANIZATION.md](EXPORT_ORGANIZATION.md) - Comprehensive migration guide
 - [examples/](examples/) - Working code examples
 
 ## Conclusion