Skip to content

feat(runtime): resolve tenant default currency onto ExecutionContext - #2119

Merged
xuyushun441-sys merged 1 commit into
mainfrom
phase1-currency-context
Jun 21, 2026
Merged

xuyushun441-sys merged 1 commit into
mainfrom
phase1-currency-context

Conversation

@xuyushun441-sys

Copy link
Copy Markdown
Collaborator

Phase 1 of unifying currency resolution

Audit finding: the localization.currency setting (tenant-scoped, default USD, documented as "ISO 4217 code applied when a currency field omits its own") was declared but had zero runtime consumers. resolveExecutionContext read only timezone + locale, so no code path could ever reach the tenant default. Likewise currencyConfig.defaultCurrency (field-level) has no reader. The whole field→tenant currency fallback exists only as prose.

This PR lays the foundation: carry the tenant default currency on every request context, mirroring timezone/locale exactly.

Changes

  • spec: ExecutionContext.currency (ISO 4217, optional).
  • runtime (resolveExecutionContext): resolveLocalization now reads localization.currency — canonical settings-service path and the direct sys_setting tenant fallback — coerced to a 3-letter ISO code, assigned to ctx.currency.
  • rest: the REST context mirror reads + carries currency too.

Undefined when no tenant default is configured → consumers render a plain number (no behavior change until consumers opt in).

Why phased

Per the unified plan (currency is declared everywhere but resolved nowhere, with ~25 divergent client sites): this keystone unblocks the rest. Follow-ups:

  • 1b: analytics measure-currency chain (measure override → field currencyConfig → ctx.currency, gated on monetary field type) + template-engine default.
  • 2: objectui — one shared resolver/formatter + a client context exposing the tenant default; replace the ad-hoc sites.
  • Out of scope (separate ADRs): dynamic per-record currency storage, and FX conversion for multi-currency aggregation.

Tests

  • resolve-execution-context → 17 passed (+2: canonical + sys_setting-fallback currency resolution; ISO-code upper-casing + junk rejection).
  • spec builds with declarations; runtime/rest build closures green.

🤖 Generated with Claude Code

ADR-0053 follow-up. The `localization.currency` setting (tenant-scoped, default
USD, documented as "applied when a currency field omits its own") was declared
but had ZERO runtime consumers — resolveExecutionContext read only timezone +
locale, so no code path could reach the tenant default.

This carries it onto the context, mirroring timezone/locale exactly:
- spec: `ExecutionContext.currency` (ISO 4217, optional).
- runtime: `resolveLocalization` reads `localization.currency` (canonical
  settings path + the direct sys_setting fallback), coerced to a 3-letter code;
  assigned to `ctx.currency`.
- rest: the REST context mirror reads + carries it too.

Foundation for the unified currency-resolution chain (field currencyConfig →
tenant localization.currency); analytics/template/renderer consumers land in
follow-ups. Undefined when unconfigured → consumers render a plain number.

Tests: resolve-execution-context 17 passed (+2: canonical + fallback currency,
ISO-code coercion/junk rejection).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jun 21, 2026 9:37am

Request Review

@github-actions github-actions Bot added documentation Improvements or additions to documentation tests tooling size/s labels Jun 21, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/rest, @objectstack/runtime, @objectstack/spec.

96 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

  • content/docs/concepts/architecture.mdx (via @objectstack/spec)
  • content/docs/concepts/cloud-artifact-api.mdx (via packages/runtime, packages/spec)
  • content/docs/concepts/cluster-semantics.mdx (via @objectstack/spec)
  • content/docs/concepts/design-principles.mdx (via packages/spec)
  • content/docs/concepts/implementation-status.mdx (via @objectstack/rest, @objectstack/runtime, @objectstack/spec)
  • content/docs/concepts/index.mdx (via @objectstack/spec)
  • content/docs/concepts/metadata-driven.mdx (via @objectstack/spec)
  • content/docs/concepts/metadata-lifecycle.mdx (via packages/spec)
  • content/docs/concepts/north-star.mdx (via packages/runtime, packages/spec)
  • content/docs/concepts/packages.mdx (via @objectstack/rest, @objectstack/runtime, @objectstack/spec)
  • content/docs/concepts/setup-app.mdx (via @objectstack/spec)
  • content/docs/concepts/skills.mdx (via @objectstack/spec)
  • content/docs/concepts/webhook-delivery.mdx (via @objectstack/spec)
  • content/docs/getting-started/architecture.mdx (via @objectstack/spec)
  • content/docs/getting-started/cli.mdx (via @objectstack/spec)
  • content/docs/getting-started/core-concepts.mdx (via @objectstack/spec)
  • content/docs/getting-started/examples.mdx (via @objectstack/spec)
  • content/docs/getting-started/quick-start.mdx (via @objectstack/spec)
  • content/docs/guides/adding-a-metadata-type.mdx (via @objectstack/spec)
  • content/docs/guides/ai-capabilities.mdx (via @objectstack/spec)
  • content/docs/guides/airtable-dashboard-analysis.mdx (via @objectstack/spec)
  • content/docs/guides/analytics-datasets.mdx (via @objectstack/spec)
  • content/docs/guides/api-reference.mdx (via @objectstack/rest, @objectstack/runtime, @objectstack/spec)
  • content/docs/guides/authentication.mdx (via @objectstack/runtime)
  • content/docs/guides/business-logic.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/backward-compatibility.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/error-catalog.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/field-type-gallery.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/field-validation-rules.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/permissions-matrix.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/protocol-diagram.mdx (via packages/spec)
  • content/docs/guides/cheatsheets/query-cheat-sheet.mdx (via @objectstack/spec)
  • content/docs/guides/cheatsheets/quick-reference.mdx (via @objectstack/spec)
  • content/docs/guides/client-sdk.mdx (via @objectstack/spec)
  • content/docs/guides/cloud-deployment.mdx (via @objectstack/runtime)
  • content/docs/guides/common-patterns.mdx (via @objectstack/spec)
  • content/docs/guides/contracts/auth-service.mdx (via packages/spec)
  • content/docs/guides/contracts/cache-service.mdx (via packages/spec)
  • content/docs/guides/contracts/data-engine.mdx (via @objectstack/spec)
  • content/docs/guides/contracts/index.mdx (via @objectstack/spec)
  • content/docs/guides/contracts/metadata-service.mdx (via packages/spec)
  • content/docs/guides/contracts/storage-service.mdx (via packages/spec)
  • content/docs/guides/data-modeling.mdx (via @objectstack/spec)
  • content/docs/guides/deployment-vercel.mdx (via @objectstack/runtime, @objectstack/spec)
  • content/docs/guides/driver-configuration.mdx (via @objectstack/runtime, @objectstack/spec)
  • content/docs/guides/error-handling-client.mdx (via @objectstack/spec)
  • content/docs/guides/error-handling-server.mdx (via @objectstack/spec)
  • content/docs/guides/formula.mdx (via @objectstack/spec)
  • content/docs/guides/hook-bodies.mdx (via @objectstack/runtime, packages/spec)
  • content/docs/guides/kernel-services.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/dashboard.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/field.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/flow.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/index.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/object.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/validation.mdx (via @objectstack/spec)
  • content/docs/guides/metadata/workflow.mdx (via @objectstack/spec)
  • content/docs/guides/packages.mdx (via @objectstack/rest, @objectstack/runtime, @objectstack/spec)
  • content/docs/guides/plugin-chatbot-integration.mdx (via @objectstack/runtime)
  • content/docs/guides/plugin-development.mdx (via @objectstack/spec)
  • content/docs/guides/plugins.mdx (via @objectstack/rest, @objectstack/spec)
  • content/docs/guides/production-readiness.mdx (via @objectstack/runtime)
  • content/docs/guides/project-scoping.mdx (via @objectstack/spec)
  • content/docs/guides/public-forms.mdx (via @objectstack/spec)
  • content/docs/guides/runtime-services/email-service.mdx (via packages/spec)
  • content/docs/guides/runtime-services/index.mdx (via packages/spec)
  • content/docs/guides/runtime-services/queue-service.mdx (via packages/spec)
  • content/docs/guides/runtime-services/sharing-service.mdx (via packages/spec)
  • content/docs/guides/runtime-services/storage-service.mdx (via packages/spec)
  • content/docs/guides/security.mdx (via @objectstack/spec)
  • content/docs/guides/seed-data.mdx (via @objectstack/spec)
  • content/docs/guides/single-project-mode.mdx (via @objectstack/runtime)
  • content/docs/guides/skills.mdx (via @objectstack/spec)
  • content/docs/guides/standards.mdx (via @objectstack/spec)
  • content/docs/guides/troubleshooting.mdx (via @objectstack/spec)
  • content/docs/protocol/knowledge.mdx (via @objectstack/spec)
  • content/docs/protocol/objectos/config-resolution.mdx (via @objectstack/spec)
  • content/docs/protocol/objectos/http-protocol.mdx (via @objectstack/runtime)
  • content/docs/protocol/objectos/i18n-standard.mdx (via @objectstack/spec)
  • content/docs/protocol/objectos/index.mdx (via @objectstack/runtime)
  • content/docs/protocol/objectos/lifecycle.mdx (via @objectstack/runtime, @objectstack/spec)
  • content/docs/protocol/objectos/plugin-spec.mdx (via @objectstack/spec)
  • content/docs/protocol/objectos/runtime-capabilities.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/index.mdx (via packages/spec)
  • content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/schema.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/security.mdx (via packages/spec)
  • content/docs/protocol/objectql/state-machine.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/actions.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/concept.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/index.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/layout-dsl.mdx (via packages/spec)
  • content/docs/protocol/objectui/record-alert.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/widget-contract.mdx (via @objectstack/spec)
  • content/docs/releases/index.mdx (via @objectstack/spec)
  • content/docs/releases/v9.mdx (via @objectstack/spec)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

@xuyushun441-sys
xuyushun441-sys merged commit 220ce5b into main Jun 21, 2026
17 checks passed
@xuyushun441-sys
xuyushun441-sys deleted the phase1-currency-context branch June 21, 2026 09:43
xuyushun441-sys added a commit that referenced this pull request Jun 21, 2026
…ig + tenant default (#2121)

* feat(analytics): resolve a monetary measure's currency via field config + tenant default

Phase 1b of unifying currency resolution (builds on ExecutionContext.currency).
The dataset measure-currency enrichment honored ONLY an explicit measure
`currency` literal — so a measure summing a currency field, or any measure on a
tenant with a configured default currency, rendered symbol-less unless the
author restated the code.

Now a MONETARY measure resolves its display currency through the documented
chain: explicit measure `currency` → source-field `currencyConfig.defaultCurrency`
→ tenant default (`ctx.currency`, from the localization setting wired in #2119).
A measure is monetary iff it declares a currency OR aggregates a `currency`-type
field — so count / avg-of-number measures never get a (wrong) currency code.

- analytics-service: `AnalyticsServiceConfig.measureCurrency(object, field)` →
  source-field `{ type, defaultCurrency }`; enrichment applies the chain, gated
  on monetary type.
- plugin: wires `measureCurrency` from the data engine's `getObject().fields`
  (same accessor the label resolver already uses).

Tests: query-dataset 15 passed (+4: field-default inheritance, tenant-ctx
fallback, explicit-override precedence, and non-currency measures staying
code-less).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: changeset for analytics measure-currency chain

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
xuyushun441-sys added a commit that referenced this pull request Jun 21, 2026
…r every user (#2122)

Phase 2a of unifying currency. The `localization` settings (currency/locale/
timezone) are gated to `setup.access`, and `discovery` is static/context-free —
so a regular user's client has no way to learn the tenant's default currency or
locale to format values consistently.

This adds `GET /api/v1/auth/me/localization`, returning the resolved
`{ currency, locale, timezone }` off the request ExecutionContext (the same
values #2119 wired in) to every AUTHENTICATED user — without the setup.access
gate on the underlying settings. A thin passthrough of `resolveCtx(c)`; the
ctx resolution itself is covered by resolve-execution-context tests.

Unblocks the objectui client (Phase 2): a LocalizationProvider can fetch this
once and feed a single currency/number formatter the tenant default + locale,
replacing ~20 ad-hoc per-site currency-resolution paths.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
xuyushun441-sys added a commit that referenced this pull request Jun 21, 2026
…ode; showcase demo (#2123)

* docs(currency): document the field→tenant resolution chain; fix currencyMode; showcase demo

Follows the currency-resolution work (#2102/#2119/#2121/#2122). Brings the
skills + showcase in line with the now-implemented chain.

- objectstack-ui SKILL: document `DatasetMeasure.currency` (ISO 4217) and its
  resolution order (measure → field `currencyConfig` → tenant default).
- objectstack-data field-types: FIX a real doc bug — `currencyMode` was
  documented as `'multi'/'single'`, the schema is `'fixed'/'dynamic'`; add a
  "Currency resolution (ADR-0053)" note (field default → tenant default → plain
  number, never a hardcoded `$`).
- objectstack-i18n SKILL: note the workspace regional defaults (timezone /
  locale / currency) — the `localization` settings, resolved onto ExecutionContext
  and exposed at `/auth/me/localization`.
- showcase: declare a fixed `currencyConfig.defaultCurrency` on field-zoo's
  currency field (demonstrates + smoke-covers the symbol path); refresh the
  chart-gallery `budget`/`spent` comment, which claimed an unspecified-currency
  amount "must not show a $" — now it falls back to the tenant default.

Verified: app-showcase builds (field + dataset parse); check:skill-docs in sync.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(showcase): currencyConfig requires precision (typecheck)

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
Preview — 0e4febf5 Deployed Jun 21, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/s tests tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants