@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): refuse malformed field `scale`/`precision` declarations at authoring time (#8321)
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the migration prescription is
+registered under protocol major 18, where `os migrate meta` users will look).
+
+`Field.scale` ("Decimal places") and `Field.precision` ("Total digits") are
+digit counts, but both parsed as bare `z.number()` — admitting `scale: 2.5`
+and `scale: -1`, neither of which has a defined meaning as a count. That
+looseness became load-bearing when #7501 made `scale` enforced at write time:
+the runtime branch deliberately guards on `Number.isInteger(def.scale) &&
+def.scale >= 0` (inventing floor/round semantics in a consumer would be PD #12
+guessing), so a typo'd declaration silently got **no enforcement at all** —
+the declared-but-inert shape that hides AI-authored metadata errors.
+
+**What is refused:** a non-integer or negative `scale` or `precision`, at
+parse time with the issue path and substance (`invalid_type` "expected int" /
+`too_small` ">=0") — the house `z.number().int().min(0)` shape (ADR-0078
+declared=enforced).
+
+**What stays accepted:** every well-formed declaration byte-identically
+(`0`, `2`, any non-negative integer, or no declaration).
+`CurrencyConfigSchema.precision` (under `currencyConfig`) is a **different
+surface** with its own bounds and `scale → precision` alias table — unchanged.
+
+**Stored metadata is not hard-broken:** a `sys_metadata` row already at rest
+with a malformed value keeps loading — the ADR-0087 D2 conversion
+`field-malformed-scale-precision-removed` (retired from the load path,
+replayed by the stored-row rehydration seam and `os migrate meta`) drops the
+meaningless key, which is behaviour-preserving because a malformed declaration
+enforced nothing. The semantic entry
+`field-scale-precision-integer-refused` (protocol major 18) tells authors to
+re-declare the digit count they meant.
+
+<!-- adr-0087: registered field-scale-precision-integer-refused -->
@@ -67,8 +67,8 @@ const result = CurrencyConfigSchema.parse(data);
 | **defaultValue** | `any` | optional | Default applied on INSERT when the field is omitted or null (`''` is a real value, not absence). Three legal shapes (#7127), discriminated in the engine's own order: a CEL Expression envelope `{ dialect: 'cel', source: 'today()' }` (accepted structurally; result type is a runtime concern); a runtime TOKEN — `NOW()` on `datetime`/`date`/`time` only, `current_user` on `user` or `lookup` with `reference: 'sys_user'` only, neither on a multi-value field; or a LITERAL, which must satisfy this field's own stored value contract (ADR-0104 D1 `valueSchemaFor`). Anything else is refused at parse time with a prescriptive message. |
 | **maxLength** | `number` | optional | Max character length |
 | **minLength** | `number` | optional | Min character length |
-| **precision** | `number` | optional | Total digits |
-| **scale** | `number` | optional | Decimal places |
+| **precision** | `integer` | optional | Total digits (non-negative integer) |
+| **scale** | `integer` | optional | Decimal places (non-negative integer) |
 | **min** | `number` | optional | Minimum value |
 | **max** | `number` | optional | Maximum value |
 | **useGrouping** | `boolean` | optional | Digit-grouping presentation hint for `number` fields (#7768) — maps to `Intl.NumberFormat`'s `useGrouping`. Absent = renderer decides (interim heuristic today, locale default eventually); `false` = author opts out of grouping (e.g. a year or other ordinal/identifier integer); `true` = author pins grouping on. |
 
@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
+import { FieldSchema } from '@objectstack/spec/data';
 import { validateRecord, normalizeMultiValueFields, coerceBooleanFields, ValidationError } from './record-validator.js';
 
 /**
@@ -797,10 +798,30 @@ describe('validateRecord — number `scale` is enforced by rejection (#7501)', (
     expect(() => validateRecord(schema, { free: 0.123456789 }, 'insert')).not.toThrow();
   });
 
-  it('a malformed declaration (non-integer or negative scale) stays unenforced', () => {
-    // `scale: 2.5` has no defined meaning; inventing floor/round semantics
-    // here would be consumer-side guessing (PD #12). It behaves exactly as
-    // every declaration did before the branch existed: not at all.
+  it('a malformed declaration (non-integer or negative scale) is refused at AUTHORING time (#8321)', () => {
+    // FLIPPED by #8321 (was: "stays unenforced"). `scale: 2.5` has no defined
+    // meaning; inventing floor/round semantics here would be consumer-side
+    // guessing (PD #12), so the runtime branch deliberately guarded on
+    // `Number.isInteger && >= 0` — which left a typo'd declaration silently
+    // inert. The producer now refuses it: FieldSchema rejects non-integer and
+    // negative scale/precision at parse, so a malformed declaration can no
+    // longer reach this validator through authored metadata.
+    for (const [key, value, code] of [
+      ['scale', 2.5, 'invalid_type'],
+      ['scale', -1, 'too_small'],
+      ['precision', 2.5, 'invalid_type'],
+      ['precision', -1, 'too_small'],
+    ] as const) {
+      const result = FieldSchema.safeParse({ name: 'x', label: 'X', type: 'number', [key]: value });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues.find((i) => i.path[0] === key)?.code).toBe(code);
+      }
+    }
+    // Defense-in-depth is UNCHANGED: handed a raw malformed def that bypassed
+    // the schema (a hand-built runtime schema object, not authored metadata),
+    // the runtime still refuses to invent semantics — the declaration enforces
+    // nothing rather than something the author never wrote.
     const bad = { fields: { x: { type: 'number', scale: 2.5 }, y: { type: 'number', scale: -1 } } };
     expect(() => validateRecord(bad, { x: 1.234, y: 5.5 }, 'insert')).not.toThrow();
   });
 
@@ -6498,6 +6498,103 @@ const actionGlobalNavLocationRemoved: MetadataConversion = {
   },
 };
 
+/**
+ * Field `scale` / `precision`: malformed declarations removed (protocol 18,
+ * #8321).
+ *
+ * NOT a rename — both keys are digit COUNTS, so a non-integer or negative
+ * value (`scale: 2.5`, `precision: -1`) declares nothing the runtime could
+ * enforce. #7501's write-time enforcement deliberately guards on
+ * `Number.isInteger(v) && v >= 0` and leaves a malformed declaration
+ * unenforced (inventing floor/round semantics in a consumer would be PD #12
+ * guessing), so removing the key is a pure lossless delete: the declaration
+ * never had a runtime effect to lose, and after removal the field behaves
+ * byte-identically (unenforced). The authoring schema now refuses these
+ * values (`z.number().int().min(0)`, ADR-0078 declared=enforced), so this is
+ * **retired from the load path**: a live author gets the loud refusal and
+ * fixes the source; only `migrate meta` and the stored-row rehydration seam
+ * (`applyConversionsToStoredItem`, which replays retired entries by design)
+ * apply the delete — which is what keeps an existing tenant with
+ * `scale: 2.5` at rest in `sys_metadata` loadable rather than hard-broken.
+ *
+ * Guarded to `typeof v === 'number'`: a non-number value there was never
+ * schema-legal in any protocol and is a validation problem, not a conversion
+ * target — this seam never manufactures shape. `NaN`/`Infinity` fall in
+ * (`Number.isInteger` is false for both). A WELL-FORMED count (`0`, `2`, any
+ * non-negative integer) is untouched.
+ *
+ * ⚠️ `CurrencyConfigSchema.precision` (under `currencyConfig`) is a different
+ * surface with its own bounds and alias table — deliberately not walked.
+ */
+const fieldMalformedScalePrecisionRemoved: MetadataConversion = {
+  id: 'field-malformed-scale-precision-removed',
+  toMajor: 18,
+  retiredFromLoadPath: true,
+  surface: 'object.fields.*.scale / object.fields.*.precision',
+  summary:
+    "malformed field 'scale'/'precision' declarations (non-integer or negative) are removed — "
+    + 'they were silently unenforced; the schema now refuses them at authoring (#8321)',
+  apply(stack, emit) {
+    const MALFORMED_KEYS = ['scale', 'precision'] as const;
+    const stripMalformed = (input: Dict, collection: string): Dict =>
+      mapCollection(input, collection, (owner, path) => {
+        const fields = owner.fields;
+        if (!isDict(fields)) return owner;
+        let changed = false;
+        const next: Dict = {};
+        for (const [name, def] of Object.entries(fields)) {
+          if (!isDict(def)) {
+            next[name] = def;
+            continue;
+          }
+          let current = def;
+          for (const key of MALFORMED_KEYS) {
+            const value = current[key];
+            if (typeof value !== 'number') continue;
+            if (Number.isInteger(value) && value >= 0) continue;
+            const { [key]: _removed, ...rest } = current;
+            current = rest;
+            emit({ from: `${key}: ${value}`, to: '(removed)', path: `${path}.fields.${name}.${key}` });
+          }
+          next[name] = current;
+          if (current !== def) changed = true;
+        }
+        return changed ? { ...owner, fields: next } : owner;
+      });
+    return stripMalformed(stripMalformed(stack, 'objects'), 'objectExtensions');
+  },
+  fixture: {
+    before: {
+      objects: [{
+        name: 'crm_deal',
+        label: 'Deal',
+        fields: {
+          // Non-integer scale: the #8321 repro — declared, silently unenforced.
+          amount: { type: 'number', precision: 18, scale: 2.5 },
+          // Negative precision: the other malformed direction.
+          weight: { type: 'number', precision: -1, scale: 2 },
+          // Well-formed counts survive byte-identically.
+          quantity: { type: 'number', precision: 10, scale: 0 },
+        },
+      }],
+    },
+    after: {
+      objects: [{
+        name: 'crm_deal',
+        label: 'Deal',
+        fields: {
+          amount: { type: 'number', precision: 18 },
+          weight: { type: 'number', scale: 2 },
+          quantity: { type: 'number', precision: 10, scale: 0 },
+        },
+      }],
+    },
+    // One per removed malformed key — `quantity` (and `weight.scale`,
+    // `amount.precision`) are untouched.
+    expectedNotices: 2,
+  },
+};
+
 export const CONVERSIONS_BY_MAJOR: Readonly<Record<number, readonly MetadataConversion[]>> = {
   11: [flowNodeHttpRename, pageKindJsxToHtml, flowNodeFilterAlias, objectCompactLayoutRename],
   13: [stackRolesToPositions, owdLegacyReadAliases, sharingRecipientRoleToPosition],
@@ -6570,6 +6667,7 @@ export const CONVERSIONS_BY_MAJOR: Readonly<Record<number, readonly MetadataConv
     appHiddenToUnpublished,
     actionGlobalNavLocationRemoved,
   ],
+  18: [fieldMalformedScalePrecisionRemoved],
 };
 
 /** Flattened, deterministic list of every conversion the loader knows about. */
 
@@ -40,6 +40,33 @@ describe('applyConversionsToStoredItem (stored sys_metadata rows, #3903)', () =>
     expect('execute' in out.actions[0]!).toBe(false);
   });
 
+  // #8321 — the authoring schema now refuses non-integer/negative
+  // `scale`/`precision`, but a tenant with `scale: 2.5` already at rest in
+  // `sys_metadata` must NOT become unloadable: the retired D2 conversion
+  // drops the meaningless key (behaviour-preserving — #7501's enforcement
+  // deliberately skipped malformed declarations, so it enforced nothing)
+  // and the rest of the row survives byte-identically.
+  it('drops a malformed stored scale/precision instead of breaking the row (#8321)', () => {
+    const row = {
+      name: 'crm_deal',
+      label: 'Deal',
+      fields: {
+        amount: { type: 'number', precision: 18, scale: 2.5 },
+        weight: { type: 'number', precision: -1, scale: 2 },
+        quantity: { type: 'number', precision: 10, scale: 0 },
+      },
+    };
+    const notices: ConversionNotice[] = [];
+    const out = applyConversionsToStoredItem('object', row, { onNotice: (n) => notices.push(n) });
+    expect(out.fields.amount).toEqual({ type: 'number', precision: 18 });
+    expect(out.fields.weight).toEqual({ type: 'number', scale: 2 });
+    // A well-formed count is untouched.
+    expect(out.fields.quantity).toEqual({ type: 'number', precision: 10, scale: 0 });
+    expect(
+      notices.filter((n) => n.conversionId === 'field-malformed-scale-precision-removed'),
+    ).toHaveLength(2);
+  });
+
   it('accepts the legacy PLURAL row-type spelling', () => {
     const row = { name: 'crm_deal', label: 'Deal', sharingModel: 'read' };
     const out = applyConversionsToStoredItem('objects', row) as Record<string, unknown>;
 
@@ -238,6 +238,71 @@ describe('FieldSchema', () => {
 
       expect(() => FieldSchema.parse(numberField)).not.toThrow();
     });
+
+    /**
+     * #8321 — `scale`/`precision` are digit COUNTS, so a non-integer or
+     * negative declaration has no defined meaning. #7501's write-time
+     * enforcement deliberately leaves a malformed declaration UNENFORCED
+     * (inventing floor/round semantics would be PD #12 guessing), which made
+     * `scale: 2.5` silently inert. The producer now refuses it at parse
+     * (ADR-0078 declared=enforced; `z.number().int().min(0)`).
+     */
+    describe('malformed scale/precision declarations are refused at authoring (#8321)', () => {
+      const cases: Array<[key: 'scale' | 'precision', value: number, code: string]> = [
+        ['scale', 2.5, 'invalid_type'], // the issue repro: non-integer count
+        ['scale', -1, 'too_small'],
+        ['precision', 2.5, 'invalid_type'],
+        ['precision', -1, 'too_small'],
+      ];
+      for (const [key, value, code] of cases) {
+        it(`refuses ${key}: ${value} with a ${code} issue at [${key}]`, () => {
+          const result = FieldSchema.safeParse({
+            name: 'work_hours', label: 'Work Hours', type: 'number', [key]: value,
+          });
+          expect(result.success).toBe(false);
+          if (!result.success) {
+            const issue = result.error.issues.find((i) => i.path[0] === key);
+            expect(issue?.code).toBe(code);
+            // Message substance, not just a throw: the refusal names what a
+            // legal value looks like (int / >=0), so an AI author can fix it.
+            expect(issue?.message).toMatch(code === 'invalid_type' ? /expected int/ : />=0/);
+          }
+        });
+      }
+
+      it('every legal declaration still parses byte-identically (0, positive integers, absent)', () => {
+        for (const legal of [
+          { scale: 0 },
+          { scale: 2 },
+          { precision: 18, scale: 2 },
+          { precision: 0 },
+          {}, // neither declared — no new default appears
+        ]) {
+          const input = { name: 'amount', label: 'Amount', type: 'number' as const, ...legal };
+          const result = FieldSchema.safeParse(input);
+          expect(result.success).toBe(true);
+          if (result.success) {
+            // Byte-identical on this surface: the declared counts round-trip
+            // unchanged and absence stays absence.
+            expect(result.data.scale).toBe((legal as { scale?: number }).scale);
+            expect(result.data.precision).toBe((legal as { precision?: number }).precision);
+          }
+        }
+      });
+
+      it('does NOT touch CurrencyConfigSchema.precision — a different surface with its own bounds', () => {
+        // The currency config keeps its own `.int().min(0).max(10)` contract
+        // and its `scale → precision` alias table (#7501-thread trap): `10` is
+        // legal there, and `scale` under currencyConfig renames to precision
+        // rather than being judged by Field.scale's contract.
+        const result = FieldSchema.safeParse({
+          name: 'price', label: 'Price', type: 'currency',
+          currencyConfig: { precision: 10 },
+        });
+        expect(result.success).toBe(true);
+        if (result.success) expect(result.data.currencyConfig?.precision).toBe(10);
+      });
+    });
   });
 
   describe('useGrouping — number-field digit-grouping presentation hint (#7768)', () => {
 
@@ -639,8 +639,18 @@ export const FieldSchema = lazySchema(() => strictObject({
   minLength: z.number().optional().describe('Min character length'),
 
   /** Number Constraints */
-  precision: z.number().optional().describe('Total digits'),
-  scale: z.number().optional().describe('Decimal places'),
+  // #8321 — `precision`/`scale` are digit COUNTS, so a non-integer or negative
+  // declaration has no defined meaning. #7501 made `scale` enforced at write
+  // time with a deliberate `Number.isInteger(def.scale) && def.scale >= 0`
+  // runtime guard that leaves a malformed declaration UNENFORCED (inventing
+  // floor/round semantics in a consumer would be PD #12 guessing) — so
+  // `scale: 2.5` silently got no enforcement at all: the declared-but-inert
+  // shape that hides AI-authored metadata errors. Refuse it at the producer
+  // instead (ADR-0078 declared=enforced; house pattern `z.number().int().min(0)`).
+  // ⚠️ `CurrencyConfigSchema.precision` above is a DIFFERENT surface with its
+  // own alias table (`scale → precision` there) — do not conflate.
+  precision: z.number().int().min(0).optional().describe('Total digits (non-negative integer)'),
+  scale: z.number().int().min(0).optional().describe('Decimal places (non-negative integer)'),
   min: z.number().optional().describe('Minimum value'),
   max: z.number().optional().describe('Maximum value'),
   /**
 
@@ -0,0 +1,32 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'field-scale-precision-integer-refused',
+  surface: 'object field `scale` / `precision` declarations (`Field.number` and friends) — '
+    + 'non-integer or negative values (`scale: 2.5`, `precision: -1`)',
+  replacement: 'a non-negative integer digit count, or no declaration at all. The mechanical '
+    + 'conversion (`field-malformed-scale-precision-removed`) deletes a malformed value — '
+    + 'behaviour-preserving, because #7501\'s enforcement deliberately skipped malformed '
+    + 'declarations, so they enforced nothing — but only the author knows the count they '
+    + 'MEANT (`scale: 2.5` was probably `2` or `3`): re-declare it deliberately if the '
+    + 'constraint was wanted',
+  reason:
+    'Both keys are digit COUNTS ("Total digits" / "Decimal places"), and `z.number()` admitted '
+    + 'values with no defined meaning as a count. That looseness became load-bearing when #7501 '
+    + 'made `scale` enforced at write time: the runtime branch deliberately guards on '
+    + '`Number.isInteger(def.scale) && def.scale >= 0` — inventing floor/round semantics in a '
+    + 'consumer would be PD #12 guessing — so a typo\'d declaration (`scale: 2.5`) silently got '
+    + 'no enforcement at all: exactly the declared-but-inert shape that hides AI-authored '
+    + 'metadata errors. The schema now refuses non-integer and negative values for both keys at '
+    + 'parse time (`z.number().int().min(0)`, ADR-0078 declared=enforced). '
+    + '`CurrencyConfigSchema.precision` (under `currencyConfig`) is a different surface with its '
+    + 'own bounds and alias table and is unchanged.',
+  acceptanceCriteria:
+    'Every field declaring `scale` or `precision` carries a non-negative integer. Well-formed '
+    + 'declarations (`0`, `2`, any non-negative integer) parse byte-identically to before; '
+    + 'fields declaring neither key are untouched. Stored `sys_metadata` rows carrying a '
+    + 'malformed value keep loading (the rehydration seam replays the conversion, which drops '
+    + 'the meaningless key).',
+};