fix(spec): record currency mode refuses an empty pointer and an inert defaultCurrency

Contract-review should-fixes on the record currency mode (ADR-0144 D2):

- `currencyField` is never empty (`.min(1)`), so no record amount
  carries a pointer the object door names as nothing.
- `defaultCurrency` is refused under `record`, at the key, with a
  prescription. `record` is new, so no stored row needs the tolerance
  `dynamic` keeps; the inert key is ADR-0078's shape.
- The object door reads `VALUE_DOMAIN_FIELD_TYPES` instead of repeating
  the `'text'` literal.
- ADR-0144 anchors on field.zod.ts and object.zod.ts.
- The changeset lists `@objectstack/platform-objects`, which ships the
  regenerated metadata-form bundles.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Utp6CbfVSc1hXtxLUPHZ2f

Author: claude

.changeset/27184-currency-record-mode.md

@@ -1,6 +1,7 @@
 ---
 '@objectstack/spec': minor
 '@object-ui/i18n': minor
+'@objectstack/platform-objects': minor
 ---
 
 feat(spec): `currencyMode: 'record'` + `currencyField` — a record-mode amount points at a sibling ISO 4217 code field (ADR-0144 D2)
@@ -17,7 +18,7 @@ fields: {
 }
 ```
 
-- `currencyField` is required under `record` and refused under `dynamic` and `fixed`.
+- `currencyField` is required under `record`, refused under `dynamic` and `fixed`, and never empty; `defaultCurrency` is refused under `record`.
 - The object refuses a `currencyField` that names no other declared field, a field that is not `text`, or a `text` field without `valueDomain: 'iso_4217_currency'`. Each refusal is located at `fields.FIELD.currencyConfig.currencyField` and lists the object's candidate code fields.
 - `dynamic` and `fixed` configs parse exactly as before; an app that never writes `record` sees no change.
 

packages/spec/src/data/currency-config-record-mode.test.ts

@@ -5,7 +5,8 @@
  * amount points at a sibling ISO 4217 code field on the same object.
  *
  * Two doors, one per half: `CurrencyConfigSchema` refuses the half one config
- * can see (`record` without a pointer, a pointer under another mode), and the
+ * can see (`record` without a pointer or with a `defaultCurrency`, a pointer
+ * under another mode, an empty pointer), and the
  * object's `superRefine` refuses what the pointer names (nothing, a non-text
  * field, a text field with no ISO 4217 value domain). A `formula` declaring
  * `returnType: 'currency'` carries the same config, so it meets both doors.
@@ -59,6 +60,31 @@ describe('`CurrencyConfigSchema`: `record` ⇔ `currencyField`', () => {
     expect(r.error.issues[0]!.message).toMatch(/^`currencyField` is read only under `currencyMode: 'record'`/);
   });
 
+  it('refuses an empty `currencyField`, at the key, in every mode', () => {
+    for (const mode of ['record', 'dynamic', 'fixed'] as const) {
+      const config = mode === 'fixed' ? { currencyMode: mode, defaultCurrency: 'USD', currencyField: '' } : { currencyMode: mode, currencyField: '' };
+      const r = CurrencyConfigSchema.safeParse(config);
+      expect(r.success, mode).toBe(false);
+      if (r.success) continue;
+      // Under `dynamic` / `fixed` the out-of-mode refusal is told too, at the same key.
+      expect(r.error.issues.length, mode).toBe(mode === 'record' ? 1 : 2);
+      expect(r.error.issues.every((i) => i.path.join('.') === 'currencyField'), mode).toBe(true);
+      expect(r.error.issues[0]!.message).toMatch(/^`currencyField` names a field: an empty name points at nothing/);
+    }
+  });
+
+  it('refuses `defaultCurrency` under `record`, at the key, with the prescription', () => {
+    const r = CurrencyConfigSchema.safeParse({ ...RECORD, defaultCurrency: 'EUR' });
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    expect(r.error.issues).toHaveLength(1);
+    expect(r.error.issues[0]!.code).toBe('custom');
+    expect(r.error.issues[0]!.path).toEqual(['defaultCurrency']);
+    expect(r.error.issues[0]!.message).toMatch(/^`defaultCurrency` is not read under `currencyMode: 'record'`/);
+    // …and `dynamic` keeps tolerating its inert code, for the rows #27157 left behind.
+    expect(CurrencyConfigSchema.safeParse({ currencyMode: 'dynamic', defaultCurrency: 'EUR' }).success).toBe(true);
+  });
+
   it('refuses `currencyField` under the defaulted mode (no `currencyMode` written ⇒ dynamic)', () => {
     expect(CurrencyConfigSchema.safeParse({ currencyField: 'currency_code' }).success).toBe(false);
   });

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

@@ -535,16 +535,29 @@ const CURRENCY_CONFIG_DECIMAL_PLACES_GUIDANCE: Readonly<Record<string, string>>
 };
 
 /**
- * [ADR-0144 D2] `currencyMode: 'record'` ⇔ `currencyField`. A `record`-mode
- * amount has no currency until a pointer names the sibling code field, and a
- * pointer under `dynamic` / `fixed` is read by nothing — the declared-but-inert
- * shape ADR-0078 keeps out. One located issue at `['currencyField']` either
- * way; what the pointer NAMES is the object's to judge (object.zod.ts).
+ * [ADR-0144 D2] `currencyMode: 'record'` ⇔ `currencyField`, and no
+ * `defaultCurrency` beside it. A `record`-mode amount has no currency until a
+ * pointer names the sibling code field; a pointer under `dynamic` / `fixed` is
+ * read by nothing, and neither is a `defaultCurrency` under `record` — each is
+ * the declared-but-inert shape ADR-0078 keeps out. `record` is new, so no
+ * stored row carries the second one (unlike `dynamic`, whose inert code is
+ * tolerated for the rows #27157 left behind). One located issue per inert or
+ * missing key; what the pointer NAMES is the object's to judge (object.zod.ts).
  */
-function refuseCurrencyFieldOutsideRecordMode(
-  config: { currencyMode: 'dynamic' | 'fixed' | 'record'; currencyField?: string },
+function refuseRecordModeKeyMismatch(
+  config: { currencyMode: 'dynamic' | 'fixed' | 'record'; defaultCurrency?: string; currencyField?: string },
   ctx: z.RefinementCtx,
 ): void {
+  if (config.currencyMode === 'record' && config.defaultCurrency !== undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['defaultCurrency'],
+      message:
+        `\`defaultCurrency\` is not read under \`currencyMode: 'record'\`, where each record names its own currency in `
+        + 'the field `currencyField` names: delete `defaultCurrency`, or use `currencyMode: \'fixed\'` if the field has '
+        + 'one currency.',
+    });
+  }
   if (config.currencyMode === 'record' && config.currencyField === undefined) {
     ctx.addIssue({
       code: 'custom',
@@ -621,21 +634,22 @@ export const CurrencyConfigSchema = lazySchema(() => strictObject({
   aliases: { mode: 'currencyMode', currency: 'defaultCurrency', code: 'defaultCurrency', isoCode: 'defaultCurrency' },
   guidance: CURRENCY_CONFIG_DECIMAL_PLACES_GUIDANCE,
 }, {
-  currencyMode: z.enum(['dynamic', 'fixed', 'record']).default('dynamic').describe('Currency mode. `fixed`: the field has one currency, `defaultCurrency`. `dynamic` (the default): the field has no currency of its own — amounts display in the tenant default currency (the `localization.currency` setting; a plain number when none is set) and `defaultCurrency` is not read. `record`: each record has its own currency, the ISO 4217 code stored in the sibling field `currencyField` names; `defaultCurrency` is not read. The value is a bare number in every mode (ADR-0104 D1).'),
-  defaultCurrency: z.string().length(3).optional().describe('The currency code (ISO 4217, e.g. USD, CNY, EUR) of a `fixed`-mode field: its one currency, required under `fixed`. Not read under `dynamic` (the default), where amounts display in the tenant default currency, nor under `record`, where each record names its own.'),
+  currencyMode: z.enum(['dynamic', 'fixed', 'record']).default('dynamic').describe('Currency mode. `fixed`: the field has one currency, `defaultCurrency`. `dynamic` (the default): the field has no currency of its own — amounts display in the tenant default currency (the `localization.currency` setting; a plain number when none is set) and `defaultCurrency` is not read. `record`: each record has its own currency, the ISO 4217 code stored in the sibling field `currencyField` names; `defaultCurrency` is refused. The value is a bare number in every mode (ADR-0104 D1).'),
+  defaultCurrency: z.string().length(3).optional().describe('The currency code (ISO 4217, e.g. USD, CNY, EUR) of a `fixed`-mode field: its one currency, required under `fixed`. Not read under `dynamic` (the default), where amounts display in the tenant default currency, and refused under `record`, where each record names its own.'),
   // ADR-0144 D2 — the pointer of a `record`-mode amount. Optional at the key
-  // level; `refuseCurrencyFieldOutsideRecordMode` below makes it required
-  // under `record` and refuses it under the other two modes, and the object's
-  // `superRefine` (`refuseDishonestRecordCurrencyField`, object.zod.ts) checks
-  // what it names, because only the object holds the sibling field map.
-  currencyField: z.string().optional().describe('`record` mode only, and required there: the name of the field on the same object that holds each record\'s currency — a `text` field declaring `valueDomain: \'iso_4217_currency\'` (conventionally `currency_code`). Refused under `dynamic` and `fixed`.'),
+  // level and never empty; `refuseRecordModeKeyMismatch` below makes it
+  // required under `record` and refuses it under the other two modes, and the
+  // object's `superRefine` (`refuseDishonestRecordCurrencyField`,
+  // object.zod.ts) checks what it names, because only the object holds the
+  // sibling field map.
+  currencyField: z.string().min(1, '`currencyField` names a field: an empty name points at nothing — name the field on this object that holds each record\'s ISO 4217 code, conventionally `currency_code`.').optional().describe('`record` mode only, and required there: the name of the field on the same object that holds each record\'s currency — a `text` field declaring `valueDomain: \'iso_4217_currency\'` (conventionally `currency_code`). Refused under `dynamic` and `fixed`, and never empty.'),
   // #19992 — no `.overwrite()` here any more: the #7918 ISO 4217 contradiction
   // check and the #11423 default-materializing `.overwrite()` both existed only
   // for the removed `precision` key (see CURRENCY_CONFIG_DECIMAL_PLACES_GUIDANCE
-  // above). #27157 — `fixed` ⇒ a code; ADR-0144 D2 — `record` ⇔ a pointer, both
-  // below. Parse output is `{ currencyMode }` plus the `defaultCurrency` and
+  // above). #27157 — `fixed` ⇒ a code; ADR-0144 D2 — `record` ⇔ a pointer and
+  // no code, both below. Parse output is `{ currencyMode }` plus the `defaultCurrency` and
   // `currencyField` the author wrote.
-}).superRefine(refuseFixedCurrencyWithoutCode).superRefine(refuseCurrencyFieldOutsideRecordMode));
+}).superRefine(refuseFixedCurrencyWithoutCode).superRefine(refuseRecordModeKeyMismatch));
 
 /**
  * Address Schema — structured address for the `address` field type.

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

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { z } from 'zod';
-import { FieldSchema, FieldType } from './field.zod';
+import { FieldSchema, FieldType, VALUE_DOMAIN_FIELD_TYPES } from './field.zod';
 import { ValidationRuleSchema } from './validation.zod';
 import { ActionSchema, type ActionParam } from '../ui/action.zod';
 import { ObjectListViewSchema } from '../ui/view.zod';
@@ -1857,8 +1857,11 @@ function refuseNonPictureImageField(
  * prescription and the object's candidate fields:
  *
  *  - the name is not a declared field (or is the amount itself);
- *  - the field is not `text`;
- *  - the field is `text` without `valueDomain: 'iso_4217_currency'`.
+ *  - the field's type is not one that may declare a value domain
+ *    (`VALUE_DOMAIN_FIELD_TYPES`, field.zod.ts — `text` alone today; the ADR's
+ *    "text field" rests on that set, so this door reads it rather than
+ *    repeating the literal);
+ *  - the field is of such a type without `valueDomain: 'iso_4217_currency'`.
  *
  * Judged against the AUTHORED field map. Not judged on
  * `ObjectExtensionSchema`: an extension's fields merge into an object it does
@@ -1872,15 +1875,17 @@ function refuseDishonestRecordCurrencyField(
   if (fields === null || typeof fields !== 'object') return;
   const objectName = typeof ownName === 'string' ? ownName : '<unnamed>';
   const map = fields as Record<string, { type?: unknown; valueDomain?: unknown; currencyConfig?: unknown } | null>;
+  const isCodeType = (type: unknown): boolean => typeof type === 'string' && VALUE_DOMAIN_FIELD_TYPES.has(type);
+  const codeTypes = [...VALUE_DOMAIN_FIELD_TYPES].map((t) => `\`${t}\``).join(' or ');
   const isCodeField = (f: (typeof map)[string]): boolean =>
-    f?.type === 'text' && f.valueDomain === 'iso_4217_currency';
+    isCodeType(f?.type) && f?.valueDomain === 'iso_4217_currency';
   for (const [name, field] of Object.entries(map)) {
     const config = field?.currencyConfig as { currencyMode?: unknown; currencyField?: unknown } | undefined;
     if (config?.currencyMode !== 'record' || typeof config.currencyField !== 'string') continue;
     const target = config.currencyField;
     const candidates = Object.keys(map).filter((k) => k !== name && isCodeField(map[k]!));
     const prescription =
-      '`currencyField` must name a `text` field of this object declaring `valueDomain: \'iso_4217_currency\'` — '
+      `\`currencyField\` must name a ${codeTypes} field of this object declaring \`valueDomain: 'iso_4217_currency'\` — `
       + (candidates.length > 0
         ? `candidates: ${candidates.map((c) => `\`${c}\``).join(', ')}.`
         : 'the object has none; declare one, conventionally `currency_code: Field.text({ valueDomain: \'iso_4217_currency\' })`.');
@@ -1896,20 +1901,20 @@ function refuseDishonestRecordCurrencyField(
       continue;
     }
     const type = map[target]?.type;
-    if (type !== 'text') {
+    if (!isCodeType(type)) {
       ctx.addIssue({
         code: 'custom',
         path,
         message: `\`${name}.currencyConfig.currencyField\` names \`${target}\`, a \`${String(type)}\` field on object `
-          + `\`${objectName}\`; a record currency is a \`text\` ISO 4217 code. ${prescription}`,
+          + `\`${objectName}\`; a record currency is an ISO 4217 code in a ${codeTypes} field. ${prescription}`,
       });
       continue;
     }
     if (!isCodeField(map[target]!)) {
       ctx.addIssue({
         code: 'custom',
         path,
-        message: `\`${name}.currencyConfig.currencyField\` names \`${target}\`, a \`text\` field on object \`${objectName}\` `
+        message: `\`${name}.currencyConfig.currencyField\` names \`${target}\`, a \`${String(type)}\` field on object \`${objectName}\` `
           + `that does not declare \`valueDomain: 'iso_4217_currency'\`, so a write could store any string as the `
           + `currency. Add \`valueDomain: 'iso_4217_currency'\` to \`${target}\`, or point at another field. ${prescription}`,
       });

scripts/adr-anchors/packages__spec__src__data__field.zod.ts.json

@@ -1,7 +1,8 @@
 {
   "file": "packages/spec/src/data/field.zod.ts",
   "adrs": [
-    "ADR-0120"
+    "ADR-0120",
+    "ADR-0144"
   ],
-  "invariant": "`UniqueScopeSchema` is the closed scope vocabulary `boolean | 'global' | 'organization'` (ADR-0120 D1). `'organization'` is the explicit synonym of field-level `true` — identical materialization, and `isUniqueDeclared` MUST count it (a word the vocabulary accepts but no driver reads is declarable-but-inert, ADR-0078). `'tenant'` and `'org'` are rejected, never aliased — the parse error names `'organization'` (§Terminology; PD #12: one contract, no dialects). The single-tenant story is D3's NULL-safe COALESCE bucket, NOT the retired 'composite degenerates to single-column' claim #5030 falsified."
+  "invariant": "`UniqueScopeSchema` is the closed scope vocabulary `boolean | 'global' | 'organization'` (ADR-0120 D1). `'organization'` is the explicit synonym of field-level `true` — identical materialization, and `isUniqueDeclared` MUST count it (a word the vocabulary accepts but no driver reads is declarable-but-inert, ADR-0078). `'tenant'` and `'org'` are rejected, never aliased — the parse error names `'organization'` (§Terminology; PD #12: one contract, no dialects). The single-tenant story is D3's NULL-safe COALESCE bucket, NOT the retired 'composite degenerates to single-column' claim #5030 falsified.\n\nADR-0144 D2 — `CurrencyConfigSchema` has a third mode, `record`: the amount stays a bare number (ADR-0104 D1) and `currencyField` names the sibling field holding each record's ISO 4217 code. The config door (`refuseRecordModeKeyMismatch`) requires a non-empty `currencyField` under `record`, refuses it under `dynamic` / `fixed`, and refuses `defaultCurrency` under `record`. Each refused key would be declared but read by nothing (ADR-0078). Do NOT give `record` a `defaultCurrency` fallback or a platform-chosen code field name: per D8 rules 2 and 4, the code is the record's own, the field is the author's, and nothing fills either in. What the pointer NAMES is judged on the object (object.zod.ts), not here."
 }