Skip to content

Commit 75c7a09

Browse files
committed
docs(skills): teach currencyConfig.homeAmount; changeset for the home-amount pointer
The currency block of `objectstack-data/rules/field-types.md` gains the `homeAmount` example and one paragraph, paid for by deleting restatement in the same file (3207 -> 3181 tokens). The changeset declares `@objectstack/spec` and `@objectstack/skills` minor and marks the key as released with the write-time projection (ADR-0144 D9, R2). Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017ihL2fi9zfJhUTubyJYb6V
1 parent 3a39df5 commit 75c7a09

2 files changed

Lines changed: 47 additions & 26 deletions

File tree

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/skills': minor
4+
---
5+
6+
feat(spec): `currencyConfig.homeAmount: { field, rateDate, rateField }` — a record-mode amount declares its stored home-currency amount by pointer (ADR-0144 D5)
7+
8+
Clause-②: yes (widening)
9+
Metadata-protocol: added
10+
11+
⛔ Not released alone: this ships in the same release as the write-time home-currency projection that fills these fields (ADR-0144 D9, release R2: "the `homeAmount` key never ships ahead of the engine").
12+
13+
An amount in `currencyMode: 'record'` can now declare where its value is stored after conversion into the organization's home currency (the `localization.currency` setting), which date picks the exchange rate, and where the rate used is stored. Consolidated totals then aggregate the home field like any other stored currency field.
14+
15+
```ts
16+
fields: {
17+
currency_code: Field.text({ label: 'Currency', valueDomain: 'iso_4217_currency' }),
18+
invoice_date: Field.date({ label: 'Invoice date' }),
19+
amount: Field.currency({
20+
label: 'Amount',
21+
currencyConfig: {
22+
currencyMode: 'record',
23+
currencyField: 'currency_code',
24+
homeAmount: { field: 'amount_home', rateDate: 'invoice_date', rateField: 'amount_rate' },
25+
},
26+
}),
27+
amount_home: Field.currency({ label: 'Amount (home)', readonly: true }),
28+
amount_rate: Field.number({ label: 'Rate used', readonly: true }),
29+
}
30+
```
31+
32+
- **Three required pointers.** When `homeAmount` is declared, `field`, `rateDate` and `rateField` must all be given, and none may be empty. There is no default, no injected column and no fixed field name. The document date is never taken from `created_at`. `homeAmount` is refused under `dynamic` and `fixed`.
33+
- **What the pointers name, refused at parse with a remedy and the object's candidates.** Each refusal is located at `fields.AMOUNT.currencyConfig.homeAmount.POINTER`.
34+
- `field` must name another `currency` field of the same object in `dynamic` mode (it displays in the home currency, so metadata never names that currency). No other amount may already store into it.
35+
- `rateDate` must name a `date` or `datetime` field.
36+
- `rateField` must name a `number` field. Two amounts may share it only when they have the same `currencyField` and `rateDate`.
37+
- The amount itself must be a stored `currency` field. A `formula` amount is refused.
38+
- **The home and rate fields are written by the platform only.** They must declare `readonly: true`, the existing mark that drops a client's write of the field, and no `expression`.
39+
- **Skills:** `objectstack-data/rules/field-types.md` teaches `homeAmount`. Its field names (`amount_home`, `amount_rate`) are examples, not a contract.
40+
- **Nothing to migrate.** `homeAmount` is new, and no existing config changes meaning.

‎skills/objectstack-data/rules/field-types.md‎

Lines changed: 7 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,6 @@
66
- [Common Field Configurations](#common-field-configurations)
77
- [Incorrect vs Correct](#incorrect-vs-correct)
88

9-
Quick reference for choosing the right field type from the available options.
10-
119
## Two spellings: `Field.*` factory or object literal
1210

1311
The tables below give the **object-literal** spelling. Real apps overwhelmingly
@@ -144,16 +142,6 @@ Stored as JSON on the parent row — no separate table / FK:
144142

145143
## Common Field Configurations
146144

147-
### Text with Max Length
148-
149-
```typescript
150-
{
151-
type: 'text',
152-
maxLength: 255,
153-
required: true,
154-
}
155-
```
156-
157145
### Email with Uniqueness
158146

159147
```typescript
@@ -174,7 +162,8 @@ Stored as JSON on the parent row — no separate table / FK:
174162
type: 'currency',
175163
currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' }, // ISO 4217
176164
}
177-
// per record: { currencyMode: 'record', currencyField: 'currency_code' }
165+
// per record: { currencyMode: 'record', currencyField: 'currency_code',
166+
// homeAmount: { field: 'amount_home', rateDate: 'invoice_date', rateField: 'amount_rate' } }
178167
```
179168

180169
**Currency resolution.** The value is a bare number in every mode, never
@@ -187,6 +176,11 @@ it may only restate the code, else `DATASET_INVALID` (delete it), as is a derive
187176
measure over two different `'fixed'` codes (derive from one currency or drop an
188177
operand). A `'fixed'` code is not judged against the tenant's.
189178

179+
`homeAmount` (`'record'` only, all three required): the engine stores the
180+
home-currency amount in `field` (a `'dynamic'` `currency`) at the `rateDate`
181+
(`date`) rate, and that rate in `rateField` (`number`), both `readonly: true`.
182+
Cross-currency totals sum `field`.
183+
190184
### Select with Default
191185

192186
```typescript
@@ -208,8 +202,6 @@ operand). A `'fixed'` code is not judged against the tenant's.
208202
type: 'lookup',
209203
reference: 'account',
210204
required: true,
211-
// Structured, picker-honoured filter — the former string[] `referenceFilters`
212-
// was removed (ADR-0049): it filtered nothing.
213205
lookupFilters: [
214206
{ field: 'status', operator: 'eq', value: 'active' },
215207
],
@@ -227,17 +219,6 @@ operand). A `'fixed'` code is not judged against the tenant's.
227219
}
228220
```
229221

230-
### Master-Detail with Cascade
231-
232-
```typescript
233-
{
234-
type: 'master_detail',
235-
reference: 'invoice',
236-
deleteBehavior: 'cascade',
237-
required: true,
238-
}
239-
```
240-
241222
### Formula
242223

243224
```typescript

0 commit comments

Comments
 (0)