fix(form): declare the runtime field metadata slot, ban the spec FormField misimport (#3090)

FormField.field — where object-bound paths stash the resolved
field-metadata OBJECT for widgets — rode through the index signature,
undeclared, readable only via `as any`, while the same key in the spec
form-view vocabulary is a STRING. Declaring it (Record<string, any> +
load-bearing JSDoc) makes assigning a string a compile error, retires
the casts at every read site, and a tripwire test pins the invariant:
normalizeSectionField never emits a string field — the authored form
ends at that boundary. The one deliberate boundary read in ObjectForm
(authored defs, where the string IS legitimate) is commented as such.

no-restricted-imports bans FormField/FormFieldSchema imports from
@objectstack/spec/ui: the spec type erases to `any` (objectstack#4171),
so the misimport silently deletes type safety and tsc says nothing —
the lint message is the correction, naming both layers and the
chokepoint. The parity drift guard is the one legitimate importer,
exempted inline; the rule firing on it was the mutation proof.

Ledger: FormField + FormFieldSchema move DEBT → ALLOW with the
two-layer rationale (122 → 120, 5 declared dialects).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/form-field-slot-typed-and-import-tripwire.md

@@ -0,0 +1,28 @@
+---
+"@object-ui/types": patch
+"@object-ui/components": patch
+"@object-ui/plugin-form": patch
+---
+
+fix(form): the runtime `field` metadata slot is declared instead of smuggled, and importing the spec's FormField is a lint error — #3090
+
+`FormField.field` — the slot where object-bound form paths stash the resolved
+field-metadata **object** for widgets — rode through the index signature,
+undeclared, readable only via `as any`. Same key, different layer: in the spec
+form-view vocabulary `field` is a *string* (the referenced object-field name),
+and the undeclared slot kept that pun latent. The slot is now declared
+(`field?: Record<string, any>`) with the invariant in its JSDoc: on a runtime
+FormField it is never a string — the authored string form ends at the
+`normalizeSectionField` chokepoint, and a tripwire test pins that across all
+three input shapes. Assigning a string is now a compile error; the `as any`
+casts at the read sites are gone.
+
+A `no-restricted-imports` tripwire bans importing `FormField`/
+`FormFieldSchema` from `@objectstack/spec/ui` inside this repo: the spec's
+FormField TYPE erases to `any` in its dist (objectstack#4171), so the
+misimport silently deletes type safety — tsc says nothing. The lint message
+names the two layers and the correct import. The drift-guard parity test is
+the one legitimate importer, exempted inline with its reason.
+
+Ledger: `FormField` and `FormFieldSchema` move from untriaged DEBT to ALLOW
+with the two-layer rationale written down (122 → 120).

eslint.config.js

@@ -63,6 +63,25 @@ export default tseslint.config({
     // Error so a tenth copy fails CI; all known sites were converted first, so
     // this lints clean today.
     'object-ui/no-try-catch-around-hook': 'error',
+    // objectui#3090 tripwire — the spec's FormField/FormFieldSchema are the
+    // form-VIEW vocabulary (`field` = object-field reference), a DIFFERENT
+    // layer from objectui's runtime form-field contract (`name` = data path);
+    // the translation point is `normalizeSectionField` in @object-ui/
+    // plugin-form. Worse, the spec's FormField TYPE erases to `any` in its
+    // dist (objectstack#4171), so importing it here silently deletes type
+    // safety — tsc says nothing. Error so the misimport fails at write time,
+    // with this message as the correction.
+    'no-restricted-imports': ['error', {
+      paths: [{
+        name: '@objectstack/spec/ui',
+        importNames: ['FormField', 'FormFieldSchema'],
+        message:
+          'This is the spec form-VIEW vocabulary (field = object-field reference), and its type erases to ' +
+          '`any` (objectstack#4171) — importing it silently deletes type safety. The runtime form-field ' +
+          'contract is `FormField`/`FormFieldSchema` from @object-ui/types; the two layers meet only in ' +
+          '`normalizeSectionField` (@object-ui/plugin-form). See objectui#3090.',
+      }],
+    }],
   },
 }, {
   // objectui#3010/#3021 ratchet — a module loaded inside beforeAll/beforeEach

packages/components/src/renderers/form/form.tsx

@@ -1118,7 +1118,9 @@ ComponentRegistry.register('form',
       // ObjectForm) pass the field metadata through without hoisting
       // its `widget` to the top-level form-config, which would
       // otherwise degrade a picker field to its raw `type` input.
-      const resolvedType = widget || (fieldProps as any).field?.widget || type;
+      // (`.field` is the resolved metadata OBJECT — declared on FormField
+      // since #3090, never the spec string; see types/form.ts)
+      const resolvedType = widget || fieldProps.field?.widget || type;
 
       // Cascading / role-gated option lists (#2284). For option fields,
       // narrow the set by each option's `visibleWhen` (evaluated against
@@ -1251,9 +1253,11 @@ ComponentRegistry.register('form',
                 {/* Render the actual field component based on resolved type */}
                 {renderFieldComponent(resolvedType, {
                   ...fieldProps,
-                  // specialized fields needs raw metadata, but we should traverse down if it exists
-                  // field is the field configuration loop variable
-                  field: (field as any).field || field, 
+                  // Specialized fields need the raw metadata object. `.field`
+                  // is the declared metadata slot (#3090 — never the spec
+                  // string); fall back to the field config itself when no
+                  // metadata was stashed (standalone forms).
+                  field: field.field || field,
                   ...formField,
                   inputType: fieldProps.inputType,
                   options: isOptionField ? effectiveOptions : fieldProps.options,

packages/plugin-form/src/ObjectForm.tsx

@@ -938,6 +938,10 @@ const SimpleObjectForm: React.FC<ObjectFormProps> = ({
       // predicate must be merged onto the resolved field or it is silently
       // dropped — the form renderer evaluates it with the canonical engine.
       const sectionDefByName = new Map<string, any>(
+        // AUTHORED section defs, pre-normalization — here `field` may
+        // legitimately be the spec identity STRING (the cast is the boundary,
+        // not a leak; on runtime FormFields the declared `field` slot is
+        // always the metadata object, #3090).
         section.fields.map(f => [typeof f === 'string' ? f : ((f as any).field ?? f.name), f]),
       );
       const sectionFieldNames = Array.from(sectionDefByName.keys());

packages/plugin-form/src/sectionFields.spec-parity.test.ts

@@ -30,6 +30,11 @@
  */
 
 import { describe, it, expect } from 'vitest';
+// The drift guard is the ONE legitimate importer of the spec's FormFieldSchema
+// in this repo: it exists to enumerate the spec's key set. Everywhere else the
+// import is a layer violation — see the no-restricted-imports entry in
+// eslint.config.js (#3090).
+// eslint-disable-next-line no-restricted-imports
 import { FormFieldSchema as SpecFormFieldSchema } from '@objectstack/spec/ui';
 import { mapFieldTypeToFormType } from '@object-ui/fields';
 import { normalizeSectionField } from './sectionFields';

packages/plugin-form/src/sectionFields.test.ts

@@ -30,7 +30,7 @@ describe('normalizeSectionField', () => {
     expect(f.type).toBe(mapFieldTypeToFormType('text')); // merged from object schema
     expect(f.required).toBe(true);         // spec override
     expect((f as any).colSpan).toBe(2);    // spec override
-    expect((f as any).field).toMatchObject({ type: 'text' }); // metadata object, not the string
+    expect(f.field).toMatchObject({ type: 'text' }); // metadata object, not the string
   });
 
   it('merges select options + label from the object schema', () => {
@@ -162,6 +162,23 @@ describe('normalizeSectionField', () => {
     expect(f.dependsOn).toBe('country');
   });
 
+  it('never emits a string `field` — the spec identity key ends at this boundary', () => {
+    // On a runtime FormField the declared `field` slot holds the resolved
+    // metadata OBJECT (or nothing) — never the spec's string reference. This
+    // is the invariant that makes the same-key pun safe (#3090): the string
+    // form exists only in AUTHORED defs, and this chokepoint is where it dies.
+    const shapes: Array<string | Record<string, any>> = [
+      'industry', // string shorthand
+      { field: 'industry', required: true }, // spec object
+      { field: 'ghost' }, // spec object, unknown to the schema
+      { name: 'custom', type: 'text' }, // already-runtime object
+    ];
+    for (const def of shapes) {
+      const out = normalizeSectionField(def as any, ctx);
+      expect(typeof out.field, `string field leaked for ${JSON.stringify(def)}`).not.toBe('string');
+    }
+  });
+
   it('warns once when an entry mixes both vocabularies, and the spec key wins', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     try {

packages/types/src/form.ts

@@ -1001,6 +1001,23 @@ export interface FormField {
    * @example "record.status == 'sent'"
    */
   requiredWhen?: string | { dialect?: string; source: string };
+  /**
+   * The resolved object-field metadata **object** (typically a
+   * {@link FieldMetadata} / server-served field definition), stashed by the
+   * object-bound form paths so widgets can read `precision`, `currency`,
+   * `reference_to`, `depends_on`, … It feeds the field-widget `field` prop.
+   *
+   * ⚠️ Same key, different layer: in the SPEC form-view vocabulary `field` is
+   * a **string** (the referenced object-field name). That authored shape ends
+   * at the `normalizeSectionField` chokepoint in `@object-ui/plugin-form` —
+   * on a runtime FormField this slot is never a string, and its tripwire test
+   * pins that. Declared (rather than ridden through the index signature) so
+   * assigning a string here is a compile error instead of a latent pun
+   * (#3090). Typed loosely because the stash's source is the server-served
+   * object schema, whose key set is wider than the designer-oriented
+   * {@link FieldMetadata} union.
+   */
+  field?: Record<string, any>;
   /**
    * Additional field-specific props
    */

scripts/check-spec-symbol-derivation.mjs

@@ -77,6 +77,29 @@ const ALLOW = {
       "shape kept for backward compatibility and slated for removal in a future major.",
     issue: 4115,
   },
+  "@object-ui/types:FormField": {
+    reason:
+      "Two-LAYER vocabulary, not two dialects of one concept (objectui#3090): the spec's " +
+      "FormField is the authored form-VIEW shape (`field` = object-field reference, presentation " +
+      "deltas only) while this is the runtime widget config (`name` = form data path, " +
+      "self-contained). Not derivable — and the spec's FormField type erases to `any` in its dist " +
+      "(objectstack#4171), so a re-export would delete typing outright. The layers meet only in " +
+      "`normalizeSectionField` (@object-ui/plugin-form), gated by " +
+      "sectionFields.spec-parity.test.ts (per-key behavioral coverage of the spec key set, both " +
+      "directions). Misimport of the spec names is banned by the no-restricted-imports entry in " +
+      "eslint.config.js.",
+    issue: 4115,
+  },
+  "@object-ui/types:FormFieldSchema": {
+    reason:
+      "Zod twin of the two-layer FormField split (objectui#3090): validates the RUNTIME " +
+      "vocabulary (`name` + widget `type`) that `objectui validate` enforces; the spec's " +
+      "FormFieldSchema validates the authored form-view layer. Key set pinned by " +
+      "packages/types/src/__tests__/form-field-zod-coverage.test.ts; the spec-shape rejection " +
+      "(`{ field: … }` stays invalid here) is pinned there too, and the CLI names the boundary " +
+      "in its error output instead of suggesting a lossy rename.",
+    issue: 4115,
+  },
   "@object-ui/types:SelectOptionSchema": {
     reason:
       "Spec-derived dialect (objectui#3090): spec keys flow in by reference via " +
@@ -163,8 +186,6 @@ const DEBT = {
     "DatasourceSchema",
     "DriverInterface",
     "FileMetadata",
-    "FormField",
-    "FormFieldSchema",
     "FormatValidation",
     "GestureConfig",
     "GestureType",