⚙️ [Runtime] Turso Driver + Tenant Router + Metadata Deploy Pipeline Implementation


### Summary

Implement the runtime packages and Cloud integration code that bring the multi-tenant provisioning protocol (Issue #XX) to life. This includes:

1. `@objectstack/driver-turso` — Core Turso/libSQL data driver  
2. Tenant DB Router — Request-level tenant resolution + DB routing  
3. Metadata Deploy Worker — Schema diff + DDL sync pipeline  
4. Cloud provisioning actions — Register → Auto-provision Turso DB  
5. App Marketplace install runtime — Inject metadata + sync schema  

### Architecture Overview

```
Shared Compute (Vercel Serverless)     Isolated Data (Turso DB-per-Tenant)
┌─────────────────────────────┐       ┌─────────────────────────────┐
│  HTTP Request                │       │                             │
│  ↓                           │       │  ┌───────┐  ┌───────┐     │
│  Auth (Better-Auth, shared) │       │  │Turso A│  │Turso B│     │
│  ↓                           │       │  │tenant_a│  │tenant_b│    │
│  Tenant Resolver (session→DB)│──────▶│  └───────┘  └───────┘     │
│  ↓                           │       │  ┌───────┐  ┌───────┐     │
│  ObjectQL Engine (shared)    │       │  │Turso C│  │Turso D│     │
│  ↓                           │       │  │tenant_c│  │tenant_d│    │
│  REST API (shared)           │       │  └───────┘  └───────┘     │
└─────────────────────────────┘       └─────────────────────────────┘
```

### Depends On

- Protocol Issue: `[Protocol] Cloud-Native Multi-Tenant Provisioning Protocol`
- Existing: `@objectstack/spec` tenant.zod.ts, turso.zod.ts, driver-turso.md design doc

---

### Task Breakdown

#### Part 1: `@objectstack/driver-turso` (spec repo — `packages/plugins/driver-turso/`)

> Estimated: 5 weeks | Priority: P0
> Design doc: [docs/design/driver-turso.md](https://github.com/objectstack-ai/spec/blob/main/docs/design/driver-turso.md)

- [ ] **1.1 TursoDriver — `IDataDriver` implementation** (~2 weeks)
  - `packages/plugins/driver-turso/src/turso-driver.ts`
  - Implement full `IDataDriver` contract using `@libsql/client`
  - Methods: `connect()`, `disconnect()`, `checkHealth()`, `find()`, `findOne()`, `create()`, `update()`, `upsert()`, `delete()`, `count()`, `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`, `updateMany()`, `deleteMany()`
  - Transaction support: `beginTransaction()`, `commit()`, `rollback()` via `client.transaction()`
  - Connection modes: remote (`libsql://`), local (`file:`), in-memory (`:memory:`)
  - Validate config with `TursoConfigSchema` from spec

- [ ] **1.2 QueryAST → SQLite SQL Compiler** (~1 week)
  - `packages/plugins/driver-turso/src/query-compiler.ts`
  - Translate ObjectStack `QueryAST` → SQLite-compatible SQL
  - Support: WHERE, ORDER BY, LIMIT/OFFSET, aggregations, COUNT, JOINs
  - Handle SQLite-specific quirks (no BOOLEAN type, INTEGER for booleans)
  - Parameterized queries for SQL injection prevention

- [ ] **1.3 Type Mapper** (~3 days)
  - `packages/plugins/driver-turso/src/type-mapper.ts`
  - ObjectStack field types → SQLite storage types
  - `text→TEXT`, `number→REAL`, `boolean→INTEGER`, `date→TEXT`, `json→TEXT`, `uuid→TEXT`
  - Result mapper: SQLite rows → ObjectStack record format

- [ ] **1.4 TursoSchemaDriver — `ISchemaDriver` implementation** (~1 week)
  - `packages/plugins/driver-turso/src/turso-schema-driver.ts`
  - `createCollection()` → `CREATE TABLE IF NOT EXISTS`
  - `addColumn()` → `ALTER TABLE ADD COLUMN`
  - `modifyColumn()` → Table rebuild strategy (SQLite limitation)
  - `dropColumn()` → `ALTER TABLE DROP COLUMN` (SQLite 3.35+)
  - `createIndex()` / `dropIndex()`
  - Schema introspection via `PRAGMA table_info()`

- [ ] **1.5 TursoDriverPlugin — ObjectStack kernel plugin** (~2 days)
  - `packages/plugins/driver-turso/src/turso-driver-plugin.ts`
  - Wrap TursoDriver as `RuntimePlugin`
  - Register with kernel: `kernel.use(new TursoDriverPlugin(config))`
  - Handle lifecycle: `install()` → connect, `onStart()` → health check

- [ ] **1.6 Multi-Tenant Router** (~1 week)
  - `packages/plugins/driver-turso/src/multi-tenant-router.ts`
  - `createTursoMultiTenantDriver()` factory function
  - `urlTemplate` string interpolation: `libsql://{tenant}-org.turso.io`
  - Per-tenant client cache with TTL (process-level, Serverless-safe)
  - `resolveTenant()` → returns tenant-scoped `IDataDriver`
  - Turso Platform API integration: `createDatabase()`, `deleteDatabase()`, `createToken()`

- [ ] **1.7 Test Suite** (~1 week)
  - Unit tests for query compiler, type mapper, result mapper
  - Integration tests using `:memory:` mode (no external Turso needed)
  - Multi-tenant router tests with mock Turso API
  - Target: ≥90% coverage

- [ ] **1.8 Package Setup**
  - `package.json` with `@libsql/client` dependency
  - `tsup.config.ts` for ESM/CJS dual build
  - `vitest.config.ts`
  - Export from `packages/plugins/driver-turso/src/index.ts`

#### Part 2: Schema Diff Engine (spec repo)

> Estimated: 1 week | Priority: P0

- [ ] **2.1 Schema Introspector** — `packages/plugins/driver-turso/src/schema-introspector.ts`
  - `introspectSchema(client)` → reads `sqlite_master` + `PRAGMA table_info`
  - Returns `CurrentSchema` structure (tables, columns, indexes)
  - Exclude system tables (`sys_*`, `sqlite_*`, `_litestream_*`)

- [ ] **2.2 Diff Generator** — `packages/plugins/driver-turso/src/schema-differ.ts`
  - `generateDiff(current, desired)` → `DeployDiff`
  - Detect: new tables, new columns, removed columns, type changes
  - Handle SQLite ALTER TABLE limitations (no MODIFY COLUMN)
  - Produce ordered `MigrationPlan` (DDL SQL statements)

- [ ] **2.3 Migration Executor** — `packages/plugins/driver-turso/src/migration-executor.ts`
  - `executeMigrations(client, plan)` → runs DDL in batch/transaction
  - Logging each step for deploy logs
  - Error handling with partial rollback info

#### Part 3: Metadata Deploy Worker (Cloud repo integration)

> Estimated: 1-2 weeks | Priority: P0
> NOTE: This code lives in `objectstack-ai/cloud` but depends on spec contracts

- [ ] **3.1 Deploy Worker** — `apps/cloud/lib/pipeline/deploy-worker.ts`
  - `executeDeployment(ctx: DeployContext)` — main orchestrator
  - Steps: validate → connect tenant DB → diff schema → apply DDL → register metadata → mark ready
  - Runs inside Vercel Serverless Function (no external compute needed)
  - Updates deployment status in control plane DB (Neon)

- [ ] **3.2 Bundle Parser** — `apps/cloud/lib/pipeline/bundle-parser.ts`
  - Parse uploaded `.tar.gz` bundle → extract `objectstack.json` + schema files
  - Validate against `DeployBundleSchema` (Zod)
  - Return structured `DeployBundle` object

- [ ] **3.3 Connect Push API to Deploy Worker** — Enhance existing routes
  - `apps/cloud/app/api/v1/projects/[slug]/push/confirm/route.ts` → trigger `executeDeployment()`
  - `apps/cloud/app/api/v1/webhooks/github/route.ts` → trigger deploy on push
  - Use `waitUntil()` pattern for async execution without blocking response

#### Part 4: Tenant Provisioning Integration (Cloud repo)

> Estimated: 1-2 weeks | Priority: P0

- [ ] **4.1 Turso Database Provisioner** — `apps/cloud/lib/provisioning/turso-provisioner.ts`
  - Call Turso Platform API to create database in group
  - Generate per-database auth token
  - Return `{ connectionUrl, authToken, databaseName }`
  - Handle errors, cleanup on failure

- [ ] **4.2 ObjectOS Bootstrap** — `apps/cloud/lib/provisioning/objectos-bootstrap.ts`
  - Connect to newly created Turso DB
  - Create system tables: `sys_metadata`, `sys_user`, `sys_session`, `sys_audit`
  - Register base system metadata (system objects)
  - Initialize better-auth tables (using Turso adapter)

- [ ] **4.3 Provisioning Server Action** — `apps/cloud/lib/actions/tenant-provisioning-action.ts`
  - Orchestrate: create tenant record → provision Turso DB → bootstrap ObjectOS → activate
  - Status tracking with progress steps
  - Store encrypted connection info in control plane DB

- [ ] **4.4 Registration Flow Integration** — Modify `apps/cloud/app/create-org/page.tsx`
  - After org creation → auto-trigger tenant provisioning
  - Show provisioning progress UI (creating DB → initializing → ready)
  - Redirect to project dashboard on completion

- [ ] **4.5 Tenant DB Schema (Control Plane)** — `apps/cloud/lib/db/schema.ts`
  - Add `tenant` table: id, organizationId, status, plan, databaseProvider, connectionUrl (encrypted), authToken (encrypted), region, createdAt, updatedAt
  - Drizzle migration for new table
  - Add to `drizzle.config.ts` tablesFilter

#### Part 5: App Marketplace Install Runtime (Cloud repo)

> Estimated: 1-2 weeks | Priority: P1

- [ ] **5.1 App Install Action** — `apps/cloud/lib/actions/marketplace-install-action.ts`
  - Download app manifest from marketplace registry
  - Connect to tenant's Turso DB
  - Inject metadata (objects, views, flows) via `sys_metadata`
  - Execute schema sync (create tables for new objects)
  - Import seed data (if manifest includes datasets)
  - Update `installed_package` record in control plane

- [ ] **5.2 App Uninstall Action** — `apps/cloud/lib/actions/marketplace-uninstall-action.ts`
  - Remove metadata entries
  - Optionally drop tables (with confirmation)
  - Clean up control plane records

#### Part 6: R2 Bundle Storage Integration (Cloud repo)

> Estimated: 3-5 days | Priority: P1

- [ ] **6.1 R2 Client** — `apps/cloud/lib/storage/r2-client.ts`
  - Cloudflare R2 S3-compatible client
  - `generatePresignedUploadUrl(key)` — for CLI push
  - `downloadBundle(key)` — for deploy worker
  - Key pattern: `bundles/{projectId}/{deploymentId}/bundle.tar.gz`

- [ ] **6.2 Connect Push API to R2**
  - Replace placeholder upload URL in `push/route.ts` with real R2 presigned URL
  - Add checksum verification on confirm

---

### Estimated Timeline

| Phase | Content | Duration | Priority |
|:---|:---|:---:|:---:|
| Part 1.1-1.5 | Turso Core Driver | 4 weeks | P0 |
| Part 1.6 | Multi-Tenant Router | 1 week | P0 |
| Part 2 | Schema Diff Engine | 1 week | P0 |
| Part 3 | Deploy Worker | 1-2 weeks | P0 |
| Part 4 | Tenant Provisioning | 1-2 weeks | P0 |
| Part 5 | App Install Runtime | 1-2 weeks | P1 |
| Part 6 | R2 Storage | 3-5 days | P1 |
| **Total** | | **~10-12 weeks** | |

### MVP Fast Track (4 weeks)

To get the shortest path to "注册即开通":

1. **Week 1-2**: Turso Driver (core CRUD + `:memory:` mode for tests)
2. **Week 2-3**: Tenant Provisioner + ObjectOS Bootstrap (Turso Platform API)
3. **Week 3-4**: Deploy Worker (schema diff + DDL sync) + Registration Flow
4. **Week 4**: R2 storage + Push API wiring

Defer to later: App Marketplace Install (Part 5), Multi-Tenant Router caching (Part 1.6 advanced), Uninstall (Part 5.2)

### Acceptance Criteria

- [ ] `os push` from CLI → bundle uploaded to R2 → schema synced to tenant Turso DB → deployment `ready` in ≤5 seconds
- [ ] New user registration → org created → Turso DB provisioned → ObjectOS bootstrapped → dashboard accessible in ≤10 seconds
- [ ] GitHub push webhook → auto-deploy with same pipeline
- [ ] App install from marketplace → metadata injected → tables created → app functional
- [ ] `pnpm test` passes in both `spec` and `cloud` repos
- [ ] Zero additional infrastructure cost beyond existing Vercel + Turso Free Tier

### Cost Target

| Component | Provider | Monthly Cost |
|:---|:---|:---:|
| Compute | Vercel Serverless (existing) | $0 |
| Tenant Databases (1000) | Turso Free/Starter | $0-$29 |
| Control Plane DB | Neon (existing) | $0-$19 |
| Bundle Storage | Cloudflare R2 | $0 |
| **Total** | | **$0-$48** |

### Labels

`runtime`, `driver-turso`, `multi-tenant`, `provisioning`, `deployment`, `P0`

### References

- Protocol Issue: `[Protocol] Cloud-Native Multi-Tenant Provisioning Protocol`
- [Turso Driver Design Doc](https://github.com/objectstack-ai/spec/blob/main/docs/design/driver-turso.md)  
- [Existing turso.zod.ts](https://github.com/objectstack-ai/spec/blob/main/packages/spec/src/data/driver/turso.zod.ts)
- [Cloud Push API](https://github.com/objectstack-ai/cloud/blob/main/apps/cloud/app/api/v1/projects/%5Bslug%5D/push/route.ts)
- [Cloud GitHub Webhook](https://github.com/objectstack-ai/cloud/blob/main/apps/cloud/app/api/v1/webhooks/github/route.ts)
- [Cloud Deployment Actions](https://github.com/objectstack-ai/cloud/blob/main/apps/cloud/lib/actions/deployment-actions.ts)
- ROADMAP.md Phase 6

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

⚙️ [Runtime] Turso Driver + Tenant Router + Metadata Deploy Pipeline Implementation #796

Summary

Architecture Overview

Depends On

Task Breakdown

Part 1: `@objectstack/driver-turso` (spec repo — `packages/plugins/driver-turso/`)

Part 2: Schema Diff Engine (spec repo)

Part 3: Metadata Deploy Worker (Cloud repo integration)

Part 4: Tenant Provisioning Integration (Cloud repo)

Part 5: App Marketplace Install Runtime (Cloud repo)

Part 6: R2 Bundle Storage Integration (Cloud repo)

Estimated Timeline

MVP Fast Track (4 weeks)

Acceptance Criteria

Cost Target

Labels

References

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Phase	Content	Duration	Priority
Part 1.1-1.5	Turso Core Driver	4 weeks	P0
Part 1.6	Multi-Tenant Router	1 week	P0
Part 2	Schema Diff Engine	1 week	P0
Part 3	Deploy Worker	1-2 weeks	P0
Part 4	Tenant Provisioning	1-2 weeks	P0
Part 5	App Install Runtime	1-2 weeks	P1
Part 6	R2 Storage	3-5 days	P1
Total		~10-12 weeks

Component	Provider	Monthly Cost
Compute	Vercel Serverless (existing)	$0
Tenant Databases (1000)	Turso Free/Starter	$0-$29
Control Plane DB	Neon (existing)	$0-$19
Bundle Storage	Cloudflare R2	$0
Total		$0-$48

⚙️ [Runtime] Turso Driver + Tenant Router + Metadata Deploy Pipeline Implementation #796

Description

Summary

Architecture Overview

Depends On

Task Breakdown

Part 1: @objectstack/driver-turso (spec repo — packages/plugins/driver-turso/)

Part 2: Schema Diff Engine (spec repo)

Part 3: Metadata Deploy Worker (Cloud repo integration)

Part 4: Tenant Provisioning Integration (Cloud repo)

Part 5: App Marketplace Install Runtime (Cloud repo)

Part 6: R2 Bundle Storage Integration (Cloud repo)

Estimated Timeline

MVP Fast Track (4 weeks)

Acceptance Criteria

Cost Target

Labels

References

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Part 1: `@objectstack/driver-turso` (spec repo — `packages/plugins/driver-turso/`)