Skip to content

Commit 0776905

Browse files
committed
docs(skills): teach the two fixed-currency dataset refusals beside the currency chain
A dataset measure's own `currency` no longer always wins over a `fixed` field: compile refuses a code other than the field's, and a derived measure over two different `fixed` codes, both DATASET_INVALID / 400. Two skills files and two docs pages now state both refusals, their fixes, and the two not-judged cases. The skills rows are paid down by deleting restating comments; the remainder raises two token-ratchet rows on the standing path. Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WV4czgqyQbG9VgmyNYDNt
1 parent 8f41b2d commit 0776905

6 files changed

Lines changed: 63 additions & 9 deletions

File tree

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): a dataset measure's `currency` no longer "always wins" over a `fixed` field; the skills teach the two `fixed` refusals
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- `objectstack-data` `rules/field-types.md` (Currency resolution) and `objectstack-ui` `rules/dashboards.md` (the dataset currency comment) taught that a measure's own `currency` wins under `fixed`. Dataset compile now refuses, with `DATASET_INVALID` / 400, a measure `currency` that differs from its field's `fixed` code (delete it; restating the code is accepted) and a derived measure whose monetary operands resolve to two different `fixed` codes (derive from measures in one currency, or drop the operand in the other). Both files now say so, and keep the not-judged cases explicit: a `fixed` code against the tenant currency, and a measure `currency` over a `dynamic` field.
11+
- Paid for inside each file by deleting a restating code comment; the remainder raises the two token-ratchet rows on the standing path.
12+
- No schema, key or behaviour changes.

‎content/docs/api/data-api.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -502,6 +502,14 @@ tenant default currency (the `localization.currency` setting), if one is set. A
502502
so its column shows the tenant default. The cube query on this page carries no column
503503
`currency`.
504504

505+
Over a `fixed` field the measure's `currency` may only restate the field's code. A
506+
different code is refused when the dataset compiles, with `DATASET_INVALID` / 400: delete
507+
the measure's `currency`, and the column takes the field's code. A derived measure whose
508+
monetary operands resolve to two different `fixed` codes is refused the same way, whatever
509+
the operation: derive it from measures in one currency, or drop the operand in the other.
510+
Neither a `fixed` code against the tenant default nor a measure `currency` over a
511+
`dynamic` field is judged.
512+
505513
A measure column over a `currencyMode: 'record'` amount has one currency per row, so it
506514
carries `currencyField` instead of `currency`: the name of the dimension column, in the same
507515
answer, that groups by the amount's code field (`currencyConfig.currencyField`). Each row's

‎content/docs/data-modeling/currency.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,18 @@ that column. A `count` column never carries `currencyField`. See the
171171
currency** (another code field, a `fixed` code, an explicit measure code or the tenant
172172
currency) is refused at compile with `DATASET_INVALID` / 400, whatever the operation.
173173
A derived measure over a `count`, such as an amount per invoice, stays legal.
174+
- **A dataset measure whose `currency` differs from its field's `fixed` code** is refused
175+
at compile with `DATASET_INVALID` / 400: `currency: 'USD'` over a field fixed to `EUR`
176+
would label euros as dollars. Delete the measure's `currency`, and the column takes the
177+
field's code. A `currency` that restates the field's code is accepted.
178+
- **A derived measure whose monetary operands resolve to two different `fixed` codes** is
179+
refused at compile with `DATASET_INVALID` / 400, whatever the operation. Derive it from
180+
measures in one currency, or drop the operand in the other. A derived `sum` or
181+
`difference` over one `fixed` code carries that code, so a measure built on it is judged
182+
the same way.
183+
- **Not judged:** a `fixed` code against the tenant currency, which compile does not know,
184+
and a measure `currency` over a `dynamic` field, which wins as the top of the currency
185+
chain.
174186

175187
### In the Console
176188

‎scripts/check-skills-token-ratchet.mjs‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -679,7 +679,15 @@ export const CEILINGS = new Map([
679679
// zero headroom to absorb any of it, ceiling +126. Maintainer ruling
680680
// 2026-09-22 on decision batch #213 (item 1 carries the TOCs: 「四个超长 SKILL.md 按 500 行切,整段示例与 platform 的运维尾段下沉 references/,零删内容;同卡顺手:data 的 description 压到约 700 字符、长参考文件加目录」),
681681
// verbatim and untranslated: 「1 2 4 同意」.
682-
['skills/objectstack-data/rules/field-types.md', 3158],
682+
// 3158 -> 3207 (#27994): the Currency resolution paragraph teaches the two `fixed`
683+
// refusals #27991 added (a measure `currency` other than the field's `fixed` code; a
684+
// derived measure over two `fixed` codes), each fix, and the not-judged tenant case.
685+
// PAID DOWN FIRST by the Formula example's `returnType` comment, which restated the
686+
// Calculated table's return types. The file is 12827 bytes -> 3207 tokens, zero
687+
// headroom, ceiling +49, pinned AT the measurement. Standing ruling (2026-10-27, tap A,
688+
// verbatim and untranslated): 「A:先削重复,余额按实测提高」; recognised path per ruling
689+
// record 6513306068.
690+
['skills/objectstack-data/rules/field-types.md', 3207],
683691
['skills/objectstack-data/rules/indexing.md', 3241],
684692
['skills/objectstack-data/rules/lifecycle.md', 1590],
685693
['skills/objectstack-data/rules/naming.md', 773],
@@ -827,7 +835,15 @@ export const CEILINGS = new Map([
827835
// follows it down to the new measurement, the ratchet's ordinary direction.
828836
// 6239 -> 6221 (#26602): LOWERED. The metric-widget bullet teaches the measure's `polarity`,
829837
// paid inside the file; the ceiling follows the file down to the measurement (24881 bytes).
830-
['skills/objectstack-ui/rules/dashboards.md', 6221],
838+
// 6221 -> 6262 (#27994): the dataset currency comment teaches the two `fixed` refusals
839+
// #27991 added, each fix, and the two not-judged cases. PAID DOWN FIRST: the metric
840+
// example's `colorVariant` comment no longer restates that the measure's `format` /
841+
// `currency` drive the number (Widget `options` says it), and the measure example in the
842+
// currency comment shrinks to its `currency` key (the dataset above shows the shape).
843+
// The file is 25047 bytes -> 6262 tokens, zero headroom, ceiling +41, pinned AT the
844+
// measurement. Standing ruling (2026-10-27, tap A, verbatim and untranslated):
845+
// 「A:先削重复,余额按实测提高」; recognised path per ruling record 6513306068.
846+
['skills/objectstack-ui/rules/dashboards.md', 6262],
831847
// 3011 -> 3141 (#19715, card item 4): a 5-line table of contents at the top,
832848
// anchors to the file's existing headings, nothing else changed. +132 tokens,
833849
// of which the row's 2 tokens of headroom absorb 2; the CEILING moves 130.

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -181,8 +181,11 @@ Stored as JSON on the parent row — no separate table / FK:
181181
`{ value, currency }`. Shown: `'fixed'`, `defaultCurrency`; `'dynamic'`
182182
(default), the tenant `localization.currency`, else a plain number (never
183183
`$`); `'record'`, each record's code in the `text` field `currencyField`
184-
names (by convention `currency_code`), with `valueDomain: 'iso_4217_currency'`. Under
185-
`'fixed'`/`'dynamic'` a measure's own `currency` wins.
184+
names (by convention `currency_code`), with `valueDomain: 'iso_4217_currency'`. A
185+
dataset measure's own `currency` wins over a `'dynamic'` field; over a `'fixed'` one
186+
it may only restate the code, else `DATASET_INVALID` (delete it), as is a derived
187+
measure over two different `'fixed'` codes (derive from one currency or drop an
188+
operand). A `'fixed'` code is not judged against the tenant's.
186189

187190
### Select with Default
188191

@@ -243,7 +246,7 @@ import { F } from '@objectstack/spec';
243246
const total = {
244247
type: 'formula',
245248
expression: F`record.amount * record.tax_rate`,
246-
returnType: 'number', // 'number' | 'text' | 'boolean' | 'date' | 'currency' (money; own currencyConfig)
249+
returnType: 'number', // see the Calculated table
247250
};
248251
```
249252

‎skills/objectstack-ui/rules/dashboards.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ export const SalesDashboard: Dashboard = {
178178
dataset: 'opportunity_metrics', values: ['total_amount'],
179179
filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
180180
layout: { x: 0, y: 0, w: 3, h: 2 },
181-
colorVariant: 'success', // the accent; the measure's own `format` + `currency` drive the number
181+
colorVariant: 'success', // the accent only
182182
// Period-over-period: renderer fetches the prior quarter and
183183
// surfaces a secondary value + delta arrow automatically.
184184
compareTo: { kind: 'previousPeriod' },
@@ -295,13 +295,16 @@ defineDataset({
295295
dimensions: [{ name: 'signed_date', field: 'signed_date', type: 'date', dateGranularity: 'month' }],
296296
measures: [{ name: 'signed_count', aggregate: 'count' }],
297297
});
298-
// A money measure may set `currency` (ISO 4217):
299-
// `{ name: 'revenue', aggregate: 'sum', field: 'amount', currency: 'USD' }`.
298+
// A money measure may set `currency` (ISO 4217), e.g. `currency: 'USD'`.
300299
// Chain: measure `currency` → the field's `defaultCurrency` (`fixed`
301300
// only) → tenant `localization.currency`; omit it for counts. A
302301
// `currencyMode: 'record'` amount refuses `currency` and ungrouped
303302
// sum/avg/min/max; grouped by its code field, the column carries
304-
// `currencyField` (per-row code column); a `count` never does.
303+
// `currencyField` (per-row code column); a `count` never does. A `fixed`
304+
// field refuses a different `currency` (delete it; restating is fine), and
305+
// a derived measure refuses operands in two `fixed` codes (derive from one
306+
// currency or drop one). Not judged: `currency` over a `dynamic` field, a
307+
// `fixed` code against the tenant's.
305308

306309
// The widget just selects the dimension by name:
307310
const signedByMonth: DashboardWidget = { id: 'signed_by_month', type: 'line',

0 commit comments

Comments
 (0)