form0-core 0.1.15 → 0.1.17

package/README.md

@@ -40,6 +40,29 @@ scope fields like `main_org_id`, and media or location settings. Operational cou
 application or API boundaries, not treated as engine-authored schema. A top-level
 `form.version` may still exist, but the engine does not bump or consume it.
 
+### Record-side contract
+
+`form0-core` intentionally uses two different choice-value shapes:
+
+- Live engine / renderer values use renderer shape:
+  - single / boolean: `{ choice, other }`
+  - multi: `{ choices, other }`
+- Structured records use canonical stored shape:
+  - single / boolean: `{ choice_value, other_value }`
+  - multi: `{ choices_value, other_value }`
+
+Record-side utilities follow this contract:
+
+- `createStructuredRecord()` outputs canonical stored records
+- `normalizeStructuredRecord()` consumes and returns canonical stored records
+- `buildFormRecordSnapshot()` consumes canonical stored records and returns renderer snapshot values
+- `projectDatasetRowValues()` consumes canonical stored rows
+- Choice `FIELD_SPECS` keep separate validators by context:
+  - `valueValidator` validates live engine / renderer values
+  - `recordValueValidator` validates canonical stored record values
+
+Record status remains top-level as `@status`; it is not stored inside `form_values`.
+
 ## Security
 
 See `SECURITY.md` for security modes and configuration.

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "form0-core",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "description": "Schema-driven engine that powers form0 ecosystem.",
+  "description": "Schema-driven engine that powers form0 ecosystem. Looking for the full form0 ecosystem? Install the CLI: `npm install -g form0-cli`",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
     "test": "node tests/form0-core.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/builtin-metadata.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/security-test.js",
-    "postinstall": "node scripts/postinstall.cjs",
     "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
     "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""
   },

package/scripts/{postinstall.cjs → legacy-postinstall-message.cjs}

@@ -1,3 +1,7 @@
+// Legacy reference only.
+// This script is intentionally not wired into package.json lifecycle hooks.
+// It is retained as a reference for the previous install-time guidance message.
+
 const PACKAGE_NAME = 'form0-core';
 
 const npmUserAgent = process.env.npm_config_user_agent || '';

package/src/index.js

@@ -6,6 +6,12 @@ export {
   buildFormRecordSnapshot,
 } from './utilities/structured-record.js';
 export { validateSchema } from './schema/schema-validator.js';
+export {
+  validateFieldValue,
+  validateRecordFieldValue,
+  getFieldValueValidator,
+  getRecordFieldValueValidator,
+} from './schema/field-value-registry.js';
 //export { validateSchema, resolveSupportingImagePath } from './schema/schema-validator.js';
 export { generateKey } from './utilities/hash.js';
 export {

package/src/schema/field-specs.js

@@ -1,4 +1,5 @@
 import { validateChoiceFieldChoices } from '../utilities/field-helpers.js';
+import { validateStoredChoiceValue } from '../utilities/choice-value-shapes.js';
 import {
   isNonEmptyString,
   validateFormLinkRecordDefaults,
@@ -316,6 +317,10 @@ export const FIELD_SPECS = {
       }
       return null;
     },
+    recordValueValidator: (field, value) =>
+      validateStoredChoiceValue(field, value, {
+        context: 'FIELD_SPECS.recordValueValidator',
+      }),
     defaultProducer: (field) => {
       if (field.default_value) {
         const choice = field.choices.find((c) => c.value === field.default_value);
@@ -466,6 +471,10 @@ export const FIELD_SPECS = {
       }
       return null;
     },
+    recordValueValidator: (field, value) =>
+      validateStoredChoiceValue(field, value, {
+        context: 'FIELD_SPECS.recordValueValidator',
+      }),
     defaultProducer: (field) => {
       if (field.default_value) {
         const selectedChoices = field.choices
@@ -596,6 +605,10 @@ export const FIELD_SPECS = {
       }
       return null;
     },
+    recordValueValidator: (field, value) =>
+      validateStoredChoiceValue(field, value, {
+        context: 'FIELD_SPECS.recordValueValidator',
+      }),
     defaultProducer: (field) => {
       if (field.default_value) {
         const choice = field.choices.find((c) => c.value === field.default_value);

package/src/schema/field-value-registry.js

@@ -19,6 +19,29 @@ export function validateFieldValue(field, value) {
   return null;
 }
 
+/**
+ * Validates a structured-record field value against its specification
+ * @param {object} field - The field definition
+ * @param {any} value - The stored record value to validate
+ * @returns {string|null} - Error message if validation fails, or null if valid
+ */
+export function validateRecordFieldValue(field, value) {
+  const spec = FIELD_SPECS[field.type];
+  if (!spec) {
+    return `Unsupported field type: ${field.type}`;
+  }
+
+  if (typeof spec.recordValueValidator === 'function') {
+    return spec.recordValueValidator(field, value);
+  }
+
+  if (typeof spec.valueValidator === 'function') {
+    return spec.valueValidator(field, value);
+  }
+
+  return null;
+}
+
 /**
  * Returns the value validator function for a field type
  * @param {string} fieldType - The field type
@@ -29,6 +52,25 @@ export function getFieldValueValidator(fieldType) {
   return spec ? spec.valueValidator : null;
 }
 
+/**
+ * Returns the structured-record value validator function for a field type
+ * Falls back to the live value validator when no record-specific validator exists.
+ * @param {string} fieldType - The field type
+ * @returns {function|null} - The record value validator function or null if not found
+ */
+export function getRecordFieldValueValidator(fieldType) {
+  const spec = FIELD_SPECS[fieldType];
+  if (!spec) {
+    return null;
+  }
+
+  if (typeof spec.recordValueValidator === 'function') {
+    return spec.recordValueValidator;
+  }
+
+  return typeof spec.valueValidator === 'function' ? spec.valueValidator : null;
+}
+
 /**
  * Validates TextField value
  * @param {object} field - The field definition

package/src/utilities/choice-value-shapes.js

@@ -0,0 +1,318 @@
+const SINGLE_CHOICE_TYPES = new Set(['SingleChoiceField', 'BooleanField']);
+const MULTI_CHOICE_TYPES = new Set(['MultiChoiceField']);
+const RENDERER_ALIAS_KEYS = ['choice', 'choices', 'other'];
+
+const isRecordObject = (value) =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const cloneJson = (value) => {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+};
+
+const trimString = (value) => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const isChoicePrimitive = (value) =>
+  typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+
+const normalizeChoiceLabel = (value) => {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+
+  return isChoicePrimitive(value) ? value : null;
+};
+
+const toFieldType = (field) => trimString(field?.type) ?? trimString(field?.field_type);
+
+const toFieldIdentifier = (field) =>
+  trimString(field?.data_name) ??
+  trimString(field?.output_key) ??
+  trimString(field?.key) ??
+  trimString(field?.field_id) ??
+  trimString(field?.label) ??
+  'choice field';
+
+const getChoiceKind = (field) => {
+  const fieldType = toFieldType(field);
+  if (SINGLE_CHOICE_TYPES.has(fieldType)) {
+    return 'single';
+  }
+
+  if (MULTI_CHOICE_TYPES.has(fieldType)) {
+    return 'multi';
+  }
+
+  return null;
+};
+
+const getCanonicalSelectionKey = (field) =>
+  getChoiceKind(field) === 'multi' ? 'choices_value' : 'choice_value';
+
+const createChoiceShapeError = (context, field, message) => {
+  const prefix = trimString(context) ?? 'record-side choice utilities';
+  return new Error(`[form0] ${prefix}: field "${toFieldIdentifier(field)}" ${message}`);
+};
+
+const assertCanonicalChoiceShape = (field, rawValue, context) => {
+  if (rawValue === null || typeof rawValue === 'undefined') {
+    return;
+  }
+
+  if (!isRecordObject(rawValue)) {
+    throw createChoiceShapeError(
+      context,
+      field,
+      'must be a canonical stored object using *_value arrays'
+    );
+  }
+
+  const rendererKeys = RENDERER_ALIAS_KEYS.filter((key) =>
+    Object.prototype.hasOwnProperty.call(rawValue, key)
+  );
+  if (rendererKeys.length > 0) {
+    throw createChoiceShapeError(
+      context,
+      field,
+      `must not use renderer keys (${rendererKeys.join(', ')})`
+    );
+  }
+
+  const kind = getChoiceKind(field);
+  if (kind === 'single' && Object.prototype.hasOwnProperty.call(rawValue, 'choices_value')) {
+    throw createChoiceShapeError(
+      context,
+      field,
+      'must use "choice_value" instead of "choices_value"'
+    );
+  }
+
+  if (kind === 'multi' && Object.prototype.hasOwnProperty.call(rawValue, 'choice_value')) {
+    throw createChoiceShapeError(
+      context,
+      field,
+      'must use "choices_value" instead of "choice_value"'
+    );
+  }
+};
+
+const resolveSchemaChoice = (field, rawValue) => {
+  if (!Array.isArray(field?.choices)) {
+    return null;
+  }
+
+  return (
+    field.choices.find(
+      (choice) =>
+        isRecordObject(choice) &&
+        Object.prototype.hasOwnProperty.call(choice, 'value') &&
+        choice.value === rawValue
+    ) ?? null
+  );
+};
+
+const normalizeStoredSelectedEntry = (field, entry, context) => {
+  if (!isRecordObject(entry)) {
+    throw createChoiceShapeError(context, field, 'must store selected entries as objects');
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(entry, 'value')) {
+    throw createChoiceShapeError(context, field, 'must store selected entries with a "value"');
+  }
+
+  const matchedChoice = resolveSchemaChoice(field, entry.value);
+  const resolvedLabel = matchedChoice
+    ? (normalizeChoiceLabel(matchedChoice.label) ?? entry.value)
+    : (normalizeChoiceLabel(entry.label) ?? entry.value);
+
+  return {
+    ...entry,
+    value: entry.value,
+    label: resolvedLabel,
+  };
+};
+
+const normalizeStoredOtherEntry = (field, entry, context) => {
+  if (!isRecordObject(entry)) {
+    throw createChoiceShapeError(context, field, 'must store other entries as objects');
+  }
+
+  const hasPrimitiveValue = isChoicePrimitive(entry.value);
+  const normalizedLabel = normalizeChoiceLabel(entry.label);
+
+  if (!hasPrimitiveValue && normalizedLabel === null) {
+    throw createChoiceShapeError(
+      context,
+      field,
+      'must store other entries with a primitive "label" or "value"'
+    );
+  }
+
+  return {
+    ...entry,
+    ...(hasPrimitiveValue ? { value: entry.value } : {}),
+    label: normalizedLabel ?? entry.value,
+  };
+};
+
+const normalizeChoiceEntryArray = (field, entries, normalizer, context, keyName) => {
+  if (typeof entries === 'undefined') {
+    return [];
+  }
+
+  if (!Array.isArray(entries)) {
+    throw createChoiceShapeError(context, field, `"${keyName}" must be an array`);
+  }
+
+  return entries.map((entry) => normalizer(field, entry, context));
+};
+
+export function isChoiceFieldLike(field) {
+  return getChoiceKind(field) !== null;
+}
+
+export function normalizeStoredChoiceValue(field, rawValue, options = {}) {
+  const context = options.context;
+  const kind = getChoiceKind(field);
+
+  if (!kind || rawValue === null || typeof rawValue === 'undefined') {
+    return rawValue;
+  }
+
+  assertCanonicalChoiceShape(field, rawValue, context);
+
+  const selectionKey = getCanonicalSelectionKey(field);
+  const normalized = {
+    ...rawValue,
+    [selectionKey]: normalizeChoiceEntryArray(
+      field,
+      rawValue[selectionKey],
+      normalizeStoredSelectedEntry,
+      context,
+      selectionKey
+    ),
+    other_value: normalizeChoiceEntryArray(
+      field,
+      rawValue.other_value,
+      normalizeStoredOtherEntry,
+      context,
+      'other_value'
+    ),
+  };
+
+  return normalized;
+}
+
+export function validateStoredChoiceValue(field, rawValue, options = {}) {
+  try {
+    const normalized = normalizeStoredChoiceValue(field, rawValue, options);
+    const kind = getChoiceKind(field);
+    const fieldIdentifier = toFieldIdentifier(field);
+
+    if (normalized && kind === 'single' && toFieldType(field) === 'BooleanField') {
+      if (normalized.other_value.length > 0) {
+        return `${fieldIdentifier} does not support 'other_value' values`;
+      }
+    }
+
+    if (normalized && kind !== null && toFieldType(field) !== 'BooleanField') {
+      if (field.allow_other !== true && normalized.other_value.length > 0) {
+        return `${fieldIdentifier} does not allow 'other_value' values`;
+      }
+    }
+
+    return null;
+  } catch (error) {
+    if (error instanceof Error) {
+      return error.message.replace(/^\[form0\] [^:]+: /, '');
+    }
+
+    return 'stored choice value is invalid';
+  }
+}
+
+export function toRendererChoiceValue(field, rawValue, options = {}) {
+  const kind = getChoiceKind(field);
+  if (!kind || rawValue === null || typeof rawValue === 'undefined') {
+    return rawValue;
+  }
+
+  const normalized = normalizeStoredChoiceValue(field, rawValue, options);
+  const selectionKey = getCanonicalSelectionKey(field);
+
+  if (kind === 'multi') {
+    return {
+      choices: cloneJson(normalized[selectionKey]),
+      other: cloneJson(normalized.other_value),
+    };
+  }
+
+  return {
+    choice: cloneJson(normalized[selectionKey]),
+    other: cloneJson(normalized.other_value),
+  };
+}
+
+export function readStoredChoiceSelectionValues(field, rawValue, options = {}) {
+  const kind = getChoiceKind(field);
+  if (!kind) {
+    return [];
+  }
+
+  const normalized = normalizeStoredChoiceValue(field, rawValue, options);
+  if (normalized === null || typeof normalized === 'undefined') {
+    return [];
+  }
+
+  const selectionKey = getCanonicalSelectionKey(field);
+  const selectedValues = normalized[selectionKey]
+    .map((entry) => entry.value)
+    .filter((entry) => typeof entry !== 'undefined');
+  const otherValues = normalized.other_value
+    .map((entry) =>
+      isChoicePrimitive(entry.value) ? entry.value : normalizeChoiceLabel(entry.label)
+    )
+    .filter((entry) => typeof entry !== 'undefined' && entry !== null);
+
+  return [...selectedValues, ...otherValues];
+}
+
+export function readStoredChoiceDisplayValues(field, rawValue, options = {}) {
+  const kind = getChoiceKind(field);
+  if (!kind) {
+    return [];
+  }
+
+  const normalized = normalizeStoredChoiceValue(field, rawValue, options);
+  if (normalized === null || typeof normalized === 'undefined') {
+    return [];
+  }
+
+  const selectionKey = getCanonicalSelectionKey(field);
+  const selectedLabels = normalized[selectionKey]
+    .map(
+      (entry) =>
+        normalizeChoiceLabel(entry.label) ??
+        (isChoicePrimitive(entry.value) ? entry.value : undefined)
+    )
+    .filter((entry) => typeof entry !== 'undefined' && entry !== null);
+  const otherLabels = normalized.other_value
+    .map(
+      (entry) =>
+        normalizeChoiceLabel(entry.label) ??
+        (isChoicePrimitive(entry.value) ? entry.value : undefined)
+    )
+    .filter((entry) => typeof entry !== 'undefined' && entry !== null);
+
+  return [...selectedLabels, ...otherLabels];
+}

package/src/utilities/dataset-descriptors.js

@@ -1,10 +1,13 @@
 import { flattenFields } from './field-helpers.js';
+import {
+  readStoredChoiceDisplayValues,
+  readStoredChoiceSelectionValues,
+} from './choice-value-shapes.js';
 
 const ROOT_DATASET_ID = '__root__';
 const CONTAINER_TYPES = new Set(['Section', 'BuildingPlanSection']);
 
-const isRecord = (value) =>
-  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 
 const toTrimmedString = (value) => {
   if (typeof value !== 'string') {
@@ -57,11 +60,9 @@ const uniqueAliases = (...values) => {
   return aliases;
 };
 
-const toFieldId = (field) =>
-  toTrimmedString(field?.key) ?? toTrimmedString(field?.data_name);
+const toFieldId = (field) => toTrimmedString(field?.key) ?? toTrimmedString(field?.data_name);
 
-const toOutputKey = (field) =>
-  toTrimmedString(field?.data_name) ?? toTrimmedString(field?.key);
+const toOutputKey = (field) => toTrimmedString(field?.data_name) ?? toTrimmedString(field?.key);
 
 const toFieldLabel = (field) =>
   toTrimmedString(field?.label) ??
@@ -343,173 +344,10 @@ export function getFieldQuerySemantics(field) {
   return { ...semantics };
 }
 
-const toChoiceValueList = (field) => {
-  if (!Array.isArray(field?.choices)) {
-    return [];
-  }
-
-  return field.choices.filter((choice) => isRecord(choice));
-};
-
-const isChoicePrimitive = (value) =>
-  typeof value === 'string' ||
-  typeof value === 'number' ||
-  typeof value === 'boolean';
-
-const normalizeChoiceEntryValue = (entry) => {
-  if (isChoicePrimitive(entry)) {
-    return entry;
-  }
-
-  if (!isRecord(entry)) {
-    return undefined;
-  }
-
-  if (isChoicePrimitive(entry.value)) {
-    return entry.value;
-  }
-
-  if (isChoicePrimitive(entry.label)) {
-    return entry.label;
-  }
-
-  return undefined;
-};
-
-const normalizeChoiceEntryDisplayValue = (entry) => {
-  if (isChoicePrimitive(entry)) {
-    return entry;
-  }
-
-  if (!isRecord(entry)) {
-    return undefined;
-  }
-
-  if (isChoicePrimitive(entry.label)) {
-    return entry.label;
-  }
-
-  if (isChoicePrimitive(entry.value)) {
-    return entry.value;
-  }
-
-  return undefined;
-};
-
-const normalizeChoiceEntryLabel = (field, entry) => {
-  const normalizedValue = normalizeChoiceEntryValue(entry);
-  if (typeof normalizedValue === 'undefined') {
-    return undefined;
-  }
-
-  const matched = toChoiceValueList(field).find(
-    (choice) =>
-      Object.prototype.hasOwnProperty.call(choice, 'value') &&
-      choice.value === normalizedValue,
-  );
-  if (matched) {
-    return toTrimmedString(matched.label) ?? normalizedValue;
-  }
-
-  if (isRecord(entry) && isChoicePrimitive(entry.label)) {
-    return entry.label;
-  }
-
-  return normalizedValue;
-};
-
-const toSingleChoiceSelectionValues = (rawValue) => {
-  if (isRecord(rawValue)) {
-    const choiceValues = Array.isArray(rawValue.choice)
-      ? rawValue.choice
-          .map((entry) => normalizeChoiceEntryValue(entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-    const otherValues = Array.isArray(rawValue.other)
-      ? rawValue.other
-          .map((entry) => normalizeChoiceEntryValue(entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-
-    return [...choiceValues, ...otherValues];
-  }
-
-  const normalized = normalizeChoiceEntryValue(rawValue);
-  return typeof normalized === 'undefined' ? [] : [normalized];
-};
-
-const toSingleChoiceDisplayValues = (field, rawValue) => {
-  if (isRecord(rawValue)) {
-    const choiceLabels = Array.isArray(rawValue.choice)
-      ? rawValue.choice
-          .map((entry) => normalizeChoiceEntryLabel(field, entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-    const otherLabels = Array.isArray(rawValue.other)
-      ? rawValue.other
-          .map((entry) => normalizeChoiceEntryDisplayValue(entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-
-    return [...choiceLabels, ...otherLabels];
-  }
-
-  const normalized = normalizeChoiceEntryLabel(field, rawValue);
-  return typeof normalized === 'undefined' ? [] : [normalized];
-};
-
-const toMultiChoiceSelectionValues = (rawValue) => {
-  if (isRecord(rawValue)) {
-    const selectedValues = Array.isArray(rawValue.choices)
-      ? rawValue.choices
-          .map((entry) => normalizeChoiceEntryValue(entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-    const otherValues = Array.isArray(rawValue.other)
-      ? rawValue.other
-          .map((entry) => normalizeChoiceEntryValue(entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-
-    return [...selectedValues, ...otherValues];
-  }
-
-  if (Array.isArray(rawValue)) {
-    return rawValue
-      .map((entry) => normalizeChoiceEntryValue(entry))
-      .filter((entry) => typeof entry !== 'undefined');
-  }
-
-  return [];
-};
-
-const toMultiChoiceDisplayValues = (field, rawValue) => {
-  if (isRecord(rawValue)) {
-    const selectedLabels = Array.isArray(rawValue.choices)
-      ? rawValue.choices
-          .map((entry) => normalizeChoiceEntryLabel(field, entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-    const otherLabels = Array.isArray(rawValue.other)
-      ? rawValue.other
-          .map((entry) => normalizeChoiceEntryDisplayValue(entry))
-          .filter((entry) => typeof entry !== 'undefined')
-      : [];
-
-    return [...selectedLabels, ...otherLabels];
-  }
-
-  if (Array.isArray(rawValue)) {
-    return rawValue
-      .map((entry) => normalizeChoiceEntryLabel(field, entry))
-      .filter((entry) => typeof entry !== 'undefined');
-  }
-
-  return [];
-};
-
 const toSingleChoiceLabel = (field, rawValue) => {
-  const labels = toSingleChoiceDisplayValues(field, rawValue);
+  const labels = readStoredChoiceDisplayValues(field, rawValue, {
+    context: 'projectDatasetRowValues',
+  });
   if (labels.length === 0) {
     return rawValue;
   }
@@ -518,7 +356,9 @@ const toSingleChoiceLabel = (field, rawValue) => {
 };
 
 const toMultiChoiceLabels = (field, rawValue) => {
-  const labels = toMultiChoiceDisplayValues(field, rawValue);
+  const labels = readStoredChoiceDisplayValues(field, rawValue, {
+    context: 'projectDatasetRowValues',
+  });
   if (labels.length === 0) {
     return rawValue;
   }
@@ -645,7 +485,7 @@ const collectRepeatableDatasets = (elements, context, datasets) => {
         repeatable_output_path: descriptor.repeatable_output_path,
         parent_dataset_id: descriptor.id,
       },
-      datasets,
+      datasets
     );
   });
 };
@@ -681,7 +521,7 @@ export function buildDatasetDescriptors(schema) {
       repeatable_output_path: [],
       parent_dataset_id: ROOT_DATASET_ID,
     },
-    datasets,
+    datasets
   );
 
   return datasets;
@@ -702,11 +542,10 @@ const readFirstAliasValue = (value, aliases) => {
 };
 
 const normalizeScalarValue = (field, value) => {
-  if (
-    field?.field_type === 'SingleChoiceField' ||
-    field?.field_type === 'BooleanField'
-  ) {
-    return toSingleChoiceSelectionValues(value)[0];
+  if (field?.field_type === 'SingleChoiceField' || field?.field_type === 'BooleanField') {
+    return readStoredChoiceSelectionValues(field, value, {
+      context: 'projectDatasetRowValues',
+    })[0];
   }
 
   if (Array.isArray(value)) {
@@ -725,7 +564,9 @@ const normalizeScalarValue = (field, value) => {
 
 const normalizeTermValues = (field, value) => {
   if (field?.field_type === 'MultiChoiceField') {
-    return toMultiChoiceSelectionValues(value);
+    return readStoredChoiceSelectionValues(field, value, {
+      context: 'projectDatasetRowValues',
+    });
   }
 
   if (!Array.isArray(value)) {
@@ -733,13 +574,14 @@ const normalizeTermValues = (field, value) => {
   }
 
   return value.filter(
-    (entry) =>
-      typeof entry === 'string' ||
-      typeof entry === 'number' ||
-      typeof entry === 'boolean',
+    (entry) => typeof entry === 'string' || typeof entry === 'number' || typeof entry === 'boolean'
   );
 };
 
+/**
+ * Project a canonical stored row into dataset display/scalar/term values.
+ * Choice fields must already use the stored `*_value` record shape.
+ */
 export function projectDatasetRowValues(descriptor, rowValues) {
   const sourceRecord = isRecord(rowValues) ? rowValues : {};
   const source =

package/src/utilities/structured-record.js

@@ -4,6 +4,11 @@ import {
   buildFieldIdentityMap,
   projectDatasetRowValues,
 } from './dataset-descriptors.js';
+import {
+  isChoiceFieldLike,
+  normalizeStoredChoiceValue,
+  toRendererChoiceValue,
+} from './choice-value-shapes.js';
 
 const CONTAINER_TYPES = new Set(['Section', 'BuildingPlanSection']);
 const TIMESTAMP_KEYS = [
@@ -131,102 +136,6 @@ const buildScopeFromElements = (elements) => {
   return scope;
 };
 
-const resolveChoiceLabel = (field, rawValue, fallbackLabel) => {
-  const normalizedValue = trimString(rawValue);
-  if (!normalizedValue) {
-    return fallbackLabel ?? null;
-  }
-
-  if (Array.isArray(field?.choices)) {
-    const matched = field.choices.find(
-      (choice) =>
-        isRecordObject(choice) &&
-        Object.prototype.hasOwnProperty.call(choice, 'value') &&
-        choice.value === normalizedValue
-    );
-    if (matched) {
-      return trimString(matched.label) ?? normalizedValue;
-    }
-  }
-
-  return fallbackLabel ?? normalizedValue;
-};
-
-const normalizeChoiceEntry = (field, entry) => {
-  if (!isRecordObject(entry)) {
-    return entry;
-  }
-
-  const rawValue = trimString(entry.value) ?? trimString(entry.label) ?? trimString(entry.id);
-  if (!rawValue) {
-    return { ...entry };
-  }
-
-  return {
-    ...entry,
-    value: rawValue,
-    label: resolveChoiceLabel(field, rawValue, trimString(entry.label)),
-  };
-};
-
-const normalizeChoiceList = (field, entries) => {
-  if (!Array.isArray(entries)) {
-    return entries;
-  }
-
-  return entries.map((entry) => normalizeChoiceEntry(field, entry));
-};
-
-const normalizeChoiceStructuredValue = (field, rawValue) => {
-  if (!isRecordObject(rawValue)) {
-    return rawValue;
-  }
-
-  const normalized = { ...rawValue };
-
-  if (field?.type === 'SingleChoiceField' || field?.type === 'BooleanField') {
-    if (Array.isArray(rawValue.choice_value)) {
-      normalized.choice_value = normalizeChoiceList(field, rawValue.choice_value);
-    }
-    if (Array.isArray(rawValue.choice)) {
-      normalized.choice = normalizeChoiceList(field, rawValue.choice);
-    }
-    if (Array.isArray(rawValue.other_value)) {
-      normalized.other_value = rawValue.other_value.map((entry) =>
-        isRecordObject(entry) ? { ...entry } : entry
-      );
-    }
-    if (Array.isArray(rawValue.other)) {
-      normalized.other = rawValue.other.map((entry) =>
-        isRecordObject(entry) ? { ...entry } : entry
-      );
-    }
-    return normalized;
-  }
-
-  if (field?.type === 'MultiChoiceField') {
-    if (Array.isArray(rawValue.choices_value)) {
-      normalized.choices_value = normalizeChoiceList(field, rawValue.choices_value);
-    }
-    if (Array.isArray(rawValue.choices)) {
-      normalized.choices = normalizeChoiceList(field, rawValue.choices);
-    }
-    if (Array.isArray(rawValue.other_value)) {
-      normalized.other_value = rawValue.other_value.map((entry) =>
-        isRecordObject(entry) ? { ...entry } : entry
-      );
-    }
-    if (Array.isArray(rawValue.other)) {
-      normalized.other = rawValue.other.map((entry) =>
-        isRecordObject(entry) ? { ...entry } : entry
-      );
-    }
-    return normalized;
-  }
-
-  return normalized;
-};
-
 const buildFieldReferenceMap = (schema) => {
   const identityMap = buildFieldIdentityMap(schema);
   const references = new Map();
@@ -323,12 +232,10 @@ const normalizeRecordScope = (record, scope) => {
       return;
     }
 
-    if (
-      field.field?.type === 'SingleChoiceField' ||
-      field.field?.type === 'BooleanField' ||
-      field.field?.type === 'MultiChoiceField'
-    ) {
-      formValues[entry.key] = normalizeChoiceStructuredValue(field.field, entry.value);
+    if (isChoiceFieldLike(field.field)) {
+      formValues[entry.key] = normalizeStoredChoiceValue(field.field, entry.value, {
+        context: 'normalizeStructuredRecord',
+      });
     }
   });
 
@@ -363,7 +270,11 @@ const buildSnapshotState = (formValues, scope) => {
       return;
     }
 
-    rawValues[field.dataName] = cloneJson(entry.value);
+    rawValues[field.dataName] = isChoiceFieldLike(field.field)
+      ? toRendererChoiceValue(field.field, entry.value, {
+          context: 'buildFormRecordSnapshot',
+        })
+      : cloneJson(entry.value);
   });
 
   scope.repeatables.forEach((repeatableField) => {
@@ -436,6 +347,10 @@ const extractSnapshotTimestamps = (record) => ({
   updated_at_server: toNullableString(record?.updated_at_server) ?? null,
 });
 
+/**
+ * Normalize a canonical stored record for downstream record-side consumers.
+ * Renderer/live aliases are rejected; known choice labels are refreshed from the supplied schema.
+ */
 export function normalizeStructuredRecord(schema, record, options = {}) {
   const normalized = isRecordObject(record) ? cloneJson(record) : {};
   const mode = trimString(options.mode) ?? 'derived';
@@ -456,6 +371,10 @@ export function normalizeStructuredRecord(schema, record, options = {}) {
   return normalized;
 }
 
+/**
+ * Build a renderer snapshot from a canonical stored record.
+ * Choice fields are converted back to renderer/live shape while record metadata stays top-level.
+ */
 export function buildFormRecordSnapshot(schema, record, options = {}) {
   const normalizedRecord = normalizeStructuredRecord(schema, record, {
     mode: 'derived',