feat(formula): label(record.<field>) renders a select value in the reader's locale - #26755

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/formula, @objectstack/objectql, touching 45 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/formula/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

26 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e.

⛔ 10 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 37d5eb6037c6db34d5546c8cb6ff68412747c005 && git checkout 37d5eb6037c6db34d5546c8cb6ff68412747c005
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e 8ffe3ae67856cc968eb7ae61788f1b2f6611cac3 && git checkout -B drift-repro a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e && git merge --no-ff 8ffe3ae67856cc968eb7ae61788f1b2f6611cac3

node scripts/docs-audit/affected-docs.mjs --json a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e

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 a485b5a3e28d84550e8a33bbb5cfc2d52c82ff9e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f780ce7816bc82896e4777be152ee6e4e4ec6455
Local-runs: none
Scope: skills/objectstack-formula/SKILL.md + packages/formula/src/stdlib.ts, packages/formula/src/types.ts, packages/formula/src/validate.ts, packages/formula/src/cel-engine.ts, packages/formula/src/index.ts, packages/objectql/src/formula-option-labels.ts, packages/objectql/src/engine.ts (the applyFormulaPlan / hydrateWriteFormulas / computeStoredExpressions / evaluateFormulaField / serveFormulaField / find / findOne / insert / update hunks), .changeset/26608-formula-option-label.md, content/docs/data-modeling/formulas.mdx (cited, read against the code; the test files and the dogfood test were read to judge them, not reviewed)

Inputs read: card #26608 (body, triage 6440185938, claim 6442789358, amendment 6442958772, os-dev-report 6444975664), PR #26755 body and file list, the net diff 43731031..f780ce78 (merge-base of origin/main), and the check-runs on the head. The PR has no reviews and one bot comment (docs-drift, advisory). The head's tree was read through a detached git checkout of the fetched sha for file reads only — nothing built, run or re-run — and the checkout was restored afterwards.

① Derived judgments

Each accept-set or public-surface change the diff implies, named right or wrong against the tree:

1. CEL grammar widens by one bare-callable name, label, registered as a MACRO (stdlib.ts bindOptionLabel, env.registerFunction('label(ast): string', …)). The type check accepts exactly the AST shape record.FIELD (optionLabelFieldOf: op ., receiver id = record, non-empty string member) and refuses a literal, a path through a lookup, an optional read, previous.FIELD and a computed argument with one message (LABEL_ARGUMENT_REFUSAL). Registered unconditionally, like can and hasCapability, so the publish gate's answer does not depend on which context built the environment. Right. The widening reaches every CEL surface the skill lists (formula, visibleWhen, validation when, hook/sharing condition, flow, seed) because the stdlib is one environment; only the engine's formula serving pins optionLabels, so everywhere else label() compiles and then faults at run time (see ④).
2. EvalContext.optionLabels (type EvalOptionLabels, field → stored value as text → label) is pure data, not a CEL variable. buildScope (stdlib.ts ~764-787) mounts record, previous, input, user/os, org, env, extra only; optionLabels travels on StdLibBinding and is read through read() at call time, as the permission binding is. stdlib.ts imports no translator, no i18n type, no resolver. Right, and it is the seat instruction's first invariant.
3. @objectstack/formula public surface: EvalOptionLabels exported from index.ts; registerStdLib gains a fourth optional parameter (index.ts already exported it); CEL_STDLIB_FUNCTIONS gains 'label'. All additive. Right.
4. Catalog counts in validate.ts (77 registered / 42 bare / 35 receiver-only / 30 from registerStdLib / 38 advertised): the advertised list moved 37 → 38 and the bare count 41 → 42 by exactly the one name the diff registers; cel-stdlib-drift.test.ts asserts list identities (toEqual([]), the withheld set), not the prose numbers, so the hasCapability absorption the dev reports (34 → 35 receiver-only) is a prose repair of a count main already under-stated. Right; Test Core will measure it.
5. @objectstack/objectql surface: setI18nService accepts three more optional methods (getTranslations, getFallbackLocale, getDefaultLocale), which II18nService already carries and plugin.ts:1167 already passes whole. Additive. Right.
6. evaluateFormulaField (exported, sync) changes behaviour: a label() formula no longer faults with "no option labels" but evaluates against declaredOptionLabels(schema, plan). Disclosed in its docblock and in the PR's reader table. Right as a documented exception (judged in ④).
7. One translation path. readerOptionLabels builds the bundle as metaTranslationBundleOf does (getLocales() × getTranslations(locale), meta-item-read-gate.ts:2757-2769), builds the options as metaTranslateOptions does (fallbackChain: [getFallbackLocale()], defaultLocale: getDefaultLocale(), :2783-2790), and calls the same translateObject from @objectstack/spec/system with { name, fields }. translateObject (i18n-resolver.ts:3837) resolves a field's option label as objects.NAME.fields.FIELD.options.VALUE then picklists.PICKLIST.options.VALUE (:3878-3889) when the field carries picklist; optionFields keeps the whole field def so the picklist key survives, and every registry read passes finishServedObject → resolvePicklistFields (registry.ts:3838-3855), so a picklist-bound field reaches the module with its options resolved. No key is spelled in objectql. Right, and the dogfood test pins /meta/object label == formula label on one boot.
8. Locale: ExecutionContext.locale, which both the REST and the MCP door set from Accept-Language (resolve-execution-context.ts:216, preferredLocaleFromHeader, the same parser metaRequestLocale uses). Right for every request that sends the header (the console always does). Observation, not a finding: with no header, the metadata route falls to ?locale= then getDefaultLocale(), while the execution context falls to the settings service's localization — the two can disagree only on a header-less request, and the dogfood "no locale" case is served the declared labels, which is the documented answer.
9. Readers wired (the claim names them; each one found in the tree): find (engine.ts:13590-13596), findOne (:13879-13883), the insert 201 body (hydrateWriteFormulas, :15855-15861), the by-id update body (:17800-17807; a predicate update returns a count and has no rows to hydrate, pre-existing), serveFormulaField (:6594-6597, and ScopedContext.serveFormulaField at :22003 passes the hook's own execution context), expand (expandRelatedRecords runs this.find with { ...execCtx, __expandRead: true }, so a lookup's display name follows the reader). Stored expressions: both storedExpressionServing objects (insert :14960, update :16364) carry optionLabelsFor: declaredOptionLabels, and all four computeStoredExpressions sites share them. No REST export or MCP path evaluates formulas on its own: every one found goes through engine.find/findOne. Right; no reader missed.
10. Search: a formula field has no column (the skill's own "formula is virtual" warning; where/searchableFields refuse one). Unchanged. Right.
11. Tenant / permission: the map is built from the read object's own declared options after that object's read doors; nothing from another object is reachable (the macro refuses record.lookup.field at compile; an expand is a separate find under the related object's doors). A reader allowed the formula but denied the select field reads the label of a value the formula already exposed raw before this PR — pre-existing, not widened. No new leak.

② Semver level

Changeset .changeset/26608-formula-option-label.md: @objectstack/formula: minor, @objectstack/objectql: minor, with Clause-②: yes (widening) and Metadata-protocol: added line-initial in both the changeset body and the PR body. A new accepted CEL function in an authorable expression.source is a new accepted value (added), and added on a package the diff moves takes at least minor (AGENTS.md Post-Task Checklist step 3): matches. Nothing is narrowed, removed or re-meant, so no BREAKING banner and no ADR-0087 disposition is owed. @objectstack/dogfood is private: true; content/docs/** is not a package. skip-changeset does not apply. Right.

③ Boundary flags

• Dev flag: Tier H (skills/** on the file list). Confirmed: landing waits for the maintainer's word; the Governed Surface Queue Guard is green on this head. This record is the contract-tier review of the governed paths; it does not substitute for the approval.
• Dev flag: Skills-docs: follow-up owed — skills/objectstack-formula/evals/cel-predicates-formulas.json. The form is the one the claim template allows (.claude/skills/pm-dispatch/SKILL.md:313: follow-up owed — FILES, which the seat rewrites to #N before ACCEPT after filing the card). SKILL.md and formulas.mdx teach label() in this diff; the eval does not exercise it. The file is at its ceiling (1046/1046 per the dev's ratchet reading; check-skills-token-ratchet is green). Answered: deferral accepted; the seat files the owed card and rewrites the line.
• open_questions[0] — where does the label() eval land? Answer: A, a follow-up card. Trimming evals 1–5 changes what those cases grade, which is a Tier H content decision for the maintainer (and the ceiling is a ratchet ruling, not a dev's call). The follow-up card should carry one compact label(record.kind) case plus the ceiling question, and — tied to ④ should-fix 1 — a negative case asserting must_not_contain: ['label('] in a validation-rule prompt, since that is the wrong authoring this surface now makes possible.
• Dev flag: PR body not patched (three cosmetic fixes the seat writes: the 需要你做的 section's second action moves to Acceptance notes, the bundle readings are missing, the Verification bullets are not folded). Prose outside hits; noted for the seat, not judged here.
• Dev flag: check:dual-build-cjs-loads not measured locally; the derived families on the head answer it (see the check-runs below).
• Out-of-scope findings (dev's): label() outside a formula faults at run time with no publish-time refusal — carried into ④; the dogfood tsc heap reading — environment, not a code finding.
• Deviation from the order's sketch (EvalContext.locale threaded into the function) to the accepted design (caller resolves data): recorded in amendment 6442958772 before the diff; the tree follows the amendment.

④ Design judgment

skills/objectstack-formula/SKILL.md (the hits file): a new "Options" table row for label(record.f). Each claim was read against the code: "in the reader's locale" (engine reads: ①-8/9), "Only record.FIELD" (optionLabelFieldOf), "'' for null" (optionLabelOf: value === null || value === undefined → ''), "A stored (non-formula) field stores the declared label" (storedExpressionServing.optionLabelsFor = declaredOptionLabels, pinned by the objectql test's search_name case). The table header's promise ("every entry resolves at runtime, and this table documents them all") is enforced by skill-catalog-sync.test.ts and the drift probe, both updated. Token reading 5600/5997. The row holds against the code and the card's scenario (a formula nameField composed of option labels, read on the toast, H1, related list and lookup).

Attempts to break it, with the outcome of each:

• label() reads only pinned data; stdlib.ts takes no resolver. Holds (①-2). The map is read at call time through read(), so the shared evaluation environment answers each evaluation from its own map; the drift probe hands optionLabels: { a: { 1: 'One' } } and nothing else reads it.
• A stored expression stores the declared label, never the writer's locale. Holds: declaredOptionLabels ignores locale by construction; the objectql test writes under zh-CN and reads search_name = v2 · Clean off the store.
• Value with no declared option → the stored value itself (the select control shows the same). Silent by design and documented in the skill row's sibling docs; acceptable. Null → '' (documented). Multi-select → throws renders ONE option value (typeof value === 'object'); the SQL driver's formatOutput JSON.parses json columns on read (sql-driver.ts:18724, :18858), so a multi-select reaches the macro as an array and the fault is loud. Unknown field → loud at publish when a schema is in play (buildEnv registers record as the typed OsRecordScope, so checker.check(args[0]) refuses an undeclared member) and, at run time, cel-js's no_such_key surfaces as a runtime fault. Non-select field → see should-fix 1: loud on a non-null value (declares no options), silent '' on a null one, because the null check precedes the options check. Context without optionLabels → throws, which the engine never reaches (the map is built whenever label( is in the plan's sources); outside a formula field it is the loud fault the docs describe.
• The sync evaluateFormulaField left out. It evaluates with the DECLARED labels (not a throw, not the writer's locale). Its live readers: resolveRecordTitle (record-title.ts:142) when no serving channel is at hand, i.e. the hook sandbox's ctx.recordTitle fallback (body-runner.ts:283). plugin-approvals recordTitleOf reads the served row's column and is not on this path. So the only place a declared label is "served" is a hook that composes its own text from a title it evaluates without a read channel — the dev's disclosed exception; no console reader the card names reads it. No wrong label is served to a named reader. Noted as a seam for a later card if a hook consumer (notification text) surfaces.
• Reader missed? None found (①-9). A list view and a related list are find; an export or an MCP data tool reads through find/findOne with the door's execution context (resolve-execution-context.ts:216 is the shared door for REST and /mcp).
• Tenant/permission leak? None new (①-11).
• Map build cost: bundleOf pulls every locale's bundle on each read whose plan calls label( — the same work GET /meta/object does per request; planCallsOptionLabel is one regex per formula source otherwise. Acceptable; an observation.

Findings

• Should-fix 1 (skill row, the hits file). The stdlib table is the one table the skill's predicate surfaces (visibleWhen, validation when, hook/sharing condition, flow) read from, and §"CEL surfaces" says an unevaluable validation predicate aborts the write. The row does not say that label() answers only where the engine serves a formula field; formulas.mdx does. An author who writes label(record.status) == '草稿' in a validation rule passes os build and then every write to that object faults. Add the clause to the row (≈15 tokens; 397 of headroom), e.g. "formula fields only — in a predicate it faults; compare the stored value there". Not a must-fix: the failure is loud, names the function, and nothing silently wrong is served.
• Should-fix 2 (stdlib.ts optionLabelOf, cited code). Check the field's options entry before the null short-circuit, so label(record.title) on a text field faults on every row rather than only on rows where title is non-null; and, where ExprSchemaHint.fieldTypes is present at publish (validate.ts typeSoundnessIssue), refuse label() on a field whose spec type declares no options so the shape is caught at build like the other argument shapes are. Both are tightenings of a loud path, not corrections of a served value.
• Must-fix: none.

Check-runs on f780ce78 at render time: every concluded derived family is green — Lint (ESLint, repo & tooling, docs & code guards, CI/release/engine, PM dispatch-gates, scoped ×3), Type Check (source gates, consumer gates, debt ledger), Check Changeset (latest run; one earlier run cancelled by the re-run), Governed Surface Queue Guard, PR-body guards, Spec property liveness, Dogfood Regression Gate, Build Docs, Check Documentation Links, Test UI, Build UI Deps, Build Core, Build & E2E UI, Test Core 1/8, 7/8 and 8/8. Still in progress at the last reading: Test Core 2/8–6/8, Type Check · workspace, Type Check UI. Their conclusions are the gate verdicts for those families; the Tier H landing already waits on green CI and the maintainer's word, so this record's verdict stands on the tree and the concluded families, and the seat re-reads the head's check-runs before the landing.

Implemented-by: claude/project-thread-luyb0c
Reviewed-by: session_01WGufzfhobWEgUUrjz4rrbh

VERDICT: PASS

席位核对 · ACCEPT · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-27T15:29Z

Head 8ffe3ae67856cc968eb7ae61788f1b2f6611cac3. Card #26608, claim 6442789358 (surface amended by 6442958772), dev report 6444975664.

• Contract review: owed at CONTRACT_REVIEW_TIER for the formula function catalog (label()) and skills/objectstack-formula/SKILL.md. PASS 6445230404 at f780ce78, with no must-fixes. The one commit since then, 8ffe3ae6, lands both should-fixes only:

  • (a) The SKILL.md label() row now says it works in formula fields only, and that in a predicate (validation, visibility, hook) it faults, so authors compare the stored value there.
  • (b) optionLabelOf checks the field's options before the null short-circuit, so label(record.textfield) faults on every row. option-label.test.ts pins a null text field faulting.

  The diff from f780ce78 to 8ffe3ae6 is 3 files, +15/−9.

• Lane seat (rest of the diff, TIER_DEFAULT):

  • objectql builds the label map per read through translateObject in ExecutionContext.locale. That is the one path GET /meta/object serves, with picklist inheritance intact.
  • The map is wired into find, findOne, the insert and update responses, serveFormulaField and expand.
  • Stored expressions store the declared label.
  • The dogfood test pins POST, PATCH, GET and list in zh-CN and en-US on a real boot.
  • No ui/** change.
  • Search is unchanged.

• Not carried: the optional publish-time refusal of label() on a non-options field (validate.ts typeSoundnessIssue). The run-time fault is loud on every row.

• Skills-docs: #26760, the eval follow-up. cel-predicates-formulas.json is at 1046 / 1046, and the card carries the negative predicate case.

• Shape: Fixes #26608, 14 files. @objectstack/formula and @objectstack/objectql are minor. Clause-②: yes (widening) and Metadata-protocol: added. check-governed-merges --pr 26755: 1 path is governed (skills/**), 948 changed lines.

• Gates: check-runs on this head are 43 success, 9 skipped and 0 red.

• Landing: Tier H. The maintainer approved and armed it at 2026-10-27T15:07Z. This seat arms nothing.