docs(spec): FieldSchema points a bare currency key at currencyConfig (#8163) (#9088)

`currency` has never been a declared FieldSchema key -- only `currencyConfig`
is -- but the rejection carried only the surface history line, with no
pointer to the declarable form. Adds a `guidance` prose entry (the same
`storageNotNull`-style case already on this surface, not an `aliases`
rename -- the target is a NESTED key a flat rename cannot express):
`currency` is not a field key; a fixed currency is declared as
`currencyConfig: { currencyMode: 'fixed', defaultCurrency: '...' }`. A field
without one uses the tenant default at runtime.

Accept/reject is byte-for-byte unchanged -- `currency` was rejected before
this change and stays rejected after it.


Claude-Session: https://claude.ai/code/session_01225pUjnCKWqxcc1PeqKFUq

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

Author: os-zhuang

.changeset/field-currency-guidance.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): `FieldSchema` points a bare `currency` key at the declarable `currencyConfig` form (#8163)
+
+`currency` has never been a declared `FieldSchema` key — only `currencyConfig`
+is. Writing the natural spelling was always a loud parse error, but a **bare**
+one: the rejection carried only the surface history line ("Until #4001 closed
+this shape these were dropped silently…"), with no pointer to the declarable
+form. The spelling is not hypothetical — objectui's `resolveFieldCurrency`
+reads `field.currency` first from looser grid/column configs, so it circulates
+in configs an AI author will have seen.
+
+The target is a NESTED key (`currencyConfig.defaultCurrency` under
+`currencyMode: 'fixed'`), which a flat `aliases` rename cannot express — so
+this is prose (`guidance`), the same `storageNotNull`-style case already on
+this surface: `currency` is not a field key; a fixed currency is declared as
+`currencyConfig: { currencyMode: 'fixed', defaultCurrency: '…' }`. A field
+without one uses the tenant default at runtime.
+
+Accept/reject is byte-for-byte unchanged — `currency` was rejected before this
+change and stays rejected after it; only the rejection's message gains a
+prescription.

packages/spec/src/data/field.test.ts

@@ -168,6 +168,59 @@ describe('CurrencyValueSchema', () => {
   });
 });
 
+// ===========================================================================
+// #8163 — field-level `currency` is rejected with no pointer to the
+// declarable nested form (`currencyConfig.defaultCurrency`). Same
+// `unrecognized_keys`-probing pattern as
+// `shared/visible-when-alias-guidance.test.ts`: this is prose (`guidance`),
+// not a rename (`aliases`) — the target is a NESTED key a flat rename cannot
+// express — and acceptance is byte-identical: `currency` was rejected before
+// this card and stays rejected after it.
+// ===========================================================================
+
+/** The `unrecognized_keys` message for `value`, or a loud test failure. */
+function unrecognizedKeyMessage(value: unknown): string {
+  const r = FieldSchema.safeParse(value);
+  expect(r.success, `expected REJECTION, got a successful parse of ${JSON.stringify(value)}`).toBe(false);
+  const issues = (r as { success: false; error: { issues: Array<{ code?: string; message?: string }> } }).error.issues;
+  const hit = issues.find((i) => i.code === 'unrecognized_keys');
+  expect(hit, `no \`unrecognized_keys\` issue in ${JSON.stringify(issues)}`).toBeDefined();
+  return hit?.message ?? '';
+}
+
+describe('FieldSchema — field-level `currency` key guidance (#8163)', () => {
+  const FIELD = { name: 'amount', label: 'Amount', type: 'currency' } as const;
+
+  it('`currency` stays rejected — a prescription is not an acceptance', () => {
+    expect(FieldSchema.safeParse({ ...FIELD, currency: 'JPY' }).success).toBe(false);
+  });
+
+  it('names the declarable nested form, `currencyConfig` / `defaultCurrency`', () => {
+    const m = unrecognizedKeyMessage({ ...FIELD, currency: 'JPY' });
+    expect(m).toContain('`currency` is not a field key');
+    expect(m).toContain('currencyConfig');
+    expect(m).toContain('defaultCurrency');
+    // The claim the prose makes is real — the nested form it names really parses.
+    expect(
+      FieldSchema.safeParse({
+        ...FIELD,
+        currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' },
+      }).success,
+    ).toBe(true);
+  });
+
+  it('is prose, not a rename — no `Did you mean` for `currency` (the target is a nested key)', () => {
+    const m = unrecognizedKeyMessage({ ...FIELD, currency: 'JPY' });
+    expect(m).not.toContain('Did you mean');
+  });
+
+  it('a sibling unknown key does NOT get the currency prescription (anti-vacuity)', () => {
+    const m = unrecognizedKeyMessage({ ...FIELD, totallyBogusKey: true });
+    expect(m).not.toContain('currencyConfig');
+    expect(m).not.toContain('defaultCurrency');
+  });
+});
+
 describe('FieldSchema', () => {
   describe('Basic Field Properties', () => {
     it('should accept valid field with minimal properties', () => {

packages/spec/src/data/field.zod.ts

@@ -573,6 +573,18 @@ export const FieldSchema = lazySchema(() => strictObject({
       '`columnName` was removed in the 16.x line (#2377) — the SQL driver hardcodes the physical '
       + 'column to the field key, so a custom name was ignored. External/federated objects map '
       + 'physical columns with `external.columnMap` (ADR-0062 D7).',
+    // `currency` is not, and has never been, a declared FieldSchema key — it is
+    // not a retirement, just a natural spelling with no landing key of its own
+    // (#8163). Prose rather than an `aliases` rename because the target is a
+    // NESTED key: `currencyConfig.defaultCurrency` under `currencyMode: 'fixed'`,
+    // which a flat rename cannot express. The spelling is not hypothetical —
+    // objectui's `resolveFieldCurrency` reads `field.currency` first from looser
+    // grid/column configs, so it circulates in configs an AI author will have
+    // seen.
+    currency:
+      '`currency` is not a field key — a fixed currency is declared as `currencyConfig: '
+      + '{ currencyMode: \'fixed\', defaultCurrency: \'JPY\' }`. A field without one uses '
+      + 'the tenant default at runtime.',
     referenceFilters:
       '`referenceFilters` (string[]) was removed in the 16.x line (#2377) — the lookup picker only '
       + 'ever read the structured form. Use `lookupFilters: [{ field, operator, value }]`.',