fix(spec,objectql): word the currency scale refusal's remedy as ruled

The refusal of `scale` on a `currency` field, its ADR-0087 semantic entry
`field-currency-scale-refused`, the `scale` describe, the changeset and the
validator's comments now prescribe one thing: delete the key. A currency's
decimal places are the currency's: its ISO 4217 minor unit decides its
display, and its write allowance stays unconstrained (today's contract). No
other key is named as a place to move the value.

What is refused and what is accepted do not change. The spec pins now hold
the ruled wording on the message (first sentence, both ruled clauses) and
the absence of any other key, beside the firing and dark controls. The
registry is regenerated with gen:migration-registry.

Claude-Session: https://claude.ai/code/session_013RDBh5DqXd2xnLwvHLgLFr
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/19629-currency-scale-retired.md

@@ -9,26 +9,25 @@ Clause-②: no (narrowing)
 
 **BREAKING** — an accept-set narrowing on a published authoring surface, shipped as `minor` under the repo's launch-window convention for accept-set narrowings. A `currency` field that declares `scale` — any value, `scale: 0` included — no longer parses. The hand-migration prescription is registered under protocol major 18 as `field-currency-scale-refused`.
 
-On a currency field the key was three-faced. The metadata-admin field designer offered it as stored metadata; the amount's cell never read it, because a currency amount's fraction digits come from its currency's own ISO 4217 minor unit; and the record validator's `max_scale` branch still refused writes carrying more decimals. An author who set `scale: 3` bought a narrower write contract and no visible change. The maintainer's ruling retires the key from the type rather than aligning the money faces to it.
+A currency's decimal places are the currency's, not a setting. On a currency field the key was three-faced. The metadata-admin field designer offered it as stored metadata; the amount's cell never read it, because a currency amount's fraction digits come from its currency's own ISO 4217 minor unit; and the record validator's `max_scale` branch still refused writes carrying more decimals. An author who set `scale: 3` bought a narrower write contract and no visible change. The maintainer's rulings retire the key from the type rather than aligning the money faces to it.
 
-**`@objectstack/spec`** — `FieldSchema` refuses `scale` on `type: 'currency'` with a located issue at `scale` whose remedy names `currencyConfig.precision`. No alias and no grace window. `scale` on `number`, `percent`, `rating`, `slider` and `formula` is untouched, and the key's describe now names that set.
+**`@objectstack/spec`** — `FieldSchema` refuses `scale` on `type: 'currency'` with a located issue at `scale`. Its remedy: delete the key; the currency's ISO 4217 minor unit decides how the amount displays, and the field's write allowance stays unconstrained. The remedy names no other key to carry the value. No alias and no grace window. `scale` on `number`, `percent`, `rating`, `slider` and `formula` is untouched, and the key's describe now names that set.
 
-**`@objectstack/objectql`** — the record validator's `max_scale` branch no longer reads `scale` for `currency`, so the type leaves the enforced set. A field definition that reaches the validator without passing `FieldSchema` (stored before this release, or built by hand at runtime) therefore narrows nothing either. `min`, `max` and the finite-number check still apply to `currency`, and `number` / `percent` / `rating` / `slider` still refuse over-scale writes exactly as before. A currency write with more decimals than a former `scale` is now ACCEPTED. Enforcing `currencyConfig.precision` on writes instead was offered to the maintainer and not taken.
+**`@objectstack/objectql`** — the record validator's `max_scale` branch no longer reads `scale` for `currency`, so the type leaves the enforced set. A field definition that reaches the validator without passing `FieldSchema` (stored before this release, or built by hand at runtime) therefore narrows nothing either. `min`, `max` and the finite-number check still apply to `currency`, and `number` / `percent` / `rating` / `slider` still refuse over-scale writes exactly as before. A currency write with more decimals than a former `scale` is now ACCEPTED: the write allowance stays unconstrained, the contract every currency field without `scale` already had. Enforcing a currency width on writes instead was offered to the maintainer and not taken.
 
 ## FROM → TO
 
 | you wrote | write instead |
 |:--|:--|
-| `Field.currency({ label: 'Amount', scale: 2 })` | `Field.currency({ label: 'Amount' })` — delete the key |
-| `{ type: 'currency', scale: 2, currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' } }` | `{ type: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD', precision: 2 } }` — or just delete `scale` |
-| `{ type: 'currency', scale: 2, currencyConfig: { precision: 2, … } }` | `{ type: 'currency', currencyConfig: { precision: 2, … } }` — delete `scale` |
+| `Field.currency({ label: 'Amount', scale: 2 })` | `Field.currency({ label: 'Amount' })` |
+| `{ type: 'currency', scale: 2, currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' } }` | `{ type: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' } }` |
 
-Delete the key by default. Move the value to `currencyConfig.precision` only on a field that already declares a `currencyConfig`. ⛔ Never add a `currencyConfig` just to carry the value: that block materializes `currencyMode: 'dynamic'` and `defaultCurrency: 'CNY'`, and the second changes the currency the field resolves. Under `currencyMode: 'fixed'` a moved value that contradicts the fixed currency's ISO 4217 digits is refused there in turn.
+The one-line fix: delete `scale` from every `currency` field. Nothing replaces it, so ⛔ do not re-declare the value under any other key. The currency's ISO 4217 minor unit decides how the amount displays.
 
 What an upgrade changes beyond the refusal:
 
 - **Writes.** A currency value with more decimals than the deleted `scale` is accepted where it used to answer `VALIDATION_FAILED` with field code `max_scale`.
-- **Two console faces, until the console catches up.** In the console version pinned when this landed, the grid summary footer and the dashboard metric widget read a currency column's `scale ?? 0`. A deleted `scale: 2` therefore renders those two faces with zero decimals until the console derives them from the currency the way the cell does. The cell and the edit widget are unaffected.
+- **Two console faces.** At the console pin measured when this change was written, the grid summary footer and the dashboard metric widget read a currency column's `scale ?? 0`. This change lands only after the console derives both faces from the currency, the way the cell does, and after this repository's console pin has moved past that console change. So in the console bundled with this release, deleting `scale` changes neither face.
 
 ## Who is affected, measured
 

content/docs/protocol/objectql/schema.mdx

@@ -289,7 +289,7 @@ fields:
 | `valueDomain` | `string` | `text` | Standard the written value must belong to: `iana_time_zone`, `iso_4217_currency` or `iso_3166_alpha2` (the closed vocabulary shared with settings specifiers). |
 | `min` | `number` | `number`, `currency` | Minimum numeric value. |
 | `max` | `number` | `number`, `currency` | Maximum numeric value. |
-| `scale` | `number` | `number`, `percent`, `rating`, `slider` | Decimal places, enforced on writes. Refused on `currency`: a currency amount's decimal places come from its currency's ISO 4217 minor unit. |
+| `scale` | `number` | `number`, `percent`, `rating`, `slider` | Decimal places, enforced on writes. Refused on `currency` — delete it there: a currency amount's decimal places are its currency's, so its ISO 4217 minor unit decides the display. |
 | `precision` | `number` | `number`, `currency` | Total digits (including scale). |
 | `options` | `array` | `select`, `multiselect` | List of valid values. |
 | `multiple` | `boolean` | `select`, `lookup` | Allow multiple selections. |

packages/objectql/src/validation/record-validator.test.ts

@@ -1280,10 +1280,11 @@ describe('validateRecord — a fraction-stored percent derives `scale + 2` (#193
  * a hand-built runtime schema) narrows nothing either.
  *
  * Three pins, per the ruling: a currency write with more decimals is ACCEPTED
- * when nothing declares a width (today's contract, unchanged); the same write
- * is accepted with a legacy `scale` on the def (the change); and `number` /
- * `percent` still refuse the identical over-scale write (the controls that
- * prove the branch is live in this harness, not deleted).
+ * when nothing declares a width (today's contract, unchanged — ruling
+ * 5805782503, letter 乙: a currency's write allowance stays unconstrained);
+ * the same write is accepted with a legacy `scale` on the def (the change);
+ * and `number` / `percent` still refuse the identical over-scale write (the
+ * controls that prove the branch is live in this harness, not deleted).
  */
 describe('validateRecord — `currency` is outside the max_scale enforced set (#19629)', () => {
   const fieldsOf = (

packages/objectql/src/validation/record-validator.ts

@@ -792,18 +792,21 @@ function validateOne(
     // ── `currency` is OUTSIDE the enforced set (#19629) ──
     // Maintainer ruling 5791803339 (batch #215 item 1, letter B): `scale` is
     // retired from the `currency` type. `FieldSchema` refuses the key there at
-    // parse, with a remedy naming `currencyConfig.precision`, so no authored
-    // currency field declares it any more — and this branch stops reading
-    // `def.scale` for the type, so a declaration that reaches here anyway (a
-    // stored field that predates the refusal, a hand-built runtime schema)
-    // narrows nothing either. The key was the currency field's one enforced
-    // effect: the amount's cell never read it, so an author who set it bought a
-    // narrower write contract and no visible change. `min` / `max` and the
-    // finite-number check above still apply to `currency` unchanged.
-    // ⛔ Not replaced by a read of `currencyConfig.precision`: enforcing that
-    // width on writes (the ruling's B′) was offered and NOT taken — a currency
+    // parse, with the remedy ruling 5805782503 (batch #218 item 2, letter 乙)
+    // words (delete the key; the currency's ISO 4217 minor unit decides its
+    // display), so no authored currency field declares it any more — and this
+    // branch stops reading `def.scale` for the type, so a declaration that
+    // reaches here anyway (a stored field that predates the refusal, a
+    // hand-built runtime schema) narrows nothing either. The key was the
+    // currency field's one enforced effect: the amount's cell never read it,
+    // so an author who set it bought a narrower write contract and no visible
+    // change. `min` / `max` and the finite-number check above still apply to
+    // `currency` unchanged.
+    // ⛔ Not replaced by a read of any other key: a currency's write
+    // allowance stays unconstrained (ruling 乙, today's contract) — a currency
     // write carries whatever decimals it carries, exactly as it always has on
-    // a currency field that declared no `scale`.
+    // a currency field that declared no `scale`. Enforcing a currency width on
+    // writes (the first ruling's B′) was offered and NOT taken.
     if (
       t !== 'currency' &&
       def.scale !== undefined &&

packages/spec/src/data/field-currency-scale-refused.test.ts

@@ -3,7 +3,12 @@
 /**
  * #19629 — `scale` is RETIRED from the `currency` field type (maintainer ruling
  * 5791803339, batch #215 item 1, letter B): a currency field carrying `scale`
- * is refused at parse, with a remedy naming `currencyConfig.precision`.
+ * is refused at parse. The remedy is worded by ruling 5805782503 (batch #218
+ * item 2, letter 乙 — a currency's decimal places are the currency's, not a
+ * setting): delete the key; the currency's ISO 4217 minor unit decides its
+ * display, and its write allowance stays unconstrained. It names no other key
+ * to carry the value, and the remedy pins below hold both halves: the ruled
+ * wording is present, and the retired pointer is absent.
  *
  * On a currency field the key was offered by the field designer, never read by
  * the amount's cell, and still enforced on writes by `packages/objectql`'s
@@ -29,16 +34,28 @@ function scaleIssues(result: { success: boolean; error?: { issues: Issue[] } }):
   return result.success ? [] : result.error!.issues.filter((i) => i.path[i.path.length - 1] === 'scale');
 }
 
+/**
+ * The ruled remedy, held on the message itself: the wording is the contract
+ * here (ruling 乙 rules the prescription, not only the refusal), so the pin
+ * reads the first sentence verbatim, the two ruled clauses, and the ABSENCE of
+ * any key the author could be sent to instead.
+ */
+function expectRuledRemedy(message: string): void {
+  expect(message.startsWith('`scale` is not valid on a `currency` field — delete the key.')).toBe(true);
+  expect(message).toContain('the currency\'s ISO 4217 minor unit (2 for USD, 0 for JPY, 3 for KWD) decides how the amount displays');
+  expect(message).toContain('the field\'s write allowance stays unconstrained');
+  expect(message).not.toMatch(/currencyConfig|precision/);
+}
+
 describe('#19629 — `scale` on a `currency` field is refused at parse', () => {
-  it('refuses the designer-produced shape, located at `scale`, with the remedy naming `currencyConfig.precision`', () => {
+  it('refuses the designer-produced shape, located at `scale`, with the ruled remedy: delete the key, and no other key named', () => {
     const result = FieldSchema.safeParse({ name: 'amount', label: 'Amount', type: 'currency', scale: 3 });
     expect(result.success).toBe(false);
     const issues = scaleIssues(result);
     expect(issues).toHaveLength(1);
     expect(issues[0].code).toBe('custom');
     expect(issues[0].path).toEqual(['scale']);
-    // The ruled remedy's named subject — the one knob the refusal points to.
-    expect(issues[0].message).toContain('`currencyConfig.precision`');
+    expectRuledRemedy(issues[0].message);
   });
 
   it('refuses every declared value, `scale: 0` and `scale: 2` included — it is the key that is retired', () => {
@@ -49,16 +66,20 @@ describe('#19629 — `scale` on a `currency` field is refused at parse', () => {
     }
   });
 
-  it('refuses it beside a `currencyConfig` too — the width key is not an alias for it', () => {
+  it('refuses it beside a `currencyConfig` too, with the same remedy — the block neither licenses the key nor receives its value', () => {
     const result = FieldSchema.safeParse({
       name: 'amount',
       label: 'Amount',
       type: 'currency',
       scale: 2,
-      currencyConfig: { precision: 2, currencyMode: 'fixed', defaultCurrency: 'USD' },
+      currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' },
     });
     expect(result.success).toBe(false);
-    expect(scaleIssues(result)).toHaveLength(1);
+    const issues = scaleIssues(result);
+    expect(issues).toHaveLength(1);
+    // The field that most invites a "move it into the block" remedy gets the
+    // same prescription as every other: delete the key.
+    expectRuledRemedy(issues[0].message);
   });
 
   it('fires through the `Field.currency()` helper and `ObjectSchema` — the path an object document crosses', () => {
@@ -71,6 +92,7 @@ describe('#19629 — `scale` on a `currency` field is refused at parse', () => {
     const issues = scaleIssues(result);
     expect(issues).toHaveLength(1);
     expect(issues[0].path).toEqual(['fields', 'amount', 'scale']);
+    expectRuledRemedy(issues[0].message);
   });
 });
 
@@ -81,14 +103,20 @@ describe('#19629 — CONTROLS: what the refusal must leave alone', () => {
     expect(FieldSchema.parse(once)).toEqual(once);
   });
 
-  it('the remedy target parses: `currencyConfig.precision` on a currency field', () => {
-    const result = FieldSchema.safeParse({
-      name: 'amount',
-      label: 'Amount',
-      type: 'currency',
-      currencyConfig: { precision: 3, currencyMode: 'fixed', defaultCurrency: 'KWD' },
-    });
-    expect(result.success).toBe(true);
+  it('following the remedy parses: each refused shape, with `scale` deleted and nothing added, is accepted', () => {
+    const refused: Record<string, unknown>[] = [
+      { name: 'amount', label: 'Amount', type: 'currency', scale: 3 },
+      { name: 'amount', label: 'Amount', type: 'currency', scale: 2, min: 0, currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'KWD' } },
+    ];
+    for (const shape of refused) {
+      expect(FieldSchema.safeParse(shape).success).toBe(false);
+      const remedied = { ...shape };
+      delete remedied.scale;
+      expect(Object.keys(remedied)).toEqual(Object.keys(shape).filter((k) => k !== 'scale'));
+      const result = FieldSchema.safeParse(remedied);
+      expect(result.success, JSON.stringify(remedied)).toBe(true);
+      if (result.success) expect('scale' in result.data).toBe(false);
+    }
   });
 
   it('every type the key still applies to keeps it — number, percent, rating, slider', () => {
@@ -99,9 +127,11 @@ describe('#19629 — CONTROLS: what the refusal must leave alone', () => {
     }
   });
 
-  it('the describe names the type set the key still applies to, and the currency refusal', () => {
+  it('the describe names the type set the key still applies to, and the currency refusal with the ruled remedy', () => {
     const description = (FieldSchema.shape as Record<string, { description?: string }>).scale?.description ?? '';
     expect(description).toContain('Applies to `number`, `percent`, `rating` and `slider`');
-    expect(description).toContain('REFUSED on a `currency` field');
+    expect(description).toContain('REFUSED on a `currency` field — delete it there');
+    expect(description).toContain('the currency\'s ISO 4217 minor unit decides how the amount displays');
+    expect(description).not.toContain('currencyConfig');
   });
 });

packages/spec/src/data/field-scale.ts

@@ -68,14 +68,18 @@
  * - `currency` — ruled since, and not by a row here: `scale` is RETIRED from
  *   the `currency` type (#19629, ruling 5791803339 letter B) and refused at
  *   parse, so a currency field declares no `scale` for this table to default.
- *   The amount's cell resolves its fraction digits from the currency's own
- *   ISO 4217 minor-unit count and never read the key; measured at
+ *   Ruling 5805782503 (letter 乙) words the refusal's remedy: a currency's
+ *   decimal places are the currency's, not a setting — its ISO 4217 minor
+ *   unit decides its display. The amount's cell resolves its fraction
+ *   digits from the currency's own ISO 4217 minor-unit count and never read
+ *   the key; measured at
  *   `.objectui-sha` pin `62597c588072` (the pin when the ruling landed), the
  *   grid summary footer and the dashboard metric widget did read it on a
  *   currency column, as `scale ?? 0` — the ruling's consumer half is
- *   objectui#10221. The one `2` that looks
- *   like a currency default belongs to an inline grid COLUMN's rounding of a
- *   computed result, not to a field's display width.
+ *   objectui#10221, which ruling 乙 widens to that metric widget and lands
+ *   first. The one `2` that looks like a currency default belongs to an
+ *   inline grid COLUMN's rounding of a computed result, not to a field's
+ *   display width.
  *
  * ⛔ Neither reading is an argument for a `0` row: `number` still awaits its
  * own ruling, and `currency` no longer has a declaration to resolve.