feat: extend tenant runtime protocol — quotas, usage tracking, contract tests

[Copilot]

Completes the multi-tenant runtime protocol layer by adding missing schema fields and contract test coverage for the cloud provisioning architecture.

Schema extensions

• TenantRuntimeContextSchema — add tenantQuotas: TenantQuotaSchema.optional() for per-request quota access downstream; make tenantRegion optional per spec
• TenantUsageSchema — align field names with issue spec: currentUsers, currentStorageBytes, currentObjectCount, currentRecordCount, deploymentsToday, apiRequestsThisMinute
• DeployBundleSchema — add seedData[] for seed data records in deployment bundles
• AppManifestSchema — add seedData[] for seed data records in app manifests

// Per-request tenant context now carries quotas (tenantRegion is optional)
const ctx = TenantRuntimeContextSchema.parse({
  ...kernelContext,
  tenantId: 'tenant_abc',
  tenantPlan: 'pro',
  tenantDbUrl: 'libsql://tenant-abc.turso.io',
  tenantQuotas: { maxUsers: 500, maxObjects: 100 },
});

Contract tests (4 new files)

• tenant-router.test.ts — ITenantRouter session resolution, client caching, cache invalidation
• deploy-pipeline-service.test.ts — IDeployPipelineService validate → plan → execute → rollback
• provisioning-service.test.ts — IProvisioningService lifecycle (provision/suspend/resume/destroy/migrate)
• app-lifecycle-service.test.ts — IAppLifecycleService compatibility check, install, upgrade, uninstall

ROADMAP

• Updated Phase 6.2 Multi-Tenancy checklist to reflect completed protocol work

Test results: 229 files, 6383 tests passing (was 225/6363).

Note: Pre-existing TS2300: Duplicate identifier 'IncidentNotificationMatrix' in incident-response.zod.ts is unrelated.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Runtime] 内核多租户 Runtime 协议升级 — Tenant Context + Router + Deploy Pipeline 合同</issue_title>
<issue_description>

Summary

升级 @objectstack/spec 内核协议层，为 Cloud 多租户 "注册即开通" 架构提供完整的类型定义和服务合同。

背景

spec v3.0 已完成 TenantSchema、TenantIsolationLevel、KernelContextSchema 等基础协议。现在需要扩展以支持：

• 请求级租户上下文注入
• 租户路由合同（session → tenantId → DB connection）
• 元数据驱动部署流水线合同
• 配额与用量追踪协议
• 应用安装生命周期合同

开发任务

Part A: Tenant Runtime Context 扩展

• A1. TenantRuntimeContextSchema — 扩展 packages/spec/src/kernel/context.zod.ts

  // 在 KernelContextSchema 基础上扩展
  TenantRuntimeContextSchema = KernelContextSchema.extend({
    tenantId: z.string().describe('Current tenant ID from session'),
    tenantPlan: z.enum(['free', 'pro', 'enterprise']).describe('Tenant subscription plan'),
    tenantRegion: z.string().optional().describe('Primary database region'),
    tenantDbUrl: z.string().describe('Turso DB connection URL for current tenant'),
    tenantQuotas: TenantQuotaSchema.optional(),
  });

  • 更新 context.test.ts 增加新字段测试
  • 确保向后兼容（新字段可选或有默认值）

• A2. TenantUsageSchema — 新增到 packages/spec/src/system/tenant.zod.ts

  TenantUsageSchema = z.object({
    currentUsers: z.number().int(),
    currentStorageBytes: z.number().int(),
    currentObjectCount: z.number().int(),
    currentRecordCount: z.number().int(),
    deploymentsToday: z.number().int(),
    apiRequestsThisMinute: z.number().int(),
  });

• A3. 扩展 TenantQuotaSchema — 增加以下字段

  • maxObjects: z.number().int().optional() — 最大对象数
  • maxRecordsPerObject: z.number().int().optional() — 每对象最大记录数
  • maxDeploymentsPerDay: z.number().int().optional() — 每日最大部署次数
  • 更新现有测试

Part B: 服务合同定义

• B1. ITenantRouter 合同 — packages/spec/src/contracts/tenant-router.ts (NEW)

  export interface ITenantRouter {
    resolveTenant(session: AuthSession): Promise<TenantRuntimeContext>;
    getTenantDriver(tenantId: string): Promise<Driver>;
    invalidateCache(tenantId: string): void;
  }

  • 注意：Driver 类型引用 @objectql/types 中已有的 Driver interface

• B2. IDeployPipelineService 合同 — packages/spec/src/contracts/deploy-pipeline-service.ts (NEW)

  export interface IDeployPipelineService {
    validateBundle(bundle: DeployBundle): DeployValidationResult;
    planDeployment(tenantId: string, bundle: DeployBundle): Promise<MigrationPlan>;
    executeDeployment(tenantId: string, plan: MigrationPlan): Promise<DeployResult>;
    rollbackDeployment(tenantId: string, deploymentId: string): Promise<void>;
  }

• B3. IProvisioningService 合同 — packages/spec/src/contracts/provisioning-service.ts (NEW)

  export interface IProvisioningService {
    provisionTenant(request: TenantProvisioningRequest): Promise<TenantProvisioningResult>;
    suspendTenant(tenantId: string): Promise<void>;
    resumeTenant(tenantId: string): Promise<void>;
    destroyTenant(tenantId: string): Promise<void>;
    getTenantStatus(tenantId: string): Promise<TenantProvisioningStatus>;
  }

• B4. IAppLifecycleService 合同 — packages/spec/src/contracts/app-lifecycle-service.ts (NEW)

  export interface IAppLifecycleService {
    checkCompatibility(tenantId: string, manifest: AppManifest): Promise<CompatibilityResult>;
    installApp(tenantId: string, manifest: AppManifest): Promise<AppInstallResult>;
    upgradeApp(tenantId: string, appId: string, newManifest: AppManifest): Promise<AppInstallResult>;
    uninstallApp(tenantId: string, appId: string): Promise<void>;
  }

Part C: 数据 Schema 定义

• C1. TenantProvisioningSchema — packages/spec/src/system/provisioning.zod.ts (NEW)

  • TenantProvisioningRequestSchema — 输入：orgId, plan, region
  • TenantProvisioningResultSchema — 输出：tenantId, connectionUrl, status
  • TenantProvisioningStatusEnum — 'provisioning' | 'active' | 'suspended' | 'failed' | 'destroying'
  • ProvisioningStepSchema — 单步状态追踪

• C2. DeployBundleSchema — packages/spec/src/system/deploy-bundle.zod.ts (NEW)

  • DeployBundleSchema — objects[], views[], flows[], permissions[], seedData[]
  • DeployManifestSchema — version, checksum, metadata
  • DeployDiffSchema — added/modified/removed
  • MigrationPlanSchema — 有序 DDL 列表
  • DeployStatusEnum — 'validating' | 'diffing' | 'migrating' | 'registering' | 'ready' | 'failed'

• C3. AppManifestSchema — packages/spec/src/system/app-install.zod.ts (NEW)

  • AppManifestSchema — name, version, objects[], views[], flows[], seedData[]
  • AppInstallResultSchema — installed objects, created tables, seeded records
  • AppCompatibilityCheckSchema — kernel version check, conflict detection

• C4. 扩展 TenantSchema — 修改 packages/spec/src/system/tenant.zod.ts

  • 新增 `databaseProvider: z.enum(['turso', 'postgres', 'mem...

• Fixes [Runtime] 内核多租户 Runtime 协议升级 — Tenant Context + Router + Deploy Pipeline 合同 #797

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Error		Feb 24, 2026 5:35am
spec	Error		Feb 24, 2026 5:35am

[hotlong]

@copilot 仔细评估是否已完成所有开发需求

[Copilot]

@copilot 仔细评估是否已完成所有开发需求

经过仔细评估，发现了以下未对齐项并已在 a769e38 中修复：

1. A1 tenantRegion — issue 要求 .optional()，之前实现为 .min(1) (required)。已改为 optional。
2. A2 TenantUsageSchema 字段名 — issue 指定 currentStorageBytes/currentObjectCount/currentRecordCount，之前为 storageBytes/objectCount/totalRecords。已重命名对齐。
3. C2 DeployBundleSchema — 缺少 seedData[]。已添加。
4. C3 AppManifestSchema — 缺少 seedData[]。已添加。

所有其他需求 (A1 tenantQuotas, A2 currentUsers/apiRequestsThisMinute, A3 TenantQuotaSchema, B1-B4 contracts + tests, C1-C4 schemas, D1-D2 exports, D4 ROADMAP) 均已完成。229 test files / 6383 tests 全部通过。

[Copilot]

Pull request overview

This PR completes the multi-tenant runtime protocol layer by adding schema extensions for quota/usage tracking and comprehensive contract test coverage for the cloud provisioning architecture. The changes align with the "Protocol First" design principle, providing runtime validation schemas and service interface definitions.

Changes:

• Extended TenantRuntimeContextSchema to include optional tenantQuotas field and make tenantRegion optional
• Renamed TenantUsageSchema fields to follow current* prefix convention (currentUsers, currentObjectCount, currentRecordCount, currentStorageBytes, etc.)
• Added seedData arrays to both DeployBundleSchema and AppManifestSchema for deployment and app installation workflows
• Added 4 contract test files covering tenant routing, provisioning lifecycle, deploy pipeline, and app installation

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/spec/src/system/tenant.zod.ts	Renamed TenantUsageSchema fields to current* prefix, added currentUsers and apiRequestsThisMinute fields
packages/spec/src/system/tenant.test.ts	Updated tests to match new TenantUsageSchema field names
packages/spec/src/kernel/context.zod.ts	Added tenantQuotas field, made tenantRegion optional in TenantRuntimeContextSchema
packages/spec/src/kernel/context.test.ts	Added tests for tenantQuotas field, removed tenantRegion from required fields tests
packages/spec/src/system/deploy-bundle.zod.ts	Added seedData field to DeployBundleSchema
packages/spec/src/system/deploy-bundle.test.ts	Added test coverage for seedData field
packages/spec/src/system/app-install.zod.ts	Added seedData field to AppManifestSchema
packages/spec/src/system/app-install.test.ts	Added test coverage for seedData field
packages/spec/src/contracts/tenant-router.test.ts	New contract tests for ITenantRouter (session resolution, client caching, cache invalidation)
packages/spec/src/contracts/provisioning-service.test.ts	New contract tests for IProvisioningService (provision, suspend, resume, destroy, migrate)
packages/spec/src/contracts/deploy-pipeline-service.test.ts	New contract tests for IDeployPipelineService (validate, plan, execute, rollback)
packages/spec/src/contracts/app-lifecycle-service.test.ts	New contract tests for IAppLifecycleService (compatibility check, install, upgrade, uninstall)
ROADMAP.md	Updated Phase 6.2 Multi-Tenancy checklist to mark completed protocol work