@@ -0,0 +1,16 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/formula': patch
+'@objectstack/spec': patch
+---
+
+feat(objectql): a record-currency amount is refused without its code, refused in an ungrouped raw aggregate, and refused under a summary roll-up
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+- **A `record`-mode amount is stored with its currency code (ADR-0144 D8 rule 4).** An insert or update that would store a value in a `currency` field declaring `currencyConfig: { currencyMode: 'record', currencyField }` while that code field is blank (absent, `null` or white space) is refused `ERR_CURRENCY_CODE_REQUIRED` / 400, with `field` naming the code field and `amountField` the amount. The server never fills a currency in. On an update, only a write that carries the amount or its code is judged, against the stored row with the payload laid over it, so an edit of another field never meets it. The `validate()` preview (`validateData`) answers the same refusal as the row's finding for an insert and for a by-id update, so a dry run does not pass a row the write refuses. The code is registered under `@objectstack/objectql` in the ADR-0112 error-code ledger.
+- **A raw aggregate over a `record`-mode amount groups by its code field (ADR-0144 D6).** `sum`, `avg`, `min` and `max` over such a field through `engine.aggregate` are refused `INVALID_FIELD` / 400 unless `groupBy` names the code field; grouped, each currency totals on its own. `count` and `count_distinct` are not judged. Before, USD 100 and EUR 100 summed to 200 under one label.
+- **A `summary` roll-up over a `record`-mode amount is refused at registration (ADR-0144 D6).** `sum` / `avg` / `min` / `max` of such a child field is refused `INVALID_METADATA` / 422 (`RecordCurrencySummaryRefusedError`) at whichever object's registration completes the pair. Before, child rows of USD 100 and JPY 15000 rolled up to 15100. Use `count`, or roll up a stored home-currency amount.
+- **`inferFormulaReturn` carries a record currency (`@objectstack/formula`).** A formula over a `record`-mode amount now declares `returnType: 'currency'` with `currencyConfig: { currencyMode: 'record', currencyField }`, the code field its sources name, instead of a tenant-default (`dynamic`) amount. Two record-mode amounts naming different code fields, or a record-mode amount meeting a `fixed` or `dynamic` one, are not one currency and are not stamped as money.
+- **Nothing to migrate.** `currencyMode: 'record'` is new; no field declared before it meets any of these refusals.
@@ -0,0 +1,23 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-analytics': minor
+---
+
+feat(spec,service-analytics): analytics over a record-currency amount — grouped answers name a per-row currency, an ungrouped amount aggregate is refused, and two compile-time guards on record-mode measures (ADR-0144 D2, D6)
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+A measure column over a `currencyMode: 'record'` amount now carries `fields[].currencyField` on a `queryDataset` answer: the name of the dimension column that groups by the amount's code field. Each row's currency is that row's value of it, and the column carries no `currency`. Before, a breakdown by currency labelled every group with one code.
+
+- `AnalyticsResult.fields[].currencyField` (`@objectstack/spec/contracts`) and the same key on `AnalyticsResultResponseSchema` (`@objectstack/spec/api`).
+- The cube door refuses a `sum`, `avg`, `min` or `max` over a record-mode amount whose query does not group by the code field, with `INVALID_FIELD` / 400 naming the measure, the field and its object. It judges every path: a dataset or registered cube, an ad-hoc `query` over the object (`amount_sum`), and a draft preview. A `totals` grouping that drops the code, the grand total included, is refused the same way. `count` reads no amount and is served, and its column carries neither currency key.
+
+Two compile-time refusals, `DATASET_INVALID` / 400, on the record mode alone, so nothing that compiled before is refused:
+
+- a measure `currency` over a record-mode amount, whose currency is per row, including on a derived measure that resolves to one;
+- a derived measure that combines a record-mode amount with an operand in another currency (another code field, a `fixed` code, an explicit code or the tenant's), for every op. A count operand is not compared, so an amount-per-invoice ratio still compiles.
+
+The same two shapes over `fixed` fields only are not judged here; ADR-0144 open item 12 refuses them on a card of its own after this release.
+
+⛔ Not released alone: this ships in the same release as the record currency mode, its write refusals and the per-row display.
@@ -474,7 +474,7 @@ is executed. `POST /analytics/sql` refuses the same keys. To order by a member,
 <Callout type="info">
 **`fields[]` is the resolved presentation surface — read it first.** Each entry carries
 `name` and `type` and, when the producer declares them, `label`, `format`, `currency`,
-`percentScale`, `builtinAggregate`, `aggregate`, `nullLabel` and `polarity` (which direction
+`currencyField`, `percentScale`, `builtinAggregate`, `aggregate`, `nullLabel` and `polarity` (which direction
 of a measure's change is good news, relayed from the dataset measure): the optional members
 `AnalyticsResultResponseSchema` declares (`packages/spec/src/api/analytics.zod.ts`),
 mirrored member for member by `IAnalyticsService.query`'s `AnalyticsResult` and bound to
@@ -500,6 +500,13 @@ tenant default currency (the `localization.currency` setting), if one is set. A
 so its column shows the tenant default. The cube query on this page carries no column
 `currency`.
 
+A measure column over a `currencyMode: 'record'` amount has one currency per row, so it
+carries `currencyField` instead of `currency`: the name of the dimension column, in the same
+answer, that groups by the amount's code field (`currencyConfig.currencyField`). Each row's
+currency is that row's value of that column. A `sum`, `avg`, `min` or `max` over such an
+amount is refused `INVALID_FIELD` / 400 unless the query groups by the code field, on the
+dataset query and the cube query alike; a `count` is served.
+
 The dataset query also states each measure column's `aggregate` (`count`, `sum`, `avg`,
 `min`, `max`, `count_distinct`), whether or not the author labelled the measure, so a
 chart can tell a count from a sum. `builtinAggregate` is narrower: it is present only
 
@@ -169,3 +169,40 @@ describe('CONTROL — a numeric formula stays `number`', () => {
     expect(inferFormulaReturn('record.amount *', FIELDS)).toEqual({});
   });
 });
+
+describe('a formula over a record-mode amount carries the record currency (ADR-0144 D2)', () => {
+  const RECORD = { currencyMode: 'record', currencyField: 'currency_code' } as const;
+  const RECORD_FIELDS: Readonly<Record<string, FormulaSourceField>> = {
+    currency_code: { type: 'text' },
+    other_code: { type: 'text' },
+    amount: { type: 'currency', currencyConfig: RECORD },
+    tax: { type: 'currency', currencyConfig: RECORD },
+    fee: { type: 'currency', currencyConfig: { currencyMode: 'record', currencyField: 'other_code' } },
+    budget: { type: 'currency' },
+    usd: { type: 'currency', currencyConfig: USD },
+    quantity: { type: 'number' },
+  };
+
+  it('stamps `record` mode with the source amount\'s code field, never the tenant default', () => {
+    expect(inferFormulaReturn('record.amount * 0.1', RECORD_FIELDS))
+      .toEqual({ returnType: 'currency', currencyConfig: RECORD });
+    expect(inferFormulaReturn('record.amount + record.tax', RECORD_FIELDS))
+      .toEqual({ returnType: 'currency', currencyConfig: RECORD });
+    expect(inferFormulaReturn('round(record.amount * record.quantity)', RECORD_FIELDS))
+      .toEqual({ returnType: 'currency', currencyConfig: RECORD });
+  });
+
+  it('an amount over its own currency is a plain ratio', () => {
+    expect(inferFormulaReturn('record.tax / record.amount', RECORD_FIELDS).returnType).not.toBe('currency');
+  });
+
+  it('two different currencies meeting are not one amount', () => {
+    for (const source of [
+      'record.amount + record.fee', // two code fields
+      'record.amount + record.budget', // record + the tenant default
+      'record.amount + record.usd', // record + fixed USD
+    ]) {
+      expect(inferFormulaReturn(source, RECORD_FIELDS).returnType, source).not.toBe('currency');
+    }
+  });
+});
@@ -79,15 +79,25 @@ export interface FormulaSourceField {
  *
  * - `returnType` — absent when no concrete type can be proven.
  * - `currencyConfig` — present only for a `currency` result whose currency is
- *   `fixed`. A `dynamic` result (the tenant default currency) declares no config,
- *   exactly as a `dynamic` currency field may carry none.
+ *   `fixed`, or `record` (ADR-0144 D2: each record's own currency, carried as
+ *   the same `currencyField` its source amounts name). A `dynamic` result (the
+ *   tenant default currency) declares no config, exactly as a `dynamic`
+ *   currency field may carry none.
  */
 export interface FormulaReturnDeclaration {
   readonly returnType?: NonNullable<Field['returnType']>;
-  readonly currencyConfig?: { readonly currencyMode: 'fixed'; readonly defaultCurrency: string };
+  readonly currencyConfig?:
+    | { readonly currencyMode: 'fixed'; readonly defaultCurrency: string }
+    | { readonly currencyMode: 'record'; readonly currencyField: string };
 }
 
-type MoneyCurrency = { readonly mode: 'dynamic' } | { readonly mode: 'fixed'; readonly code: string };
+type MoneyCurrency =
+  | { readonly mode: 'dynamic' }
+  | { readonly mode: 'fixed'; readonly code: string }
+  // [ADR-0144 D2] Each record's own currency, the code in the sibling field
+  // `field` names. Two record-mode amounts are one currency only when they
+  // name the same code field.
+  | { readonly mode: 'record'; readonly field: string };
 
 type Dim =
   | { readonly kind: 'money'; readonly currency: MoneyCurrency }
@@ -125,8 +135,9 @@ function isNode(v: unknown): v is Node {
 }
 
 function sameCurrency(a: MoneyCurrency, b: MoneyCurrency): boolean {
-  if (a.mode === 'dynamic' || b.mode === 'dynamic') return a.mode === b.mode;
-  return a.code === b.code;
+  if (a.mode === 'fixed' && b.mode === 'fixed') return a.code === b.code;
+  if (a.mode === 'record' && b.mode === 'record') return a.field === b.field;
+  return a.mode === b.mode;
 }
 
 /**
@@ -137,8 +148,16 @@ function sameCurrency(a: MoneyCurrency, b: MoneyCurrency): boolean {
 function currencyOf(config: unknown): MoneyCurrency | null {
   const parsed = CurrencyConfigSchema.safeParse(config ?? {});
   if (!parsed.success) return null;
-  if (parsed.data.currencyMode !== 'fixed') return { mode: 'dynamic' };
-  return parsed.data.defaultCurrency === undefined ? null : { mode: 'fixed', code: parsed.data.defaultCurrency };
+  if (parsed.data.currencyMode === 'fixed') {
+    return parsed.data.defaultCurrency === undefined ? null : { mode: 'fixed', code: parsed.data.defaultCurrency };
+  }
+  // [ADR-0144 D2] A `record`-mode amount is in the currency its sibling code
+  // field holds — never the tenant default a `dynamic` stamp would claim. The
+  // schema requires the pointer under `record`, so a parsed config carries it.
+  if (parsed.data.currencyMode === 'record') {
+    return parsed.data.currencyField ? { mode: 'record', field: parsed.data.currencyField } : null;
+  }
+  return { mode: 'dynamic' };
 }
 
 /** Is `d` a number that is not an amount (a quantity or a constant)? */
@@ -256,8 +275,10 @@ function sourceOf(input: ExprInput): string | null {
  *
  * - Provably money ⇒ `{ returnType: 'currency' }`, plus
  *   `currencyConfig: { currencyMode: 'fixed', defaultCurrency }` when the
- *   source amounts are in one fixed currency. Sources in two different
- *   currencies are not provably one amount, and fall through.
+ *   source amounts are in one fixed currency, or
+ *   `currencyConfig: { currencyMode: 'record', currencyField }` when they are
+ *   record-mode amounts naming one code field (ADR-0144 D2). Sources in two
+ *   different currencies are not provably one amount, and fall through.
  * - Otherwise ⇒ the {@link inferExpressionType} answer as `returnType`
  *   (`number` / `text` / `boolean` / `date`), or `{}` when that is `unknown` —
  *   unchanged from before this function existed, so a numeric formula stays
@@ -281,9 +302,13 @@ export function inferFormulaReturn(
     if (celType !== null && MONEY_CEL_TYPES.has(celType)) {
       const dim = dimOf(parseCelToAst(source), fields);
       if (dim.kind === 'money') {
-        return dim.currency.mode === 'fixed'
-          ? { returnType: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: dim.currency.code } }
-          : { returnType: 'currency' };
+        if (dim.currency.mode === 'fixed') {
+          return { returnType: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: dim.currency.code } };
+        }
+        if (dim.currency.mode === 'record') {
+          return { returnType: 'currency', currencyConfig: { currencyMode: 'record', currencyField: dim.currency.field } };
+        }
+        return { returnType: 'currency' };
       }
     }
   }
 
@@ -50,6 +50,7 @@ import type { WriteObservabilityOptions } from '@objectstack/spec/contracts';
 import { validateRecordInScope, normalizeBlankTypedValues, normalizeNumericStringValues, ValidationError, valueShapeStrictEffective, mediaStrictEffective } from './validation/record-validator.js';
 import { evaluateValidationRules, hasParentScopedRequiredWhen, stripReadonlyFields, stripRuntimeOwnedFields } from './validation/rule-validator.js';
 import { createBatchSummaryAccumulator } from './summary-batch-accumulation.js';
+import { assertRecordCurrencyCodes, RecordCurrencyCodeRequiredError } from './validation/record-currency-code.js';
 import { resolveEngineUpdateDispatch, type EngineUpdateDispatchData } from './engine-update-dispatch.js';
 import {
   droppedFieldEvents,
@@ -393,11 +394,15 @@ export async function validate(
   // `undefined` = no stored row: the row is judged on the patch alone, as
   // it was before these reads existed.
   const storedRows: Array<Record<string, unknown> | undefined> = [];
+  // The by-id address each stored row was read from, for a refusal that names the record.
+  const storedIds: unknown[] = [];
   for (const submitted of submittedRows) {
     let stored: Record<string, unknown> | undefined;
+    let storedId: unknown;
     if (mode === 'update' && submitted && typeof submitted === 'object') {
       const dispatch = resolveEngineUpdateDispatch(submitted as EngineUpdateDispatchData, undefined);
       if (dispatch.kind === 'by-id') {
+        storedId = dispatch.id;
         const visible = await this.findOne(object, {
           where: { id: dispatch.id },
           context: { ...(options?.context ?? {}), [RAW_FILE_VALUES_CONTEXT_KEY]: true },
@@ -417,6 +422,7 @@ export async function validate(
       }
     }
     storedRows.push(stored);
+    storedIds.push(storedId);
   }
   // The merged view each rule evaluates, and the one the reference reads
   // below key on: the write reads a traversed FK off the same merge
@@ -543,6 +549,21 @@ export async function validate(
         // preview admits exactly what the write would.
         keptOptionValues: options?.context?.keptOptionValues,
       });
+      // [ADR-0144 D8 rule 4] The write's blank-code refusal, at the write's
+      // step and on the write's image: the insert row as stored, or the stored
+      // row with the patch over it (`judgedViews`, the by-id update's
+      // `priorRecord ⊕ payload`), judging only the pairs the patch touches.
+      // An update with no stored row here (a predicate dispatch, an id this
+      // caller cannot read) is not judged: the image the write judges is a
+      // row the preview does not hold. A code column the read door withholds
+      // from this caller is absent from the stored row, so the preview reads
+      // it as blank — stricter than the write, never laxer.
+      if (mode === 'insert' || storedRows[i]) {
+        assertRecordCurrencyCodes(
+          object, (schemaForValidation as { fields?: unknown } | undefined)?.fields,
+          mode === 'insert' ? row : judgedViews[i], mode, mode === 'insert' ? undefined : row, storedIds[i],
+        );
+      }
       warnings.push(...evaluateValidationRules(schemaForValidation as any, row, mode, {
         // [#22445] The stored row, when this row named one: the by-id
         // update's `previous: priorRecord`. Absent, the record is the patch.
@@ -571,6 +592,10 @@ export async function validate(
       if (e instanceof ValidationError) {
         return { valid: false, errors: e.fields.map((f) => ({ ...f })), warnings };
       }
+      // The write throws this refusal whole; the preview answers it as the row's finding.
+      if (e instanceof RecordCurrencyCodeRequiredError) {
+        return { valid: false, errors: [{ field: e.field, code: e.code, message: e.message }], warnings };
+      }
       throw e;
     }
     batchSummaries?.accept(row);