@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": minor
+"@objectstack/lint": minor
+---
+
+feat(spec,rest,lint): an import mapping target may name a declared part of a compound field (`mailing_address.street`), and the importer assembles the parts into one value (#20149)
+
+Clause-②: yes
+
+**What was missing.** A mapping could write each source column to one flat
+field only, so nothing could build an `address` value from the separate
+street / city / state / postal code / country columns a spreadsheet carries.
+A dotted target such as `mailing_address.street` named no field and was
+refused at `objectstack validate`, on the dry run and on the commit.
+
+**What changes.**
+
+- `@objectstack/spec`: `ImportFieldMappingSchema.target` declares the part
+  path. A target may name `field.part` when `field` is a declared field whose
+  stored value schema is a closed object of optional strings (today:
+  `address`), and `part` is a key that schema declares: `street`, `city`,
+  `state`, `postalCode`, `country`, `countryCode`, `formatted`. The part names
+  are read from the value schema, never listed by hand. The one verdict,
+  `judgeImportMappingTarget`, answers the new `{ kind: 'part', field, part }`;
+  `indexImportMappingTargets` carries each compound field's parts on
+  `parts`; `unknownImportMappingTargets` gives each refused target a `reason`
+  (`unknown` or `collides`) and, for a dotted target, what its `head` names.
+  `location` is not compound for import: its parts are required numbers, so a
+  value assembled from text cells would be the wrong type.
+- `@objectstack/rest`: `applyMappingToRows` assembles every part target of a
+  row into one value under the field's key, before the engine sees the row,
+  whatever transform produced the part (`none`, `map`, `constant`, `join`,
+  each element of a `split`). A blank part cell (empty, whitespace or a
+  `nullValues` token) is left out, string parts are trimmed under
+  `trimWhitespace`, and a row whose parts are all blank leaves the field
+  unset, as a blank flat cell does. On an update the assembled value replaces
+  the stored one. The dry run and the commit judge the same assembled row.
+- `@objectstack/lint`: `mapping-target-field-unknown` accepts a declared part
+  and reports what stays refused, naming the legal parts each time.
+
+**Still refused, at `objectstack validate`, on the dry run and on the commit
+(`400 INVALID_FIELD`, before any row):**
+
+- a part the value does not declare (`mailing_address.stret`); the refusal
+  lists the declared parts;
+- a dotted path on a field with no parts (`full_name.first`). A dotted target
+  never traverses a reference (`account.name`): map the column to the
+  reference field with transform `lookup`;
+- a mapping that writes a field both whole and by part (`mailing_address` and
+  `mailing_address.street`): one row carries one value for the field. Map it
+  whole or by its parts, not both.
+
+**What to do.** Nothing, unless you want the capability: point each address
+column at `field.part`, for example `{ source: 'Zip', target:
+'mailing_address.postalCode' }`.
@@ -104,7 +104,7 @@ Each `fieldMapping` entry:
 | Key | Type | What it does |
 |:---|:---|:---|
 | `source` | `string \| string[]` | Source column header(s). An array is only meaningful for `join`. |
-| `target` | `string \| string[]` | Target field name(s). An array is only meaningful for `split`. |
+| `target` | `string \| string[]` | Target field name(s), or `field.part` for a declared part of an address field (`mailing_address.street`; the parts are `street`, `city`, `state`, `postalCode`, `country`, `countryCode`, `formatted`). The parts one row maps are assembled into the field's one value: a blank part cell is left out, a row whose parts are all blank leaves the field unset, and on an update the assembled value replaces the stored one. A mapping writes a field whole or by its parts, never both. An array is only meaningful for `split`. |
 | `transform` | `TransformType` | Defaults to `'none'`. |
 | `params` | object | Configuration for the transform — `value`, `valueMap`, `separator`. |
 
 
@@ -28,7 +28,7 @@ const result = ImportFieldMappingSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **source** | `string \| string[]` | ✅ | Source column header(s) |
-| **target** | `string \| string[]` | ✅ | Target object field(s) |
+| **target** | `string \| string[]` | ✅ | Target object field(s); a declared part of a compound field is written field.part (e.g. mailing_address.street), and the parts one row maps are assembled into that field's value |
 | **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | optional (default: `"none"`) |  |
 | **params** | `{ value?: any; valueMap?: Record<string, any>; separator?: string }` | optional |  |
 
@@ -61,7 +61,7 @@ const result = ImportFieldMappingSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **source** | `string \| string[]` | ✅ | Source column header(s) |
-| **target** | `string \| string[]` | ✅ | Target object field(s) |
+| **target** | `string \| string[]` | ✅ | Target object field(s); a declared part of a compound field is written field.part (e.g. mailing_address.street), and the parts one row maps are assembled into that field's value |
 | **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | optional (default: `"none"`) |  |
 | **params** | `{ value?: any; valueMap?: Record<string, any>; separator?: string }` | optional |  |
 
 
@@ -29,12 +29,12 @@ const mapping = (fieldMapping: unknown[], extra: Record<string, unknown> = {}) =
 });
 
 describe('validateMappingTargetFields', () => {
-  it('reports a target that names no field of the object, located at the mapping (the card\'s shape)', () => {
+  it('reports a target that names no field of the object, located at the mapping', () => {
     const findings = validateMappingTargetFields({
       objects: [contact],
       mappings: [mapping([
         { source: 'Name', target: 'full_name' },
-        { source: 'Street', target: 'mailing_address.street' },
+        { source: 'Mail', target: 'emial' },
       ])],
     });
     expect(findings).toHaveLength(1);
@@ -44,10 +44,87 @@ describe('validateMappingTargetFields', () => {
       where: 'mapping "contact_import" · object "crm_contact"',
       path: 'mappings[0].fieldMapping[1].target',
     });
-    // Names the target and the object, and says why a dotted path is not one.
-    expect(findings[0].message).toContain('"mailing_address.street"');
+    // Names the target and the object, and the closest name the object has.
+    expect(findings[0].message).toContain('"emial"');
     expect(findings[0].message).toContain('"crm_contact"');
-    expect(findings[0].message).toContain('"mailing_address" is a field of "crm_contact"');
+    expect(findings[0].message).toContain('Did you mean "email"?');
+  });
+
+  // [#20149] The card's shape, which #20150 pinned red here, is now a target:
+  // a declared part of a compound field. The flip is load-bearing: the whole
+  // address template is green, every part the value schema declares.
+  it('is green on a mapping that writes an address by its declared parts (the card\'s five columns and more)', () => {
+    expect(validateMappingTargetFields({
+      objects: [contact],
+      mappings: [mapping([
+        { source: 'Name', target: 'full_name' },
+        { source: 'Street', target: 'mailing_address.street' },
+        { source: 'City', target: 'mailing_address.city' },
+        { source: 'State', target: 'mailing_address.state' },
+        { source: 'Zip', target: 'mailing_address.postalCode' },
+        { source: 'Country', target: 'mailing_address.country' },
+        { source: 'x', target: 'mailing_address.countryCode', transform: 'constant', params: { value: 'US' } },
+        { source: ['Line 1', 'Line 2'], target: 'mailing_address.formatted', transform: 'join' },
+      ])],
+    })).toEqual([]);
+  });
+
+  it('refuses a part the address value does not declare, naming every part it does', () => {
+    const findings = validateMappingTargetFields({
+      objects: [contact],
+      mappings: [mapping([{ source: 'Street', target: 'mailing_address.stret' }])],
+    });
+    expect(findings.map((f) => f.path)).toEqual(['mappings[0].fieldMapping[0].target']);
+    expect(findings[0].rule).toBe(MAPPING_TARGET_FIELD_UNKNOWN);
+    expect(findings[0].message).toContain(
+      '"stret" is not a part of the address field "mailing_address": the parts a target may name on it are '
+      + 'street, city, state, postalCode, country, countryCode, formatted.',
+    );
+    expect(findings[0].message).toContain('Did you mean "street"?');
+    expect(findings[0].hint).toContain(
+      'or at a declared part of a compound field as field.part (mailing_address: street, city, state, postalCode, country, countryCode, formatted)',
+    );
+  });
+
+  it('refuses a dotted path on a field with no parts — and never reads it as a lookup traversal', () => {
+    const findings = validateMappingTargetFields({
+      objects: [{ ...contact, fields: { ...contact.fields, account: { type: 'lookup', reference: 'crm_account' } } }],
+      mappings: [mapping([
+        { source: 'First', target: 'full_name.first' },
+        { source: 'Account', target: 'account.name' },
+      ])],
+    });
+    expect(findings.map((f) => f.path)).toEqual([
+      'mappings[0].fieldMapping[0].target',
+      'mappings[0].fieldMapping[1].target',
+    ]);
+    expect(findings[0].message).toContain('The text field "full_name" is a field of "crm_contact" with no parts');
+    expect(findings[1].message).toContain('The lookup field "account" is a field of "crm_contact" with no parts');
+    expect(findings[1].message).toContain('Map the column to "account" with transform "lookup"');
+    // The part list rides along either way, so the author sees what IS a part.
+    expect(findings[0].hint).toContain('mailing_address: street, city');
+  });
+
+  it('refuses a part of a field the same mapping also writes whole — the two collide', () => {
+    const findings = validateMappingTargetFields({
+      objects: [contact],
+      mappings: [mapping([
+        { source: 'Address JSON', target: 'mailing_address' },
+        { source: 'Street', target: 'mailing_address.street' },
+      ])],
+    });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      rule: MAPPING_TARGET_FIELD_UNKNOWN,
+      path: 'mappings[0].fieldMapping[1].target',
+      // The collision names the field AND lists its legal parts, as every refusal does.
+      hint: 'Map the field whole or by its parts, not both. A declared part of a compound field is written '
+        + 'field.part (mailing_address: street, city, state, postalCode, country, countryCode, formatted).',
+    });
+    expect(findings[0].message).toContain(
+      'writes the compound field "mailing_address" of object "crm_contact" both whole (fieldMapping[0].target) '
+      + 'and by its part "street" (fieldMapping[1].target)',
+    );
   });
 
   it('is green on the control mapping — declared fields only', () => {
 
@@ -15,6 +15,17 @@
  * written, so the author meets the refusal at `os validate` rather than at the
  * first import.
  *
+ * ## A declared part of a compound field (#20149)
+ *
+ * A target may also name a declared PART of a compound field
+ * (`mailing_address.street`); the import endpoint assembles the parts one row
+ * maps into that field's one value. The shared verdict decides which fields
+ * are compound and which parts they declare, from the field's value schema.
+ * This rule reports what stays refused, and names the legal parts each time:
+ * a part the value does not declare (`mailing_address.stret`), a dotted path
+ * on a field with no parts (never a lookup traversal), and a part of a field
+ * the same mapping also writes whole (the two would collide on one value).
+ *
  * ## One verdict, two doors
  *
  * The verdict is not written here. It is `unknownImportMappingTargets`
@@ -46,11 +57,20 @@
  * them; the import door, which reads the registered object, still judges them.
  */
 
-import { indexImportMappingTargets, unknownImportMappingTargets } from '@objectstack/spec/data';
+import {
+  indexImportMappingTargets,
+  REFERENCE_VALUE_TYPES,
+  unknownImportMappingTargets,
+  type ImportMappingTargetHead,
+} from '@objectstack/spec/data';
 
 import { listNames, recordsOf, suggestName } from './object-graph.js';
 
-/** A `fieldMapping[].target` that names no field of the mapping's object. */
+/**
+ * A `fieldMapping[].target` the mapping cannot write on its object: it names no
+ * field and no declared part of a compound field, or it names a part of a field
+ * the same mapping also writes whole.
+ */
 export const MAPPING_TARGET_FIELD_UNKNOWN = 'mapping-target-field-unknown';
 
 export interface MappingTargetFieldFinding {
@@ -99,8 +119,10 @@ function extensionFieldsByTarget(stack: AnyRec): Map<string, AnyRec[]> {
 }
 
 /**
- * Report every import-mapping target that names no field of its object.
- * Returns findings (empty = clean).
+ * Report every import-mapping target its mapping cannot write on its object:
+ * one that names no field and no declared part of a compound field, and a
+ * part of a field the same mapping also writes whole. Returns findings
+ * (empty = clean).
  */
 export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFinding[] {
   const findings: MappingTargetFieldFinding[] = [];
@@ -128,31 +150,83 @@ export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFi
 
     const misses = unknownImportMappingTargets(mapping.fieldMapping, objectDef);
     if (misses.length === 0) continue; // clean, or skip 2
-    const known = indexImportMappingTargets(objectDef)?.names ?? new Set<string>();
+    const index = indexImportMappingTargets(objectDef);
+    const known = index?.names ?? new Set<string>();
+    // The object's compound fields and their legal parts, which EVERY finding's
+    // hint lists, a collision's included (ruling on #20149, item 3).
+    const compoundParts = index && index.parts.size > 0
+      ? [...index.parts].map(([field, parts]) => `${field}: ${parts.join(', ')}`).join('; ')
+      : '';
     const mappingName = strName(mapping.name) ?? `#${mi}`;
+    const where = `mapping "${mappingName}" · object "${objectName}"`;
 
     for (const miss of misses) {
-      const dot = miss.target.indexOf('.');
-      const head = dot > 0 ? miss.target.slice(0, dot) : undefined;
-      const dotted = head !== undefined && known.has(head)
-        ? ` "${head}" is a field of "${objectName}", but a target names a whole field: a dotted path into a field's value is not a target.`
-        : '';
+      if (miss.reason === 'collides') {
+        const dot = miss.target.indexOf('.');
+        findings.push({
+          severity: 'error',
+          rule: MAPPING_TARGET_FIELD_UNKNOWN,
+          where,
+          path: `mappings[${mi}].${miss.path}`,
+          message:
+            `Import mapping "${mappingName}" writes the compound field "${miss.target.slice(0, dot)}" of object ` +
+            `"${objectName}" both whole (${miss.wholeAt}) and by its part "${miss.target.slice(dot + 1)}" ` +
+            `(${miss.path}). One row carries one value for a field, so the two collide, and the import endpoint ` +
+            `refuses this mapping before any row, on the dry run and the commit alike (INVALID_FIELD).`,
+          hint:
+            'Map the field whole or by its parts, not both. A declared part of a compound field is ' +
+            `written field.part (${compoundParts}).`,
+        });
+        continue;
+      }
       findings.push({
         severity: 'error',
         rule: MAPPING_TARGET_FIELD_UNKNOWN,
-        where: `mapping "${mappingName}" · object "${objectName}"`,
+        where,
         path: `mappings[${mi}].${miss.path}`,
         message:
           `Import mapping "${mappingName}" writes target "${miss.target}", which names no field of ` +
           `object "${objectName}". The import endpoint refuses this mapping before any row, on the dry ` +
           `run and the commit alike (INVALID_FIELD), so it can import nothing.` +
-          dotted +
-          (dotted ? '' : suggestName(miss.target, known)),
+          (miss.head?.field ? dottedReason(miss.head, miss.target, objectName) : suggestName(miss.target, known)),
         hint:
           `Point the target at a field "${objectName}" declares, or at a column the platform provisions ` +
-          `on it. Addressable names: ${listNames(known)}.`,
+          `on it` +
+          (compoundParts ? `, or at a declared part of a compound field as field.part (${compoundParts})` : '') +
+          `. Addressable names: ${listNames(known)}.`,
       });
     }
   }
   return findings;
 }
+
+/**
+ * Why a dotted target whose head names a field of the object is still no
+ * target (#20149): its part is not one the field's value declares, or the
+ * field has no parts at all.
+ */
+function dottedReason(head: ImportMappingTargetHead, target: string, objectName: string): string {
+  const field = head.type ? `the ${head.type} field "${head.name}"` : `"${head.name}"`;
+  if (head.parts) {
+    const part = target.slice(head.name.length + 1);
+    return (
+      ` "${part}" is not a part of ${field}: the parts a target may name on it are ` +
+      `${head.parts.join(', ')}.` + suggestName(part, head.parts)
+    );
+  }
+  if (head.type && REFERENCE_VALUE_TYPES.has(head.type)) {
+    return (
+      ` ${capitalize(field)} is a field of "${objectName}" with no parts: a dotted target never ` +
+      `traverses a reference. Map the column to "${head.name}" with transform "lookup", which resolves ` +
+      `the cell's display text to a record id.`
+    );
+  }
+  return (
+    ` ${capitalize(field)} is a field of "${objectName}" with no parts: only a compound field ` +
+    `(one whose value declares parts, such as an address) takes a part target.`
+  );
+}
+
+function capitalize(text: string): string {
+  return text.length > 0 ? text[0].toUpperCase() + text.slice(1) : text;
+}
@@ -178,7 +178,12 @@ function coerceError(
 
 // ── blank / null handling ──────────────────────────────────────────
 
-function isBlank(value: unknown, nullValues?: string[]): boolean {
+/**
+ * Whether a cell is blank: absent, empty or whitespace, or one of the
+ * request's `nullValues`. Exported for the named mapping's compound-part
+ * assembly (#20149), which drops a blank part by this same rule.
+ */
+export function isBlank(value: unknown, nullValues?: string[]): boolean {
   if (value === null || value === undefined) return true;
   if (typeof value === 'string') {
     const s = value.trim();