Implement ObjectStack kernel API specifications (P0/P1/P2)

[Copilot]

Implements batch operations, metadata caching, error standardization, full-text search, and view persistence APIs to support ObjectUI requirements.

Batch Operations (batch.zod.ts)

Added updateMany/deleteMany with atomic transaction support:

// POST /api/v1/data/{object}/batch
{
  operation: 'update',
  records: [
    { id: '1', data: { status: 'active' } },
    { id: '2', data: { status: 'active' } }
  ],
  options: {
    atomic: true,           // rollback on any failure
    returnRecords: true,    // include full records in response
    continueOnError: false  // stop on first error
  }
}

Max 200 records/batch. Partial success handling with per-record error details.

Metadata Cache Control (cache.zod.ts)

ETag-based conditional requests for metadata endpoints:

// Request with If-None-Match header
const response = await client.meta.getCached('account', {
  ifNoneMatch: '"686897696a7c876b7e"'
});

// Returns 304 Not Modified if unchanged
if (response.notModified) {
  // use cached version
} else {
  // update cache with response.data, response.etag
}

Selective invalidation by target type (object/field/permission/layout).

Error Standardization (errors.zod.ts)

50+ machine-readable error codes with categorization, HTTP status mapping, and retry guidance:

{
  code: 'validation_error',
  message: 'Validation failed for 2 fields',
  category: 'validation',
  httpStatus: 400,
  retryable: false,
  fieldErrors: [
    { field: 'email', code: 'invalid_format', value: 'not-an-email' },
    { field: 'age', code: 'value_out_of_range', value: 150, constraint: { max: 120 } }
  ]
}

Full-Text Search (extended query.zod.ts)

Added search parameter with fuzzy matching, field boosting, and language analysis:

{
  object: 'article',
  search: {
    query: 'machine learning',
    fields: ['title', 'content'],
    fuzzy: true,
    boost: { title: 2.0, content: 1.0 },
    language: 'en',
    highlight: true
  },
  where: { published: true },
  limit: 10
}

View Persistence (view-storage.zod.ts)

Save/share UI configurations for list, kanban, calendar, chart views. Supports column layouts, filters, sorting, and per-user defaults.

Notes

• Field-level permissions, GraphQL, audit logs already existed
• WebSocket/SSE realtime subscriptions already implemented
• Aggregation queries ($groupby, $aggregate) already supported
• Added 85 tests, all 2164 tests passing

Original prompt

5️⃣ ObjectStack 内核需求

为充分发挥 ObjectUI 的能力，建议 @objectstack 内核 提供以下功能：

5.1 必需功能

功能 优先级 说明
批量更新 API P0 client.data.updateMany(resource, records[])
元数据缓存控制 P0 client.meta.getCached() 或 ETag 支持
错误码标准化 P0 统一错误响应格式
WebSocket/SSE 支持 P1 实时数据订阅
字段级权限 P1 支持字段级读/写权限
批量操作事务 P1 原子性批量操作
5.2 增强功能

功能 优先级 说明
GraphQL 端点 P2 可选的 GraphQL API
全文搜索 P2 $search 参数支持
聚合查询 P2 $groupby, $aggregate
视图定义存储 P2 存储 UI 视图配置
审计日志 P2 数据变更历史
5.3 API 规范建议

批量更新 API

// POST /api/v1/data/{object}/batch
{
"operation": "update",
"records": [
{ "id": "1", "name": "Updated Name 1" },
{ "id": "2", "name": "Updated Name 2" }
],
"options": {
"atomic": true, // 事务性
"returnRecords": true
}
}

// Response
{
"success": true,
"updated": 2,
"records": [...],
"errors": []
}
实时订阅 API

// WebSocket: ws://api/v1/realtime
{
"action": "subscribe",
"resource": "contacts",
"filters": { "status": "active" },
"events": ["create", "update", "delete"]
}

// 服务器推送
{
"event": "update",
"resource": "contacts",
"data": { "id": "123", "name": "John Doe" },
"timestamp": "2026-01-29T12:00:00Z"
}

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jan 30, 2026 9:54am

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

[Copilot]

Pull request overview

This PR implements ObjectStack kernel API specifications to support ObjectUI requirements, focusing on batch operations, metadata caching, error standardization, full-text search, and view persistence.

Changes:

• Added batch operations API with atomic transaction support (max 200 records per batch)
• Implemented ETag-based metadata caching with conditional requests
• Standardized 50+ error codes with categorization and retry guidance
• Extended query schema with full-text search capabilities
• Added view storage API for persisting UI configurations

Reviewed changes

Copilot reviewed 62 out of 62 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/spec/src/data/query.zod.ts	Added full-text search schema to query AST
packages/spec/src/data/query.test.ts	Added 15 test cases for full-text search functionality
packages/spec/src/api/view-storage.zod.ts	Implemented view persistence schemas for list/kanban/calendar/chart views
packages/spec/src/api/index.ts	Exported new batch, cache, errors, and view-storage modules
packages/spec/src/api/errors.zod.ts	Added standardized error codes with HTTP status mapping
packages/spec/src/api/errors.test.ts	Added comprehensive error handling test suite
packages/spec/src/api/cache.zod.ts	Implemented ETag-based caching protocol
packages/spec/src/api/cache.test.ts	Added cache invalidation and conditional request tests
packages/spec/src/api/batch.zod.ts	Implemented batch operations with transaction support
packages/spec/src/api/batch.test.ts	Added batch operation validation tests
packages/spec/json-schema/*	Generated JSON schemas for new API types
content/docs/references/*	Added documentation for new system protocols (logging, metrics, tracing)

[Copilot]

The new documentation files (tracing.mdx, metrics.mdx, logging.mdx) are added but lack examples or usage scenarios beyond the basic schema documentation. Consider adding practical examples showing how these protocols integrate with the batch operations, caching, and error handling features introduced in this PR to provide better context for developers.