@@ -0,0 +1,99 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ADR-0144 D2 in the Studio field editor: a currency amount's mode, the
+ * `record`-mode `currencyField` picker over the object's own ISO 4217 code
+ * fields, and "Create currency field", which writes explicit metadata.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach, beforeAll } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ObjectSchema } from '@objectstack/spec/data';
+import {
+  currencyCodeFieldCandidates,
+  nextCurrencyCodeFieldName,
+  switchCurrencyMode,
+} from './CurrencyConfigField';
+
+vi.mock('../useMetadata', () => ({
+  useMetadataClient: () => ({
+    list: vi.fn().mockResolvedValue([]),
+    listDrafts: vi.fn().mockResolvedValue([]),
+  }),
+}));
+
+vi.mock('../previews/useObjectFields', () => ({
+  useObjectFields: () => ({ fields: [], loading: false, error: null }),
+}));
+
+import { ObjectFieldInspector } from './ObjectFieldInspector';
+
+afterEach(cleanup);
+
+beforeAll(() => {
+  for (const m of ['hasPointerCapture', 'setPointerCapture', 'releasePointerCapture'] as const) {
+    if (!Element.prototype[m]) {
+      // @ts-expect-error test shim
+      Element.prototype[m] = m === 'hasPointerCapture' ? () => false : () => {};
+    }
+  }
+  if (!Element.prototype.scrollIntoView) Element.prototype.scrollIntoView = () => {};
+});
+
+function renderAmount(fields: Record<string, Record<string, unknown>>) {
+  const onPatch = vi.fn();
+  render(
+    <ObjectFieldInspector
+      type="object"
+      name="invoice"
+      draft={{ name: 'invoice', fields }}
+      selection={{ kind: 'field', id: 'amount' }}
+      onPatch={onPatch}
+      onClearSelection={vi.fn()}
+      onSelectionChange={vi.fn()}
+      readOnly={false}
+      locale="en-US"
+    />,
+  );
+  const saved = () => onPatch.mock.calls.at(-1)![0].fields as Record<string, Record<string, unknown>>;
+  return { onPatch, saved };
+}
+
+const CODE = { type: 'text', label: 'Currency', valueDomain: 'iso_4217_currency' };
+
+describe('Studio currency section (ADR-0144 D2)', () => {
+  it('a mode switch keeps only the keys that mode reads', () => {
+    expect(switchCurrencyMode({ currencyMode: 'record', currencyField: 'currency_code' }, 'dynamic')).toEqual({ currencyMode: 'dynamic' });
+    expect(switchCurrencyMode({ currencyMode: 'fixed', defaultCurrency: 'EUR' }, 'record')).toEqual({ currencyMode: 'record' });
+    expect(switchCurrencyMode({ currencyMode: 'fixed', defaultCurrency: 'EUR' }, 'fixed')).toEqual({ currencyMode: 'fixed', defaultCurrency: 'EUR' });
+  });
+
+  it('the picker lists only text fields in the ISO 4217 domain, never the amount itself', () => {
+    const entries = [
+      { name: 'amount', def: { type: 'currency' } },
+      { name: 'currency_code', def: CODE },
+      { name: 'note', def: { type: 'text' } },
+      { name: 'country', def: { type: 'text', valueDomain: 'iso_3166_alpha2' } },
+    ];
+    expect(currencyCodeFieldCandidates(entries, 'amount')).toEqual(['currency_code']);
+    expect(nextCurrencyCodeFieldName(entries)).toBe('currency_code_2');
+    expect(nextCurrencyCodeFieldName([])).toBe('currency_code');
+  });
+
+  it('offers the record mode and the currencyField picker on a currency field', () => {
+    renderAmount({ amount: { type: 'currency', label: 'Amount', currencyConfig: { currencyMode: 'record', currencyField: 'currency_code' } }, currency_code: CODE });
+    expect(screen.getByRole('combobox', { name: 'Currency mode' })).toHaveTextContent('Record');
+    expect(screen.getByRole('combobox', { name: /Currency field/ })).toHaveTextContent('currency_code');
+  });
+
+  it('"Create currency field" writes an explicit code field and the pointer, and the object parses', async () => {
+    const { saved } = renderAmount({ amount: { type: 'currency', label: 'Amount', currencyConfig: { currencyMode: 'record' } } });
+    await userEvent.click(screen.getByTestId('currency-config-create-code-field'));
+    const fields = saved();
+    expect(fields.amount.currencyConfig).toEqual({ currencyMode: 'record', currencyField: 'currency_code' });
+    expect(fields.currency_code).toEqual({ type: 'text', label: 'Currency', valueDomain: 'iso_4217_currency', required: true });
+    expect(ObjectSchema.safeParse({ name: 'invoice', label: 'Invoice', fields }).success).toBe(true);
+  });
+});
@@ -0,0 +1,170 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The Studio field editor's currency section: a currency amount's
+ * `currencyConfig` (ADR-0144 D2), in its three modes —
+ *
+ *  - `dynamic` (the default): no currency of its own; the organization
+ *    currency displays;
+ *  - `fixed`: one currency, `defaultCurrency`;
+ *  - `record`: each record names its own, in the sibling code field
+ *    `currencyField` points at.
+ *
+ * The pointer is picked from the object's own record-currency code fields —
+ * `text` fields declaring `valueDomain: 'iso_4217_currency'`, the only fields
+ * the spec accepts there — and "Create currency field" writes one such field
+ * with explicit metadata and points at it, so the author never has to know the
+ * convention to get a valid declaration. Nothing here guesses a code or a
+ * pointer: an unpicked pointer stays absent and the spec's own refusal says so
+ * on save.
+ */
+
+import * as React from 'react';
+import { Button } from '@object-ui/components';
+import { Plus } from 'lucide-react';
+import { InspectorSelectField, InspectorTextField } from './_shared.js';
+import type { FieldEntry } from '../previews/object-fields-io.js';
+
+/** The record-currency code field's value domain (ADR-0144 D2). */
+export const CURRENCY_CODE_VALUE_DOMAIN = 'iso_4217_currency';
+
+/** The naming convention for a record-currency code field (guidance, never a contract — ADR-0144 D8 rule 2). */
+export const CURRENCY_CODE_FIELD_NAME = 'currency_code';
+
+export type CurrencyMode = 'dynamic' | 'fixed' | 'record';
+
+export interface CurrencyConfigDraft {
+  currencyMode?: CurrencyMode;
+  defaultCurrency?: string;
+  currencyField?: string;
+}
+
+/** Whether a field def is a record-currency code field: `text` + the ISO 4217 domain. */
+export function isCurrencyCodeFieldDef(def: Record<string, unknown> | undefined): boolean {
+  return def?.type === 'text' && def.valueDomain === CURRENCY_CODE_VALUE_DOMAIN;
+}
+
+/** The fields of `entries` (other than `self`) a `record`-mode pointer may name. */
+export function currencyCodeFieldCandidates(entries: readonly FieldEntry[], self: string): string[] {
+  return entries.filter((e) => e.name !== self && isCurrencyCodeFieldDef(e.def)).map((e) => e.name);
+}
+
+/** `currency_code`, or `currency_code_2`, `_3`, … when the name is taken. */
+export function nextCurrencyCodeFieldName(entries: readonly FieldEntry[]): string {
+  const taken = new Set(entries.map((e) => e.name));
+  if (!taken.has(CURRENCY_CODE_FIELD_NAME)) return CURRENCY_CODE_FIELD_NAME;
+  let n = 2;
+  while (taken.has(`${CURRENCY_CODE_FIELD_NAME}_${n}`)) n += 1;
+  return `${CURRENCY_CODE_FIELD_NAME}_${n}`;
+}
+
+/**
+ * The config a mode switch writes. Each mode keeps only the keys it reads, so
+ * the spec's own pairing rule holds by construction: `currencyField` exists
+ * only under `record`, and `defaultCurrency` is carried only under `fixed`. A
+ * key the author already wrote for the target mode is kept; none is invented.
+ */
+export function switchCurrencyMode(prev: CurrencyConfigDraft | undefined, mode: CurrencyMode): CurrencyConfigDraft {
+  if (mode === 'fixed') {
+    return { currencyMode: 'fixed', ...(prev?.defaultCurrency ? { defaultCurrency: prev.defaultCurrency } : {}) };
+  }
+  if (mode === 'record') {
+    return { currencyMode: 'record', ...(prev?.currencyField ? { currencyField: prev.currencyField } : {}) };
+  }
+  return { currencyMode: 'dynamic' };
+}
+
+/**
+ * The explicit metadata "Create currency field" writes: a required `text`
+ * field in the ISO 4217 domain. Required because a record-mode amount without
+ * a code has no currency, and the server refuses a blank code at write.
+ */
+export function newCurrencyCodeFieldDef(label: string): Record<string, unknown> {
+  return { type: 'text', label, valueDomain: CURRENCY_CODE_VALUE_DOMAIN, required: true };
+}
+
+export function CurrencyConfigField({
+  config,
+  candidates,
+  onCommit,
+  onCreateCodeField,
+  disabled,
+  tr,
+}: {
+  config: CurrencyConfigDraft | undefined;
+  /** {@link currencyCodeFieldCandidates} of the object this field belongs to. */
+  candidates: readonly string[];
+  /** Write the whole config. */
+  onCommit: (next: CurrencyConfigDraft) => void;
+  /** Append a record-currency code field and point this amount at it, in one write. */
+  onCreateCodeField: () => void;
+  disabled?: boolean;
+  tr: (key: string) => string;
+}) {
+  const mode: CurrencyMode = config?.currencyMode ?? 'dynamic';
+  const pointer = config?.currencyField;
+  return (
+    <div className="space-y-2" data-testid="currency-config-field">
+      <InspectorSelectField
+        label={tr('designer.field.currency.mode')}
+        value={mode}
+        options={[
+          { value: 'dynamic', label: tr('designer.field.currency.modeDynamic') },
+          { value: 'fixed', label: tr('designer.field.currency.modeFixed') },
+          { value: 'record', label: tr('designer.field.currency.modeRecord') },
+        ]}
+        onCommit={(v) => onCommit(switchCurrencyMode(config, v as CurrencyMode))}
+        disabled={disabled}
+      />
+      {mode === 'fixed' && (
+        <InspectorTextField
+          label={tr('designer.field.currency.defaultCurrency')}
+          value={config?.defaultCurrency ?? ''}
+          // A three-letter code, written upper-case as ISO 4217 spells it.
+          onCommit={(v) => {
+            const code = v.trim().toUpperCase();
+            onCommit(code ? { currencyMode: 'fixed', defaultCurrency: code } : { currencyMode: 'fixed' });
+          }}
+          placeholder="USD"
+          disabled={disabled}
+        />
+      )}
+      {mode === 'record' && (
+        <>
+          <InspectorSelectField
+            label={tr('designer.field.currency.currencyField')}
+            value={pointer ?? ''}
+            options={[
+              { value: '', label: tr('designer.field.currency.currencyFieldNone') },
+              ...candidates.map((name) => ({ value: name, label: name })),
+            ]}
+            // Unpicking DELETES the pointer: the spec refuses a `record` config
+            // without one on save, which is the honest answer, rather than a
+            // pointer at a field the author never chose.
+            onCommit={(v) => onCommit(v ? { currencyMode: 'record', currencyField: v } : { currencyMode: 'record' })}
+            required
+            disabled={disabled}
+          />
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={onCreateCodeField}
+            disabled={disabled}
+            data-testid="currency-config-create-code-field"
+          >
+            <Plus className="mr-1 h-3.5 w-3.5" />
+            {tr('designer.field.currency.createCodeField')}
+          </Button>
+          <p className="text-xs text-muted-foreground">{tr('designer.field.currency.recordHint')}</p>
+        </>
+      )}
+    </div>
+  );
+}
@@ -102,6 +102,13 @@ import {
   type FieldTypeId,
 } from '../previews/field-types.js';
 import { FieldTypePicker } from './FieldTypePicker.js';
+import {
+  CurrencyConfigField,
+  currencyCodeFieldCandidates,
+  nextCurrencyCodeFieldName,
+  newCurrencyCodeFieldDef,
+  type CurrencyConfigDraft,
+} from './CurrencyConfigField.js';
 import { CelPredicateField } from '../CelPredicateField.js';
 import type { CelLintIssue } from '../celAuthoring.js';
 import { t, tFormat, type SupportedLocale } from '../i18n.js';
@@ -794,6 +801,26 @@ export function ObjectFieldInspector({
     writeView({ shape: view.shape, entries: nextEntries });
   };
 
+  /**
+   * ADR-0144 D2 — "Create currency field": append a record-currency code field
+   * (explicit metadata: `text`, the ISO 4217 domain, required) right after this
+   * amount and point the amount at it, as ONE write, so the draft never holds
+   * a `record` config pointing at a field that does not exist yet.
+   */
+  const createCurrencyCodeField = () => {
+    const codeName = nextCurrencyCodeFieldName(view.entries);
+    const nextEntries = [...view.entries];
+    nextEntries[idx] = {
+      ...entry,
+      def: { ...def, currencyConfig: { currencyMode: 'record', currencyField: codeName } },
+    };
+    nextEntries.splice(idx + 1, 0, {
+      name: codeName,
+      def: newCurrencyCodeFieldDef(tr('designer.field.currency.codeFieldLabel')),
+    });
+    writeView({ shape: view.shape, entries: nextEntries });
+  };
+
   /**
    * objectui#12326 — on a `controlled_by_parent` object a `master_detail` field
    * is `required: true` and its Required box is locked on: the object derives
@@ -1298,6 +1325,16 @@ export function ObjectFieldInspector({
               />
             </div>
           )}
+          {(type === 'currency' || (type === 'formula' && def.returnType === 'currency')) && (
+            <CurrencyConfigField
+              config={def.currencyConfig as CurrencyConfigDraft | undefined}
+              candidates={currencyCodeFieldCandidates(view.entries, name)}
+              onCommit={(next) => patchDef({ currencyConfig: next })}
+              onCreateCodeField={createCurrencyCodeField}
+              disabled={readOnly}
+              tr={tr}
+            />
+          )}
           {isTexty(type) && (
             <div className="grid grid-cols-2 gap-2">
               <InspectorNumberField