docs(skills): field-types rule states a formula's five returnType members and the currencyConfig a currency formula carries (#22743) (#22798)

Fixes #22743

Clause-②: no

`skills/objectstack-data/rules/field-types.md` taught a formula's
`returnType` as the four-member set `'number' | 'text' | 'boolean' |
'date'` (the `formula` table row, line 129) and its formula example said
`(no 'currency')` (line 253). `@objectstack/spec` declares five members:
`packages/spec/src/data/field.zod.ts:1727` is `returnType:
z.enum(['number', 'text', 'boolean', 'date', 'currency'])`, and `:1786`
reads `currencyConfig` for a currency field and for a formula whose
`returnType` is `currency`, the same `CurrencyConfigSchema`, absent
meaning `dynamic`, the tenant default currency. Both sites now state the
five-member set and name `currencyConfig` as the carrier.

## What changed

- `skills/objectstack-data/rules/field-types.md`
- the `formula` table row: `returnType` lists `'currency'` as its fifth
member and the cell adds `'currency' carries its own currencyConfig`
(one row, 0 net lines).
- the formula example: the `returnType` comment reads `'number' | 'text'
| 'boolean' | 'date' | 'currency' (money; own currencyConfig)`; `(no
'currency')` is gone.
- the example's trailing `CEL — record. prefixes required` comment is
removed: it restated the table cell two sections above (`expression`
(CEL, `record.` prefixes)), and the deletion pays the file's token
ratchet (headroom was 12 tokens, 51 bytes; the two edits cost 86 bytes
gross, 46 net after the deletion).
- the example's value stays `returnType: 'number'`, and nothing is said
about how a currency formula renders (the renderer half is
objectstack-ai/objectui#12111, not shipped), as the card requires.
- `.changeset/22743-field-types-currency-returntype.md`:
`@objectstack/skills` `patch`. On `origin/main` `a8f24b092`,
`packages/skills/` exists (`@objectstack/skills` 17.7.0, in the
changeset `fixed` group); its `build` copies `skills/**` into
`dist/skills/...` and `files` ships `dist`, so this text is published
and `skip-changeset` does not apply.

## 维护者速读(草稿)

**改了什么。** 对外发布的技能包 `objectstack-data` 里 `rules/field-types.md`
的两处文本:formula 字段的 `returnType` 成员从四个改为五个(加上 `'currency'`),并写明
`'currency'` 公式自带 `currencyConfig`(与 currency 字段同一结构)。为了不突破技能文本的 token
上限,删掉了示例里一行与上方表格重复的注释(CEL / `record.` 前缀)。另加一个 `@objectstack/skills` 的
patch changeset。

**为什么改。** spec 已在 `main` 上把 `returnType` 扩成五成员(#22727 对应的 PR
#22733),技能文本仍教四成员且明写 "no 'currency'"。读这份文本的 AI 作者会给金额公式打上
`number`,与平台事实相反。

**风险与代价(含回滚)。** 纯文本改动,不碰运行时与 schema;`rules/field-types.md` 的 token 余量从
12 降到 1,后续改这份文件要先删再加。不教"货币公式按货币渲染"(渲染半边 objectui#12111 未发货)。回滚:revert 本
PR 即可,无数据影响。

**席位意见。** (留空)

**你要做的。** Tier H(`skills/**`):审阅两处措辞是否准确、是否同意用删掉示例的 CEL 注释来支付 token;同意则
APPROVE,由席位走队列落地。

## Verification (head `6fbe9810b`, a merge of `origin/main` `a8f24b092`;
delta vs `origin/main` is exactly the two files above)

Gates. `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derives 40 commands at `6fbe9810b`
(byte-identical to the list derived at `7237ed7cb`); each ran alone with
its exit captured before any pipe; `--ran` with the recorded codes
reconciles 40 derived, 39 run, 1 NOT-MEASURED, 0 UNRUN.
- 39 exit 0, among them `node scripts/check-skills-token-ratchet.mjs`
(`54 authored bundle file(s) within their ceilings`) and its
`--self-test` (65 cases), `pnpm check:skill-identifier-liveness`, `pnpm
check:skill-frame-sync`, `pnpm check:skill-compatibility`, `pnpm
check:corpus-claim-drift`, `pnpm check:role-word`, `pnpm
check:doc-authoring`, `pnpm check:nul-bytes`, `pnpm
check:pm-governed-merges`, `node scripts/check-empty-changeset.mjs
--base origin/main`, `node scripts/check-changeset-no-major.mjs --base
origin/main`, `node scripts/check-adr-0087-registration.mjs --base
origin/main`, `node scripts/check-ci-filter-parity.mjs`, `node
scripts/check-doc-route-spelling.mjs --advisory`.
- NOT MEASURED: `pnpm check:dual-build-cjs-loads` exits 3 (PREREQUISITE
NOT MET: it loads the built entry points of every published package;
this worktree holds 35 built packages, not the whole tree; CI's Build
Core runs it after `pnpm build`). The diff touches no package source.
- Beyond the derivation, the skills lane's own checks in
`packages/spec`: `check:skill-docs` exit 0 (`Skill docs in sync`),
`check:skill-refs` exit 0 (`9 generated files in sync`),
`check:skill-examples` exit 0 (`262 prose examples type-check across 3
surface(s)`, run after the SDK build below; before it the gate refused
with exit 3 on the unbuilt `packages/client-react/dist`).
`field-types.md` carries no `os:check` marker, so none of its blocks is
in that gate's population.
- Test: `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2
src/data/currency-mode-family-closure.pin.test.ts` under the verify
lock, 1 file, 6 passed. This pin reads `field-types.md` as a
currency-mode site (legs A and B).
- Builds under the verify lock: `@objectstack/spec` (VERDICT
command-exit 0, 107 s), then the `@objectstack/client-react` +
`@objectstack/client` closure (35 tasks, VERDICT command-exit 0, 199 s).
That second build is what let `check:dts-closure`,
`check:lean-entry-closure`, `check:sourcemap-no-sources-content` and
`@objectstack/lint check:doc-formula-expressions` measure: all four
refused with exit 3 before it and exit 0 after.

Line and token budget (tokens are `ceil(utf8 bytes / 4)`, the ratchet's
own convention).
- `rules/field-types.md`: 327 → 327 lines (0 net); 12581 → 12627 bytes;
3146 → 3157 tokens against a ceiling of 3158 (headroom 12 → 1).
- `skills/objectstack-data/` as a whole (every authored file, SKILL.md,
rules, evals, references): 3811 → 3811 lines; 39280 → 39291 authored
tokens (+11), plus 1739 generator-owned tokens unchanged
(`references/_index.md`).
- the catalog's ten SKILL.md files: 4410 → 4410 lines, unchanged (none
touched; `skills/objectstack-data/SKILL.md` stays 6128/6128).
- the whole catalog: ratcheted (authored) 144191 → 144202 tokens (+11);
bundle total 155082 → 155093.

## Acceptance notes

- Not filed, a teaching choice for the maintainer: the formula example
`total = record.amount * record.tax_rate` keeps `returnType: 'number'`.
If `amount` is a currency field, `@objectstack/formula`'s
`inferFormulaReturn` stamps `{ returnType: 'currency' }` on that
expression, so the example's value reads as the very stamp the card
warns against. Switching the example to `'currency'` is outside the two
lines the card names and costs ratchet tokens the file no longer has.
- `inferFormulaReturn`'s stamping (the card's second replacement bullet)
is not taught, by the dispatch's budget-first instruction.
- `skills/objectstack-data/SKILL.md` names `returnType: 'text'` twice
(the `nameField` rows) and teaches no member set; untouched, as
required.
- The token ratchet prices each file separately (shrink-only, per file),
not a skill directory as one set; the edit was paid inside
`rules/field-types.md` either way.

objectstack-ai/objectui#12111 remains open. #22727 is not addressed
here; PR #22733 landed it.

---
_Generated by [Claude
Code](https://claude.ai/code/session_011u73oxZ5X95qrARPTeoU6v)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/22743-field-types-currency-returntype.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/skills': patch
+---
+
+fix(skills): the `objectstack-data` field-types rule names all five formula `returnType` members, `'currency'` included, and the `currencyConfig` a currency formula carries (#22743)
+
+Clause-②: no
+
+`skills/objectstack-data/rules/field-types.md` taught a formula's `returnType` as the four-member set `'number' | 'text' | 'boolean' | 'date'`, and its formula example said `(no 'currency')`. `@objectstack/spec`'s `FieldSchema.returnType` is the five-member enum `'number' | 'text' | 'boolean' | 'date' | 'currency'`, and a formula whose `returnType` is `'currency'` carries its currency in its own `currencyConfig` — `CurrencyConfigSchema`, the same shape a `currency` field declares; absent, the mode is `dynamic`, the tenant default currency. The `formula` table row and the formula example now both state the five-member set and name `currencyConfig` as the carrier. The example's `CEL — record. prefixes required` comment, which restated the table cell above it, is removed to pay the skill's token ratchet. Nothing is said about how a currency formula renders.

skills/objectstack-data/rules/field-types.md

@@ -126,7 +126,7 @@ Stored as JSON on the parent row — no separate table / FK:
 
 | Type | When to Use | Config |
 |:-----|:------------|:-------|
-| `formula` | Computed from an expression referencing other fields | `expression` (CEL, `record.` prefixes), `returnType` (`'number' \| 'text' \| 'boolean' \| 'date'`) |
+| `formula` | Computed from an expression referencing other fields | `expression` (CEL, `record.` prefixes), `returnType` (`'number' \| 'text' \| 'boolean' \| 'date' \| 'currency'`); `'currency'` carries its own `currencyConfig` |
 | `summary` | Roll-up aggregation from child records | `summaryOperations` ({ object, field, function, relationshipField?, filter? }) |
 | `autonumber` | Auto-incrementing display format ({0000} counter + optional date / {field} tokens, resets per scope) | `format` (shorthand) / `autonumberFormat` (canonical) — e.g., `"CASE-{0000}"`, `"AD{YYYYMMDD}{0000}"` |
 
@@ -249,8 +249,8 @@ import { F } from '@objectstack/spec';
 
 const total = {
   type: 'formula',
-  expression: F`record.amount * record.tax_rate`,  // CEL — `record.` prefixes required
-  returnType: 'number',   // 'number' | 'text' | 'boolean' | 'date' (no 'currency')
+  expression: F`record.amount * record.tax_rate`,
+  returnType: 'number',   // 'number' | 'text' | 'boolean' | 'date' | 'currency' (money; own currencyConfig)
 };
 ```