@@ -0,0 +1,21 @@
+---
+"@objectstack/spec": minor
+---
+
+fix(spec): a currency field's `precision` is its total digit count again — `precision: 18` on a fixed-USD field parses instead of being refused as a contradiction of the currency's two decimal places (#20011)
+
+Clause-②: yes (widening) — one refusal is removed from `FieldSchema`, so the accepted set grows. Nothing that parsed before is refused now, no key is renamed or retired, and the output of every previously accepted field is byte-identical.
+
+## What was wrong
+
+`FieldSchema` compared a currency field's field-level `precision` with the ISO 4217 fraction digits of its fixed currency, and refused any difference. The key is declared `Total digits (non-negative integer)`, so a DECIMAL(18,2) USD amount writes `precision: 18`. That field was refused with "currency USD has 2 fraction digits; `precision: 18` contradicts it", and the refusal told the author to write `precision: 2`, which is a total-digit count of 2.
+
+The check assumed the field-level key was the currency display width, because the Studio currency widget used to read it that way. That reading is gone. The ruled contract is that a currency amount's decimal places come from the currency and are not a field setting. No renderer reads the field-level `precision` as decimal places, and the SQL column does not read it at all.
+
+## What it does now
+
+- The field-level `precision` on a `currency` field is not compared with the currency. Any non-negative integer parses in every currency mode and is carried through unchanged.
+- `currencyConfig.precision` is a different key and is unchanged. Under `currencyMode: 'fixed'` it must still agree with the currency's fraction digits, and a contradiction is still refused at `currencyConfig.precision` with the same message.
+- `scale` on a `currency` field is still refused.
+
+Nothing to migrate. Metadata that parsed before parses the same way. A currency field that had to drop `precision` or set it to the currency's fraction digits to get through validation can now declare its real total digit count.
@@ -149,7 +149,6 @@ code lives in `currencyConfig`, never in the value.
 | Property | Type | Default | Description |
 |:---|:---|:---|:---|
 | `precision` | `number` | — | Total digits |
-| `scale` | `number` | — | Decimal places |
 | `min` | `number` | — | Minimum value |
 | `max` | `number` | — | Maximum value |
 | `currencyConfig.precision` | `number` | `2` | Decimal precision for currency |
@@ -160,13 +159,20 @@ code lives in `currencyConfig`, never in the value.
 { name: 'price', label: 'Price', type: 'currency', currencyConfig: { precision: 2, currencyMode: 'fixed', defaultCurrency: 'USD' } }
 ```
 
-A declared `precision` must agree with the currency's ISO 4217 fraction digits
-when the currency is statically known — that is, when `currencyConfig` is in
-`fixed` mode. Publish-time validation rejects the contradiction, naming both
-numbers ("currency JPY has 0 fraction digits; `precision: 2` contradicts it"):
-the yen has no minor unit to show two digits of, and `precision: 2` on a KWD
-field would silently drop the third fils digit that exists. Omit `precision`
-to let renderers derive the width from the currency itself. The rule is
+A currency amount's decimal places are its currency's ISO 4217 minor unit
+(2 for USD, 0 for JPY, 3 for KWD), not a field setting, so a `currency` field
+takes no `scale`: publish-time validation refuses the key. The field-level
+`precision` is the amount's total digit count — a DECIMAL(18,2) amount declares
+`precision: 18` — and is never compared with the currency.
+
+A declared `currencyConfig.precision` must agree with the currency's ISO 4217
+fraction digits when the currency is statically known — that is, when
+`currencyConfig` is in `fixed` mode. Publish-time validation rejects the
+contradiction, naming both numbers ("currency JPY has 0 fraction digits;
+`precision: 2` contradicts it"): the yen has no minor unit to show two digits
+of, and `precision: 2` on a KWD field would silently drop the third fils digit
+that exists. Omit `currencyConfig.precision` to let renderers derive the width
+from the currency itself. The rule is
 deliberately partial: a field in `dynamic` currencyMode has no single currency
 to check against, and currency codes outside CLDR `currencyData`
 (cryptocurrency or custom business codes) are not checked. The rule judges
 
@@ -152,7 +152,7 @@ These properties apply to **all** field types and are validated by the base `Fie
 | `min` | `number` | — | Minimum monetary value |
 | `max` | `number` | — | Maximum monetary value |
 | `currencyConfig.precision` | `number` | `2` | Decimal places (0–10) |
-| `currencyConfig.currencyMode` | `enum` | `dynamic` | `fixed` pins the field to `defaultCurrency`, and an authored `precision` must agree with that currency's ISO 4217 fraction digits; `dynamic` displays the tenant default currency (the `localization.currency` setting). Not a per-record choice |
+| `currencyConfig.currencyMode` | `enum` | `dynamic` | `fixed` pins the field to `defaultCurrency`, and an authored `currencyConfig.precision` must agree with that currency's ISO 4217 fraction digits (the field-level `precision`, total digits, is not compared); `dynamic` displays the tenant default currency (the `localization.currency` setting). Not a per-record choice |
 | `currencyConfig.defaultCurrency` | `string` | `CNY` | 3-character currency code (ISO 4217 or crypto): the field's currency under `fixed`; not the displayed currency under `dynamic` |
 
 **Default constraints:** Stored as a **bare number** (a finite numeric scalar — `valueSchemaFor` routes `currency` to `z.number().finite()`); there is no `{ value, currency }` envelope on the value path. The currency **code** is never stored per record: it is field configuration, carried by `currencyConfig` above. Precision defaults to 2 decimal places.
 
@@ -3,9 +3,10 @@
 /**
  * ISO 4217 / CLDR currency fraction digits — the static digit table behind the
  * #7918 publish-time rule (maintainer ruling 2026-08-12, Option A): a currency
- * field whose AUTHORED `precision` contradicts its statically-known currency's
- * fraction digits is rejected at parse/publish time, with a message naming
- * both numbers.
+ * field whose AUTHORED `currencyConfig.precision` contradicts its
+ * statically-known currency's fraction digits is rejected at parse/publish
+ * time, with a message naming both numbers. The FIELD-level `precision` key is
+ * not judged here: it is "Total digits", not decimal places (#20011).
  *
  * ## Provenance — CLDR `currencyData`, checked in, not probed at runtime
  *
@@ -84,12 +85,16 @@ export function currencyFractionDigits(code: string): number | undefined {
 }
 
 /**
- * The #7918 verdict, shared by BOTH anchors of the rule — the field-level
- * `precision` key (checked in `FieldSchema`'s `superRefine`) and
- * `CurrencyConfigSchema.precision` (checked pre-default inside that schema) —
- * so the two doors cannot drift apart in wording. Returns the issue message
- * when `precision` contradicts `currency`'s fraction digits, `undefined` when
- * they agree or the currency is unknown (fail-open).
+ * The #7918 verdict for `CurrencyConfigSchema.precision`, checked pre-default
+ * inside that schema (its `.superRefine`, and the `.overwrite` that decides
+ * whether the default 2 may be materialized). Returns the issue message when
+ * `precision` contradicts `currency`'s fraction digits, `undefined` when they
+ * agree or the currency is unknown (fail-open).
+ *
+ * ⛔ Not for the FIELD-level `precision` key. That key is "Total digits" — a
+ * DECIMAL(18,2) amount declares `precision: 18` — so comparing it with a
+ * fraction-digit count refuses correct metadata and prescribes a total-digit
+ * count of 2. `FieldSchema` ran this verdict on it until #20011.
  *
  * The message's first clause names both numbers, verbatim per the ruling:
  * "currency JPY has 0 fraction digits; `precision: 2` contradicts it".
 
@@ -2,10 +2,15 @@
 
 /**
  * #7918 (maintainer ruling 2026-08-12, Option A) — publish-time rejection of a
- * declared currency `precision` that contradicts the currency's ISO 4217 /
- * CLDR fraction digits, when the currency is statically known
+ * declared `currencyConfig.precision` that contradicts the currency's ISO 4217
+ * / CLDR fraction digits, when the currency is statically known
  * (`currencyConfig.currencyMode: 'fixed'`).
  *
+ * #20011 — the FIELD-level `precision` key is NOT judged by this rule. It is
+ * "Total digits" (the `p` of a DECIMAL(p, s) amount), and a currency's decimal
+ * places are the currency's, not a setting (ruling 5805782503, letter 乙). The
+ * field-level block below pins that it parses whatever the currency.
+ *
  * The rule is deliberately partial: `dynamic` currencyMode has no single
  * currency to check against and is out of reach BY DESIGN; codes outside CLDR
  * `currencyData` (crypto/custom) fail OPEN. The rule fires ONLY on an AUTHORED
@@ -222,44 +227,65 @@ describe('#11423 — the materialized precision default is never one the schema
   });
 });
 
-describe('#7918 — field-level anchor (FieldSchema.superRefine; the key has no default)', () => {
+describe('#20011 — field-level `precision` is total digits, never judged against the currency (FieldSchema)', () => {
+  // Ruling 5805782503 (letter 乙): a currency's decimal places are the
+  // currency's, not a setting — and the key's own describe is "Total digits".
+  // The #7918 check that compared this key with the fixed currency's fraction
+  // digits refused `precision: 18` on a USD amount (a DECIMAL(18,2)) and
+  // prescribed `precision: 2`; it is gone, and these pins hold it gone.
   const base = { name: 'amount', label: 'Amount', type: 'currency' as const };
+  const fixed = (defaultCurrency: string) => ({ currencyMode: 'fixed' as const, defaultCurrency });
 
-  it('rejects an authored field-level precision contradicting the fixed currency (JPY + 2)', () => {
-    const result = FieldSchema.safeParse({
-      ...base, precision: 2,
-      currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' },
-    });
-    expect(result.success).toBe(false);
-    const issue = firstIssue(result)!;
-    expect(issue.code).toBe('custom');
-    expect(issue.path).toEqual(['precision']);
-    expect(issue.message).toContain('currency JPY has 0 fraction digits');
-    expect(issue.message).toContain('`precision: 2` contradicts it');
+  it('accepts `precision: 18` on a fixed-USD field — a DECIMAL(18,2) amount — and keeps the authored 18', () => {
+    const result = FieldSchema.safeParse({ ...base, precision: 18, currencyConfig: fixed('USD') });
+    expect(result.success).toBe(true);
+    // Carried through as authored: nothing rewrites the total-digit count to
+    // the currency's fraction digits.
+    expect(result.data!.precision).toBe(18);
   });
 
-  it('accepts a field-level precision agreeing with the fixed currency (JPY + 0, KWD + 3)', () => {
-    expect(FieldSchema.safeParse({
-      ...base, precision: 0,
-      currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' },
-    }).success).toBe(true);
+  it('still accepts `precision: 2` on a fixed-USD field', () => {
+    const result = FieldSchema.safeParse({ ...base, precision: 2, currencyConfig: fixed('USD') });
+    expect(result.success).toBe(true);
+    expect(result.data!.precision).toBe(2);
+  });
+
+  it('flipped: `precision: 2` on a fixed-JPY field parses — a DECIMAL(2,0) amount — where #7918 refused it', () => {
+    const result = FieldSchema.safeParse({ ...base, precision: 2, currencyConfig: fixed('JPY') });
+    expect(result.success).toBe(true);
+    expect(result.data!.precision).toBe(2);
+  });
+
+  it('accepts a total-digit count on every fraction-digit class (0: JPY, 2: USD, 3: KWD)', () => {
+    const cases: Array<[string, number]> = [
+      ['JPY', 0], ['JPY', 12], ['USD', 2], ['USD', 18], ['KWD', 3], ['KWD', 2], ['KWD', 15],
+    ];
+    for (const [code, precision] of cases) {
+      const result = FieldSchema.safeParse({ ...base, precision, currencyConfig: fixed(code) });
+      expect(result.success, `${code} + precision ${precision}`).toBe(true);
+      expect(result.data!.precision).toBe(precision);
+    }
+  });
+
+  it('adds no currency-only total-digit coherence rule — a count below the fraction digits parses, as `precision` below `scale` does on a number', () => {
+    // Measured parity, not an endorsement of the value: no numeric type
+    // relates `precision` to its decimal places at parse, so a currency-only
+    // rule would be the one such rule, on a key no face reads.
+    expect(FieldSchema.safeParse({ ...base, precision: 1, currencyConfig: fixed('USD') }).success).toBe(true);
     expect(FieldSchema.safeParse({
-      ...base, precision: 3,
-      currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'KWD' },
+      name: 'qty', label: 'Qty', type: 'number' as const, precision: 1, scale: 2,
     }).success).toBe(true);
   });
 
-  it('no currencyConfig ⇒ no statically-known currency ⇒ no verdict', () => {
+  it('unchanged outside fixed mode: no currencyConfig, and dynamic (authored or defaulted)', () => {
     expect(FieldSchema.safeParse({ ...base, precision: 2 }).success).toBe(true);
-  });
-
-  it('dynamic (authored or defaulted) currencyMode ⇒ no verdict', () => {
+    expect(FieldSchema.safeParse({ ...base, precision: 18 }).success).toBe(true);
     expect(FieldSchema.safeParse({
       ...base, precision: 2,
       currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'JPY' },
     }).success).toBe(true);
     expect(FieldSchema.safeParse({
-      ...base, precision: 2,
+      ...base, precision: 18,
       currencyConfig: { defaultCurrency: 'JPY' },
     }).success).toBe(true);
   });
@@ -270,7 +296,17 @@ describe('#7918 — field-level anchor (FieldSchema.superRefine; the key has no
     }).success).toBe(true);
   });
 
-  it('the currencyConfig-level check reaches through the FieldSchema door (path is prefixed)', () => {
+  it('crosses the object door (ObjectSchema.create) and re-parses stably with the authored 18', () => {
+    const obj = ObjectSchema.create({
+      name: 'invoice', label: 'Invoice',
+      fields: { amount: { label: 'Amount', type: 'currency', precision: 18, currencyConfig: fixed('USD') } },
+    });
+    const reparsed = ObjectSchema.safeParse(JSON.parse(JSON.stringify(obj)));
+    expect(reparsed.success).toBe(true);
+    expect(reparsed.data!.fields.amount.precision).toBe(18);
+  });
+
+  it('the currencyConfig-level check still reaches through the FieldSchema door (a different key; unchanged)', () => {
     const result = FieldSchema.safeParse({
       ...base,
       currencyConfig: { precision: 2, currencyMode: 'fixed', defaultCurrency: 'JPY' },
@@ -280,17 +316,21 @@ describe('#7918 — field-level anchor (FieldSchema.superRefine; the key has no
     expect(issue.code).toBe('custom');
     expect(issue.path).toEqual(['currencyConfig', 'precision']);
     expect(issue.message).toContain('currency JPY has 0 fraction digits');
+    expect(issue.message).toContain('Declare `precision: 0`');
   });
 
-  it('both anchors fire independently when both keys contradict', () => {
+  it('with both keys authored, only the currencyConfig anchor fires — the field-level key raises nothing', () => {
     const result = FieldSchema.safeParse({
       ...base, precision: 2,
       currencyConfig: { precision: 2, currencyMode: 'fixed', defaultCurrency: 'JPY' },
     });
     expect(result.success).toBe(false);
-    const paths = result.error!.issues.map((i) => i.path.join('.'));
-    expect(paths).toContain('precision');
-    expect(paths).toContain('currencyConfig.precision');
+    const issues = result.error!.issues;
+    expect(issues).toHaveLength(1);
+    expect(issues[0].code).toBe('custom');
+    expect(issues[0].path).toEqual(['currencyConfig', 'precision']);
+    expect(issues[0].message).toContain('currency JPY has 0 fraction digits');
+    expect(issues[0].message).toContain('Declare `precision: 0`');
   });
 });
 
 
@@ -29,8 +29,9 @@ import {
 } from './default-value-shape';
 import { AddressSchema, FILE_REFERENCE_TYPES, MULTI_CAPABLE_TYPES, MULTI_OPTION_TYPES, REFERENCE_VALUE_TYPES } from './field-value.zod';
 // #7918 — the ISO 4217 / CLDR fraction-digit contradiction check (maintainer
-// ruling 2026-08-12, Option A). One shared verdict for both anchors: the
-// field-level `precision` key and `CurrencyConfigSchema.precision`.
+// ruling 2026-08-12, Option A), read by `CurrencyConfigSchema.precision`'s
+// anchor. The FIELD-level `precision` key is total digits and is not compared
+// against the currency (#20011 — see the note in `FieldSchema`'s superRefine).
 import { currencyPrecisionContradiction } from './currency-fraction-digits';
 import { ValueDomainSchema } from '../shared/value-domain.zod';
 
@@ -2306,31 +2307,20 @@ export const FieldSchema = lazySchema(() => {
     });
   }
 
-  // #7918 (maintainer ruling 2026-08-12, Option A): the FIELD-level
-  // `precision` key doubles as the currency display width — objectui's
-  // CurrencyField reads it, and objectui#4361 pinned authored-precision-wins
-  // there — so an authored value contradicting the statically-known currency's
-  // ISO 4217 / CLDR fraction digits is rejected at this seam too. The currency
-  // is statically known only under `currencyConfig.currencyMode: 'fixed'`
-  // (`dynamic` is out of reach BY DESIGN; a field with no `currencyConfig` has
-  // only the runtime tenant default, which is not static). This key has NO
-  // schema default, so `undefined` here IS "not authored" — the
-  // authored-vs-defaulted trap lives entirely on the `currencyConfig` twin of
-  // this check, which runs pre-default inside `CurrencyConfigSchema` itself.
-  // Unknown currency codes fail OPEN (see currency-fraction-digits.ts).
-  if (
-    field.type === 'currency' &&
-    field.precision !== undefined &&
-    field.currencyConfig?.currencyMode === 'fixed'
-  ) {
-    const contradiction = currencyPrecisionContradiction(
-      field.currencyConfig.defaultCurrency,
-      field.precision,
-    );
-    if (contradiction !== undefined) {
-      ctx.addIssue({ code: 'custom', path: ['precision'], message: contradiction });
-    }
-  }
+  // #20011 — the FIELD-level `precision` on a `currency` field is NOT compared
+  // against the currency's ISO 4217 fraction digits, on purpose. The key is
+  // declared "Total digits" — the `p` of a DECIMAL(p, s) amount, so
+  // `precision: 18` on a fixed-USD field is DECIMAL(18,2) — and a currency's
+  // decimal places are the currency's, not a setting (ruling 5805782503,
+  // batch #218 item 2, letter 乙). The #7918 check that stood here (maintainer
+  // ruling 2026-08-12, Option A) rested on one premise: objectui's
+  // CurrencyField read this key as its display width. objectui#10276 retired
+  // that reading, and no face reads the key as decimal places, so the check
+  // refused the ruled contract and prescribed a total-digit count of 2.
+  // ⛔ Do not reinstate a comparison here, and do not add a total-digit
+  // coherence rule for currency alone: no numeric type has one. The
+  // `currencyConfig.precision` twin is a DIFFERENT key ("Decimal precision")
+  // and keeps its own check inside `CurrencyConfigSchema`.
 
   // #9689 (maintainer ruling 2026-08-19, Q1 = A): an AUTHORED
   // `deleteBehavior: 'set_null'` on a `master_detail` is a publish-time error.