refactor: Address PR review feedback - improve documentation and remove ambiguous deprecated properties

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

packages/foundation/core/src/util.ts

@@ -110,6 +110,8 @@ export function convertIntrospectedSchemaToObjects(
 
             if (foreignKey) {
                 // This is a lookup field
+                // Note: name must be set explicitly here since we're creating the config programmatically.
+                // When defined in YAML (ObjectConfig.fields Record), the name is auto-populated from the key.
                 fieldConfig = {
                     name: column.name,
                     type: 'lookup',
@@ -121,6 +123,8 @@ export function convertIntrospectedSchemaToObjects(
                 // Regular field
                 const fieldType = mapDatabaseTypeToFieldType(column.type);
 
+                // Note: name must be set explicitly here since we're creating the config programmatically.
+                // When defined in YAML (ObjectConfig.fields Record), the name is auto-populated from the key.
                 fieldConfig = {
                     name: column.name,
                     type: fieldType,

packages/foundation/core/src/validator.ts

@@ -190,11 +190,10 @@ export class Validator {
                 }
             }
 
-            // Pattern validation (supports both pattern and deprecated regex)
-            const patternValue = validation.pattern ?? validation.regex;
-            if (patternValue) {
+            // Pattern validation
+            if (validation.pattern) {
                 try {
-                    const pattern = new RegExp(patternValue);
+                    const pattern = new RegExp(validation.pattern);
                     if (!pattern.test(String(value))) {
                         results.push({
                             rule: `${fieldName}_pattern`,
@@ -208,7 +207,7 @@ export class Validator {
                     results.push({
                         rule: `${fieldName}_pattern`,
                         valid: false,
-                        message: `Invalid regex pattern: ${patternValue}`,
+                        message: `Invalid regex pattern: ${validation.pattern}`,
                         severity: 'error',
                         fields: [fieldName],
                     });

packages/foundation/types/src/field.ts

@@ -114,7 +114,16 @@ export interface FieldOption {
  * The Protocol Constitution (SpecField) defines the core field schema.
  * This adds runtime conveniences and extensions.
  * 
- * We make certain spec fields optional since Zod applies defaults at parse time.
+ * Properties from the protocol Field interface that are re-declared here:
+ * - `name`, `label`: Made optional for runtime convenience (auto-populated from Record key)
+ * - `type`: Extended union type to include runtime-specific types (vector, grid, location, object)
+ * - `options`: Extended to allow numeric values for backwards compatibility
+ * - Boolean flags (`required`, `multiple`, `unique`, `hidden`, `readonly`, `encryption`, `index`, `externalId`):
+ *   Made optional since Zod applies defaults at parse time, but runtime usage typically specifies these explicitly
+ * - `deleteBehavior`: Made optional with protocol-compatible enum values
+ * 
+ * All other protocol properties (description, defaultValue, maxLength, minLength, precision, scale, min, max,
+ * reference, referenceFilters, writeRequiresMasterRead, expression, formula, summaryOperations) are inherited as-is.
  */
 export interface FieldConfig extends Omit<Field, 'name' | 'label' | 'type' | 'options' | 'required' | 'multiple' | 'unique' | 'deleteBehavior' | 'hidden' | 'readonly' | 'encryption' | 'index' | 'externalId'> {
     /** Field name (inferred from Record key when used in ObjectConfig.fields) */
@@ -166,7 +175,32 @@ export interface FieldConfig extends Omit<Field, 'name' | 'label' | 'type' | 'op
 
     /**
      * Reference to another object for lookup/master_detail fields.
-     * @deprecated Use 'reference' from SpecField instead
+     * 
+     * @deprecated Legacy alias for the protocol-level `reference` field (inherited from {@link Field}).
+     * 
+     * **Migration Guidance:**
+     * - **New schemas MUST** use the `reference` field (defined in the protocol Field interface) instead of `reference_to`.
+     * - **During migration**, engines and tooling SHOULD:
+     *   - Treat `reference_to` as a fallback alias for `reference` (i.e., if `reference` is undefined and `reference_to`
+     *     is defined, behave as though `reference` were set to the same value).
+     *   - Prefer the protocol `reference` value when both are present.
+     * - This property is retained only for backward compatibility with older *.object.yml definitions and will be
+     *   removed in a future major version once all callers have migrated to `reference`.
+     * 
+     * @example
+     * ```yaml
+     * # Old (deprecated):
+     * fields:
+     *   owner:
+     *     type: lookup
+     *     reference_to: users
+     * 
+     * # New (protocol-compliant):
+     * fields:
+     *   owner:
+     *     type: lookup
+     *     reference: users
+     * ```
      */
     reference_to?: string;
 
@@ -207,12 +241,6 @@ export interface FieldConfig extends Omit<Field, 'name' | 'label' | 'type' | 'op
      */
     min_height?: number;
 
-    /**
-     * Regular expression pattern for validation.
-     * @deprecated Use validation.pattern instead
-     */
-    regex?: string;
-    
     /** 
      * Field validation configuration.
      * Defines validation rules applied at the field level.
@@ -230,10 +258,11 @@ export interface FieldConfig extends Omit<Field, 'name' | 'label' | 'type' | 'op
         min_length?: number;
         /** Maximum length for strings */
         max_length?: number;
-        /** Regular expression pattern for validation */
+        /** 
+         * Regular expression pattern for validation.
+         * Use this for custom pattern matching (e.g., /^[A-Z]{2}\d{4}$/ for codes).
+         */
         pattern?: string;
-        /** Regex pattern (alias for pattern) */
-        regex?: string;
         /** Custom validation message */
         message?: string;
     };

packages/runtime/server/src/metadata.ts

@@ -199,7 +199,7 @@ export function createMetadataHandler(app: IObjectQL, options?: MetadataHandlerO
                     max: field.max,
                     minLength: field.minLength,
                     maxLength: field.maxLength,
-                    regex: field.regex
+                    validation: field.validation
                 });
             }