`crm_contact` models a postal address as five flat text fields while `crm_account` and `crm_lead` use `Field.address()` — and AGENTS.md's own guidance names `Field.address()` for exactly this

[os-steve]

Blocked-by: objectstack-ai/objectstack#20149

Observation-class finding, noticed while working #1827 (which gave the five flat fields their missing form surface). ⛔ Deliberately not changed there — this is a data-model question with an importer contract and a migration behind it, not a form-layout fix.

The inconsistency

Three objects in this app carry a postal address, and they are modelled two different ways.

object	field	shape
crm_account	billing_address	Field.address({ … }) — one structured value with street / city / state / postalCode / country parts
crm_lead	address	Field.address({ … })
crm_contact	mailing_street · mailing_city · mailing_state · mailing_postal_code · mailing_country	five independent text / textarea fields

AGENTS.md's Field Type Guidance table takes a side:

| Mailing address | Field.address() | Structured postal address |

So the contact is the outlier against both its sibling objects and this repo's own written guidance.

Why it may nevertheless be deliberate

src/mappings/contact_import.mapping.ts states the flat shape as a decision, in its header:

"Address lands in the flat mailing_* text fields, which is why contacts (unlike accounts and leads) carry address columns in their template."

and src/mappings/account_import.mapping.ts refers to the same split from the other side. So somebody knew. What is not on the record is the reasoning — the comment states the consequence (contacts get five CSV columns) rather than the reason, and no ADR or ruling is cited. A reader today cannot tell a considered modelling choice from an accident that was later described.

There is also a plausible historical reason worth checking before anyone acts: #664 (closed) reported Field.address() values rendering as raw JSON on the detail page. If the flat shape was chosen to dodge that renderer, the premise may have expired — that would need re-measuring against the pinned @objectstack/console@17.4.0 rather than assumed in either direction.

What a change would actually cost

Not a rename. Converting crm_contact to Field.address() moves:

• the object schema and the mailing_address field group;
• the import mapping and the shipped assets/import-templates/contacts.csv — a customer-facing contract, five columns collapsing to one structured target;
• the contact form section added by The five crm_contact.mailing_* fields: the CSV importer writes them and the authored contact form may show none of them — clear the last 5 field-no-consumers warnings blocking #1581 (epic #1579) #1827, and the synthesized detail screen;
• field labels in all four locales, which are currently five rows per locale;
• content/docs/sales/contacts.mdx and its .zh-Hans / .zh-Hant siblings, which describe "five separate fields" by name;
• existing data.

That is why this is filed rather than done, and why it wants a decision before an implementation.

What is being asked for

A ruling on which shape crm_contact should carry, recorded where the next reader will find it:

• keep the flat fields — then say why in contact.object.ts, so the deviation from AGENTS.md is an authored decision rather than a silent one, and consider whether the guidance table needs a caveat;
• convert to Field.address() — then it is a migration card with the surfaces above enumerated, and the importer contract change needs its own call.

⛔ This finding takes no side. It records that the two objects disagree, that the guidance names one of them, and that the reason is nowhere on the record.

Refs: #1827 (where it was noticed) · #664 (the address renderer defect, closed).

---

Generated by Claude Code

[hotlong]

Ruling: batch #163 item 3 · convert (crm_contact models its mailing address as one Field.address() like crm_account and crm_lead, per AGENTS.md's own field-type guidance; re-measure #664 first; the shipped import template keeps its five columns, mapped into the compound field's parts; existing data converted once) · maintainer 「163 同意」 2026-09-18T14:09Z

Director seat, summon #24, session_01Wj1HUjzyeiBQ8atRf1ZhaL. Presented in detail with the recommendation convert; the maintainer agreed. Facts (this card): three objects carry a postal address, two as Field.address() and the contact as five flat mailing_* text fields; AGENTS.md's Field Type Guidance names Field.address() for a mailing address; the only record of the flat choice is a mapping-file comment stating its consequence, not its reason; #664 (address values rendering as raw JSON, closed) is the plausible historical cause and must be re-measured against the pinned console before acting. Mainstream: Salesforce Contact.MailingAddress is a compound field, the same shape as Account.BillingAddress.

Ruling — convert

1. Precondition: re-measure Address fields render as raw JSON on the record detail page #664 on the pinned @objectstack/console — a Field.address() value must render as a unit on the contact detail page. If it does not, stop and report; the conversion waits on the renderer, ⛔ not on a flat-field workaround.
2. crm_contact declares mailing_address: Field.address({ … }); the five mailing_* fields retire in the same change (ADR-0049 shape, with the app's own retirement discipline).
3. Import contract: assets/import-templates/contacts.csv keeps its five customer-facing columns; contact_import.mapping.ts maps them into the compound field's street / city / state / postalCode / country parts. ⛔ The customer's template does not change.
4. The The five crm_contact.mailing_* fields: the CSV importer writes them and the authored contact form may show none of them — clear the last 5 field-no-consumers warnings blocking #1581 (epic #1579) #1827 form section renders the one field; labels collapse from five rows per locale to one; content/docs/sales/contacts.mdx and its .zh-Hans / .zh-Hant siblings say one structured field; existing rows are converted once by a one-off system write.
5. The reason is recorded in contact.object.ts in one sentence, so the next reader sees an authored decision.

⛔ 保留平铺 would keep the app's own guidance contradicted by one of three objects.

Four-facet reading: ① three objects, one shape, the repo's guidance holds; ② a contact's address is an everyday field; ③ an AI following the guidance no longer hits an exception; ④ convergence to an existing shape, no new one.

Execution

needs-user-decision → pm:queue; metadata stays. Covers #1199's five mailing_* rows. Clause-②: no.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round R64 (serial dispatch, maintainer instruction verbatim: 「串行派发」) · 2026-09-25T13:59Z
Session: session_01X8U3asekbiC7yWoEPWR4Dg
Branch: claude/issue-1836-contact-mailing-address
Worktree: hotcrm-issue-1836
Domain: repo:hotcrm (single-lane repo — no domain:* taxonomy)
Seat: repo:hotcrm#1
File surface: src/sales/objects/contact.object.ts, src/sales/mappings/contact_import.mapping.ts, src/sales/views/contact.view.ts, src/sales/translations/{en,zh-CN,es-ES,ja-JP}/objects.customer.ts, contact seeds under src/sales/data/ if they carry mailing_*, a one-off conversion script in the scripts/backfill-*.ts shape, content/docs/sales/contacts{,.zh-Hans,.zh-Hant}.mdx, affected tests, one .changeset/. ⛔ assets/import-templates/contacts.csv does NOT change (ruling item 3). src/sales/mappings/account_import.mapping.ts only if it truly depends on contact's mailing_* (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — default judgement tier, hand-picked (dispatch-gates --tier refuses hotcrm paths from the objectstack checkout)
Clause-②: no
Thread-read: 5731202390
Serial constraints cleared: open PRs — #1956 (src/sales/profiles/**, account.hook.ts, revenue objects, docs administration/revenue), #1960 (#1828: revenue line-item hooks, scripts/backfill-line-number.ts, tests), #1950 (src/sales/objects/opportunity*, epic). None touches contact.object.ts, the contact mapping/view, or objects.customer.ts; #1950's file list does not include objects.customer.ts. #1902 (seed pricing, src/sales/data/) is queued behind this card.

[objectstack-fleet]

os-dev-report
{
"issue": 1836,
"status": "blocked",
"branch": "claude/issue-1836-contact-mailing-address",
"pr": null,
"session": "session_01X8U3asekbiC7yWoEPWR4Dg (subagent; parent's id, as named in claim 5833663897)",
"premise_still_valid": true,
"summary": "Card premise holds (crm_contact still carries five flat mailing_* text fields on origin/main c881114; account/lead use Field.address). Ruling precondition 1 PASSES: on pinned @objectstack/console 17.4.0 a Field.address value renders as one unit on the contact detail page (#664 has expired). PM mechanism assumption A1 is FALSIFIED: the 17.4.0 importer cannot write a compound field's parts from separate CSV columns. A mapping targeting mailing_address.street / .city / .state / .postalCode / .country fails every row of the unchanged contacts.csv on commit (50/50 INVALID_FIELD: Unknown field 'mailing_address.street' on object 'crm_contact'), while the same request as dryRun reports 44 created. Per the dispatch (no workaround, it becomes an upstream card) and AGENTS.md section 2 (no landing the half we can land now), I stopped: no code commit, no PR. Ruling item 3 (template keeps five columns, mapped into the parts) cannot be honoured on 17.4.0, so the conversion waits on an upstream importer capability; the seat files the platform card and this one takes Blocked-by.",
"ruling_quoted": [
"1. Precondition: re-measure #664 on the pinned @objectstack/console - a Field.address() value must render as a unit on the contact detail page. If it does not, stop and report; the conversion waits on the renderer, not on a flat-field workaround.",
"2. crm_contact declares mailing_address: Field.address({ ... }); the five mailing_* fields retire in the same change (ADR-0049 shape, with the app's own retirement discipline).",
"3. Import contract: assets/import-templates/contacts.csv keeps its five customer-facing columns; contact_import.mapping.ts maps them into the compound field's street / city / state / postalCode / country parts. The customer's template does not change.",
"4. The #1827 form section renders the one field; labels collapse from five rows per locale to one; content/docs/sales/contacts.mdx and its .zh-Hans / .zh-Hant siblings say one structured field; existing rows are converted once by a one-off system write.",
"5. The reason is recorded in contact.object.ts in one sentence, so the next reader sees an authored decision."
],
"measurement_664_browser": "PASS on @objectstack/console 17.4.0 (rest 17.4.0). Experimental tree: contact.object.ts with mailing_address: Field.address({ label: 'Mailing Address', group: 'mailing_address' }), view section fields [{ field: 'mailing_address', span: 'full' }]. Contact inserted via POST /api/v1/data/crm_contact/import format json with a nested mailing_address object (1/1 created; read-back returns the object with street/city/state/postalCode/country). Headless Chromium (/opt/pw-browsers/chromium) at /console/apps/app.objectstack.hotcrm/crm_contact/record/ID: the Mailing Address section shows one field MAILING ADDRESS = '12 Harbour Way, Austin, TX 78701, USA'; probe RAW_JSON_PRESENT false (no '"street":' and no '[object Object]' in body text). Screenshot kept in the session scratchpad.",
"measurement_import_unchanged_csv": "A1 FALSIFIED on 17.4.0. Fresh dev DB, accounts.csv imported first via crm_account_import (50/50 ok). Then the UNCHANGED contacts.csv via POST /api/v1/data/crm_contact/import {format:csv, mappingName:crm_contact_import} with targets mailing_address.street/.city/.state/.postalCode/.country: commit => total 50, ok 0, errors 50, every row code INVALID_FIELD 'Unknown field mailing_address.street on object crm_contact'. dryRun:true on the same body => ok 44, errors 6 (only the HR department rows), i.e. the dry run predicts success the commit refuses. Mechanism (read in node_modules/@objectstack/rest/dist/index.js, src/import-mapping.ts applyMappingToRows): transforms none/lookup/constant/map/split/join each assign mapped[target] as one flat key; nothing composes a nested object, and coerceRow passes a key with no field meta through untouched, so the engine sees a literal 'mailing_address.street' key. join into mailing_address would produce a string, which account_import.mapping.ts already records as rejected per row ('expected object, received string', objectstack#4633). pnpm validate accepted the dotted targets with no diagnostic (exit 0). Control: the engine itself accepts the compound value (nested JSON row, 1/1 created), so the gap is the mapping layer only. Baseline on main's flat mapping, same CSV: 44 created, 6 failed (HR, see findings), mailing_street..mailing_country populated.",
"measurement_conversion": "NOT MEASURED: one-off conversion script, reason: stopped at A1 before implementation; no script written.",
"tests": "NOT MEASURED: verify chain (validate, typecheck, lint, lint:i18n-gate, hygiene, hygiene:tokens, build, test), token ratchet before/after, lint field-no-consumers before/after - reason: no code change to verify (blocked at A1; tree restored, git diff HEAD empty). Only run: pnpm validate on the experimental tree, exit 0 (warnings for the orphaned mailing* translation keys; none for the dotted mapping targets).",
"files_changed": [],
"deviations": [
"Empty branch claude/issue-1836-contact-mailing-address pushed at c881114 (== origin/main at dispatch) as the rule-1 write probe; left in place as the claim's landing marker, carries no commits.",
"The baseline import (flat mapping) ran against a server that was a reload of the first dev instance, not a fresh DB (the first objectstack dev watcher's child survived my kill of the npx PID and hot-reloaded after I restored the tree; accounts therefore read 'updated 50'). Metadata was baseline (flat mailing_* populated on read-back); verdict unaffected. All dev-server PIDs I started were killed by PID afterwards.",
"No PR opened, so no label-write and no Fixes line; the claim's file surface was not touched in any commit."
],
"mcp_calls": "0",
"api_writes": "2 - git push of the empty branch (not REST); POST /repos//issues/1836/comments (this os-dev-report, via the fleet-write relay)",
"open_questions": [
{
"question": "Ruling item 3 needs the platform importer to compose a compound (address) value from separate CSV columns; 17.4.0 cannot. How does #1836 proceed?",
"options": [
"A: file the upstream card (objectstack: mapping fieldMapping target into a compound field's part, e.g. dotted target or a compose transform, plus the dry-run/commit disagreement), put Blocked-by on #1836, resume the original ruling once the pinned @objectstack/* carries it",
"B: maintainer revisits item 3 (template changes, or address columns dropped from the contact template like accounts)",
"C: land items 1,2,4,5 now and leave import broken - excluded by AGENTS.md section 2 and the dispatch"
],
"recommendation": "A, because the ruling is explicit that the customer template does not change and AGENTS.md section 2 forbids landing the half; the engine already accepts the compound value (measured), so the gap is narrow and upstream-shaped."
}
],
"out_of_scope_findings": [
"class: a - reach: public door POST /api/v1/data/crm_contact/import with mappingName crm_contact_import and the shipped assets/import-templates/contacts.csv on main: 6 of 50 rows fail invalid_option 'Department: "HR" is not a known option' (rows 7,15,23,31,39,47; option is value hr / label Human Resources; importer matches value exactly or label case-insensitively) - the app's own customer template is rejected by its own picklist; repo hotcrm; dedupe words: contacts.csv HR department invalid_option import template",
"class: a (platform, for the upstream card) - reach: same public door, dryRun:true with a dotted fieldMapping target reports ok 44 while the commit fails 50/50 INVALID_FIELD; Seam: spec:defineMapping fieldMapping[].target -> runtime:@objectstack/rest import-mapping.ts applyMappingToRows / engine insert; the dry run does not predict the commit verdict (sibling of objectstack#4633); dedupe words: import dry run INVALID_FIELD dotted target compound address mapping",
"class: c (platform) - reach: named producer contact_import.mapping.ts experimental target 'mailing_address.street' - pnpm validate (objectstack validate 17.4.0) exit 0 with no diagnostic for a fieldMapping target that names no field, which the runtime rejects on every row; dedupe words: mapping target unknown field validate lint fieldMapping",
"carrier: docs/requirements/0004-contact-buying-centre-map.md line 33 names the 'structured mailing_* block' - whoever lands the #1836 conversion; noted, not filed"
]
}

---

Generated by Claude Code

[objectstack-fleet]

Release: session session_01X8U3asekbiC7yWoEPWR4Dg · reason: the dev stopped correctly at the ruling's import contract (report 5833767403) · destination: pm:blocked, Blocked-by: objectstack-ai/objectstack#20149, unassigned · 2026-09-25T14:10Z

Why this waits on the platform (measured on 17.4.0)

• Ruling precondition 1 passes: a Field.address() value renders as one unit on the contact detail page, so Address fields render as raw JSON on the record detail page #664 no longer applies.
• Ruling item 3 cannot be met: the 17.4.0 importer writes each mapped column to one flat key. The unchanged contacts.csv mapped into mailing_address.street … .country fails 50/50 on commit (INVALID_FIELD), while dryRun reports 44 ok. The engine does accept the compound value itself (a nested JSON row imports and reads back), so only the mapping layer is missing.
• ⛔ No half landing (AGENTS.md §2): converting the field now would break the customer template the ruling says must not change.

Filed upstream as objectstack-ai/objectstack#20149 (capability, plus the dry-run≠commit and validate-silence observations). The ruling stands unchanged and resumes as written once the pinned @objectstack/* carries it.

Also recorded by the dev, not filed here: the shipped contacts.csv has 6 of 50 rows rejected today (Department: "HR" is not a known option; the option's value is hr, label "Human Resources"). This is on main independent of this card and goes to the maintainer.