import mapping: no fieldMapping target can build a compound (address) value from separate CSV columns — a dotted target passes validate and dry-run, then fails every row on commit

[objectstack-fleet]

Ruled: 5852138019 · letter A · 2026-09-27T03:00Z
Blocked-by: #20150
Seam: spec ImportFieldMappingSchema.target (a declared part of a compound field, field.part) → runtime packages/rest import-mapping.ts applyMappingToRows assembly, and the shared target door in objectstack validate / dryRun

Filing-gate category ① — reproducible platform defect/gap with a named landing (@objectstack/rest import-mapping.ts applyMappingToRows), found by the repo:hotcrm seat while executing a maintainer ruling.
Reader: objectstack triage → the lane that owns packages/rest import mapping (and packages/spec defineMapping if the fix is a new transform). Ruled A (comment 5852138019): a Seam: card in the spec lane, dispatched vertically once #20150 has landed. hotcrm#1836 waits on it with Blocked-by:.
Dedup (MCP search_issues, repo objectstack, open+closed): "import mapping fieldMapping target compound address field parts street city dotted target" → 0 hits; control "import mapping address expected object received string join transform" → 1 hit (#5137, unrelated), so the query reaches this area. Related, closed: #4633 (dry run did not pre-check a string aimed at an address field — a different defect).

What happens (measured on @objectstack/* 17.4.0, by the hotcrm#1836 dev, report hotcrm#1836 comment 5833767403)

A mapping can only write each CSV column to one flat key. Nothing can assemble street / city / state / postalCode / country columns into one Field.address() value.

• fieldMapping targets mailing_address.street … mailing_address.country against the unchanged customer template (50 rows):
  • commit: ok 0, errors 50, every row INVALID_FIELD: Unknown field 'mailing_address.street' on object 'crm_contact'.
  • dryRun: true, same body: ok 44 — the dry run again promises what the commit refuses (Import dry run green-lights a row the write then rejects: structured value shapes (address / location) are not pre-checked #4633's contract: the dry run predicts the write).
  • objectstack validate exits 0 with no diagnostic for a fieldMapping.target that names no field.
• Mechanism (read in @objectstack/rest dist, src/import-mapping.ts applyMappingToRows): every transform (none / lookup / constant / map / split / join) writes mapped[target] as a single flat key; coerceRow passes a key with no field metadata through untouched, so the engine receives a literal dotted key. join into the address field yields a string, which the engine rejects per row (Import dry run green-lights a row the write then rejects: structured value shapes (address / location) are not pre-checked #4633's message: expected object, received string).
• Control: the engine itself accepts the compound value — a nested JSON row (mailing_address: { street, city, … }) imports 1/1 and reads back intact, and the 17.4.0 console renders it as one unit.

Why it matters

A structured address cannot be fed by a spreadsheet at all. hotcrm already paid for this twice: its account import template dropped its address columns for this reason (src/sales/mappings/account_import.mapping.ts:100-106), and the maintainer's 2026-09-18 ruling on hotcrm#1836 (convert the contact's five flat mailing_* fields to one Field.address(), "the customer's template does not change") cannot land.

The three observations, for triage to split or keep together

1. Capability: a way for a mapping to write into a compound field's parts (a dotted target resolved into a nested value, or a compose transform).
2. Dry run ≠ commit for a target naming no field (sibling of Import dry run green-lights a row the write then rejects: structured value shapes (address / location) are not pre-checked #4633).
3. Author-time silence: validate accepts a fieldMapping.target that names no field on the object.

[objectstack-fleet]

Path: business objects, records and views | records-forms.named-import-mapping | P6

维护者速读

客户的通讯录表格里，地址分成五列：街道、城市、省/州、邮编、国家。平台的地址字段是一个整体值，而导入映射只能把一列写进一个平铺字段，没有任何写法能把这五列拼成一个地址。

结果：hotcrm 按你在 hotcrm#1836 的裁定，把联系人的五个平铺地址字段合并成一个地址字段；这之后，客户原来的导入表格就导不进来了，每一行都失败。hotcrm 的客户导入模板早先已经为此删掉了地址列。

三条路：

• A 映射目标可以写「地址字段.部件」，例如 mailing_address.street。部件名只能是平台为地址声明的七个（street / city / state / postalCode / country / countryCode / formatted）。导入时，把同一行的各部件组装成一个地址值。部件名写错，在 validate、试运行和正式导入三处都会当场被拒。
• B 新增一种「组装」转换：一条映射列出多个来源列，再用参数写明每列对应哪个部件，目标写地址字段本身。
• C 不做。表格导不进结构化地址：客户只能先把表格转成嵌套 JSON，或者 hotcrm 退回五个平铺字段，也就是推翻 hotcrm#1836 的裁定。

推荐 A。回一个字母：A / B / C。

另外有两个缺陷不需要等这次裁定，已拆到 #20150（domain:cli · p2）：目标写了不存在的字段时，试运行报「成功」，正式导入却全部失败；objectstack validate 对此也不报错。

os-decision-facets

• ① 项目长远合理性 —— A 沿用「目标写字段名」这一个概念，只把它延伸到 spec 已经声明的地址部件，判定仍在导入入口一处完成。B 多出一个转换类型和一张自由格式的参数表，导入转换矩阵多一行永久义务。C 让结构化地址在最常见的数据来源（表格）面前不可用。
• ② 实际业务拉动 —— 今天就有人撞上：hotcrm 的联系人导入（按本卡原文，hotcrm#1836 挂着 Blocked-by: 本卡），以及早已删掉地址列的 hotcrm 客户模板。任何把地址存成结构化字段、客户数据又来自表格的应用都会撞上。
• ③ 防 AI 犯错 —— A 的部件名是闭合集合，取自 spec 的地址定义，写错就响亮拒绝。B 的参数键是自由结构，要另写一套校验，漏掉一处就是静默丢列。C 的失败是响亮的，但没有出路，AI 会被推去绕行（拆回平铺字段）。
• ④ 创业阶段不扩散 —— A 不新增键，也不新增枚举值，只扩一处入口判定。B 新增一个枚举值和它的参数形状。C 零新增，但把 hotcrm 已裁定的改动卡死。

Governing text: ImportFieldMappingSchema.target — "Target object field(s)" (packages/spec/src/data/mapping.zod.ts); its docblock: "one target field may be composed from several columns (split / join)". AddressSchema is a closed strict object with seven declared parts (packages/spec/src/data/field-value.zod.ts). Nothing declares a part target or a compose transform, so A and B both widen the published mapping contract. That puts the choice on the manual floor: it is a feature addition and a public-contract change.

Prior rulings read: fieldmapping, compound, dotted, address, compose, import mapping, sub-field → 7 hits; ADR-0045 D3, ADR-0063 D2, ADR-0071 D1, ADR-0081 D2, ADR-0104 D1, ADR-0110 D2, ADR-0131 D3. All seven are term collisions ("compose", "address" and "dotted" in other senses); none rules on import mapping. thread: none.

推荐：A。终态：两年后，表格导入按字段部件映射复合字段，与主流平台一致。例如 Salesforce 的复合地址字段，就是按 MailingStreet、MailingCity 这样的部件字段导入的。回退：B。⛔ 不选 C。
自检：只看①选 A；②③④ 是否翻转：否。
置信缺口：除地址外，是否还有别的带部件的字段类型需要同样的写法，本席没有逐一清点。hotcrm#1836 上的 Blocked-by: 行本席在本会话读不到（hotcrm 不在本会话的可读范围），按本卡原文记。

裁后执行：

• A ⇒ 先落 import mapping: a fieldMapping.target that names no field passes objectstack validate and the dry run, then fails every row on commit #20150 的入口判定（目标必须是对象上的字段）。再由 spec 声明「目标可以写复合字段的已声明部件」（domain:spec，minor，Clause-②: yes）。之后，packages/rest 的导入映射组装嵌套值，validate 和试运行用同一判定检查部件名（domain:cli，用 Blocked-by: 排在 spec 之后）。hotcrm#1836 随之解锁。
• B ⇒ spec 新增 compose 转换及其参数形状，rest 实现，导入转换矩阵加一行。
• C ⇒ 本卡关为 not planned，hotcrm#1836 需要重新裁定。

---

Triage (English audit line): routed to the decision box — needs-user-decision · priority:p2 · domain:spec · area:records. Observation 1 (the capability) widens the published mapping contract, which is on the manual floor, so triage does not adjudicate it. Observations 2 and 3 need no ruling and are split to #20150 (domain:cli · p2). hotcrm#1836 is reported to carry Blocked-by: this card; this seat did not re-read it. Triage seat #6015 · session_01CRZSc7dU8oDStbTbSwhuZe · 2026-09-25T14:46Z.

[objectstack-fleet]

Ruling: batch #225 item 2 · letter A · maintainer 「同意」 2026-09-27T02:58Z

Director seat, summon #30, session_01AsCNgFBs8HCjwhyHQsFbx3. After batch #225 the maintainer asked for a mainstream-platform comparison on this card and on #19995 (「20149 19995 其他主流平台是怎么处理类似问题的，帮我分析给我建议」); the comparison was presented in the seat chat and the maintainer answered 「同意」 to its recommendation.

Ruled: A — a mapping target may name a declared part of a compound field (mailing_address.street); the importer assembles the parts into one value; the part names are the closed set the value schema declares.

Mainstream reading the ruling rests on: Salesforce writes and imports compound addresses only through component fields (MailingStreet, MailingCity, MailingState, MailingPostalCode, MailingCountry); the compound field itself is never a mapping target, and an unknown component name fails mapping validation. Dynamics 365, HubSpot and Zoho keep addresses flat and map column by column. Odoo's importer writes into sub-records through slash paths (partner_id/name). Shopify's and Google Contacts' CSV templates carry part columns the importer assembles into the address object. Django REST Framework writes nested fields through dotted source paths. No mainstream importer offers a compose transform with a parameter table (option B), and none leaves a structured address unreachable from a spreadsheet (option C). A is the path-style spelling of the same idiom.

Readings on origin/main 8d1f7ab785: packages/spec/src/data/mapping.zod.ts — target: z.union([z.string(), z.array(z.string())]).describe('Target object field(s)'), docblock item 2 「one target field may be composed from several columns (split / join)」; packages/spec/src/data/field-value.zod.ts — AddressSchema is a strictObject with seven declared parts (street, city, state, postalCode, country, countryCode, formatted), and LocationValueSchema is the only other strict-object value schema; packages/rest/src/import-mapping.ts applyMappingToRows writes every transform's result to a flat mapped[target] key.

Execution parameters, ruled here so the dispatch needs no second decision:

1. Spelling: the dotted path, only on an import mapping's target. The head must be a field whose value schema is a declared strict object (address; whether location is included is measured by the dev against the spec and written down either way); the tail must be a key that schema declares. A dotted target whose head is not a compound field is refused, ⛔ never read as a lookup traversal (that is the lookup transform's business). No suffix-style part fields are minted.
2. Assembly: the parts mapped from one row are assembled into one object; formatted is a legal part; the assembled value is validated against the value schema (unknown key, type).
3. One door: objectstack validate, dryRun: true and the commit judge a target with the same function — the door import mapping: a fieldMapping.target that names no field passes objectstack validate and the dry run, then fails every row on commit #20150 lands (a target must be a field on the object), extended here to a declared part; a refusal names the field and lists the legal parts.
4. Ordering: import mapping: a fieldMapping.target that names no field passes objectstack validate and the dry run, then fails every row on commit #20150 (domain:cli, pm:queue) lands first; this card is pm:blocked on it and returns to the queue when it closes.
5. This card is a Seam: card in the spec lane (domain:spec kept): spec declares the part-path grammar on ImportFieldMappingSchema.target, and the runtime half (the packages/rest assembly, the shared door in validate / dry run) is dispatched vertically with it. Clause-②: yes; changeset minor for @objectstack/spec and @objectstack/rest. hotcrm#1836 unlocks when the capability is installable.
6. Not done here: part-level filters and list columns (Salesforce-style first-class parts); the same spelling is reusable if that is wanted later.

Confidence gaps carried: hotcrm is not readable from this session, so its Blocked-by: line is taken from the card body; whether LocationValueSchema needs the same path is unmeasured and left to the dev's reading.

---

Generated by Claude Code

[objectstack-fleet]

Unblocked: pm:blocked → pm:queue · domain:spec seat 2 (session_01QcAS3qiYYZNezaxZxaUdMV) · 2026-09-27T10:37Z · ⛔ Not a claim.

• Blocker: Blocked-by: #20150, the one import-mapping target verdict this card extends. import mapping: a fieldMapping.target that names no field passes objectstack validate and the dry run, then fails every row on commit #20150 closed completed at 2026-09-27T10:35Z via PR fix(rest,lint): refuse an import mapping target that names no field, on the dry run, the commit and validate alike #20208 → 7e7fab738f, verified by content on origin/main.
• Double-check: the latest conversion reason is exactly that line (triage's routing 5853335141: "import mapping: no fieldMapping target can build a compound (address) value from separate CSV columns — a dotted target passes validate and dry-run, then fails every row on commit #20149 … follows in the same lane by extending this predicate"). No later merged PR names import mapping: no fieldMapping target can build a compound (address) value from separate CSV columns — a dotted target passes validate and dry-run, then fails every row on commit #20149.
• Where the extension lands, for whoever claims it:
  • one new arm in judgeImportMappingTarget (packages/spec/src/data/import-mapping-target.ts), at the place the PR marked. ImportMappingTargetIndex.fields carries the declared definitions, and today a dotted target is pinned unknown.
  • The lint message "a dotted path into a field's value is not a target" (packages/lint/src/validate-mapping-target-fields.ts) is rewritten in the same PR.
  • The ruling is A (5852138019): the part names are the closed set the value schema declares, and the importer assembles the parts into one value.

State: pm:blocked → pm:queue. priority:p2, domain:spec and area:records are unchanged, and there is no assignee.

[objectstack-fleet]

Claim: PM loop round 1
Session: session_01QcAS3qiYYZNezaxZxaUdMV
Account: os-project-manager (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-20149-import-mapping-compound-parts
Worktree: objectstack-issue-20149
Domain: domain:spec (the same cross-domain exception path as #20150, per triage 5853335141)
Seat: domain:spec#2 (seat post #18549)
File surface:

• packages/spec/src/data/import-mapping-target.ts: the ONE marked compound-part arm in judgeImportMappingTarget, the part-name set read from the value schema, and its tests.
• packages/rest/src/import-mapping.ts / import-prepare.ts: assembling a row's parts into one compound value, and their tests, including the integration pin.
• packages/lint/src/validate-mapping-target-fields.ts: its message ("a dotted path into a field's value is not a target"), and its tests.
• The body of content/docs/data-modeling/import-mappings.mdx, only where a sentence turns false.
• .changeset/.
• ⛔ Not that page's frontmatter (PR docs(content): apply the approved search-intent title rule to 169 authored pages, short nav labels kept via navTitle #20170). ⛔ No second predicate. ⛔ Not rest-server.ts. ⛔ Not objectql.
  Stop on a breach and explain it in the report.
  Container & model: M, mode:subagent, model: default judgment tier (a clause-② widening of the target vocabulary; built at the default tier, reviewed at tier)
  Clause-②: yes
  Thread-read: 5855100129
  Serial constraints cleared: read at 2026-09-27T10:40Z — Open-PR census (12 open PRs): none touches the import-mapping target verdict, the rest import files or the lint rule. PR #20170 edits only the frontmatter of import-mappings.mdx, and PR #17076 (Version Packages) only changesets. PR #20208 (#20150), which this card extends, merged as 7e7fab738f on origin/main 7e7fab738f. No in-flight claim names these files.

---

Scope, restated from the dev contract: 「范围 = 这张 issue,别无其它。」 The ruling is 5852138019 (A): a target may name a declared part of a compound field; the importer assembles the parts into one value; the part names are the closed set the value schema declares.