feat(objectql): record-currency guards — blank code refuses the write; ungrouped sum/avg/min/max over a record-mode amount refused; summary roll-up over one refused at registration

.changeset/27186-record-currency-guards.md

@@ -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.

content/docs/references/api/automation-api.mdx

@@ -347,7 +347,7 @@ const result = AutomationApiErrorCode.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +349 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +350 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
 | **message** | `string` | ✅ | The inner refusal's own diagnostic text, verbatim, without the node and operation prefixes the run's failure text adds |
 
 ### Allowed Values: `FlowInnerRefusal.code`
@@ -479,6 +479,7 @@ const result = AutomationApiErrorCode.parse(data);
 * `ERR_AUTONUMBER_COLLISION`
 * `ERR_BULK_RESULT_MISMATCH`
 * `ERR_CROSS_DATASOURCE_TRANSACTION_WRITE`
+* `ERR_CURRENCY_CODE_REQUIRED`
 * `ERR_DATASOURCE_UNAVAILABLE`
 * `ERR_DRIVER_CONNECT`
 * `ERR_FILE_CONSTRAINT`

content/docs/references/api/contract.mdx

@@ -28,7 +28,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +349 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +350 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -167,6 +167,7 @@ const result = ApiErrorSchema.parse(data);
 * `ERR_AUTONUMBER_COLLISION`
 * `ERR_BULK_RESULT_MISMATCH`
 * `ERR_CROSS_DATASOURCE_TRANSACTION_WRITE`
+* `ERR_CURRENCY_CODE_REQUIRED`
 * `ERR_DATASOURCE_UNAVAILABLE`
 * `ERR_DRIVER_CONNECT`
 * `ERR_FILE_CONSTRAINT`

content/docs/references/api/error-code-ledger.mdx

@@ -334,6 +334,7 @@ const result = ErrorCode.parse(data);
 * `ERR_AUTONUMBER_COLLISION`
 * `ERR_BULK_RESULT_MISMATCH`
 * `ERR_CROSS_DATASOURCE_TRANSACTION_WRITE`
+* `ERR_CURRENCY_CODE_REQUIRED`
 * `ERR_DATASOURCE_UNAVAILABLE`
 * `ERR_DRIVER_CONNECT`
 * `ERR_FILE_CONSTRAINT`

packages/formula/src/formula-return.test.ts

@@ -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');
+    }
+  });
+});

packages/formula/src/formula-return.ts

@@ -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' };
       }
     }
   }

packages/objectql/src/engine-validate.ts

@@ -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);