`Field.formula({ scale: 2 })` is not applied: a percentage formula stores and returns `41.666666666666664`, and the record page prints all 15 digits

[os-zhuang]

Field.formula({ scale: 2 }) is not applied: a percentage formula stores and returns 41.666666666666664, and the record page prints all 15 digits

Measured on 17.1.0 (open edition, objectstack dev), HotCRM's crm_campaign.

The declaration

src/objects/campaign.object.ts:

response_rate: Field.formula({
 label: 'Response Rate %',
 expression: F`coalesce(record.num_sent, 0) > 0
 ? (coalesce(record.num_responses, 0) * 100.0) / record.num_sent
 : 0.0`,
 scale: 2,
}),

What the runtime returns

GET /api/v1/data/crm_campaign/<id> with num_sent: 12, num_responses: 5:

{"response_rate": 41.666666666666664, "roi": 400, "num_sent": 12, "num_responses": 5}

scale: 2 is declared and has no effect — the raw double is what is stored/returned, so every consumer inherits it. The record page renders it verbatim:

效果数据
 响应率（%）
 41.666666666666664

That is what an end user sees on the campaign page, next to 预算成本 28,000 and 投资回报率（%） 400. It reads like a bug in the product to them, and there is nothing an app author can do about it declaratively: they did declare the scale.

Why it matters beyond cosmetics

A formula field's scale is the only declarative rounding an author has. If it is inert:

• every division-shaped formula (rates, ratios, per-unit prices, averages) is a coin flip on how it prints;
• values that flow onward into a stored money/decimal field hit that field's own decimal validation and get rejected — the same tail that makes x * (d/100) unwritable to a 2-decimal money column. So an inert scale is not only display noise, it can turn a downstream write into a hard failure.

Expected

Either the engine applies scale when evaluating the formula (round-half-up to N decimals before returning/persisting), or scale is rejected at author time on Field.formula so authors know they must round inside the expression. Silently accepting a rounding declaration and not rounding is the shape that costs an app author a production incident.

crm_campaign.roi carries the same scale: 2 and happens to divide evenly in the seed data, so it looks fine — that is the accident, not the rule.

[os-elon]

Claim: PM loop round 28
Session: session_019yDEhPBC3tcGkW9bkce1HM
Branch: claude/issue-10280-formula-scale-inert
Worktree: objectstack-issue-10280
Domain: domain:engine
File surface: empty — measurement only this round. ⛔ No file is edited. Read-only plus a booted app.
Container & model: M, mode:subagent, model: opus. --tier returns no path-derived mandate; opus because the question is a semantics conflict, not a lookup.
Clause-②: no for the measurement. ⛔ The likely remedy is Clause-② and cannot be dispatched here — see below.
Serial constraints cleared: in-flight siblings are #9350 (packages/drivers/driver-sql/src/live-dialect-matrix.testkit.ts) and #8006 (census, empty write surface). All three declare no write surface overlap.

⚠️ Why this is measurement-first and not the obvious fix

The card offers a fork — "either the engine applies scale … or scale is rejected at author time" — and I nearly dispatched the first half as a plain declared-≠-enforced repair. Checking the tree first stopped that, and it should stop the dev too.

packages/objectql/src/validation/record-validator.ts:586 carries a landed ruling for the sibling face:

scale — enforced by REJECTION, never rounding (#7501)

while the formula field's own declaration (packages/spec/src/data/field.zod.ts:657) says the opposite:

Decimal places to round a computed numeric/currency result to.

⇒ Two faces of one key name declare opposite semantics, and one of them has a standing ruling behind it. Making the formula face round would ship a second, contradicting meaning for scale; making it reject would break every app that already declares it (HotCRM does). Neither is a repair a seat picks on its own, and the card is right that silently accepting a rounding declaration and not rounding is the worst of the three.

⛔ So no line is written this round. The card's severity is not in question — it is a bug, priority:p1, and a user reads 41.666666666666664 on a real campaign page today. What is in question is which of three remedies is correct, and that is decided by facts the tree can supply.

📌 The card's sharper consequence, which should survive into whatever gets ruled: an unrounded formula value flowing into a stored decimal column meets that column's own scale validation and is rejected — so an inert scale can turn a downstream write into a hard failure, not just display noise.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
 "issue": 10280,
 "status": "needs_decision",
 "branch": "claude/issue-10280-formula-scale-inert",
 "pr": null,
 "premise_still_valid": true,
 "summary": "MEASUREMENT run, empty file surface, no line written — as dispatched. The user-visible symptom is REAL and I reproduced the card's exact number on my own harness (OBSERVED). But two of the dispatch's own framing facts are FALSIFIED, and both make the fork easier, not harder. (1) PM assumption (b) is WRONG: field.zod.ts:657 is not a formula face — InlineGridColumnSchema spans 618-662, FieldSchema starts at 663, and its ONLY scale is :816. So Field.formula({scale}) and Field.number({scale}) are ONE declaration, not two contradicting ones. (2) PM assumption (a) is confirmed for the engine but wrong as 'entirely inert': scale next to an expression IS read and ROUNDS today — objectui deriveMasterDetail.ts:246/296 copies it to col.scale and fields/src/widgets/GridField.tsx:315-316 computeRow does Number(v.toFixed(scale)) before the value is persisted. That is the real third face assumption (c) suspected, and it is prior art FOR rounding. (3) #7501's ruling (2026-08-11) is scoped to 'the number validator' validating an INCOMING WRITE, with the rationale 'silent rounding is silently altering data' — i.e. do not mutate what a caller SENT. A formula field has no caller-sent value: it is virtual, the engine computes it from the author's own declaration. So option 1 NEIGHBOURS that ruling, it does not contradict it. (4) PREMISE CORRECTION, minor but worth the record: the card's title says the value is 'stored'. It is not — formula fields are virtual and my harness shows the stored row as {num_sent, num_responses, id} with no response_rate at all. Only the 'returns' half is true; the symptom is undiminished. (5) The docs TEACH the broken thing: content/docs/data-modeling/formulas.mdx promises it in prose ('declare the value type with returnType, and decimal places with scale') and demos it three times under 'Financial Calculations' — the first demo being ((revenue-cost)/revenue)*100, the card's exact percentage-division shape. Empty branch was pushed as the rule-1 write-route probe and carries ZERO commits; worktree removed cleanly; no PR, as ruled. NOT filing the docs/designer/builder disagreement as separate issues: it is not an adjacent defect, it is this card's cost column — which of the three the docs must match is exactly what the ruling decides, so filing now would pre-empt it.",
 "tests": "No gate union owed or claimed — empty diff, nothing for a gate to judge. Build (prerequisite for the harness, under the shared lock, exit captured before any pipe): pnpm --filter '@objectstack/objectql^...' build -> EXIT=0; pnpm --filter @objectstack/objectql --filter @objectstack/driver-sql build -> EXIT=0 ('Build success', 'Done'). MEASUREMENT HARNESS (scratchpad only, imports the built dist, drives the real ObjectQL engine through ObjectStackProtocolImplementation — the same protocol surface REST calls): REPRO_EXIT=0. (c) SYMPTOM, OBSERVED, card's shape and numbers (num_sent 12, num_responses 5, formula + returnType number + scale 2): CREATE and GET both return response_rate = 41.666666666666664 — BYTE-IDENTICAL to the card's reported value, 15 digits after the point. HotCRM is not available in this container, so this is my own construction of the card's shape, not the card's number re-reported. Stored row: {\"num_sent\":12,\"num_responses\":5,\"id\":\"r_1\"} — response_rate ABSENT, confirming virtual-not-stored. (a) POSITIVE CONTROL, OBSERVED — the probe is not blind: the SAME scale key on a STORED currency column IS read and enforced. Unrounded 1.1*2.2 = 2.4200000000000004 into currency scale:2 -> REFUSED, code VALIDATION_FAILED, field error {\"field\":\"amount\",\"code\":\"max_scale\",\"constraint\":{\"scale\":2,\"actual\":16}}, message 'Amount must have at most 2 decimal places (got 16)'. Within-scale 59.97 -> ACCEPTED. So the zero on the formula path is a real zero on a working instrument. (d) REACHABILITY, OBSERVED and it is the strongest argument for acting: the refusal above IS the card's third consequence, measured. Control leg: the same value rounded to scale FIRST (Number(raw.toFixed(2)) = 2.42) -> ACCEPTED. That rounding is not hypothetical — it is what objectui computeRow already does, and examples/app-crm/src/objects/opportunity-line-item.object.ts + examples/app-showcase/src/data/objects/invoice.object.ts both ship Field.currency({scale:2, expression: cel`record.quantity * record.unit_price`}) relying on it. Round-at-producer + reject-at-store is already the architecture; the type:'formula' face is the one place the producer half is missing. READ FROM SOURCE, not executed: engine inertness — FormulaPlanEntry is `{ name: string; expression: Expression }` (engine.ts:764), planFormulaProjection reads only def.type and def.expression, applyFormulaPlan does `rec[fp.name] = r.ok ? r.value : null` (engine.ts:~1236). scale is structurally unable to reach evaluation. record-validator.ts:575 number branch covers number/currency/percent/rating/slider — 'formula' is not in it; :744 says formula outputs are 'explicitly open per the spec contract'. Drivers do NOT read scale for DDL: 4 hits across packages/drivers/*/src, all prose/temporal, none the field-level key; positive control on the same instrument = 704 'field' hits in sql-driver.ts, so that zero is real too. Author-time: no superRefine gates scale by field type, so it parses on ANY type including formula. Both metadata designer forms ALREADY gate it to the number family — field.form.ts:44 visibleWhen \"data.type == 'number'\", object.form.ts:132 \"data.type in ['number','currency','percent']\" — neither offers it on formula, so the designer already disagrees with the TS builder and the docs.",
 "open_questions": [
 {
 "question": "Field.formula({ scale }) parses, is taught by the docs, and is ignored by the engine. Which of the three remedies is correct? Facts that decide it: it is ONE schema property (FieldSchema.scale :816) shared with the number family, not two contradicting declarations; #7501 ruled on the VALIDATOR mutating a caller-sent value, which a virtual formula never has; and rounding a computed value to scale before it meets the stored column's scale rejection is ALREADY the shipped architecture (objectui computeRow), relied on by two example apps.",
 "options": [
 "1 — ROUND in the engine: applyFormulaPlan rounds a numeric result to scale when the field declares one. BREAKS: nothing measured. Does NOT contradict #7501 (different actor, different object: the engine rounding its own computed value from the author's declaration vs the validator mutating data a caller submitted). Makes the docs' three worked examples correct. Fits returnType, whose own docstring says it exists so 'display formatting, validation' consumers can read a declared type. Matches the sibling computed face, ending the split where objectui rounds a formula in a grid cell while the data API does not.",
 "2 — REJECT scale on Field.formula at author time. BREAKS: the published docs' prose promise plus 3 worked examples in content/docs/data-modeling/formulas.mdx (the first is the card's own percentage-division shape); every downstream app already declaring it (HotCRM does, today — unmeasurable from here, 0 in-repo app declarations). Also requires an ADR-0087 conversion and narrows a shipped authorable surface. Leaves authors with no declarative rounding at all and the (d) refusal permanently reachable by hand.",
 "3 — REMOVE scale from the formula face entirely. Same breakage count as 2, and strictly worse for authors: it removes the only declarative rounding a formula has while the number family keeps the identical key. Because it is ONE property, 'removing it from formula only' means introducing a per-type gate that does not exist today — more machinery than 1, for less capability."
 ],
 "recommendation": "1 (round in the engine) — but this is the maintainer's call, and I am reporting it as a fork, not choosing. On the four axes: REAL BUSINESS NEED — measured, not speculative: a real user reads 41.666666666666664 on a real campaign page, the docs sell the feature in prose and three demos, and two shipped example apps already depend on round-to-scale-before-store for their writes to succeed at all. LONG-TERM SOUNDNESS — it makes one property mean one thing across both computed faces and completes a pipeline the codebase already committed to (round at the producer, reject at the store); options 2/3 leave the producer half missing on the only face that has no client to do it. AI-AUTHORED-METADATA SAFETY — this is the decisive axis and it cuts toward 1: today the declaration is accepted, documented, and silently ignored, which is exactly the shape that hides an AI-authored error; making it work removes the trap, whereas making it reject also removes the trap but simultaneously breaks the documentation the generator learned from. STARTUP SCOPE — no capability expansion: the key is already declared, already authorable, already taught; this is enforcement of an existing declaration, which ADR-0049 enforce-or-remove asks for, and it is one rounding step inside an existing loop. The one thing I would NOT do silently is extend it beyond numerics — scale on a text/boolean/date formula should stay a no-op or be refused, and that sub-question rides along with whichever option is picked."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code

[os-elon]

os-decision-facets

ACCEPT (measurement delivered) → escalating. pm:dispatched → needs-user-decision.

PM seat domain:engine, session session_019yDEhPBC3tcGkW9bkce1HM, reviewer of record. Zero files edited, empty branch, no PR — as fenced.

The fork has collapsed to nearly one option, and it collapsed because two of MY framing facts were wrong. Both corrections are verified independently below.

⛔ Correction 1 — the "two contradicting declarations" do not exist. That was my error.

I dispatched this saying Field.formula's scale and Field.number's scale declare opposite semantics, citing field.zod.ts:657 against :816. Verified on origin/main just now:

:618 export const InlineGridColumnSchema = …
:657 scale: … 'Decimal places to round a computed numeric/currency result to.' ← belongs to the INLINE GRID COLUMN
:661 }));
:663 export const FieldSchema = …
:816 scale: … 'Decimal places (non-negative integer)' ← the field's ONLY scale

⇒ Field.formula({ scale }) and Field.number({ scale }) are ONE property. There is no contradiction to resolve.

⭐ A new instance of this lane's oldest failure, on me: a line number tells you WHERE, not WHOSE. I grepped scale, got line numbers, and attributed them to schemas I had not checked the boundaries of. ⛔ Not to be inherited.

⛔ Correction 2 — #7501 does not forbid this

Its ruling is scoped to the number validator mutating a value a caller SENT, with the rationale "silent rounding is silently altering data". A formula field has no caller-sent value — it is virtual, computed by the engine from the author's own declaration. ⇒ Option 1 neighbours that ruling; it does not contradict it. The actor and the object are both different.

⭐ And rounding-at-producer is already shipped on the sibling computed face

Verified in objectui: packages/fields/src/widgets/GridField.tsx:316

next[c.name] = scale != null ? Number(v.toFixed(scale)) : v;

A computed grid column already rounds to scale before the value is written back. So the architecture — round at the producer, reject at the store — is not a proposal; it is what the codebase already does everywhere except type: 'formula', which is the one producer face with no client to do it for it.

The reachability, measured rather than argued

The card's third consequence is the strongest reason to act and it is now observed, with a control:

unrounded 1.1*2.2 = 2.4200000000000004 → currency scale:2 ⇒ REFUSED
 VALIDATION_FAILED, {"field":"amount","code":"max_scale","constraint":{"scale":2,"actual":16}}
control: the same value rounded first (2.42) ⇒ ACCEPTED

⇒ An inert scale does not merely print badly — it makes a downstream write fail. And two shipped example apps (app-crm/opportunity-line-item, app-showcase/invoice) already declare Field.currency({ scale: 2, expression: … }) relying on the rounding half existing.

⭐ The positive control matters: the same scale key on a stored column IS read and enforced, so the zero on the formula path is a real zero on a working instrument — not a blind probe.

📌 Two corrections to the card itself

1. The title is wrong on one word. It says the value "stores and returns" — it does not store. Formula fields are virtual; the measured stored row is {num_sent, num_responses, id} with no response_rate at all. Only the returns half is true. ⚠️ The symptom is undiminished, but the mechanism differs and a fix aimed at persistence would miss.

2. The docs teach the broken thing. content/docs/data-modeling/formulas.mdx promises it in prose and demonstrates it three times under "Financial Calculations" — the first demo being ((revenue-cost)/revenue)*100, the card's exact percentage-division shape.

3. platform long-term coherence — option 1 makes one property mean one thing on both computed faces and completes a pipeline the codebase already committed to. Options 2/3 leave the producer half missing on the only face that has no client to supply it. ⚠️ And because it is ONE property, "remove it from formula only" (option 3) requires a per-type gate that does not exist today — more machinery for less capability.

4. measured business pull — real and observed: a user reads 41.666666666666664 on a live campaign page; the docs sell the feature in prose and three demos; two shipped example apps depend on round-before-store for their writes to succeed at all.

5. AI-agent error-resistance — decisive. Today the declaration is accepted, documented, and silently ignored — the exact shape that hides an author's (or an agent's) error. Option 1 removes the trap. Option 2 also removes it but simultaneously breaks the documentation the generator learned from, which is a worse trade for a metadata platform.

6. startup scope discipline — option 1 is no capability expansion: the key is already declared, already authorable, already taught. This is enforcement of an existing declaration, which is what ADR-0049 enforce-or-remove asks for.

Recommendation: option 1. ⚠️ And I want to be explicit that I am not adjudicating it despite the evidence being lopsided — adjudication belongs to the triage seat, not to an executing one, and "the evidence is clear" is exactly when that boundary is easiest to step over.

• 1 — round in the engine. applyFormulaPlan rounds a numeric result when the field declares scale. Breaks nothing measured. ⭐ Recommended.
• 2 — reject scale on Field.formula at author time. Breaks the docs' prose plus 3 worked examples, breaks every app already declaring it (HotCRM does), needs an ADR-0087 conversion, and leaves authors with no declarative rounding at all while the refusal in the measurement above stays permanently reachable.
• 3 — remove it from the formula face. Same breakage as 2, plus the per-type gate that does not exist.

⚠️ A sub-question rides along with whichever is picked, and should be answered in the same stroke: scale on a non-numeric formula (text / boolean / date). It should stay a no-op or be refused — ⛔ it should not be decided silently by whoever implements.

⚠️ Confidence gap: how many out-of-repo apps declare Field.formula({ scale }) is unobservable from here — in-repo the count is 0 app declarations, HotCRM is 1 known external, and objectstack cloud not being live is the only thing bounding the rest. That number is the one input that could move option 2 from "breaks the docs" to "breaks users".

⛔ Not dispatchable until ruled, but worth noting for scheduling: option 1 is not Clause-② by the mechanical boundary test — it neither widens the accept set nor the public surface; it enforces a declaration that already ships. So this lane can implement it the moment it is ruled, fable or no fable.

---

Generated by Claude Code