feat(unitpreferences): name the path override in resolved metadata

A resolved displayUnits response reads the same whether the target unit
came from the path or from the active preset, so a client editing the
metadata cannot tell one from the other, and one saving it back cannot
say which fields the path owns.

The response now carries an override object naming the target unit and
display format the path itself chose, empty when the path follows the
preset. A metadata PUT that carries it is taken at its word, which is a
plainer answer than reading an echo by its shape.

Author: mairas

docs/guides/unitpreferences.md

@@ -116,7 +116,8 @@ Request the metadata for any path:
     "formula": "value * 1.94384",
     "inverseFormula": "value / 1.94384",
     "symbol": "kn",
-    "displayFormat": "0.0"
+    "displayFormat": "0.0",
+    "override": {}
   }
 }
 ```
@@ -129,6 +130,7 @@ The `displayUnits` object provides everything you need to display the value:
 - **inverseFormula**: A Math.js expression to convert back from the display unit to SI (useful for user input).
 - **symbol**: The symbol to display next to the value.
 - **displayFormat**: (Optional) A format pattern for consistency (e.g., "0.0" for one decimal place).
+- **override**: The part of the answer the path itself chose rather than the active preset, as `targetUnit` and `displayFormat`. Empty when the path follows the preset. Display code can ignore this; an editor needs it to tell "knots because this path asks for knots" from "knots because the preset says so". A `PUT` of the whole object is read the same way, so saving a response back does not turn the preset's current choices into a path override.
 
 ### WebSocket Stream
 
@@ -173,7 +175,8 @@ ws.onopen = () => {
               "formula": "value * 1.94384",
               "inverseFormula": "value / 1.94384",
               "symbol": "kn",
-              "displayFormat": "0.0"
+              "displayFormat": "0.0",
+              "override": {}
             }
           }
         }

src/unitpreferences/resolver.ts

@@ -4,7 +4,32 @@ import {
   getActivePreset,
   getActivePresetForUser
 } from './loader'
-import { EnhancedDisplayUnits, DisplayUnitsMetadata } from './types'
+import {
+  EnhancedDisplayUnits,
+  DisplayUnitsMetadata,
+  DisplayUnitsOverride
+} from './types'
+
+/**
+ * What the path itself chose, as opposed to what the preset supplied.
+ *
+ * A response this server resolved carries that answer in its `override`
+ * field; anything else is the stored metadata, where every field present is
+ * the path's own.
+ */
+function pathOverride(
+  displayUnits: DisplayUnitsMetadata
+): DisplayUnitsOverride {
+  const owned = displayUnits.override ?? displayUnits
+  const override: DisplayUnitsOverride = {}
+  if (owned.targetUnit !== undefined) {
+    override.targetUnit = owned.targetUnit
+  }
+  if (owned.displayFormat !== undefined) {
+    override.displayFormat = owned.displayFormat
+  }
+  return override
+}
 
 /**
  * Given stored displayUnits metadata, resolve the full conversion info
@@ -24,6 +49,18 @@ export function resolveDisplayUnits(
   }
 
   const category = storedDisplayUnits.category
+  const override = pathOverride(storedDisplayUnits)
+  // Resolving a response this server already resolved is the same job as
+  // resolving the stored metadata it came from.
+  const stored: DisplayUnitsMetadata = storedDisplayUnits.override
+    ? {
+        category,
+        ...override,
+        formula: storedDisplayUnits.formula,
+        inverseFormula: storedDisplayUnits.inverseFormula,
+        symbol: storedDisplayUnits.symbol
+      }
+    : storedDisplayUnits
 
   // "base" category means display in SI units without conversion
   if (category === 'base') {
@@ -33,50 +70,54 @@ export function resolveDisplayUnits(
       formula: 'value',
       inverseFormula: 'value',
       symbol: pathSiUnit || '',
-      displayFormat: undefined
+      displayFormat: undefined,
+      override
     }
   }
 
   // "custom" category stores explicit conversion info
   if (category === 'custom') {
-    if (!storedDisplayUnits.targetUnit) {
+    if (!stored.targetUnit) {
       return null
     }
     // Identity conversion: targetUnit matches the path's SI unit
-    if (pathSiUnit && storedDisplayUnits.targetUnit === pathSiUnit) {
+    if (pathSiUnit && stored.targetUnit === pathSiUnit) {
       return {
         category: 'custom',
-        targetUnit: storedDisplayUnits.targetUnit,
+        targetUnit: stored.targetUnit,
         formula: 'value',
         inverseFormula: 'value',
-        symbol: storedDisplayUnits.symbol || storedDisplayUnits.targetUnit,
-        displayFormat: storedDisplayUnits.displayFormat
+        symbol: stored.symbol || stored.targetUnit,
+        displayFormat: stored.displayFormat,
+        override
       }
     }
     // If formula is stored, use it directly
-    if (storedDisplayUnits.formula) {
+    if (stored.formula) {
       return {
         category: 'custom',
-        targetUnit: storedDisplayUnits.targetUnit,
-        formula: storedDisplayUnits.formula,
-        inverseFormula: storedDisplayUnits.inverseFormula || '',
-        symbol: storedDisplayUnits.symbol || storedDisplayUnits.targetUnit,
-        displayFormat: storedDisplayUnits.displayFormat
+        targetUnit: stored.targetUnit,
+        formula: stored.formula,
+        inverseFormula: stored.inverseFormula || '',
+        symbol: stored.symbol || stored.targetUnit,
+        displayFormat: stored.displayFormat,
+        override
       }
     }
     // Otherwise look up from definitions using pathSiUnit
     if (pathSiUnit) {
       const definitions = getMergedDefinitions()
       const conversion =
-        definitions[pathSiUnit]?.conversions?.[storedDisplayUnits.targetUnit]
+        definitions[pathSiUnit]?.conversions?.[stored.targetUnit]
       if (conversion) {
         return {
           category: 'custom',
-          targetUnit: storedDisplayUnits.targetUnit,
+          targetUnit: stored.targetUnit,
           formula: conversion.formula,
           inverseFormula: conversion.inverseFormula,
-          symbol: conversion.symbol || storedDisplayUnits.targetUnit,
-          displayFormat: storedDisplayUnits.displayFormat
+          symbol: conversion.symbol || stored.targetUnit,
+          displayFormat: stored.displayFormat,
+          override
         }
       }
     }
@@ -96,8 +137,8 @@ export function resolveDisplayUnits(
   // Step 2: Determine target unit
   // Priority: path override > preset default
   let targetUnit: string
-  if (storedDisplayUnits.targetUnit) {
-    targetUnit = storedDisplayUnits.targetUnit
+  if (stored.targetUnit) {
+    targetUnit = stored.targetUnit
   } else if (preset?.categories?.[category]?.targetUnit) {
     targetUnit = preset.categories[category].targetUnit
   } else {
@@ -113,8 +154,8 @@ export function resolveDisplayUnits(
       inverseFormula: 'value',
       symbol: siUnit,
       displayFormat:
-        storedDisplayUnits.displayFormat ||
-        preset?.categories?.[category]?.displayFormat
+        stored.displayFormat || preset?.categories?.[category]?.displayFormat,
+      override
     }
   }
 
@@ -137,8 +178,8 @@ export function resolveDisplayUnits(
     inverseFormula: conversion.inverseFormula,
     symbol: conversion.symbol,
     displayFormat:
-      storedDisplayUnits.displayFormat ||
-      preset?.categories?.[category]?.displayFormat
+      stored.displayFormat || preset?.categories?.[category]?.displayFormat,
+    override
   }
 }
 
@@ -148,10 +189,11 @@ export function resolveDisplayUnits(
  * Clients read metadata back resolved — target unit, formulas and format
  * filled in from the active preset — so writing it back verbatim would store
  * the preset's current choices as a path override and detach the path from
- * the preset. The resolved shape carries a formula and the stored shape does
- * not, which is what tells an echo of the resolution apart from an override
- * the client states itself. In an echo, a value the preset would have
- * produced anyway is dropped unless the path already stored it.
+ * the preset. A resolved response names the path's own choices in its
+ * `override` field, which settles the question outright. A client that sends
+ * neither is read by shape: the resolved shape carries a formula and the
+ * stored shape does not, and in a formula-carrying echo a value the preset
+ * would have produced anyway is dropped unless the path already stored it.
  *
  * @param incoming - displayUnits as received in a metadata PUT
  * @param previous - displayUnits currently stored for the path
@@ -172,12 +214,17 @@ export function stripResolvedDisplayUnits(
   // A custom unit is nothing but its explicit conversion, and "base" needs
   // no conversion at all.
   if (category === 'custom') {
-    return incoming
+    const { override: _override, ...stored } = incoming
+    return stored
   }
   if (category === 'base') {
     return { category }
   }
 
+  if (incoming.override) {
+    return { category, ...incoming.override }
+  }
+
   const echoesResolution = incoming.formula !== undefined
   const preset = username ? getActivePresetForUser(username) : getActivePreset()
   const presetCategory = preset?.categories?.[category]

src/unitpreferences/types.ts

@@ -66,6 +66,14 @@ export interface DisplayUnitsMetadata {
   inverseFormula?: string // Only if custom category
   symbol?: string // Only if custom category
   displayFormat?: string // Only if path override
+  override?: DisplayUnitsOverride // Only on the way out, never stored
+}
+
+// The part of a resolved response the path itself chose, as opposed to the
+// part the active preset supplied. Empty when the path follows the preset.
+export interface DisplayUnitsOverride {
+  targetUnit?: string
+  displayFormat?: string
 }
 
 // What server returns in GET /meta response
@@ -76,4 +84,5 @@ export interface EnhancedDisplayUnits {
   inverseFormula: string
   symbol: string
   displayFormat?: string
+  override: DisplayUnitsOverride
 }

test/metadata-e2e.ts

@@ -250,6 +250,13 @@ describe('Display unit metadata', function () {
     await new Promise((resolve) => setTimeout(resolve, 200))
   }
 
+  const servedDisplayUnits = async (skPath = SPEED_PATH_SLASHES) => {
+    const meta = await fetch(`${v1Api}/vessels/self/${skPath}/meta`).then((r) =>
+      r.json()
+    )
+    return meta.displayUnits
+  }
+
   const storedDisplayUnits = (): DisplayUnitsMetadata | undefined => {
     const deltas = JSON.parse(
       fs.readFileSync(
@@ -341,6 +348,52 @@ describe('Display unit metadata', function () {
     expect(storedDisplayUnits()).to.deep.equal({ category: 'speed' })
   })
 
+  it('names the path override in the resolved metadata', async () => {
+    await putSpeedMeta({ category: 'speed', targetUnit: 'm/s' })
+    expect(await servedDisplayUnits()).to.include({
+      targetUnit: 'm/s',
+      symbol: 'm/s'
+    })
+    expect((await servedDisplayUnits()).override).to.deep.equal({
+      targetUnit: 'm/s'
+    })
+  })
+
+  it('leaves the override empty for a path that follows the preset', async () => {
+    const displayUnits = await servedDisplayUnits('navigation/speedOverGround')
+    expect(displayUnits.targetUnit).to.equal(PRESET_SPEED_UNIT)
+    expect(displayUnits.override).to.deep.equal({})
+  })
+
+  it('keeps the override a resolved response is saved back with', async () => {
+    await putSpeedMeta({
+      category: 'speed',
+      targetUnit: PRESET_SPEED_UNIT,
+      formula: 'value * 1.94384',
+      inverseFormula: 'value * 0.514444',
+      symbol: PRESET_SPEED_UNIT,
+      displayFormat: '0.0',
+      override: { targetUnit: PRESET_SPEED_UNIT }
+    })
+    expect(storedDisplayUnits()).to.deep.equal({
+      category: 'speed',
+      targetUnit: PRESET_SPEED_UNIT
+    })
+  })
+
+  it('drops what a resolved response says the path does not own', async () => {
+    await putSpeedMeta({
+      category: 'speed',
+      targetUnit: 'm/s',
+      formula: 'value',
+      inverseFormula: 'value',
+      symbol: 'm/s',
+      displayFormat: '0.0',
+      override: {}
+    })
+    expect(storedDisplayUnits()).to.deep.equal({ category: 'speed' })
+  })
+
   it('sends the resolved conversion to connected clients', async () => {
     const receiver = new WsPromiser(
       `ws://localhost:${port}/signalk/v1/stream?subscribe=self&sendMeta=all&sendCachedValues=false`,