Repository navigation
Commit c3842ac
feat(spec): a lookup field declares which fields a pick fills (lookupAutofill) (#28244)
domain:spec#1 · os-tesla · session_01L9qibwb6hBqszPTYJobitm
<!-- claude-projects-attribution: {"github_login":"os-tesla"} -->
_Requested by **Tesla** · [project
thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoVaESC6HURrqfbfYJPCW9Nm)_
Fixes #27945
Clause-②: yes (widening)
Metadata-protocol: added
Skills-docs: follow-up #28246
## 维护者速读
- 改了什么:查找字段新增 `lookupAutofill`
声明,写明「选中一条记录后,用它的哪个字段填本记录的哪个字段」(例:报价行选产品,`unit_price ←
list_price`);规范侧在解析时和 `os validate` / `os build` 时校验,界面侧填值是后续 ui 卡。
- 为什么改:HotCRM 报价行的销售价只能在保存后由服务端钩子补上,表单里选完产品看不到价格;平台没有任何元数据能声明「选查找就带出字段」。
- 风险与回滚:纯新增可选键,现有元数据零影响;明细网格 `autofill` 列键的默认与语义不变(有对照测试)。回滚即 revert 本
PR。
- 先看:`packages/spec/src/data/field.zod.ts` 的 `lookupAutofill`(describe
里的覆盖规则)、`packages/spec/src/stack.zod.ts` 的
`lookupAutofillTypeMismatch`(类型兼容表)、`packages/spec/src/data/object.zod.ts`
的 `refuseDishonestLookupAutofill`。
- 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run
src/data/field-lookup-autofill.test.ts`,预期 18/18 通过。
- 需要你做的:无,席位落地。
## What changes
**The declaration: `FieldSchema.lookupAutofill`.** A single-value
`lookup` / `master_detail` field may declare `[{ target, source,
overwrite? }]`. A pick in the lookup copies the picked record's `source`
field (a field of the `reference` object) into this record's `target`
field. HotCRM's quote line declares it on its product lookup as `[{
target: 'unit_price', source: 'list_price' }]`. A pair is a closed shape
(`strictObject`, with alias prescriptions `from` → `source`, `field` →
`target`, `replace` → `overwrite`, and a few more), and the list is
`.min(1)`.
**The overwrite rule, stated in the describe.** A pick never replaces a
value somebody wrote. The target is filled only while it is empty or
still holds the value an earlier pick filled in, so a value the user
typed, or one the record already stored, stays. A pair that declares
`overwrite: true` says otherwise out loud and replaces the target on
every pick. This is the HotCRM server hook's own rule moved to the form:
its negotiated `unit_price` is defaulted only when blank and never
overwritten on update.
**Placement: the field, not a form view.** The record form draws a field
from its definition whichever form shows it: a declared form view, a
`formViews` entry, or the derived form an object without one gets. The
inline line-item grid hydrates its columns from the same child field
definitions (`hydrateColumns`). So the field is the one home both
readers reach. A form-view key would be invisible to the grid and to
every other form of the object.
**Relation to the grid column key `autofill`, which is unchanged.**
`InlineGridColumnSchema.autofill` keeps its contract: it governs only
the grid's implicit same-named copy, on by default
(`GridField.tsx#lookupAutofillPatch` overwrites with it today). A
declared pair applies in a grid column over the field too, under its own
overwrite rule, and takes its target out of the same-named copy, so one
target never has two writers on one pick. `autofill: false` still
switches off only the same-named copy. The describe says this, and a
control test pins the column key's parse and its describe byte-for-byte.
**Three doors judge it, each with a located refusal:**
| Door | Refuses | Code + path |
|:---|:---|:---|
| `FieldSchema` superRefine | the key off `lookup` / `master_detail`; on
`multiple: true` | `custom` at `lookupAutofill` |
| `ObjectSchema` superRefine (`refuseDishonestLookupAutofill`) | a
target that is the lookup itself, not a declared field, `readonly`,
computed (`formula`, `summary`, `autonumber`, or an `expression`), or
named twice | `custom` at `fields.FIELD.lookupAutofill.N.target` |
| `defineStack` cross-reference pass (`collectLookupAutofillErrors`) | a
source the referenced object does not declare, an `internal` source, a
source whose value the target cannot hold |
`STACK_CROSS_REFERENCE_INVALID` (422), one finding per pair, prefixed
`Object 'O' field 'F' lookupAutofill[N].source:` |
The first two run at every parse, the save door included. The third runs
at `os validate` / `os build`, because only the stack holds the
referenced object. It follows `collectHydratedInlineColumnErrors`: a
referenced object the stack does not declare is not judged, and neither
is an undeclared source that is one of the injected audit columns
(`created_at`, …).
**Type rule** (`lookupAutofillTypeMismatch`): the same type with the
same multiplicity; a string-valued source (`text`, `textarea`, `email`,
`url`, `phone`, `markdown`, `richtext`, `html`, `autonumber`) into a
plain text target; `number` and `currency` into each other; a
relationship only into a relationship over the same object. A `formula`
source is judged by its `returnType`. A `summary`, or a formula with no
`returnType`, is not judged.
**Generated artefacts:**
`content/docs/references/data/{field,object}.mdx`,
`content/docs/references/system/migration.mdx`,
`packages/spec/authorable-surface/data.json`,
`docs/audits/2026-07-unknown-key-strictness-ledger.counts/data.md` (one
new strict site), `packages/spec/liveness/state-counts/field.md`.
**Liveness:** `liveness/field.json` gains a `planned` row (with `target`
/ `source` / `overwrite` children), naming the producer (HotCRM's quote
line) and the consumer (the ui card: `LookupField` and `GridField`). No
`authorWarn`, on the `referenceDeletedWhen` precedent. A warned field
row would reopen the lint's field walk, which is outside this card's
surface.
**Form ledger:** `metadata-form-zod-reconciliation.test.ts` gains an
`omit` row for `field.lookupAutofill` (planned, not yet read), beside
`conditionalFormatting`.
**Changeset:** `.changeset/27945-lookup-pick-autofill.md`,
`@objectstack/spec` minor, with both declaration lines.
**Not in this PR (the ui half).** The record form's lookup widget and
the line-item grid writing the declared targets on pick are a separate
`domain:ui` card. This PR does not touch `ui/`.
## Tests
`packages/spec/src/data/field-lookup-autofill.test.ts`, 18 cases, each
refusal pinned by its code and its path (never by the prose around it):
- **Field half:** accepts on `lookup` and `master_detail` (control);
refuses the key on a `text` field and on a `multiple: true` lookup
(`custom` at `lookupAutofill`); refuses an empty list (`too_small`), a
non-snake_case name (`invalid_format` at `lookupAutofill.0.target`) and
an unknown key, whose message names `source` (`unrecognized_keys` at
`lookupAutofill.0`).
- **Target half:** the HotCRM shape and three target kinds parse clean
(control); the lookup itself, an undeclared target, a `readonly` target,
a `formula`, an `autonumber`, a stored field with an `expression`, and a
target named twice (refused at the later pair, index 1) are each one
`custom` issue at `fields.crm_product.lookupAutofill.N.target`. The
registered `object` type schema (the save door) refuses the same way.
- **Source half:** the HotCRM shape and seven compatible pairings build
clean (control), as do an unresolved referenced object and an injected
audit column; an undeclared source, an `internal` source, and five type
mismatches (`text` → `currency`, `number` → `boolean`, a lookup over
another object, a list → a single value, a `currency` formula →
`boolean`) each raise one `STACK_CROSS_REFERENCE_INVALID` (422) finding
at `lookupAutofill[N].source`.
- **Control, grid `autofill` unchanged:** a lookup column still parses
with `autofill: true` and `false`, an identity-only column still parses,
the key's describe is pinned byte-for-byte, and a grid column refuses
`lookupAutofill` (the pairs live on the field only).
Also re-run on the merged head: `packages/spec` vitest over `src/data`,
`src/stack*`, `src/compose-stacks*`, `src/define-stack*`,
`src/inline-grid-column-carriers.test.ts` and
`src/system/metadata-form-zod-reconciliation.test.ts`. The result was
Test Files 200/200 and Tests 6051 passed, 1 todo. `pnpm --filter
@objectstack/spec typecheck` passed (exit 0), and so did `pnpm --filter
@objectstack/spec build` (no new dropped-refinement site: the checks sit
in the existing `FieldSchema` / `ObjectSchema` superRefines).
## Acceptance notes
- **The publish-time door, measured.** The order asked for the declared
map to be validated "at publish". Inside `packages/spec` there are two
doors. The parse runs at every door, the metadata save included, and it
judges the field half and the target half. The stack cross-reference
pass runs at `os validate` / `os build` only ("No wire door raises it",
in `StackCrossReferenceError`'s own docblock), and it judges the source
half. A runtime metadata save therefore judges the target and not the
source. The runtime publish gate's object-aware field-ref checks live in
`@objectstack/lint` (`validate-object-field-refs.ts`), which is outside
this card's surface. Extending that rule to `lookupAutofill[].source`
would close the gap for the save door. I am noting that here and not
filing it: an unjudged source fills nothing, and a refusal at `os build`
already covers every package-authored stack.
- **`objectExtensions`.** A `lookupAutofill` declared on a field that an
object extension adds is judged by the field half and by the source half
(the stack pass merges extension fields by name). Its target half is not
judged, because `ObjectExtensionSchema` has no view of the base object's
field map. This is the same reach as `referenceDeletedWhen`.
- **A `readonly` target is refused, by design.** HotCRM's line
`list_price` is `readonly` and is stamped by its server hook. So the
HotCRM declaration is `unit_price ← list_price` only, and `list_price`
keeps arriving from the hook on save. Filling a readonly field on the
form would show a value that the save then strips.
- **Field-level security is not judged at authoring.** A source the
reader cannot read (field `requiredPermissions`, or a permission set
marking it non-readable) arrives masked or absent at run time. The ui
half should read an absent value as "nothing to fill". `internal` is
judged because it is absent for every reader.
- **The grid's same-named copy overwrites; a declared pair does not.**
This PR does not change the grid's `autofill` behaviour. The ui card
applies the declared pairs under this key's overwrite rule and takes
each declared target out of the same-named copy, as the describe states.
The contract review can judge whether that relation is the right one.
- **Out of scope, by the order:** the ui half (the record form's
`LookupField` and `GridField` writing the declared targets on pick) is
the follow-up `domain:ui` card, which the seat files. The `Skills-docs:`
line above names the two teaching files owed with it.
## Verification
Every reading below was taken on head `4c70e71e`, which is `origin/main`
`7c3cc889` merged into the branch. The diff against `main` is the same
13 paths as before the merge.
<details><summary>Derived gates: 107/107, all exit 0, reconciled with
<code>dispatch-gates --ran</code> (0 NOT-MEASURED)</summary>
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 107 families from 13 changed paths
at `4c70e71e`. The list is identical to the one derived before the
merge, at `6ea314a6`.
- Each family ran with `</dev/null`, and each exit code was recorded
before any pipe. 106 exited 0 in the sweep. `check:skill-examples`
answered exit 3 (PREREQUISITE NOT MET) because the merge's spec rebuild
left the `client-react` closure stale. After `turbo run build
--filter='@objectstack/client-react...'` it exited 0.
- `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--ran FILE` printed: `✓ dispatch-gates --ran: 107 derived famil(ies)
accounted for — 107 run, 0 NOT-MEASURED`.
- On the pre-merge head `6ea314a6`, the same 107 also all reached exit
0. Seven exit-3 prerequisites needed workspace dists, and
`check-plugin-teardown-shape --self-test` needed its pinned commit
fetched. `check:type-check-debt` needed a longer window than the first
sweep's per-gate timeout.
</details>
<details><summary>Spec artefacts, build and types</summary>
- `pnpm --filter @objectstack/spec build` exited 0. No new
dropped-refinement site, and the baseline is unchanged.
- `pnpm --filter @objectstack/spec check:generated` reported all 14
artefacts current, after `--fix` regenerated the three it proved stale
(`check:docs`, `check:strictness-ledger`, `check:liveness`), plus
`gen:docs` for `object.mdx` after the merge.
- `pnpm --filter @objectstack/spec typecheck` exited 0 (src, scripts and
the test layer).
</details>
<details><summary>Local-only families (not in the derivation; machine
state, reported only)</summary>
- `pnpm check:skill-frame-freshness` exited 0.
- `pnpm check:dev-prereqs` exited 1, on machine state only: 29 `ui/`
workspace packages have no `dist/` in this container, because the `ui/`
tree was not built. This diff touches no `ui/` path.
</details>
Dogfood: not run. The PR title carries no `!` and `Clause-②` carries the
`(widening)` arm.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01L9qibyU9JHYh6atGVnEXr3)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 744ad0a commit c3842ac
17 files changed
Lines changed: 688 additions & 8 deletions
File tree
- .changeset
- content/docs/references
- data
- system
- docs/audits/2026-07-unknown-key-strictness-ledger.counts
- packages
- drivers/driver-sql/src
- metadata-core/src
- metadata-protocol/src
- spec
- authorable-surface
- liveness
- state-counts
- src
- data
- system
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
86 | 86 | | |
87 | 87 | | |
88 | 88 | | |
| 89 | + | |
89 | 90 | | |
90 | 91 | | |
91 | 92 | | |
| |||
224 | 225 | | |
225 | 226 | | |
226 | 227 | | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
227 | 236 | | |
228 | 237 | | |
229 | 238 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
264 | 264 | | |
265 | 265 | | |
266 | 266 | | |
| 267 | + | |
267 | 268 | | |
268 | 269 | | |
269 | 270 | | |
| |||
629 | 630 | | |
630 | 631 | | |
631 | 632 | | |
| 633 | + | |
632 | 634 | | |
633 | 635 | | |
634 | 636 | | |
| |||
0 commit comments