Merge pull request #755 from objectstack-ai/copilot/complete-roadmap-development

Author: hotlong

ROADMAP.md

@@ -98,8 +98,8 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 | `.describe()` Annotations | 7,111+ |
 | Service Contracts | 25 |
 | Contracts Implemented | 13 (52%) |
-| Test Files | 199 |
-| Tests Passing | 5,805 / 5,805 |
+| Test Files | 208 |
+| Tests Passing | 5,921 / 5,921 |
 | `@deprecated` Items | 3 |
 | Protocol Domains | 15 (Data, UI, AI, API, Automation, Cloud, Contracts, Identity, Integration, Kernel, QA, Security, Shared, Studio, System) |
 
@@ -127,10 +127,10 @@ Support record comments, @mention, activity feed, and changelog for the ObjectUI
 | Real-time collaboration (OT/CRDT) | ✅ | `system/collaboration.zod.ts` |
 | `IFeedService` contract | ✅ | `contracts/feed-service.ts` |
 | `service-feed` in-memory implementation | ✅ | `@objectstack/service-feed` (40 tests) |
-| Pin/star comments | 🔴 | Not yet specified |
+| Pin/star comments | ✅ | `data/feed.zod.ts` → `pinned`/`starred`, `api/feed-api.zod.ts` → Pin/Star endpoints |
 | Comment notification integration with `INotificationService` | 🔴 | `service-notification` not implemented |
-| Activity feed search/filter endpoint | 🔴 | Not yet specified |
-| Changelog (field-level audit trail) endpoint | 🟡 | `FieldChangeSchema` exists; dedicated API pending |
+| Activity feed search/filter endpoint | ✅ | `api/feed-api.zod.ts` → `SearchFeedRequestSchema` |
+| Changelog (field-level audit trail) endpoint | ✅ | `api/feed-api.zod.ts` → `GetChangelogRequestSchema`, `ChangelogEntrySchema` |
 
 ### 2. Automation Persistence & Scheduling Specs
 
@@ -146,11 +146,11 @@ Multi-stage triggers, action pipelines, execution logs, and cron scheduling stan
 | Retry policies with exponential backoff | ✅ | `automation/webhook.zod.ts` |
 | `IAutomationService` contract | ✅ | `contracts/automation-service.ts` |
 | `service-automation` DAG engine (MVP) | ✅ | `@objectstack/service-automation` (27 tests) |
-| Execution log/history storage protocol | 🔴 | No dedicated `ExecutionLogSchema`; only string arrays in results |
-| Execution error tracking & diagnostics | 🔴 | Not yet specified |
-| Conflict resolution for concurrent executions | 🔴 | Not yet specified |
-| Checkpointing/resume for interrupted flows | 🔴 | Not yet specified |
-| Scheduled execution persistence (next-run, pause/resume) | 🔴 | Limited to cron strings; no runtime state tracking |
+| Execution log/history storage protocol | ✅ | `automation/execution.zod.ts` → `ExecutionLogSchema`, `ExecutionStepLogSchema` |
+| Execution error tracking & diagnostics | ✅ | `automation/execution.zod.ts` → `ExecutionErrorSchema`, `ExecutionErrorSeverity` |
+| Conflict resolution for concurrent executions | ✅ | `automation/execution.zod.ts` → `ConcurrencyPolicySchema` |
+| Checkpointing/resume for interrupted flows | ✅ | `automation/execution.zod.ts` → `CheckpointSchema` |
+| Scheduled execution persistence (next-run, pause/resume) | ✅ | `automation/execution.zod.ts` → `ScheduleStateSchema` |
 
 ### 3. File Direct Upload & Resumable Upload Protocol
 
@@ -165,10 +165,10 @@ CloudFile / PresignedUrl schema supporting S3/Azure/GCS direct-to-cloud file upl
 | Bucket encryption & CORS | ✅ | `system/object-storage.zod.ts` |
 | `IStorageService` contract | ✅ | `contracts/storage-service.ts` |
 | `service-storage` local FS + S3 skeleton | ✅ | `@objectstack/service-storage` (8 tests) |
-| Chunked upload with resume token | 🔴 | No resume token for interrupted uploads |
-| Upload progress tracking protocol | 🔴 | Not yet specified |
-| Mobile / file picker / browser fallback | 🔴 | Not yet specified |
-| File type whitelist/blacklist validation | 🔴 | Not yet specified |
+| Chunked upload with resume token | ✅ | `api/storage.zod.ts` → `InitiateChunkedUploadRequestSchema`, `resumeToken` |
+| Upload progress tracking protocol | ✅ | `api/storage.zod.ts` → `UploadProgressSchema` |
+| Mobile / file picker / browser fallback | 🔴 | Not yet specified (runtime concern) |
+| File type whitelist/blacklist validation | ✅ | `api/storage.zod.ts` → `FileTypeValidationSchema` |
 
 ### 4. Streaming Data Export & Batch Operation Optimization
 
@@ -182,11 +182,11 @@ Cursor/Pagination protocol for large-scale data import/export with template-base
 | Import mapping configuration | ✅ | `data/mapping.zod.ts` |
 | Dataset import mode | ✅ | `data/dataset.zod.ts` |
 | Full query & filter language | ✅ | `data/filter.zod.ts` |
-| Streaming/chunked export endpoint (CSV/JSON/Excel) | 🔴 | Not yet specified |
-| Import validation & deduplication | 🔴 | Not yet specified |
-| Template-based field mapping for import/export | 🔴 | Mapping schema exists; no template registry |
-| Scheduled export jobs & status query | 🔴 | Not yet specified |
-| Export job progress & download URL | 🔴 | Not yet specified |
+| Streaming/chunked export endpoint (CSV/JSON/Excel) | ✅ | `api/export.zod.ts` → `CreateExportJobRequestSchema`, `ExportFormat` |
+| Import validation & deduplication | ✅ | `api/export.zod.ts` → `ImportValidationConfigSchema`, `DeduplicationStrategy` |
+| Template-based field mapping for import/export | ✅ | `api/export.zod.ts` → `ExportImportTemplateSchema`, `FieldMappingEntrySchema` |
+| Scheduled export jobs & status query | ✅ | `api/export.zod.ts` → `ScheduledExportSchema` |
+| Export job progress & download URL | ✅ | `api/export.zod.ts` → `ExportJobProgressSchema` |
 
 ### 5. API Capability Declaration & Service Discovery
 
@@ -198,10 +198,10 @@ Strengthen discovery capabilities for frontend intelligent adaptation.
 | Dynamic API route mapping | ✅ | `api/discovery.zod.ts` → `ApiRoutesSchema` |
 | Localization info (locale, timezone) | ✅ | `api/discovery.zod.ts` |
 | Custom metadata extensions | ✅ | `api/discovery.zod.ts` |
-| Capabilities declaration (comments, automation, search, cron, files, analytics) | 🔴 | No hierarchical capability descriptors |
-| Per-service version info | 🔴 | Not yet specified |
-| Rate limit & quota disclosure | 🔴 | Not yet specified |
-| OpenAPI/GraphQL schema discovery endpoint | 🔴 | Not yet specified |
+| Capabilities declaration (comments, automation, search, cron, files, analytics) | ✅ | `api/discovery.zod.ts` → `capabilities` with hierarchical descriptors |
+| Per-service version info | ✅ | `api/discovery.zod.ts` → `ServiceInfoSchema.version` |
+| Rate limit & quota disclosure | ✅ | `api/discovery.zod.ts` → `ServiceInfoSchema.rateLimit` |
+| OpenAPI/GraphQL schema discovery endpoint | ✅ | `api/discovery.zod.ts` → `DiscoverySchema.schemaDiscovery` |
 
 > **Recommendation:** Sync this roadmap with ObjectUI / client / runner / console and prioritize v3.1 protocol to fill core platform gaps.
 

packages/spec/src/api/discovery.test.ts

@@ -536,3 +536,150 @@ describe('DiscoverySchema with services', () => {
     expect(discovery.services['ai'].enabled).toBe(false);
   });
 });
+
+// ==========================================
+// ServiceInfoSchema — version & rateLimit
+// ==========================================
+
+describe('ServiceInfoSchema (version field)', () => {
+  it('should accept a service with version', () => {
+    const info = ServiceInfoSchema.parse({
+      enabled: true,
+      status: 'available',
+      route: '/api/v1/data',
+      provider: 'objectql',
+      version: '3.0.6',
+    });
+    expect(info.version).toBe('3.0.6');
+  });
+
+  it('should allow version to be omitted', () => {
+    const info = ServiceInfoSchema.parse({
+      enabled: true,
+      status: 'available',
+    });
+    expect(info.version).toBeUndefined();
+  });
+});
+
+describe('ServiceInfoSchema (rateLimit field)', () => {
+  it('should accept a service with rateLimit', () => {
+    const info = ServiceInfoSchema.parse({
+      enabled: true,
+      status: 'available',
+      rateLimit: {
+        requestsPerMinute: 60,
+        requestsPerHour: 1000,
+        burstLimit: 10,
+        retryAfterMs: 5000,
+      },
+    });
+    expect(info.rateLimit?.requestsPerMinute).toBe(60);
+    expect(info.rateLimit?.burstLimit).toBe(10);
+  });
+
+  it('should allow rateLimit to be omitted', () => {
+    const info = ServiceInfoSchema.parse({
+      enabled: true,
+      status: 'available',
+    });
+    expect(info.rateLimit).toBeUndefined();
+  });
+
+  it('should allow partial rateLimit fields', () => {
+    const info = ServiceInfoSchema.parse({
+      enabled: true,
+      status: 'available',
+      rateLimit: {
+        requestsPerMinute: 100,
+      },
+    });
+    expect(info.rateLimit?.requestsPerMinute).toBe(100);
+    expect(info.rateLimit?.requestsPerHour).toBeUndefined();
+  });
+});
+
+// ==========================================
+// DiscoverySchema — capabilities
+// ==========================================
+
+describe('DiscoverySchema (capabilities field)', () => {
+  const fixture = {
+    name: 'ObjectStack',
+    version: '1.0.0',
+    environment: 'production' as const,
+    routes: { data: '/api/v1/data', metadata: '/api/v1/meta' },
+    services: minimalServices,
+    locale: { default: 'en-US', supported: ['en-US'], timezone: 'UTC' },
+  };
+
+  it('should accept discovery with capabilities', () => {
+    const discovery = DiscoverySchema.parse({
+      ...fixture,
+      capabilities: {
+        comments: {
+          enabled: true,
+          features: { threaded: true, reactions: true, mentions: true },
+          description: 'Feed and comments support',
+        },
+        automation: {
+          enabled: false,
+          description: 'Flow automation engine',
+        },
+      },
+    });
+    expect(discovery.capabilities?.comments.enabled).toBe(true);
+    expect(discovery.capabilities?.comments.features?.threaded).toBe(true);
+    expect(discovery.capabilities?.automation.enabled).toBe(false);
+  });
+
+  it('should allow capabilities to be omitted', () => {
+    const discovery = DiscoverySchema.parse(fixture);
+    expect(discovery.capabilities).toBeUndefined();
+  });
+});
+
+// ==========================================
+// DiscoverySchema — schemaDiscovery
+// ==========================================
+
+describe('DiscoverySchema (schemaDiscovery field)', () => {
+  const fixture = {
+    name: 'ObjectStack',
+    version: '1.0.0',
+    environment: 'production' as const,
+    routes: { data: '/api/v1/data', metadata: '/api/v1/meta' },
+    services: minimalServices,
+    locale: { default: 'en-US', supported: ['en-US'], timezone: 'UTC' },
+  };
+
+  it('should accept discovery with schemaDiscovery', () => {
+    const discovery = DiscoverySchema.parse({
+      ...fixture,
+      schemaDiscovery: {
+        openapi: '/api/v1/openapi.json',
+        graphql: '/graphql',
+        jsonSchema: '/api/v1/schemas',
+      },
+    });
+    expect(discovery.schemaDiscovery?.openapi).toBe('/api/v1/openapi.json');
+    expect(discovery.schemaDiscovery?.graphql).toBe('/graphql');
+    expect(discovery.schemaDiscovery?.jsonSchema).toBe('/api/v1/schemas');
+  });
+
+  it('should allow schemaDiscovery to be omitted', () => {
+    const discovery = DiscoverySchema.parse(fixture);
+    expect(discovery.schemaDiscovery).toBeUndefined();
+  });
+
+  it('should allow partial schemaDiscovery fields', () => {
+    const discovery = DiscoverySchema.parse({
+      ...fixture,
+      schemaDiscovery: {
+        openapi: '/api/v1/openapi.json',
+      },
+    });
+    expect(discovery.schemaDiscovery?.openapi).toBe('/api/v1/openapi.json');
+    expect(discovery.schemaDiscovery?.graphql).toBeUndefined();
+  });
+});

packages/spec/src/api/discovery.zod.ts

@@ -17,8 +17,17 @@ export const ServiceInfoSchema = z.object({
   route: z.string().optional().describe('e.g. /api/v1/analytics'),
   /** Implementation provider name */
   provider: z.string().optional().describe('e.g. "objectql", "plugin-redis", "driver-memory"'),
+  /** Service version */
+  version: z.string().optional().describe('Semantic version of the service implementation (e.g. "3.0.6")'),
   /** Human-readable reason if unavailable */
   message: z.string().optional().describe('e.g. "Install plugin-workflow to enable"'),
+  /** Rate limit configuration for this service */
+  rateLimit: z.object({
+    requestsPerMinute: z.number().int().optional().describe('Maximum requests per minute'),
+    requestsPerHour: z.number().int().optional().describe('Maximum requests per hour'),
+    burstLimit: z.number().int().optional().describe('Maximum burst request count'),
+    retryAfterMs: z.number().int().optional().describe('Suggested retry-after delay in milliseconds when rate-limited'),
+  }).optional().describe('Rate limit and quota info for this service'),
 });
 
 /**
@@ -108,6 +117,29 @@ export const DiscoverySchema = z.object({
     'Per-service availability map keyed by CoreServiceName'
   ),
 
+  /**
+   * Hierarchical capability descriptors.
+   * Declares platform features so clients can adapt UI without probing individual services.
+   * Each key is a capability domain (e.g., "comments", "automation", "search"),
+   * and its value describes what sub-features are available.
+   */
+  capabilities: z.record(z.string(), z.object({
+    enabled: z.boolean().describe('Whether this capability is available'),
+    features: z.record(z.string(), z.boolean()).optional()
+      .describe('Sub-feature flags within this capability'),
+    description: z.string().optional()
+      .describe('Human-readable capability description'),
+  })).optional().describe('Hierarchical capability descriptors for frontend intelligent adaptation'),
+
+  /**
+   * Schema discovery URLs for cross-ecosystem interoperability.
+   */
+  schemaDiscovery: z.object({
+    openapi: z.string().optional().describe('URL to OpenAPI (Swagger) specification (e.g., "/api/v1/openapi.json")'),
+    graphql: z.string().optional().describe('URL to GraphQL schema endpoint (e.g., "/graphql")'),
+    jsonSchema: z.string().optional().describe('URL to JSON Schema definitions'),
+  }).optional().describe('Schema discovery endpoints for API toolchain integration'),
+
   /**
    * Custom metadata key-value pairs for extensibility
    */