finding(core): `ExpressionEvaluator.registerFunction` upper-cases the name, so a lower-case call in an expression renders its own `${...}` source

[os-support-ai]

Out-of-scope finding from #5343, measured while replacing the fabricated getExpressionEvaluator() example in content/docs/guide/expressions.md with the real surface. Filed unassigned, not claiming. Observation-class: nothing is broken for the built-in formula names, but the public method's contract is silently case-folding.

Measured, not inferred (origin/main = bdf8cf76e, run against the built packages/core/dist/)

const fmt = (v) => new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(v);

evaluateExpression('${formatCurrency(price)}', { formatCurrency: fmt, price: 1234.5 })
 → '$1,234.50' // context-supplied function: exact name, works

const ev = new ExpressionEvaluator({ price: 1234.5 });
ev.registerFunction('formatCurrency', fmt);
ev.evaluate('${formatCurrency(price)}') → '${formatCurrency(price)}' // the SOURCE, verbatim
ev.evaluate('${FORMATCURRENCY(price)}') → '$1,234.50'

Mechanism

• ExpressionEvaluator.registerFunction(name, fn) delegates to FormulaFunctions.register, which stores under name.toUpperCase() (packages/core/src/evaluator/FormulaFunctions.ts:38). That is right for the built-ins — they are spreadsheet-style names (SUM, IF) — but the public method is spelled like "register a JS function" and the fold is silent.
• The lookup that reaches an expression is formulas.toObject(), which hands over the stored (upper-cased) keys (FormulaFunctions.ts:66), merged under the context in evaluateExpression (ExpressionEvaluator.ts:159).
• The failure is then absorbed: evaluate() catches, console.warns and returns defaultValue ?? expression (ExpressionEvaluator.ts:~448), so the reader sees the raw ${formatCurrency(price)} text rendered on screen rather than an error. The soft-fail itself looks deliberate; it is what makes the case-fold hard to notice.

Two candidate directions (not pre-judged)

1. Keep the fold, document it on registerFunction (and say the call site must use the upper-case name) — cheapest, and consistent with the formula vocabulary.
2. Make registerFunction case-preserving for the name it is given while keeping the built-ins' case-insensitive lookup — a behaviour change on a public method; needs a decision, not a drive-by.

The doc side is already settled independently: #5343 rewrote that guide section to teach context-supplied functions (exact name, verified above), so no documentation currently depends on registerFunction.

Searched for duplicates

registerFunction, formula uppercase, expression evaluator case over open issues: zero hits.

---

Generated by Claude Code

[os-zhuang]

Triage (objectui finding round): promoted to pm:queue · domain:ui · type Task, scoped to direction 1 only — document the case-fold on registerFunction (JSDoc + the method's contract statement: call sites use the upper-case name), which makes declared = enforced without touching behavior. Direction 2 (case-preserving registration) is a behavior change on a public method: if the dev concludes it is genuinely needed, stop and report — it needs a Feature card through the decision inbox, not a drive-by. S, sonnet; Clause-②: no (docs on the method, no acceptance change).

---

Generated by Claude Code

[os-sales]

Claim: PM loop round 3 (batch raised to 5 at the maintainer's instruction — 「任务很多，并发保持5」)
Session: session_012u2pRjcqAYtoEjgr3wwhnK
Branch: claude/issue-5363-registerfunction-casefold-doc
Worktree: objectui-issue-5363
Domain: domain:ui
File surface: packages/core/src/evaluator/ExpressionEvaluator.ts (+ tests if a pin is warranted, + a changeset) (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus — triage suggested sonnet, and for the writing that is right. I am going one tier up for one reason: the card reads like a bug to fix, triage ruled it a doc-only card, and the judgment being bought here is the dev declining to "fix" the behaviour. That refusal is the deliverable, and it is not a mechanical property.
Clause-②: no — documenting an existing case-fold on the method changes no acceptance behaviour and widens no public surface. ⚠️ Flips immediately if the dev takes direction 2 (case-preserving registration), which is a behaviour change on a public method; that is a stop-and-report, not a drive-by, and with Fable exhausted for this seat it would wait rather than drop tier.
Serial constraints cleared: none — packages/core/** has no in-flight claim in this lane and no PR this session touched it. Round 3's other four hold apps/console/** (#5521), packages/app-shell/src/views/studio-design/** (#5477), packages/components/src/renderers/layout/grid.tsx (#4787) and packages/plugin-detail/** (#4998) — all disjoint from this one.

Located on origin/main this round: packages/core/src/evaluator/ExpressionEvaluator.ts is the sole non-test match for registerFunction.

---

Generated by Claude Code

[os-sales]

os-dev-report

(marker above is literal text, not an HTML comment — the angle-bracket form is eaten by the sanitizer)

{
 "issue": 5363,
 "status": "done",
 "branch": "claude/issue-5363-registerfunction-casefold-doc",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5578",
 "premise_still_valid": true,
 "summary": "AGREED WITH TRIAGE — direction 1, no fork. Documented the case-fold on ExpressionEvaluator.registerFunction (JSDoc + contract statement: expressions must call the UPPER-CASE name) and did NOT change behaviour. I re-derived the fork instead of taking it on trust and direction 2 is worse on three of the four axes: the fold is the REGISTRY's contract, not this method's accident (FormulaFunctions.register folds, and every built-in SUM/IF/UPPER is registered through that same call), so a case-preserving registerFunction would put two dialects in one registry — precisely the hazard commandment #0.1 exists to stop — and it is BREAKING rather than merely unobserved, because ActionRunner.scriptAwait.test.ts already registers 'doWrite' and calls DOWRITE(). Real-business-need evidence is absent: registerFunction has zero non-test call sites in the repo, zero doc consumers (#5343 already moved the guide to context-supplied functions), so nothing is pulling for the change. Re-verification also sharpened the card: the REGISTRY API is case-insensitive (has/get answer to the original spelling) and only EXPRESSIONS are case-sensitive, because the scope is built from toObject() — that is why the fold stays invisible until an expression runs, and it is what the new JSDoc leads with. Changeset is a real patch, not the empty-frontmatter exemption, because the JSDoc is emitted into the published dist/evaluator/ExpressionEvaluator.d.ts (measured) and is therefore what consumers see on hover.",
 "tests": "All at 29d23acc0 (head of branch); exit codes captured before any pipe, each gate quoted by its own verdict line. pnpm exec vitest run packages/core/ => 'Test Files 93 passed (93)' / 'Tests 1945 passed (1945)'. The touched file alone => 'Test Files 1 passed (1)' / 'Tests 82 passed (82)' (79 pre-existing + 3 new). pnpm --filter @object-ui/core lint => LINT_EXIT=0, '513 problems (0 errors, 513 warnings)' all pre-existing no-explicit-any. pnpm --filter @object-ui/core type-check => TYPECHECK_EXIT=0 (tsc --noEmit && tsc -p tsconfig.test.json). check-control-bytes EXIT=0 ('scanned 4629 tracked text file(s)'); check-changeset-presence EXIT=0 ('2 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s)'); check-changeset-no-major EXIT=0; check-changeset-fixed EXIT=0. ABLATION (can the pin fail?): FormulaFunctions.register mutated to set(name, fn) — direction 2 simulated — gives 'Tests 3 failed | 79 passed (82)': ALL THREE new cases go red while every pre-existing case stays green, so nothing previously covered this fold and the pin is a real tripwire rather than decorative. Rebuild statement: the suite resolves its subject by RELATIVE SOURCE PATH ('../ExpressionEvaluator'), so no dist is in the loop and no rebuild sits between mutation and result. Mutation confirmed on disk by anchored grep -c on BOTH the removed and the injected text (1->0 and 0->1) plus git diff --stat — never an editor exit code; the script carried trap '<restore>' EXIT INT TERM, and the tree was verified byte-identical to HEAD afterwards (git status --porcelain empty). DECLARED NARROWING: repo-wide pnpm lint / pnpm type-check left to CI. Evidence — eslint's own population for packages/core is 185 files (count read from --format json, not guessed) and both touched files are in it; root eslint.config.js declares no projectService/parserOptions.project, so linting is NOT type-aware and this diff cannot move a verdict in an untouched file. For type-check the invariance is stronger: the ExpressionEvaluator.ts diff contains ZERO non-comment lines (single hunk at line 349; lines 1-200 byte-identical to origin/main), so the emitted type signature is unchanged and no consumer package can be affected.",
 "open_questions": [],
 "out_of_scope_findings": [
 "NOT filed, reported instead (PM may overrule): FormulaFunctions.register carries the same undocumented fold on its own public method. It is outside the dispatched file surface, and unlike the facade its name.toUpperCase() is visible in its one-line body, so the declared-vs-enforced gap this card closes does not really exist there. Filing it would spend triage on a marginal doc edit.",
 "NOT filed, mine not the repo's: my first vitest invocation used `pnpm --filter ... test -- <path>`, and the repo's own guard rejected it loudly, naming objectui#3288/#3378 and the correct form (`pnpm exec vitest run <path>` from the repo root). The guard worked exactly as designed — recorded only because it changed how every later run in this task was invoked."
 ]
}

Notes for the PM

• Scope: no breach. Exactly three files — packages/core/src/evaluator/ExpressionEvaluator.ts, packages/core/src/evaluator/__tests__/ExpressionEvaluator.test.ts, .changeset/registerfunction-casefold-doc-5363.md — independently confirmed by the presence gate's own count ("3 file(s) changed, 2 of them under the src/ of a package the release covers").
• Clause-② stays "no". I did not take direction 2, so the flag the claim comment warned about does not trip. No acceptance behaviour changed and no public surface widened.
• skip-changeset label: not applicable and not created. This PR carries a real changeset, and per the dispatch that label does not exist in objectui — I did not add or mint one.
• If the decision inbox ever opens direction 2, my recommendation would not be case-preserving registration but the stricter opposite: reject a non-upper-case name at registration time, so the mistake is loud at the authoring moment instead of silent at render time (the "declared = enforced" maximum, and the best of the four axes for AI-authored metadata). That is equally a public-method behaviour change and equally breaks the two existing 'doWrite' / 'doFailingWrite' call sites, so it belongs on a Feature card, not here. Recorded so the option is not lost, not as a request to act.

---

Generated by Claude Code

---

Generated by Claude Code