@itwin/core-backend 5.14.0-dev.21 → 5.14.0-dev.23

package/lib/esm/test/annotations/FieldFormat.test.js

@@ -0,0 +1,738 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+import { expect } from "chai";
+import * as sinon from "sinon";
+import { Code, FieldRun, SubCategoryAppearance, TextBlock } from "@itwin/core-common";
+import { FormatterSpec } from "@itwin/core-quantity";
+import { Logger } from "@itwin/core-bentley";
+import { Point3d, YawPitchRollAngles } from "@itwin/core-geometry";
+import { StandaloneDb } from "../../IModelDb";
+import { IModelTestUtils } from "../IModelTestUtils";
+import { SpatialCategory } from "../../Category";
+import { Schema, Schemas } from "../../Schema";
+import { ClassRegistry } from "../../ClassRegistry";
+import { PhysicalElement } from "../../Element";
+import { ElementDrivesTextAnnotation } from "../../annotations/ElementDrivesTextAnnotation";
+import { decimalFormat, toFormatSet } from "../AnnotationTestUtils";
+import { withEditTxn } from "../../EditTxn";
+/**
+ * How a [FieldRun]'s quantity format is resolved.
+ *
+ * Each test varies the three inputs on `formatOptions.quantity` -- `formatSet`,
+ * `kindOfQuantity`, and `persistenceUnit` -- and applies them to properties chosen so that some
+ * carry their own KindOfQuantity and some do not. That split is the dominant axis: a failed
+ * override is silently rescued by the property-side candidate when the property carries a KoQ,
+ * and only falls through to the raw string when it does not.
+ *
+ * Formats resolve in this order, and the tests below walk it from the bottom up: the FormatSet a
+ * field names, then the FormatSet adopted for the iModel, then the schema's own presentation
+ * format for the property's KindOfQuantity, then the raw value.
+ *
+ * Each test registers the FormatSets it depends on inline, so what produced a given string is
+ * visible without cross-referencing a table.
+ */
+// cspell: ignore koqs
+const ADOPTED_SET = "adopted-set";
+const ALT_SET = "alternate-set";
+/** Deliberately never registered, so lookup falls back to the adopted FormatSet. */
+const UNREGISTERED_SET = "unregistered-set";
+// ---------------------------------------------------------------------------------------------
+// Test schema
+// ---------------------------------------------------------------------------------------------
+/**
+ * Two families of KindOfQuantity live here:
+ *
+ *  - `*_PROP` are attached to properties. They give the property-side candidate something to
+ *    resolve, and are left undefined by the FormatSets in most tests below, so a field that names
+ *    nothing exercises the schema. "routes a field with no KindOfQuantity override through a
+ *    FormatSet keyed on the property's own KindOfQuantity" is the deliberate exception.
+ *  - `SCHEMA_*` are declared but never attached. Tests name them to force the
+ *    FormatSet -> SchemaFormatsProvider fallthrough.
+ *
+ * Anything else a field names (`Example.LENGTH`, `Example.AREA`, ...) is defined by the FormatSet
+ * that test registers, and exists nowhere in the schema.
+ */
+const exampleSchemaXml = `<?xml version="1.0" encoding="UTF-8"?>
+<ECSchema schemaName="FieldExample" alias="fex" version="01.00.00" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
+  <ECSchemaReference name="BisCore" version="01.00.04" alias="bis"/>
+  <ECSchemaReference name="Formats" version="01.00.00" alias="f"/>
+  <ECSchemaReference name="Units" version="01.00.09" alias="u"/>
+
+  <KindOfQuantity typeName="LENGTH_PROP" displayLabel="Length" persistenceUnit="u:M" relativeError="0.0001" presentationUnits="f:DefaultRealU(4)[u:M]"/>
+  <KindOfQuantity typeName="AREA_PROP" displayLabel="Area" persistenceUnit="u:SQ_M" relativeError="0.0001" presentationUnits="f:DefaultRealU(4)[u:SQ_M]"/>
+  <KindOfQuantity typeName="SLOPE_PROP" displayLabel="Slope" persistenceUnit="u:M_PER_M" relativeError="0.0001" presentationUnits="f:DefaultRealU(4)[u:M_PER_M]"/>
+
+  <KindOfQuantity typeName="INT_LENGTH_PROP" displayLabel="Integer Length" persistenceUnit="u:MM" relativeError="0.0001" presentationUnits="f:DefaultRealU(4)[u:M]"/>
+
+  <Unit typeName="DOUBLE_M" displayLabel="dm" phenomenon="u:LENGTH" unitSystem="u:SI" definition="u:M" numerator="2"/>
+  <KindOfQuantity typeName="CUSTOM_UNIT_PROP" displayLabel="Custom-unit Length" persistenceUnit="DOUBLE_M" relativeError="0.0001" presentationUnits="f:DefaultRealU(4)[u:M]"/>
+
+  <KindOfQuantity typeName="SCHEMA_LENGTH" displayLabel="Schema Length" persistenceUnit="u:M" relativeError="0.0001" presentationUnits="f:DefaultRealU(2)[u:M]"/>
+  <KindOfQuantity typeName="SCHEMA_AREA" displayLabel="Schema Area" persistenceUnit="u:SQ_M" relativeError="0.0001" presentationUnits="f:DefaultRealU(2)[u:SQ_M]"/>
+  <KindOfQuantity typeName="SCHEMA_ANGLE" displayLabel="Schema Angle" persistenceUnit="u:ARC_DEG" relativeError="0.0001" presentationUnits="f:DefaultRealU(2)[u:ARC_DEG]"/>
+  <KindOfQuantity typeName="SCHEMA_SLOPE" displayLabel="Schema Slope" persistenceUnit="u:M_PER_M" relativeError="0.0001" presentationUnits="f:DefaultRealU(2)[u:M_PER_M]"/>
+  <KindOfQuantity typeName="SCHEMA_RATIO" displayLabel="Schema Ratio" persistenceUnit="u:ONE" relativeError="0.0001" presentationUnits="f:DefaultRealU(2)[u:ONE]"/>
+
+  <ECEntityClass typeName="ExampleElement" modifier="None">
+    <BaseClass>bis:PhysicalElement</BaseClass>
+    <ECProperty propertyName="lengthProp" typeName="double" kindOfQuantity="LENGTH_PROP"/>
+    <ECProperty propertyName="areaProp" typeName="double" kindOfQuantity="AREA_PROP"/>
+    <ECProperty propertyName="slopeProp" typeName="double" kindOfQuantity="SLOPE_PROP"/>
+    <ECProperty propertyName="angleProp" typeName="double"/>
+    <ECProperty propertyName="ratioProp" typeName="double"/>
+    <ECProperty propertyName="point" typeName="point3d"/>
+    <ECProperty propertyName="intLengthProp" typeName="int" kindOfQuantity="INT_LENGTH_PROP"/>
+    <ECProperty propertyName="intCountProp" typeName="int"/>
+    <ECProperty propertyName="customUnitProp" typeName="double" kindOfQuantity="CUSTOM_UNIT_PROP"/>
+  </ECEntityClass>
+</ECSchema>
+`;
+class ExampleElement extends PhysicalElement {
+    static get className() { return "ExampleElement"; }
+}
+class FieldExampleSchema extends Schema {
+    static get schemaName() { return "FieldExample"; }
+}
+describe("Field format resolution example", () => {
+    let imodel;
+    let elementId;
+    before(async () => {
+        const iModelPath = IModelTestUtils.prepareOutputFile("FieldFormatExample", "test.bim");
+        imodel = StandaloneDb.createEmpty(iModelPath, { rootSubject: { name: "FieldFormatExample" }, enableTransactions: true });
+        if (!Schemas.getRegisteredSchema("FieldExample")) {
+            Schemas.registerSchema(FieldExampleSchema);
+            ClassRegistry.register(ExampleElement, FieldExampleSchema);
+        }
+        await imodel.importSchemaStrings([exampleSchemaXml]);
+        await withEditTxn(imodel, async (txn) => {
+            const model = IModelTestUtils.createAndInsertPhysicalPartitionAndModel(txn, Code.createEmpty(), true)[1];
+            const category = SpatialCategory.insert(txn, StandaloneDb.dictionaryId, "FieldFormatExampleCategory", new SubCategoryAppearance());
+            const props = {
+                classFullName: "FieldExample:ExampleElement",
+                model,
+                category,
+                code: Code.createEmpty(),
+                // Seed values chosen to convert cleanly, so a wrong conversion is obvious by inspection.
+                // Every test restates the properties it uses in a "Persisted on the element:" comment, so its
+                // expected strings can be checked without scrolling back here. Changing a value below
+                // means updating those comments too -- grep "Persisted on the element" to find them all.
+                lengthProp: 2.5, // m    -> 2500 mm, 250 cm, 8.202 ft
+                areaProp: 100, // m2   -> 1076.391 ft2
+                slopeProp: 0.01, // m/m  -> 100 :1
+                angleProp: 90, // deg  -> 1.5708 rad
+                ratioProp: 0.9, // one
+                point: { x: 1, y: 2, z: 3 },
+                intLengthProp: 2500, // mm, int-typed -> 2.5 m
+                intCountProp: 42, // no KoQ; a count, not something with units
+                customUnitProp: 1.25, // DOUBLE_M, a unit only this schema defines -> would be 2.5 m
+                placement: { origin: new Point3d(0, 0, 0), angles: new YawPitchRollAngles() },
+            };
+            elementId = txn.insertElement(props);
+        });
+    });
+    after(() => {
+        imodel.close();
+    });
+    afterEach(() => {
+        sinon.restore();
+        logWarningSpy = undefined;
+    });
+    // Sinon refuses to wrap a method twice, so tests spying on both messages share one spy.
+    // Reset alongside `sinon.restore()` in afterEach.
+    let logWarningSpy;
+    function spyOnWarnings(messagePrefix) {
+        const spy = logWarningSpy ??= sinon.spy(Logger, "logWarning");
+        return () => spy.getCalls()
+            .filter((call) => typeof call.args[1] === "string" && call.args[1].startsWith(messagePrefix))
+            .map((call) => call.args[2]());
+    }
+    /** Spies on the warning [[render]] logs for each field it could not resolve a format for.
+     * Returns the (KindOfQuantity, persistence unit) pairs those warnings report as tried.
+     */
+    function spyOnFormatWarnings() {
+        return spyOnWarnings("No format resolved for text annotation field");
+    }
+    /** Warnings that a `persistenceUnit` override disagreed with the property's unit and was ignored. */
+    function spyOnUnitOverrideWarnings() {
+        return spyOnWarnings("Ignoring persistenceUnit override");
+    }
+    /** Appends a field on `propertyName` of the seeded element, and hands it back so the test can
+     * read its content after [[render]].
+     */
+    function appendField(block, propertyName, quantity) {
+        const field = FieldRun.create({
+            propertyHost: { elementId, schemaName: "FieldExample", className: "ExampleElement" },
+            propertyPath: { propertyName },
+            formatOptions: quantity ? { quantity } : undefined,
+            cachedContent: "unevaluated",
+        });
+        block.appendRun(field);
+        return field;
+    }
+    /** Registers a provider with the given FormatSets, then evaluates `block`'s fields in place.
+     * Each call replaces the previous registration, so a test's FormatSets never leak into the
+     * next one.
+     */
+    function render(block, formatSets = {}) {
+        ElementDrivesTextAnnotation.registerFieldFormatting({
+            iModel: imodel,
+            formatSet: formatSets.adopted,
+            formatSets: formatSets.byId,
+        });
+        ElementDrivesTextAnnotation.evaluateFields({ iModel: imodel, block });
+    }
+    it("formats integer-valued properties as quantities, leaving those that resolve no format raw", async () => {
+        // Classifying a numeric property as "quantity" only decides whether the KoQ/units pipeline is
+        // consulted; it is not a claim that the value has units. A count that names no
+        // KindOfQuantity anywhere resolves no spec and falls back to the same bare `toString()` the
+        // "string" formatter would have produced, so the classification costs it nothing -- while
+        // leaving the field-level override hatch open for callers who do declare one.
+        //
+        // Persisted on the element: intLengthProp 2500 (mm, int), intCountProp 42 (no KoQ)
+        const block = TextBlock.create();
+        const measured = appendField(block, "intLengthProp");
+        const counted = appendField(block, "intCountProp");
+        const overridden = appendField(block, "intCountProp", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH", persistenceUnit: "Units.M" });
+        render(block);
+        // The property's own KoQ persists millimeters and presents meters: converted, not relabelled.
+        expect(measured.cachedContent).to.equal("2.5 m");
+        // Nothing names a KindOfQuantity, so no spec resolves and the count renders with no stray unit.
+        expect(counted.cachedContent).to.equal("42");
+        // Same property, but the field declares both halves of the override, which is the documented
+        // way to format a property that carries no KindOfQuantity of its own.
+        expect(overridden.cachedContent).to.equal("42.0 m");
+    });
+    it("renders a field with no format options from the property's own KindOfQuantity, and raw where it has none", async () => {
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp");
+        const area = appendField(block, "areaProp");
+        const slope = appendField(block, "slopeProp");
+        const angle = appendField(block, "angleProp");
+        const ratio = appendField(block, "ratioProp");
+        const point = appendField(block, "point");
+        render(block);
+        // lengthProp, areaProp and slopeProp each declare a KindOfQuantity, so with no FormatSet
+        // adopted the schema's own presentation format supplies the unit and precision.
+        expect(length.cachedContent).to.equal("2.5 m");
+        expect(area.cachedContent).to.equal("100.0 m²");
+        expect(slope.cachedContent).to.equal("0.01 m/m");
+        // angleProp, ratioProp and point declare none, and the field names none either, so there is
+        // nothing to resolve against and the persisted value is rendered as-is.
+        expect(angle.cachedContent).to.equal("90");
+        expect(ratio.cachedContent).to.equal("0.9");
+        expect(point.cachedContent).to.equal("(1, 2, 3)");
+    });
+    it("resolves a schema-defined KindOfQuantity for every property when the field supplies both the format and the unit", async () => {
+        // The only row in this group that resolves anything the baseline did not. Naming a KoQ the
+        // schema declares but no FormatSet defines reaches the SchemaFormatsProvider, and because the
+        // field also names the persistence unit, the properties that carry no KoQ of their own
+        // resolve too -- both halves of the key came from the field.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH", persistenceUnit: "Units.M" });
+        const area = appendField(block, "areaProp", { kindOfQuantity: "FieldExample.SCHEMA_AREA", persistenceUnit: "Units.SQ_M" });
+        const slope = appendField(block, "slopeProp", { kindOfQuantity: "FieldExample.SCHEMA_SLOPE", persistenceUnit: "Units.M_PER_M" });
+        const angle = appendField(block, "angleProp", { kindOfQuantity: "FieldExample.SCHEMA_ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        const ratio = appendField(block, "ratioProp", { kindOfQuantity: "FieldExample.SCHEMA_RATIO", persistenceUnit: "Units.ONE" });
+        const point = appendField(block, "point", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH", persistenceUnit: "Units.M" });
+        render(block);
+        // The SCHEMA_* KoQs declare the same units as the properties do, at precision 2 rather than 4,
+        // so the KoQ-bearing properties look unchanged from the baseline.
+        expect(length.cachedContent).to.equal("2.5 m");
+        expect(area.cachedContent).to.equal("100.0 m²");
+        expect(slope.cachedContent).to.equal("0.01 m/m");
+        // These three are the ones that moved: raw in the baseline, formatted here.
+        expect(angle.cachedContent).to.equal("90.0 °");
+        expect(ratio.cachedContent).to.equal("0.9 one");
+        expect(point.cachedContent).to.equal("(1.0 m, 2.0 m, 3.0 m)");
+    });
+    it("ignores a KindOfQuantity named without a persistence unit unless the property supplies one", async () => {
+        // Same KoQs as above with the unit leg dropped. A format alone cannot be bound to a value --
+        // something has to say what unit the persisted number is in. The property's own KoQ answers
+        // that for the first three; nothing answers it for the rest.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH" });
+        const area = appendField(block, "areaProp", { kindOfQuantity: "FieldExample.SCHEMA_AREA" });
+        const slope = appendField(block, "slopeProp", { kindOfQuantity: "FieldExample.SCHEMA_SLOPE" });
+        const angle = appendField(block, "angleProp", { kindOfQuantity: "FieldExample.SCHEMA_ANGLE" });
+        const ratio = appendField(block, "ratioProp", { kindOfQuantity: "FieldExample.SCHEMA_RATIO" });
+        const point = appendField(block, "point", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH" });
+        render(block);
+        expect(length.cachedContent).to.equal("2.5 m");
+        expect(area.cachedContent).to.equal("100.0 m²");
+        expect(slope.cachedContent).to.equal("0.01 m/m");
+        // Back to raw, unlike the test above -- dropping the unit cost these three their formatting.
+        expect(angle.cachedContent).to.equal("90");
+        expect(ratio.cachedContent).to.equal("0.9");
+        expect(point.cachedContent).to.equal("(1, 2, 3)");
+    });
+    it("treats an empty persistenceUnit like an absent one", async () => {
+        // `persistenceUnit: ""` used to silently discard the kindOfQuantity override.
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const emptyUnit = appendField(block, "lengthProp", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH", persistenceUnit: "" });
+        render(block);
+        expect(emptyUnit.cachedContent).to.equal("2.5 m");
+    });
+    it("accepts any case and either separator for names the iModel's schemas define", async () => {
+        // Override names are normalized to the schema's spelling before anything compares or looks
+        // them up. Without that, `units:m` on a meters property would be flagged as disagreeing with
+        // `Units.M`, and `fieldexample:schema_angle` would fail the exact-spelling unit lookup.
+        // Persisted on the element: lengthProp 2.5 m, angleProp 90° (no KindOfQuantity)
+        const block = TextBlock.create();
+        const respelledUnit = appendField(block, "lengthProp", { persistenceUnit: "units:m" });
+        const respelledBoth = appendField(block, "lengthProp", { kindOfQuantity: "fieldexample:schema_length", persistenceUnit: "UNITS.M" });
+        const respelledKoq = appendField(block, "angleProp", { kindOfQuantity: "fieldexample:schema_angle", persistenceUnit: "units:arc_deg" });
+        const ignored = spyOnUnitOverrideWarnings();
+        render(block);
+        expect(respelledUnit.cachedContent).to.equal("2.5 m");
+        expect(respelledBoth.cachedContent).to.equal("2.5 m");
+        expect(respelledKoq.cachedContent).to.equal("90.0 °");
+        expect(ignored()).to.be.empty;
+    });
+    it("ignores a persistence unit named without a KindOfQuantity", async () => {
+        // The mirror image: a unit with no format to apply to it. Nothing names a format, so the
+        // property-side candidate is all that is left and the result is the baseline exactly.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { persistenceUnit: "Units.M" });
+        const area = appendField(block, "areaProp", { persistenceUnit: "Units.SQ_M" });
+        const slope = appendField(block, "slopeProp", { persistenceUnit: "Units.M_PER_M" });
+        const angle = appendField(block, "angleProp", { persistenceUnit: "Units.ARC_DEG" });
+        const ratio = appendField(block, "ratioProp", { persistenceUnit: "Units.ONE" });
+        const point = appendField(block, "point", { persistenceUnit: "Units.M" });
+        render(block);
+        expect(length.cachedContent).to.equal("2.5 m");
+        expect(area.cachedContent).to.equal("100.0 m²");
+        expect(slope.cachedContent).to.equal("0.01 m/m");
+        expect(angle.cachedContent).to.equal("90");
+        expect(ratio.cachedContent).to.equal("0.9");
+        expect(point.cachedContent).to.equal("(1, 2, 3)");
+    });
+    it("logs a warning when the persistence unit override does not exist", async () => {
+        // The format leg is fine and the unit leg is garbage. A property that carries its own unit
+        // ignores the override (and says so), so its KoQ override still formats. A property with no
+        // unit of its own has nothing else to try, so it goes raw and the shortfall is logged.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH", persistenceUnit: "Units.NOT_A_UNIT" });
+        const area = appendField(block, "areaProp", { kindOfQuantity: "FieldExample.SCHEMA_AREA", persistenceUnit: "Units.NOT_A_UNIT" });
+        const slope = appendField(block, "slopeProp", { kindOfQuantity: "FieldExample.SCHEMA_SLOPE", persistenceUnit: "Units.NOT_A_UNIT" });
+        const angle = appendField(block, "angleProp", { kindOfQuantity: "FieldExample.SCHEMA_ANGLE", persistenceUnit: "Units.NOT_A_UNIT" });
+        const ratio = appendField(block, "ratioProp", { kindOfQuantity: "FieldExample.SCHEMA_RATIO", persistenceUnit: "Units.NOT_A_UNIT" });
+        const point = appendField(block, "point", { kindOfQuantity: "FieldExample.SCHEMA_LENGTH", persistenceUnit: "Units.NOT_A_UNIT" });
+        const warnings = spyOnFormatWarnings();
+        const ignored = spyOnUnitOverrideWarnings();
+        render(block);
+        expect(length.cachedContent).to.equal("2.5 m");
+        expect(area.cachedContent).to.equal("100.0 m²");
+        expect(slope.cachedContent).to.equal("0.01 m/m");
+        expect(angle.cachedContent).to.equal("90");
+        expect(ratio.cachedContent).to.equal("0.9");
+        expect(point.cachedContent).to.equal("(1, 2, 3)");
+        expect(ignored().map((w) => w.propertyName)).to.deep.equal(["lengthProp", "areaProp", "slopeProp"]);
+        expect(ignored()[0]).to.deep.equal({
+            elementId,
+            propertyName: "lengthProp",
+            persistenceUnit: "Units.NOT_A_UNIT",
+            propertyPersistenceUnit: "Units.M",
+        });
+        expect(warnings()).to.have.length(3);
+        expect(warnings().every((w) => w.tried.some((t) => t.endsWith(" in Units.NOT_A_UNIT")))).to.be.true;
+        // The metadata identifies the field so a host can find it, and lists exactly what was tried.
+        expect(warnings()[0]).to.deep.equal({
+            elementId,
+            propertyName: "angleProp",
+            formatSet: undefined,
+            tried: ["FieldExample.SCHEMA_ANGLE in Units.NOT_A_UNIT"],
+        });
+    });
+    it("ignores a valid persistence-unit override that disagrees with the property's own unit", async () => {
+        // The field claims the 2.5 stored on lengthProp is 2.5 *feet*. The schema says the property
+        // persists meters, and the schema is the authority on what a stored magnitude means: the
+        // override is a formatting hint, not a reinterpretation. The property's unit is used, and the
+        // disagreement is logged so the author can find the mistake.
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const claimsFeet = appendField(block, "lengthProp", { persistenceUnit: "Units.FT" });
+        const warnings = spyOnFormatWarnings();
+        const ignored = spyOnUnitOverrideWarnings();
+        render(block);
+        expect(claimsFeet.cachedContent).to.equal("2.5 m");
+        expect(warnings()).to.be.empty;
+        expect(ignored()).to.deep.equal([{
+                elementId,
+                propertyName: "lengthProp",
+                persistenceUnit: "Units.FT",
+                propertyPersistenceUnit: "Units.M",
+            }]);
+    });
+    it("falls back to the property's own format when the KindOfQuantity does not exist", async () => {
+        // The other leg fails this time -- a KoQ no FormatSet and no schema defines, paired with a
+        // perfectly good unit. The counterpart to the failed-unit case above, and deliberately not
+        // the same outcome: a unit override makes a claim about the stored magnitude, so failing it
+        // forfeits the property-side pair, while a KoQ override only chooses a presentation, so
+        // failing it still falls back to the property's own format.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.M" });
+        const area = appendField(block, "areaProp", { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.SQ_M" });
+        const slope = appendField(block, "slopeProp", { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.M_PER_M" });
+        const angle = appendField(block, "angleProp", { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.ARC_DEG" });
+        const ratio = appendField(block, "ratioProp", { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.ONE" });
+        const point = appendField(block, "point", { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.M" });
+        render(block);
+        expect(length.cachedContent).to.equal("2.5 m");
+        expect(area.cachedContent).to.equal("100.0 m²");
+        expect(slope.cachedContent).to.equal("0.01 m/m");
+        expect(angle.cachedContent).to.equal("90");
+        expect(ratio.cachedContent).to.equal("0.9");
+        expect(point.cachedContent).to.equal("(1, 2, 3)");
+    });
+    it("falls back to the property's own pair when both legs of the override fail", async () => {
+        // The most degenerate row: nothing the field says can be resolved. The bad persistence unit
+        // is ignored in favor of the property's, and the unknown KoQ fails, so the property's own pair
+        // is the only candidate left. The three KoQ-bearing properties render their baseline; the
+        // three KoQ-less ones have nothing to fall back to and go raw. Asserted against baselines
+        // rendered in the same pass rather than captured literals, so the claim survives any change
+        // to the seed values or the schema.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const bothLegsFail = { kindOfQuantity: "Example.DOES_NOT_EXIST", persistenceUnit: "Units.NOT_A_UNIT" };
+        const length = appendField(block, "lengthProp", bothLegsFail);
+        const area = appendField(block, "areaProp", bothLegsFail);
+        const slope = appendField(block, "slopeProp", bothLegsFail);
+        const angle = appendField(block, "angleProp", bothLegsFail);
+        const ratio = appendField(block, "ratioProp", bothLegsFail);
+        const point = appendField(block, "point", bothLegsFail);
+        const lengthBaseline = appendField(block, "lengthProp");
+        const areaBaseline = appendField(block, "areaProp");
+        const slopeBaseline = appendField(block, "slopeProp");
+        const angleBaseline = appendField(block, "angleProp");
+        const ratioBaseline = appendField(block, "ratioProp");
+        const pointBaseline = appendField(block, "point");
+        render(block);
+        expect(length.cachedContent).to.equal(lengthBaseline.cachedContent); // both "2.5 m"
+        expect(area.cachedContent).to.equal(areaBaseline.cachedContent); // both "100.0 m²"
+        expect(slope.cachedContent).to.equal(slopeBaseline.cachedContent); // both "0.01 m/m"
+        expect(angle.cachedContent).to.equal(angleBaseline.cachedContent); // both "90"
+        expect(ratio.cachedContent).to.equal(ratioBaseline.cachedContent); // both "0.9"
+        expect(point.cachedContent).to.equal(pointBaseline.cachedContent); // both "(1, 2, 3)"
+    });
+    it("prefers the adopted FormatSet's format over the property's own schema format", async () => {
+        // The happy path. Every field names a KoQ the adopted set defines and the unit its value is
+        // persisted in, so the FormatSet answers for all six -- including the three properties that
+        // carry no KoQ of their own, which the field has now supplied both halves of the key for.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        const area = appendField(block, "areaProp", { kindOfQuantity: "Example.AREA", persistenceUnit: "Units.SQ_M" });
+        const slope = appendField(block, "slopeProp", { kindOfQuantity: "Example.SLOPE", persistenceUnit: "Units.M_PER_M" });
+        const angle = appendField(block, "angleProp", { kindOfQuantity: "Example.ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        const ratio = appendField(block, "ratioProp", { kindOfQuantity: "Example.RATIO", persistenceUnit: "Units.ONE" });
+        const point = appendField(block, "point", { kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        render(block, {
+            adopted: toFormatSet("Adopted", {
+                "Example.LENGTH": decimalFormat("Units.CM", "cm", 2),
+                "Example.AREA": decimalFormat("Units.SQ_FT", "ft2", 2),
+                "Example.SLOPE": decimalFormat("Units.HORIZONTAL_PER_VERTICAL", ":1", 2),
+                "Example.ANGLE": decimalFormat("Units.RAD", "rad", 4),
+                "Example.RATIO": decimalFormat("Units.ONE", "r", 4),
+            }),
+        });
+        // Each value is converted out of its persistence unit into the adopted format's unit -- the
+        // schema's own meter/square-meter/degree presentations no longer apply.
+        expect(length.cachedContent).to.equal("250 cm");
+        expect(area.cachedContent).to.equal("1076.39 ft2");
+        expect(slope.cachedContent).to.equal("100 :1");
+        expect(angle.cachedContent).to.equal("1.5708 rad");
+        expect(ratio.cachedContent).to.equal("0.9 r");
+        expect(point.cachedContent).to.equal("(100 cm, 200 cm, 300 cm)");
+    });
+    it("applies an adopted FormatSet format without a persistence unit only where the property declares one", async () => {
+        // Same adopted set, unit leg dropped. The property's KoQ supplies the missing half for the
+        // first three; the rest have nothing to convert from and stay raw. Note this is not the
+        // schema's *format* being used -- only its persistence unit, with the FormatSet's format.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { kindOfQuantity: "Example.LENGTH" });
+        const area = appendField(block, "areaProp", { kindOfQuantity: "Example.AREA" });
+        const slope = appendField(block, "slopeProp", { kindOfQuantity: "Example.SLOPE" });
+        const angle = appendField(block, "angleProp", { kindOfQuantity: "Example.ANGLE" });
+        const ratio = appendField(block, "ratioProp", { kindOfQuantity: "Example.RATIO" });
+        const point = appendField(block, "point", { kindOfQuantity: "Example.LENGTH" });
+        render(block, {
+            adopted: toFormatSet("Adopted", {
+                "Example.LENGTH": decimalFormat("Units.CM", "cm", 2),
+                "Example.AREA": decimalFormat("Units.SQ_FT", "ft2", 2),
+                "Example.SLOPE": decimalFormat("Units.HORIZONTAL_PER_VERTICAL", ":1", 2),
+                "Example.ANGLE": decimalFormat("Units.RAD", "rad", 4),
+                "Example.RATIO": decimalFormat("Units.ONE", "r", 4),
+            }),
+        });
+        expect(length.cachedContent).to.equal("250 cm");
+        expect(area.cachedContent).to.equal("1076.39 ft2");
+        expect(slope.cachedContent).to.equal("100 :1");
+        // Unchanged from the baseline: no persistence unit from either side.
+        expect(angle.cachedContent).to.equal("90");
+        expect(ratio.cachedContent).to.equal("0.9");
+        expect(point.cachedContent).to.equal("(1, 2, 3)");
+    });
+    it("routes to the adopted FormatSet whether the field names its id, names nothing, or names an id that was never registered", async () => {
+        // Three ways of addressing the default formats, which must be indistinguishable: the adopted
+        // set is what a field gets when it asks for nothing, and an id absent from the registration
+        // falls back to it rather than failing or searching the other sets. Asserted against each
+        // other rather than against literals so it cannot drift with the formats above.
+        // Persisted on the element: lengthProp 2.5 m, angleProp 90°
+        const block = TextBlock.create();
+        const namesNothing = appendField(block, "lengthProp", { kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        const namesAdopted = appendField(block, "lengthProp", { formatSet: ADOPTED_SET, kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        const namesUnregistered = appendField(block, "lengthProp", { formatSet: UNREGISTERED_SET, kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        // Repeated on a property with no KoQ of its own, where a routing failure would fall all the
+        // way to raw rather than being masked by the property-side format.
+        const koqLessNamesNothing = appendField(block, "angleProp", { kindOfQuantity: "Example.ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        const koqLessNamesAdopted = appendField(block, "angleProp", { formatSet: ADOPTED_SET, kindOfQuantity: "Example.ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        const koqLessNamesUnregistered = appendField(block, "angleProp", { formatSet: UNREGISTERED_SET, kindOfQuantity: "Example.ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        const adopted = toFormatSet("Adopted", {
+            "Example.LENGTH": decimalFormat("Units.CM", "cm", 2),
+            "Example.ANGLE": decimalFormat("Units.RAD", "rad", 4),
+        });
+        render(block, { adopted, byId: [{ id: ADOPTED_SET, formatSet: adopted }] });
+        expect(namesNothing.cachedContent).to.equal("250 cm");
+        expect(namesAdopted.cachedContent).to.equal(namesNothing.cachedContent); // both "250 cm"
+        expect(namesUnregistered.cachedContent).to.equal(namesNothing.cachedContent); // both "250 cm"
+        expect(koqLessNamesNothing.cachedContent).to.equal("1.5708 rad");
+        expect(koqLessNamesAdopted.cachedContent).to.equal(koqLessNamesNothing.cachedContent); // both "1.5708 rad"
+        expect(koqLessNamesUnregistered.cachedContent).to.equal(koqLessNamesNothing.cachedContent); // both "1.5708 rad"
+    });
+    it("uses an alternate FormatSet's format when the field names it, in preference to the adopted one", async () => {
+        // Mixing presentations within one iModel -- imperial callouts on an otherwise metric drawing.
+        // Both sets define every key here, so the alternate's redefinition is what must win.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m, angleProp 90°,
+        // ratioProp 0.9 (dimensionless), point (1, 2, 3) m
+        const block = TextBlock.create();
+        const length = appendField(block, "lengthProp", { formatSet: ALT_SET, kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        const area = appendField(block, "areaProp", { formatSet: ALT_SET, kindOfQuantity: "Example.AREA", persistenceUnit: "Units.SQ_M" });
+        const slope = appendField(block, "slopeProp", { formatSet: ALT_SET, kindOfQuantity: "Example.SLOPE", persistenceUnit: "Units.M_PER_M" });
+        const angle = appendField(block, "angleProp", { formatSet: ALT_SET, kindOfQuantity: "Example.ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        const ratio = appendField(block, "ratioProp", { formatSet: ALT_SET, kindOfQuantity: "Example.RATIO", persistenceUnit: "Units.ONE" });
+        const point = appendField(block, "point", { formatSet: ALT_SET, kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        // The same field routed to the default formats, to prove the alternate set actually displaced
+        // the adopted one rather than both happening to agree.
+        const adoptedLength = appendField(block, "lengthProp", { kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        render(block, {
+            adopted: toFormatSet("Adopted", {
+                "Example.LENGTH": decimalFormat("Units.CM", "cm", 2),
+                "Example.AREA": decimalFormat("Units.SQ_M", "m2", 2),
+                "Example.SLOPE": decimalFormat("Units.M_PER_M", "m/m", 4),
+                "Example.ANGLE": decimalFormat("Units.ARC_DEG", "deg", 2),
+                "Example.RATIO": decimalFormat("Units.ONE", "ratio", 2),
+            }),
+            byId: [{
+                    id: ALT_SET, formatSet: toFormatSet("Alternate", {
+                        "Example.LENGTH": decimalFormat("Units.FT", "[alt]ft", 3),
+                        "Example.AREA": decimalFormat("Units.SQ_FT", "[alt]ft2", 3),
+                        "Example.SLOPE": decimalFormat("Units.HORIZONTAL_PER_VERTICAL", "[alt]:1", 2),
+                        "Example.ANGLE": decimalFormat("Units.ARC_DEG", "[alt]deg", 1),
+                        "Example.RATIO": decimalFormat("Units.ONE", "[alt]ratio", 1),
+                    }),
+                }],
+        });
+        expect(length.cachedContent).to.equal("8.202 [alt]ft");
+        expect(area.cachedContent).to.equal("1076.391 [alt]ft2");
+        expect(slope.cachedContent).to.equal("100 [alt]:1");
+        expect(angle.cachedContent).to.equal("90 [alt]deg");
+        expect(ratio.cachedContent).to.equal("0.9 [alt]ratio");
+        expect(point.cachedContent).to.equal("(3.281 [alt]ft, 6.562 [alt]ft, 9.843 [alt]ft)");
+        expect(adoptedLength.cachedContent).to.equal("250 cm");
+    });
+    it("falls through from the named alternate FormatSet to the adopted one when the alternate omits the key", async () => {
+        // The alternate set is a partial overlay, not a replacement: a field routed to it still sees
+        // every key the adopted set defines.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m²
+        const block = TextBlock.create();
+        const redefined = appendField(block, "lengthProp", { formatSet: ALT_SET, kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        const omitted = appendField(block, "areaProp", { formatSet: ALT_SET, kindOfQuantity: "Example.AREA", persistenceUnit: "Units.SQ_M" });
+        render(block, {
+            adopted: toFormatSet("Adopted", {
+                "Example.LENGTH": decimalFormat("Units.CM", "cm", 2),
+                "Example.AREA": decimalFormat("Units.SQ_FT", "ft2", 2),
+            }),
+            byId: [{
+                    id: ALT_SET, formatSet: toFormatSet("Alternate", {
+                        // Redefines the length key and says nothing about area.
+                        "Example.LENGTH": decimalFormat("Units.FT", "[alt]ft", 3),
+                    }),
+                }],
+        });
+        expect(redefined.cachedContent).to.equal("8.202 [alt]ft");
+        expect(omitted.cachedContent).to.equal("1076.39 ft2");
+    });
+    it("routes a colon-separated KindOfQuantity name to the FormatSet that defines it in dot-separated form", async () => {
+        // Pins a normalization in another package. `FormatSetFormatsProvider.getFormatSync` in
+        // ecschema-metadata normalizes the name it is asked for via `SchemaItem.parseFullName`, which
+        // accepts `schemaName:itemName` (the form the node addon emits) as well as
+        // `schemaName.itemName`, so a set keyed in dot form must answer a field that names its KoQ in
+        // colon form.
+        //
+        // If that normalization ever regresses, the alternate set misses a key it does define and the
+        // field silently falls through to the *adopted* set instead -- no throw, no warning, because a
+        // spec did resolve. This test is the tripwire: it fails with the adopted set's "250 cm" rather
+        // than the alternate's "[alt]ft".
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const colonNamed = appendField(block, "lengthProp", { formatSet: ALT_SET, kindOfQuantity: "Example:LENGTH", persistenceUnit: "Units.M" });
+        const dotNamed = appendField(block, "lengthProp", { formatSet: ALT_SET, kindOfQuantity: "Example.LENGTH", persistenceUnit: "Units.M" });
+        render(block, {
+            // Defines the same key, so a regressed alternate set falls through to here and produces a
+            // plausible-looking string instead of an obvious failure.
+            adopted: toFormatSet("Adopted", { "Example.LENGTH": decimalFormat("Units.CM", "cm", 2) }),
+            byId: [{ id: ALT_SET, formatSet: toFormatSet("Alternate", { "Example.LENGTH": decimalFormat("Units.FT", "[alt]ft", 3) }) }],
+        });
+        expect(colonNamed.cachedContent).to.equal("8.202 [alt]ft");
+        expect(colonNamed.cachedContent).to.equal(dotNamed.cachedContent); // both "8.202 [alt]ft"
+    });
+    it("resolves a key only the alternate FormatSet defines only when the field names that set", async () => {
+        // The complement of the fallthrough above: the adopted set cannot see into the alternate
+        // one. An unregistered id lands on the adopted set, so it fails the same way naming
+        // nothing does -- the fallback is one specific set, not a search of every registered set.
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const namesAlternate = appendField(block, "lengthProp", { formatSet: ALT_SET, kindOfQuantity: "Example.ALT_ONLY_LENGTH", persistenceUnit: "Units.M" });
+        const namesNothing = appendField(block, "lengthProp", { kindOfQuantity: "Example.ALT_ONLY_LENGTH", persistenceUnit: "Units.M" });
+        const namesUnregistered = appendField(block, "lengthProp", { formatSet: UNREGISTERED_SET, kindOfQuantity: "Example.ALT_ONLY_LENGTH", persistenceUnit: "Units.M" });
+        render(block, {
+            adopted: toFormatSet("Adopted", { "Example.LENGTH": decimalFormat("Units.CM", "cm", 2) }),
+            byId: [{
+                    id: ALT_SET, formatSet: toFormatSet("Alternate", {
+                        "Example.ALT_ONLY_LENGTH": decimalFormat("Units.IN", "[alt-only]in", 2),
+                    }),
+                }],
+        });
+        expect(namesAlternate.cachedContent).to.equal("98.43 [alt-only]in");
+        // Neither the adopted set nor the schema defines this key, so the property's own KoQ decides.
+        expect(namesNothing.cachedContent).to.equal("2.5 m");
+        expect(namesUnregistered.cachedContent).to.equal(namesNothing.cachedContent); // both "2.5 m"
+    });
+    it("reaches the schema from a named alternate FormatSet when neither set defines the key", async () => {
+        // The full chain in one field: alternate -> adopted -> SchemaFormatsProvider. Asserted on a
+        // property with no KoQ of its own, so a break anywhere in the chain shows up as a raw value
+        // rather than being masked by the property-side format.
+        // Persisted on the element: angleProp 90°
+        const block = TextBlock.create();
+        const angle = appendField(block, "angleProp", { formatSet: ALT_SET, kindOfQuantity: "FieldExample.SCHEMA_ANGLE", persistenceUnit: "Units.ARC_DEG" });
+        render(block, {
+            adopted: toFormatSet("Adopted", { "Example.LENGTH": decimalFormat("Units.CM", "cm", 2) }),
+            byId: [{ id: ALT_SET, formatSet: toFormatSet("Alternate", { "Example.LENGTH": decimalFormat("Units.FT", "[alt]ft", 3) }) }],
+        });
+        expect(angle.cachedContent).to.equal("90.0 °");
+    });
+    it("renders raw and logs a warning when the persistence unit is defined only by the iModel's schemas", async () => {
+        // Synchronous resolution goes through the bundled BIS units alone; SchemaUnitProvider has no
+        // synchronous path. A property persisted in a unit its own schema defines is therefore a
+        // known limitation: it renders raw and is logged, rather than being silently formatted
+        // through the wrong unit.
+        // Persisted on the element: customUnitProp 1.25 DOUBLE_M (= 2.5 m)
+        const block = TextBlock.create();
+        const custom = appendField(block, "customUnitProp");
+        const warnings = spyOnFormatWarnings();
+        render(block);
+        expect(custom.cachedContent).to.equal("1.25");
+        expect(warnings()).to.deep.equal([{ elementId, propertyName: "customUnitProp", formatSet: undefined, tried: ["FieldExample.CUSTOM_UNIT_PROP in FieldExample.DOUBLE_M"] }]);
+    });
+    it("routes a field with no KindOfQuantity override through a FormatSet keyed on the property's own KindOfQuantity", async () => {
+        // The shape a deployment is most likely to take: FormatSets keyed on the KindOfQuantities the
+        // schemas already declare, and fields that carry no overrides at all -- at most a FormatSet id
+        // to pick a presentation. Nothing here names a KoQ, so every candidate's `name` is the
+        // property's own `FieldExample.LENGTH_PROP`, supplied by the property-side pair. A FormatSet
+        // that defines that key is therefore reached without the field mentioning it.
+        //
+        // This is what makes `FieldSpecBucket.definesOwnFormat` load-bearing rather than incidental:
+        // it is asked about the property's KoQ, not only about an override.
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const namesAlternate = appendField(block, "lengthProp", { formatSet: ALT_SET });
+        const namesNothing = appendField(block, "lengthProp");
+        render(block, {
+            adopted: toFormatSet("Adopted", { "FieldExample.LENGTH_PROP": decimalFormat("Units.CM", "cm", 2) }),
+            byId: [{ id: ALT_SET, formatSet: toFormatSet("Alternate", { "FieldExample.LENGTH_PROP": decimalFormat("Units.FT", "[alt]ft", 3) }) }],
+        });
+        // Both are routed by their FormatSet, and neither falls back to the schema's own
+        // presentation format for LENGTH_PROP, which would render "2.5 m".
+        expect(namesAlternate.cachedContent).to.equal("8.202 [alt]ft");
+        expect(namesNothing.cachedContent).to.equal("250 cm");
+    });
+    it("does nothing when a field names a FormatSet whose formats it shares no key with", async () => {
+        // The complement of the test above. Naming a FormatSet does not by itself select anything:
+        // routing happens on the candidate's KoQ name, which here is the property's own
+        // `FieldExample.LENGTH_PROP` -- a key neither set defines. So both fields land on the
+        // schema's presentation format, and naming the alternate set changes nothing.
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const namesAlternate = appendField(block, "lengthProp", { formatSet: ALT_SET });
+        const noOptions = appendField(block, "lengthProp");
+        render(block, {
+            adopted: toFormatSet("Adopted", { "Example.LENGTH": decimalFormat("Units.CM", "cm", 2) }),
+            byId: [{ id: ALT_SET, formatSet: toFormatSet("Alternate", { "Example.LENGTH": decimalFormat("Units.FT", "[alt]ft", 3) }) }],
+        });
+        expect(namesAlternate.cachedContent).to.equal(noOptions.cachedContent); // both "2.5 m"
+        expect(namesAlternate.cachedContent).to.equal("2.5 m");
+    });
+    it("declines a format whose unit belongs to a different phenomenon than the persisted value", async () => {
+        // A format can only be applied if its unit is convertible from the persistence unit. An angle
+        // format cannot present a length, so the override is refused and the field falls back exactly
+        // as it would for any other unresolved format -- here, to the schema's own presentation format.
+        // Without that check the magnitude would be relabelled rather than converted ("2.5 deg"),
+        // because UnitsProvider.getConversion reports the mismatch by returning the *identity*
+        // conversion tagged `error: true`. See buildFieldFormatterSpec in fieldSpecs.ts.
+        // Persisted on the element: lengthProp 2.5 m
+        const block = TextBlock.create();
+        const crossed = appendField(block, "lengthProp", { kindOfQuantity: "Example.ANGLE", persistenceUnit: "Units.M" });
+        const baseline = appendField(block, "lengthProp");
+        render(block, {
+            adopted: toFormatSet("Adopted", { "Example.ANGLE": decimalFormat("Units.ARC_DEG", "deg", 2) }),
+        });
+        expect(baseline.cachedContent).to.equal("2.5 m");
+        expect(crossed.cachedContent).to.equal("2.5 m");
+        // Stated as an equality too, so the test keeps meaning "fell back to the baseline" rather
+        // than "happens to equal this literal" if the seed value ever changes.
+        expect(crossed.cachedContent).to.equal(baseline.cachedContent); // both "2.5 m"
+    });
+    it("degrades only the offending field when applying a format throws", async () => {
+        // FormatterSpec.applyFormatting is a much larger exception surface than the `toString()` it
+        // replaced. A throw used to escape updateField and updateFields, get swallowed by
+        // doUpdateFields, and abandon the whole element -- earlier fields mutated in memory, nothing
+        // persisted, one log line as the only trace. It must degrade this field alone.
+        // Persisted on the element: lengthProp 2.5 m, areaProp 100 m², slopeProp 0.01 m/m
+        const block = TextBlock.create();
+        const before = appendField(block, "areaProp");
+        const thrower = appendField(block, "lengthProp");
+        const after = appendField(block, "slopeProp");
+        ElementDrivesTextAnnotation.registerFieldFormatting({ iModel: imodel });
+        const applyFormatting = sinon.stub(FormatterSpec.prototype, "applyFormatting");
+        applyFormatting.callsFake(function (magnitude) {
+            if (2.5 === magnitude)
+                throw new Error("malformed format");
+            return applyFormatting.wrappedMethod.call(this, magnitude);
+        });
+        expect(() => ElementDrivesTextAnnotation.evaluateFields({ iModel: imodel, block })).to.not.throw();
+        expect(thrower.cachedContent).to.equal(FieldRun.invalidContentIndicator); // "####"
+        // The fields on either side of the failure still resolved and still persisted.
+        expect(before.cachedContent).to.equal("100.0 m²");
+        expect(after.cachedContent).to.equal("0.01 m/m");
+    });
+});
+//# sourceMappingURL=FieldFormat.test.js.map