docs(data): name currencyConfig.homeAmount on field-types, validation-rules and objectql schema pages

content/docs/data-modeling/field-types.mdx

@@ -228,6 +228,7 @@ what a record-currency amount refuses.
 | `currencyConfig.currencyMode` | `'dynamic' \| 'fixed' \| 'record'` | `'dynamic'` | Whether the column is pinned to `defaultCurrency` (`fixed`), displays in the tenant default currency, the `localization.currency` setting (`dynamic`), or takes each record's own code from the field `currencyField` names (`record`); the value is a bare number in every mode |
 | `currencyConfig.defaultCurrency` | `string` | — | The column's currency code under `fixed`, where it is required; not the displayed currency under `dynamic`; refused under `record` |
 | `currencyConfig.currencyField` | `string` | — | `record` only, and required there: the field on the same object holding each record's ISO 4217 code, a `text` field with `valueDomain: 'iso_4217_currency'` (conventionally `currency_code`); refused under `dynamic` and `fixed` |
+| `currencyConfig.homeAmount` | `object` | — | `record` only, and optional there: where the engine stores the amount converted into the home currency (the `localization.currency` setting) and the rate it used. Three required pointers into the same object: `field`, a `dynamic`-mode `currency` field declaring `readonly: true`; `rateDate`, a `date` or `datetime` field holding the document date that picks the rate; `rateField`, a `number` field declaring `readonly: true`. Refused under `dynamic` and `fixed`. See [Declaring the home amount](/docs/data-modeling/currency#declaring-the-home-amount) |
 
 ```typescript
 { name: 'price', label: 'Price', type: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' } }

content/docs/data-modeling/validation-rules.mdx

@@ -155,6 +155,7 @@ These properties apply to **all** field types and are validated by the base `Fie
 | `currencyConfig.currencyMode` | `enum` | `dynamic` | `fixed` pins the field to `defaultCurrency`; `dynamic` displays the tenant default currency (the `localization.currency` setting); `record` takes each record's own currency from the code field `currencyField` names |
 | `currencyConfig.defaultCurrency` | `string` | — | 3-character currency code (ISO 4217 or crypto): the field's currency under `fixed`, where it is required (a `fixed` config without one is refused); not the displayed currency under `dynamic`; refused under `record` |
 | `currencyConfig.currencyField` | `string` | — | Required under `record` and refused under the other two modes: a `text` field of the same object declaring `valueDomain: 'iso_4217_currency'` (the object refuses a pointer at anything else). A write that leaves a record-mode amount holding a value beside a blank code is refused, `ERR_CURRENCY_CODE_REQUIRED` / 400 |
+| `currencyConfig.homeAmount` | `object` | — | Optional under `record` and refused under the other two modes: the stored home-currency projection, three pointers into the same object, all required — `field` (a `dynamic`-mode `currency` field, `readonly: true`), `rateDate` (a `date` or `datetime` field, the document date that picks the rate) and `rateField` (a `number` field, `readonly: true`). See [Declaring the home amount](/docs/data-modeling/currency#declaring-the-home-amount) |
 
 **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 amount never carries its currency code: under `dynamic` and `fixed` the code is field configuration, carried by `currencyConfig` above, and under `record` it is the value of the record's own code field, an ordinary `text` column judged by its `valueDomain` ([Currency fields](/docs/data-modeling/currency)). Decimal places are the currency's ISO 4217 minor unit (2 for USD, 0 for JPY, 3 for KWD) and are declared nowhere — `currencyConfig` has no decimal-places key (`currencyConfig.precision` is refused, with a prescription to delete it), and the field-level `precision` is the total digit count, never compared with the currency.
 
@@ -534,7 +535,7 @@ section above). See the
 | `html` | — | Sanitized, `maxLength` |
 | `richtext` | — | Sanitized, `maxLength` |
 | `number` | — | `min`, `max`, `precision`, `scale` |
-| `currency` | — | `currencyConfig` (mode, code or code field) |
+| `currency` | — | `currencyConfig` (`currencyMode`, `defaultCurrency`, `currencyField`, `homeAmount`) |
 | `percent` | — | `min`, `max`, stored as decimal |
 | `date` | — | ISO 8601 date |
 | `datetime` | — | ISO 8601 datetime, UTC |

content/docs/protocol/objectql/schema.mdx

@@ -292,7 +292,7 @@ fields:
 | `max` | `number` | `number`, `currency` | Maximum numeric value. |
 | `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). |
-| `currencyConfig` | `object` | `currency` | Where the amount's currency comes from: `currencyMode` `dynamic` (the tenant default, the default), `fixed` (with `defaultCurrency`) or `record` (with `currencyField`, the sibling code field). |
+| `currencyConfig` | `object` | `currency` | Where the amount's currency comes from: `currencyMode` `dynamic` (the tenant default, the default), `fixed` (with `defaultCurrency`) or `record` (with `currencyField`, the sibling code field, and optionally `homeAmount`, the stored home-currency projection: `field` a `dynamic`-mode `currency` field, `rateDate` a `date` or `datetime` field, `rateField` a `number` field — see [Declaring the home amount](/docs/data-modeling/currency#declaring-the-home-amount)). |
 | `options` | `array` | `select`, `multiselect` | List of valid values. |
 | `multiple` | `boolean` | `select`, `lookup` | Allow multiple selections. |
 | `reference` | `string` | `lookup`, `master_detail` | Target object for relationships. |