feat(multi-tenant): complete Phase 2 - Turso Platform API integration and schema initialization

## Phase 2 Implementation Complete

This commit completes Phase 2 of the multi-tenant architecture implementation,
adding production-ready Turso Platform API integration and tenant schema initialization.

### New Features

**Turso Platform API Integration**
- Created `TursoPlatformClient` for programmatic database management
- Automated tenant database creation via Turso Platform API
- Tenant-specific auth token generation
- Support for database lifecycle (create, delete, get, list)
- Dual-mode operation: Production (real API) vs Development (mock mode)

**Global Control Plane**
- System object: `sys_tenant_database` - Tenant database registry
- System object: `sys_package_installation` - Package installation tracking
- Control plane driver integration for persistent tenant records
- UUID-based tenant database naming (immutable)

**Schema Initialization**
- Created `TenantSchemaInitializer` service
- Tenant database schema initialization with metadata tables
- Package schema installation per tenant
- Package schema uninstallation support

**Tenant Lifecycle Management**
- Suspend tenant databases
- Archive tenant databases (with optional platform deletion)
- Restore suspended tenants
- Lifecycle state management in control plane

### Files Added

- `packages/services/service-tenant/src/turso-platform-client.ts`
- `packages/services/service-tenant/src/tenant-schema-initializer.ts`
- `packages/services/service-tenant/src/objects/sys-tenant-database.object.ts`
- `packages/services/service-tenant/src/objects/sys-package-installation.object.ts`
- `packages/services/service-tenant/src/objects/index.ts`
- `packages/services/service-tenant/src/tenant-integration.test.ts`

### Files Updated

- `packages/services/service-tenant/src/tenant-provisioning.ts` - Enhanced from skeleton to full implementation
- `packages/services/service-tenant/src/tenant-plugin.ts` - Added system object registration
- `packages/services/service-tenant/src/index.ts` - Added new module exports
- `packages/services/service-tenant/README.md` - Added Phase 2 documentation and examples
- `ROADMAP.md` - Marked Phase 2 as complete, updated Phase 3 status

### Testing

- Integration tests for tenant provisioning (mock mode)
- UUID-based database naming validation
- Lifecycle operation tests (suspend, archive, restore)
- Control plane driver integration tests

### Next Steps (Phase 3)

Remaining items for production hardening:
- Multi-region tenant migration
- Tenant usage tracking and quota enforcement
- Cross-tenant data sharing policies
- Tenant-specific RBAC and permissions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Claude

ROADMAP.md

@@ -615,15 +615,15 @@ Objects now declare `namespace: 'sys'` and a short `name` (e.g., `name: 'user'`)
   - [x] TenantProvisioningService skeleton — Minimal prototype for tenant database provisioning (Turso Platform API integration pending)
   - [x] Multi-tenant router documentation updates — UUID naming conventions and examples
   - [x] Test coverage — TenantContextService identification and caching tests
-- [ ] **Phase 2: Turso Platform API Integration (v3.5)** — 🔴 Planned
-  - [ ] Turso Platform API client implementation
-  - [ ] Automated tenant database creation
-  - [ ] Tenant-specific auth token generation
-  - [ ] Global control plane database setup (sys_tenant_registry, sys_package_installation)
-  - [ ] Tenant database schema initialization
-  - [ ] Package installation per tenant
-- [ ] **Phase 3: Production Hardening (v4.0)** — 🔴 Planned
-  - [ ] Tenant lifecycle management (suspend, archive, restore)
+- [x] **Phase 2: Turso Platform API Integration (v3.5)** — ✅ Complete (2026-04-17)
+  - [x] Turso Platform API client implementation
+  - [x] Automated tenant database creation
+  - [x] Tenant-specific auth token generation
+  - [x] Global control plane database setup (sys_tenant_registry, sys_package_installation)
+  - [x] Tenant database schema initialization
+  - [x] Package installation per tenant
+- [ ] **Phase 3: Production Hardening (v4.0)** — 🟡 Partially Complete
+  - [x] Tenant lifecycle management (suspend, archive, restore)
   - [ ] Multi-region tenant migration
   - [ ] Tenant usage tracking and quota enforcement
   - [ ] Cross-tenant data sharing policies

packages/services/service-tenant/README.md

@@ -4,15 +4,29 @@ Multi-tenant context management and routing service for ObjectStack.
 
 ## Overview
 
-This service provides tenant identification and context resolution for multi-tenant ObjectStack deployments. It supports multiple identification strategies and manages tenant-specific database routing.
+This service provides comprehensive multi-tenant infrastructure for ObjectStack deployments, including:
+
+- Tenant identification and context resolution
+- Turso Platform API integration for automated database provisioning
+- Tenant database schema initialization
+- Global control plane management
+- Package installation per tenant
 
 ## Features
 
+### Phase 1 (Complete)
 - **Multiple Identification Sources**: Subdomain, custom domain, HTTP headers, JWT claims, session
 - **UUID-Based Tenant Naming**: Immutable tenant identifiers (not organization slugs)
 - **Tenant Context Caching**: Performance optimization for frequently accessed tenants
 - **Flexible Configuration**: Priority-based identification source ordering
 
+### Phase 2 (Complete)
+- **Turso Platform API Integration**: Automated database creation via Turso Platform API
+- **Tenant-Specific Auth Tokens**: Secure, database-specific authentication
+- **Global Control Plane**: System objects for tenant registry and package installations
+- **Schema Initialization**: Automated tenant database schema setup
+- **Package Management**: Per-tenant package installation and schema migration
+
 ## Installation
 
 ```bash
@@ -21,28 +35,108 @@ pnpm add @objectstack/service-tenant
 
 ## Usage
 
-### Basic Setup
+### Basic Setup (Tenant Routing)
 
 ```typescript
 import { createTenantPlugin } from '@objectstack/service-tenant';
 import { ObjectKernel } from '@objectstack/core';
 
 const kernel = new ObjectKernel();
 
-// Create tenant plugin
+// Create tenant plugin with routing configuration
 const tenantPlugin = createTenantPlugin({
-  enabled: true,
-  identificationSources: ['header', 'custom_domain', 'jwt_claim'],
-  tenantHeaderName: 'X-Tenant-ID',
-  customDomainMapping: {
-    'app.acme.com': '550e8400-e29b-41d4-a716-446655440000',
+  routing: {
+    enabled: true,
+    identificationSources: ['header', 'custom_domain', 'jwt_claim'],
+    tenantHeaderName: 'X-Tenant-ID',
+    customDomainMapping: {
+      'app.acme.com': '550e8400-e29b-41d4-a716-446655440000',
+    },
   },
+  registerSystemObjects: true, // Register control plane objects
 });
 
 await kernel.use(tenantPlugin);
 await kernel.bootstrap();
 ```
 
+### Tenant Provisioning
+
+```typescript
+import {
+  TenantProvisioningService,
+  TursoPlatformClient,
+} from '@objectstack/service-tenant';
+
+// Production mode: with Turso Platform API
+const provisioningService = new TenantProvisioningService({
+  turso: {
+    apiToken: process.env.TURSO_API_TOKEN!,
+    organization: 'my-org',
+  },
+  controlPlaneDriver: globalDriver, // Global control plane driver
+  defaultRegion: 'us-east-1',
+  databaseGroup: 'production-tenants',
+});
+
+// Provision a new tenant
+const result = await provisioningService.provisionTenant({
+  organizationId: 'org-123',
+  plan: 'pro',
+  region: 'us-west-2',
+  storageLimitMb: 5120,
+});
+
+console.log('Tenant provisioned:', result.tenant);
+// {
+//   id: '550e8400-e29b-41d4-a716-446655440000',
+//   databaseUrl: 'libsql://550e8400-e29b-41d4-a716-446655440000.turso.io',
+//   authToken: '<encrypted-token>',
+//   status: 'active',
+//   ...
+// }
+```
+
+### Development Mode (No Turso API)
+
+```typescript
+// Development/Mock mode: no Turso Platform API required
+const devService = new TenantProvisioningService({
+  defaultRegion: 'us-east-1',
+});
+
+const result = await devService.provisionTenant({
+  organizationId: 'org-123',
+  plan: 'free',
+});
+
+// Returns mock tenant with warnings
+console.log(result.warnings);
+// ['Running in mock mode - Turso Platform API credentials not configured']
+```
+
+### Schema Initialization
+
+```typescript
+import { TenantSchemaInitializer } from '@objectstack/service-tenant';
+
+const initializer = new TenantSchemaInitializer();
+
+// Initialize tenant database with base schema
+await initializer.initializeTenantSchema(
+  tenant.databaseUrl,
+  tenant.authToken,
+  baseObjects, // Optional: base objects to create
+);
+
+// Install package schema
+await initializer.installPackageSchema(
+  tenant.databaseUrl,
+  tenant.authToken,
+  packageObjects,
+);
+```
+
 ### Resolving Tenant Context
 
 ```typescript

packages/services/service-tenant/src/index.ts

@@ -3,3 +3,6 @@
 export * from './tenant-context';
 export * from './tenant-plugin';
 export * from './tenant-provisioning';
+export * from './turso-platform-client';
+export * from './tenant-schema-initializer';
+export * from './objects';

packages/services/service-tenant/src/objects/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export * from './sys-tenant-database.object';
+export * from './sys-package-installation.object';

packages/services/service-tenant/src/objects/sys-package-installation.object.ts

@@ -0,0 +1,111 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * sys_package_installation — Package Installation Registry
+ *
+ * Tracks which packages are installed in which tenant.
+ * Stored in the global control plane database.
+ *
+ * @namespace sys
+ */
+export const SysPackageInstallation = ObjectSchema.create({
+  namespace: 'sys',
+  name: 'package_installation',
+  label: 'Package Installation',
+  pluralLabel: 'Package Installations',
+  icon: 'package',
+  isSystem: true,
+  description: 'Per-tenant package installation registry',
+  titleFormat: '{package_id} @ {tenant_id}',
+  compactLayout: ['package_id', 'tenant_id', 'version', 'status'],
+
+  fields: {
+    id: Field.text({
+      label: 'Installation ID',
+      required: true,
+      readonly: true,
+      description: 'UUID-based installation identifier',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      defaultValue: 'NOW()',
+      readonly: true,
+    }),
+
+    updated_at: Field.datetime({
+      label: 'Updated At',
+      defaultValue: 'NOW()',
+      readonly: true,
+    }),
+
+    tenant_id: Field.text({
+      label: 'Tenant ID',
+      required: true,
+      description: 'Foreign key to tenant_database',
+    }),
+
+    package_id: Field.text({
+      label: 'Package ID',
+      required: true,
+      maxLength: 255,
+      description: 'Package identifier (e.g., @objectstack/crm)',
+    }),
+
+    version: Field.text({
+      label: 'Version',
+      required: true,
+      maxLength: 50,
+      description: 'Installed package version (semver)',
+    }),
+
+    status: Field.picklist({
+      label: 'Status',
+      required: true,
+      options: [
+        { value: 'installing', label: 'Installing' },
+        { value: 'active', label: 'Active' },
+        { value: 'disabled', label: 'Disabled' },
+        { value: 'uninstalling', label: 'Uninstalling' },
+        { value: 'failed', label: 'Failed' },
+      ],
+      defaultValue: 'installing',
+    }),
+
+    installed_at: Field.datetime({
+      label: 'Installed At',
+      required: true,
+      defaultValue: 'NOW()',
+    }),
+
+    installed_by: Field.text({
+      label: 'Installed By',
+      required: true,
+      description: 'User ID who installed the package',
+    }),
+
+    config: Field.textarea({
+      label: 'Configuration',
+      required: false,
+      description: 'JSON-serialized package-specific configuration',
+    }),
+  },
+
+  indexes: [
+    { fields: ['tenant_id', 'package_id'], unique: true },
+    { fields: ['tenant_id'] },
+    { fields: ['package_id'] },
+    { fields: ['status'] },
+  },
+
+  enable: {
+    trackHistory: true,
+    searchable: true,
+    apiEnabled: true,
+    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
+    trash: true,
+    mru: true,
+  },
+});