fix(service-analytics): a measure column takes the source field's currency only under currencyMode 'fixed' (#20091)

[objectstack-fleet]

Fixes #20091
Clause-②: no

What was wrong

AnalyticsServicePlugin passes each source field's metadata to the service through sourceFieldMeta. That hook passed on currencyConfig.defaultCurrency without reading currencyConfig.currencyMode. queryDataset resolves a monetary measure column's currency in this order: the measure's own currency, then that relayed value, then ExecutionContext.currency. So a dynamic field's defaultCurrency showed on the dataset result where the tenant currency belonged. The spec says otherwise:

• CurrencyConfigSchema defaults currencyMode to 'dynamic'. Its own precision refinement treats defaultCurrency as the field's one currency only under 'fixed'.
• The FieldSchema guidance says a fixed currency is currencyConfig: { currencyMode: 'fixed', defaultCurrency: … }, and "A field without one uses the tenant default at runtime".

objectstack-ai/objectui#10461 changed the renderer's resolveFieldCurrency to read defaultCurrency only under 'fixed'. The renderer reads an explicit column currency first, though, so the analytics faces kept overriding that rule.

Measured before the fix (commit 9a98c59b44: base fa00ebf447 plus the new test file only), and after

AnalyticsServicePlugin booted over a real ObjectQL engine on SqliteWasmDriver, with the object registered on the engine. ExecutionContext.currency = 'USD', and every authored defaultCurrency is EUR. Each cell is the result column's currency on the live path / the draft-preview path of queryDataset:

case	raw registration, before	parsed registration (ObjectSchema.parse), before	after the fix (both registrations)
{ currencyMode: 'fixed', defaultCurrency: 'EUR' }	EUR / EUR	EUR / EUR	EUR / EUR
{ currencyMode: 'dynamic', defaultCurrency: 'EUR' }	EUR / EUR	EUR / EUR	USD / USD
{ defaultCurrency: 'EUR' } (no mode)	EUR / EUR	EUR / EUR	USD / USD
{} (parses to dynamic + the schema's CNY)	USD / USD	CNY / CNY	USD / USD
currency field, no currencyConfig	USD / USD	USD / USD	USD / USD
measure currency: 'JPY' over the dynamic field	JPY / JPY	JPY / JPY	JPY / JPY
measure currency: 'JPY' over the fixed field	JPY / JPY	JPY / JPY	JPY / JPY
non-monetary control (number field)	none / none	none / none	none / none

Bold cells break the spec rule. The "before" columns are also in the message of commit 9a98c59b44. The "after" column was measured on head 131de3a37a with the same probe.

What "no mode" looks like at the relay. SchemaRegistry.registerObject stores what it is handed and does not parse. A raw registerObject call therefore arrives with no currencyMode key at all. The declared-stack path parses first, which fills in currencyMode: 'dynamic', and fills in defaultCurrency: 'CNY' when the author wrote none. Measured with ObjectSchema.parse: { defaultCurrency: 'EUR' } parses to {"precision":2,"currencyMode":"dynamic","defaultCurrency":"EUR"}, and {} parses to {"precision":2,"currencyMode":"dynamic","defaultCurrency":"CNY"}. The fix compares currencyMode === 'fixed', so both shapes fall to the tenant default. The relay supplies no default of its own.

Every reader of sourceFieldMeta().defaultCurrency in the package: one. It is enrichResultColumns (analytics-service.ts, the currency chain). The live and draft-preview paths of queryDataset both reach it, and the same loop covers __compare columns. A grep over src/ for defaultCurrency and for currenc finds nothing else:

• sourceFieldMeta's other readers take only .type (the compile gate at registerDataset, the time-dimension type, measureResultType) or max (percentScaleOf).
• Dimension columns get only a label.
• Drill metadata and dimension value labels carry no currency.
• The package has no export face.
• The cube face (AnalyticsService.query and its SQL echo) never writes a column currency. The suite pins that as measured.

The fix

• plugin.ts: the relay answers defaultCurrency only when currencyConfig.currencyMode === 'fixed', and undefined otherwise. The rule is decided at the one producer, so the one reader inherits it. An explicit measure currency still wins.
• No reader needs the raw defaultCurrency, so no second key was added. The public AnalyticsServiceConfig.sourceFieldMeta return type is unchanged. Its TSDoc now says what defaultCurrency means there (the field's FIXED currency) and what a host writing its own sourceFieldMeta must answer.
• No packages/spec change and no objectui change.

Tests

New packages/services/service-analytics/src/__tests__/currency-mode-relay.test.ts, 19 cases. Each case runs end to end through the plugin's relay, the real engine and driver, and the queryDataset result, under both registration shapes. Each asserts the live and the preview path. The cases:

• fixed, dynamic, no mode, empty config, no config;
• an explicit measure currency over a dynamic field and over a fixed one;
• a non-monetary control;
• two fixture controls: the shape really differs, and the live rows really came from the driver;
• the cube-face pin.

Before the fix: 5 failed, 14 passed. After: 19 passed. The failures before the fix were the 5 bold cells above:

AssertionError: expected 'EUR' to be 'USD'   (dynamic, raw + parsed; no mode, raw + parsed)
AssertionError: expected 'CNY' to be 'USD'   (empty config, parsed)
Tests  5 failed | 14 passed (19)

Ablation. Every negative pin was ablated through node scripts/ablation-replace.mjs in WRAP mode, after the fix was committed. Each mutation was proven on disk: the anchor count went 1 to 0 and the blob changed. Each restore was proven too: the blob equals HEAD and git diff HEAD is empty.

leg	mutation	red
A	plugin.ts: the pre-fix relay, which passes defaultCurrency whenever present	5 failed / 14 passed: dynamic ×2, no mode ×2, empty config (parsed)
B	plugin.ts: a relay that fills in the schema's CNY itself and ignores mode	8 failed / 11 passed: dynamic ×2, no mode ×2, empty config ×2, no config ×2
C	analytics-service.ts: the cube face writes a currency on its columns	13 failed / 6 passed, including the cube-face pin
D	analytics-service.ts: every measure treated as monetary	2 failed / 17 passed: the non-monetary control ×2
E	test fixture: the raw shape is parsed too	1 failed / 18 passed: the shape control

Leg C's first attempt did not run. Its replacement text still contained the anchor, so ablation-replace refused the leg before running anything ("the anchor count moved 1 -> 1"), and the file was restored. It was re-run with a replacement that consumes the anchor, and that run is the one in the table.

Package suite on the merged head 131de3a37a: pnpm --filter @objectstack/service-analytics test, 125 files / 2905 tests passed. pnpm --filter @objectstack/service-analytics run typecheck exits 0. tsc --listFiles includes the new test file (1 hit; the control plugin.ts also has 1).

Changeset

.changeset/20091-analytics-currency-mode.md: @objectstack/service-analytics, patch, with a Clause-②: no line. It is a fix to a released package that adds or removes no authorable key, export or type member. check-changeset-no-major --base origin/main exits 0, and so does check-adr-0087-registration --base origin/main: the changeset is not declared breaking, so no ADR-0087 marker is owed.

Acceptance notes

• The code labels this chain "ADR-0053", but ADR-0053 says nothing about currency. ADR-0053 is date/datetime semantics: grep -ci currenc on it gives 0, and the control datetime gives 73. This PR corrects the label on the lines it rewrites (plugin.ts relay comment, analytics-service.ts TSDoc and chain comment). It does not touch the same label in preview-column-enrichment.test.ts (the header table and two test names). No carrier: noted, not filed.
• { currencyMode: 'fixed' } with no code differs by registration door. Not measured, a source read. A raw registration relays undefined, so the column gets the tenant default. A parsed one relays the spec's defaulted CNY, which the spec's own refinement treats as the field's currency in fixed mode. The relay follows the registered shape on purpose. Supplying the spec default here would be a second copy of it.
• A host that writes its own sourceFieldMeta must apply the same rule. A type cannot express it, so the TSDoc and the changeset state it.

Local verification (head 131de3a37a, after the origin/main merge)

• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 61 commands from this diff, and all 61 exit 0. --ran (each command recorded with its exit code) answers: "61 derived, 61 run, 0 NOT-MEASURED, 0 UNRUN".
  • The derivation added six families to the dispatch-time list: check:engine-double-contract, check:objectql-double-limit, check:query-options-erasure, check:type-check-coverage, check:type-check-debt and check:where-matcher.
  • check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3), which is not a measurement. Both exit 0 after turbo run build --filter='./packages/*' --filter='./packages/*/*' (72/72 tasks).
• GITHUB_TOKEN=… node scripts/check-issue-citations.mjs exits 0: 5 citations, 3 resolve, 2 are cross-repo.
• Lint, narrowed to the touched files (pnpm lint over the whole repo is CI's job):
  • eslint --no-inline-config --format json on the 3 touched TypeScript files exits 0. The JSON reports 3 files, with 0 errors and 0 warnings.
  • eslint --print-config puts all 3 files in the linted population: 6 rules each on the two sources, and 5 on the test file.
  • Linting only these files misses nothing. eslint.config.mjs enables no type-aware linting (no parserOptions.project), and its local rules are scope-based and per-file. A diff to these files therefore cannot change a verdict on any untouched file.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-analytics, touching 3 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/plugins/packages.mdx (via AnalyticsServicePlugin (symbol, a top-level class))

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 9 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7c1039b388f46222b0029d93a03cefa9fbf5f67f → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0715c144702dcd3f30fb491cf964cb34b1ba9f94 — the merge of head 131de3a37a314a4ad55ebd2fe081247e2904d613 into base 7c1039b388f46222b0029d93a03cefa9fbf5f67f, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 0715c144702dcd3f30fb491cf964cb34b1ba9f94 && git checkout 0715c144702dcd3f30fb491cf964cb34b1ba9f94
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7c1039b388f46222b0029d93a03cefa9fbf5f67f 131de3a37a314a4ad55ebd2fe081247e2904d613 && git checkout -B drift-repro 7c1039b388f46222b0029d93a03cefa9fbf5f67f && git merge --no-ff 131de3a37a314a4ad55ebd2fe081247e2904d613

node scripts/docs-audit/affected-docs.mjs --json 7c1039b388f46222b0029d93a03cefa9fbf5f67f

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7c1039b388f46222b0029d93a03cefa9fbf5f67f → pass the list as
args.docs, on the commit named under Which tree this was computed on.