feat(spec): add fieldGroups MVP protocol to ObjectSchema

Adds simplified metadata-layer field grouping:
- New ObjectFieldGroupSchema (key/label/icon/description/defaultExpanded/visibleOn)
- Optional fieldGroups: ObjectFieldGroup[] on ObjectSchema; array order = display order
- Group keys validated unique + snake_case; field→group via existing Field.group
- 12 new tests; CHANGELOG updated under [Unreleased]

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/9a38bcfa-8efb-46a2-a910-88a4f33364d8

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Field Groups (`fieldGroups`) — simplified MVP protocol** — Introduced a data-layer protocol for grouping fields on an object in forms, detail pages, and editors. Designed to be AI-generation- and extension-friendly by intentionally minimizing surface area:
+  - New `ObjectFieldGroupSchema` in `packages/spec/src/data/object.zod.ts` with `key` (snake_case machine key), `label`, optional `icon`, `description`, `defaultExpanded` (default `true`), and `visibleOn` (expression for conditional visibility). No `order` property — **array declaration order is the display order**.
+  - `ObjectSchema` gains an optional `fieldGroups: ObjectFieldGroup[]`. Group keys are validated to be unique within an object.
+  - The existing `Field.group: string` property on `FieldSchema` is the sole field→group assignment mechanism. Field → group mapping is derived automatically from metadata registration; in-group display order equals the traversal order of `ObjectSchema.fields`. Extension packages and runtime code use `Field.group` uniformly.
+  - Supported migrations at this layer: add / rename / delete / reorder groups (by editing the `fieldGroups` array) and assigning an existing field to a group (by editing `Field.group`). Explicit per-field in-group ordering is deferred to a future iteration.
+  - New `ObjectFieldGroup` / `ObjectFieldGroupInput` type exports alongside the schema.
+  - Tests: 12 new round-trip cases in `packages/spec/src/data/object.test.ts` covering minimal/full-group parsing, required fields, snake_case key validation, declaration-order preservation, duplicate-key rejection, `Field.group` referencing, and `ObjectSchema.create()` integration.
+
 ### Added
 - **Environment-per-database multi-tenancy (`service-tenant` v4.1)** — Refactored the multi-tenant architecture from "per-organization database" to **per-environment database** high-isolation, with a hard split between Control Plane (environment registry / addressing / credentials / RBAC) and Data Plane (one physical database per environment). See [`docs/adr/0002-environment-database-isolation.md`](docs/adr/0002-environment-database-isolation.md) for the full rationale and trade-offs.
   - **Zod protocol schemas** (`packages/spec/src/cloud/environment.zod.ts`): `EnvironmentSchema`, `EnvironmentDatabaseSchema`, `DatabaseCredentialSchema`, `EnvironmentMemberSchema`, `EnvironmentTypeSchema`, `EnvironmentStatusSchema`, `EnvironmentRoleSchema`, `DatabaseCredentialStatusSchema`, `ProvisionEnvironmentRequest/ResponseSchema`, `ProvisionOrganizationRequest/ResponseSchema`. `TenantDatabaseSchema` is now marked `@deprecated`.

packages/spec/src/data/object.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { ObjectSchema, ObjectCapabilities, IndexSchema, type ServiceObject } from './object.zod';
+import { ObjectSchema, ObjectCapabilities, IndexSchema, ObjectFieldGroupSchema, type ServiceObject } from './object.zod';
 
 describe('ObjectCapabilities', () => {
   it('should apply default values correctly', () => {
@@ -847,3 +847,120 @@ describe('ObjectSchema.create() namespace auto-derivation', () => {
     expect(obj.tableName).toBe('crm_deal');
   });
 });
+
+// =================================================================
+// Field Groups (MVP) — metadata-layer protocol
+// =================================================================
+
+describe('ObjectFieldGroupSchema', () => {
+  it('should accept a minimal group (key + label)', () => {
+    const group = { key: 'contact_info', label: 'Contact Information' };
+    const result = ObjectFieldGroupSchema.parse(group);
+    expect(result.key).toBe('contact_info');
+    expect(result.label).toBe('Contact Information');
+    // defaultExpanded defaults to true
+    expect(result.defaultExpanded).toBe(true);
+    expect(result.icon).toBeUndefined();
+    expect(result.description).toBeUndefined();
+    expect(result.visibleOn).toBeUndefined();
+  });
+
+  it('should accept a fully-specified group', () => {
+    const group = {
+      key: 'billing',
+      label: 'Billing',
+      icon: 'credit-card',
+      description: 'Billing and payment details',
+      defaultExpanded: false,
+      visibleOn: '$user.isAdmin',
+    };
+    const result = ObjectFieldGroupSchema.parse(group);
+    expect(result).toEqual(group);
+  });
+
+  it('should reject missing key or label', () => {
+    expect(() => ObjectFieldGroupSchema.parse({})).toThrow();
+    expect(() => ObjectFieldGroupSchema.parse({ key: 'billing' })).toThrow();
+    expect(() => ObjectFieldGroupSchema.parse({ label: 'Billing' })).toThrow();
+  });
+
+  it('should reject non-snake_case keys', () => {
+    expect(() => ObjectFieldGroupSchema.parse({ key: 'Contact Info', label: 'x' })).toThrow();
+    expect(() => ObjectFieldGroupSchema.parse({ key: 'contact-info', label: 'x' })).toThrow();
+    expect(() => ObjectFieldGroupSchema.parse({ key: 'ContactInfo',  label: 'x' })).toThrow();
+  });
+});
+
+describe('ObjectSchema.fieldGroups', () => {
+  it('should accept an object without fieldGroups (fully optional)', () => {
+    const result = ObjectSchema.safeParse({
+      name: 'account',
+      fields: {},
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.fieldGroups).toBeUndefined();
+    }
+  });
+
+  it('should preserve declaration order of fieldGroups (array order = display order)', () => {
+    const result = ObjectSchema.parse({
+      name: 'account',
+      fields: {},
+      fieldGroups: [
+        { key: 'contact_info', label: 'Contact' },
+        { key: 'billing',      label: 'Billing' },
+        { key: 'system',       label: 'System'  },
+      ],
+    });
+    expect(result.fieldGroups?.map(g => g.key)).toEqual([
+      'contact_info', 'billing', 'system',
+    ]);
+  });
+
+  it('should reject duplicate fieldGroup keys', () => {
+    const result = ObjectSchema.safeParse({
+      name: 'account',
+      fields: {},
+      fieldGroups: [
+        { key: 'billing', label: 'Billing' },
+        { key: 'billing', label: 'Billing Details' },
+      ],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('should allow Field.group to reference a declared group key', () => {
+    const result = ObjectSchema.safeParse({
+      name: 'account',
+      fields: {
+        email:   { type: 'email', group: 'contact_info' },
+        phone:   { type: 'phone', group: 'contact_info' },
+        vat_id:  { type: 'text',  group: 'billing'       },
+        created: { type: 'datetime', group: 'system'     },
+      },
+      fieldGroups: [
+        { key: 'contact_info', label: 'Contact Information' },
+        { key: 'billing',      label: 'Billing'             },
+        { key: 'system',       label: 'System'              },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('ObjectSchema.create() should accept fieldGroups and preserve them', () => {
+    const obj = ObjectSchema.create({
+      name: 'project_task',
+      fields: {
+        title:  { type: 'text' },
+        status: { type: 'text', group: 'workflow' },
+      },
+      fieldGroups: [
+        { key: 'workflow', label: 'Workflow', icon: 'workflow' },
+      ],
+    });
+    expect(obj.fieldGroups).toEqual([
+      { key: 'workflow', label: 'Workflow', icon: 'workflow', defaultExpanded: true },
+    ]);
+  });
+});

packages/spec/src/data/object.zod.ts

@@ -211,6 +211,68 @@ export const CDCConfigSchema = z.object({
   destination: z.string().describe('Destination endpoint (e.g., "kafka://topic", "webhook://url")'),
 });
 
+/**
+ * Object Field Group Schema — MVP (data-layer protocol)
+ * 
+ * Declares the set of logical field groups for an object. A group bundles
+ * related fields together for presentation in forms, detail pages, and
+ * editors (e.g., "Contact Info", "Billing", "System").
+ * 
+ * Design rules (MVP):
+ * - Group **order** is the declaration order of this array — no `order` property.
+ * - Field → group mapping is derived automatically from `Field.group`
+ *   matching `ObjectFieldGroup.key`; the **in-group display order** equals
+ *   the traversal order of `ObjectSchema.fields`.
+ * - Fields whose `group` is unset (or references an undeclared key) are
+ *   considered ungrouped and must be rendered by consumers in a default
+ *   bucket after the declared groups, preserving their field declaration order.
+ * - Extension packages and runtime code use `Field.group` to assign fields
+ *   to an existing group — no per-field order property is introduced at this
+ *   layer.
+ * 
+ * Migration operations supported by this MVP:
+ *   - add / rename / delete / reorder groups (via the array)
+ *   - assign an existing field to a group (via `Field.group`)
+ * 
+ * Deferred (not part of MVP):
+ *   - explicit per-field in-group ordering
+ *   - nested groups / sub-groups
+ *   - permission-scoped group visibility beyond `visibleOn`
+ * 
+ * @example
+ * ```ts
+ * fieldGroups: [
+ *   { key: 'contact_info', label: 'Contact Information', icon: 'user' },
+ *   { key: 'billing',      label: 'Billing',             defaultExpanded: false },
+ *   { key: 'system',       label: 'System',              visibleOn: '$user.isAdmin' },
+ * ]
+ * ```
+ */
+export const ObjectFieldGroupSchema = z.object({
+  /** Group key — referenced by `Field.group` to assign a field to this group. Must be snake_case. */
+  key: z.string().regex(/^[a-z_][a-z0-9_]*$/, {
+    message: 'Field group key must be lowercase snake_case (e.g., "contact_info", "billing", "system")',
+  }).describe('Group machine key (snake_case). Referenced by Field.group.'),
+
+  /** Human-readable label displayed as the group header. */
+  label: z.string().describe('Group display label'),
+
+  /** Optional Lucide/Material icon name for the group header. */
+  icon: z.string().optional().describe('Icon name (Lucide/Material) for the group header'),
+
+  /** Optional description / help text shown under the group header. */
+  description: z.string().optional().describe('Optional description shown under the group header'),
+
+  /** Whether the group is expanded by default. Defaults to `true`. */
+  defaultExpanded: z.boolean().optional().default(true).describe('Whether the group is expanded by default'),
+
+  /** Optional visibility expression — when false, the entire group is hidden (e.g., "$user.isAdmin", "status == \'closed\'"). */
+  visibleOn: z.string().optional().describe('Visibility condition expression; when false the group is hidden'),
+});
+
+export type ObjectFieldGroup = z.infer<typeof ObjectFieldGroupSchema>;
+export type ObjectFieldGroupInput = z.input<typeof ObjectFieldGroupSchema>;
+
 /**
  * Base Object Schema Definition
  * 
@@ -282,6 +344,23 @@ const ObjectSchemaBase = z.object({
     message: 'Field names must be lowercase snake_case (e.g., "first_name", "company", "annual_revenue")',
   }), FieldSchema).describe('Field definitions map. Keys must be snake_case identifiers.'),
   indexes: z.array(IndexSchema).optional().describe('Database performance indexes'),
+
+  /**
+   * Field Groups (MVP)
+   * 
+   * Declares logical groups for presenting fields in forms and detail
+   * pages. The **array order is the group display order**. Each field's
+   * `Field.group` references an entry's `key` to assign it to a group;
+   * within a group, fields are displayed in their `ObjectSchema.fields`
+   * declaration order.
+   * 
+   * See {@link ObjectFieldGroupSchema} for the full MVP contract and
+   * deferred features.
+   */
+  fieldGroups: z.array(ObjectFieldGroupSchema).refine(
+    (groups) => new Set(groups.map(g => g.key)).size === groups.length,
+    { message: 'fieldGroups[].key must be unique within an object' },
+  ).optional().describe('Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema.'),
 
   /**
    * Advanced Data Management