form0-core 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025-present paqu.io
+Copyright (c) 2025-present paqu technologies
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -81,15 +81,6 @@ console.log(engine.getState());
 The engine API exposes `eval()` for calculations, conditions, and validation; `trigger()` for form
 events; and `getState()` for current values and evaluated field state.
 
-## 🔒 Security
-
-> [!CAUTION]
-> Schema expressions and event scripts execute JavaScript. Only evaluate schemas from authors you
-> trust. `SAFE` and `CUSTOM` modes provide validation controls; they are not security sandboxes.
-
-Read the [security policy](./SECURITY.md) before evaluating schemas outside a fully trusted
-authoring workflow.
-
 ## Schema and record ownership
 
 `form0-core` owns behavioral schema concerns such as fields, conditions, calculations, events, and
@@ -129,6 +120,15 @@ Record status remains top-level as `@status`; it is not stored inside `form_valu
 - [Core concepts](https://docs.form0.dev/core/concepts)
 - [Full documentation](https://docs.form0.dev)
 
+## 🔒 Security
+
+> [!CAUTION]
+> Schema expressions and event scripts execute JavaScript. Only evaluate schemas from authors you
+> trust. `SAFE` and `CUSTOM` modes provide validation controls; they are not security sandboxes.
+
+Read the [security policy](./SECURITY.md) before evaluating schemas outside a fully trusted
+authoring workflow.
+
 ## 🔗 Related repositories
 
 - [form0-cli](https://github.com/paqu-io/form0-cli) — recommended project entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -12,7 +12,7 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/numeric-field-schema.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/title-fields.test.js && node tests/builtin-metadata.test.js && node tests/calculation-expression-utils.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/numeric-field-schema.test.js && node tests/dataset-descriptors.test.js && node tests/structured-record.test.js && node tests/title-fields.test.js && node tests/builtin-metadata.test.js && node tests/calculation-expression-utils.test.js && node tests/calculation-editor.test.js && node tests/form-event-editor.test.js && node tests/form-authoring.test.js && node tests/security-test.js",
     "format": "prettier --write \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "format:check": "prettier --check \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "lint:check": "eslint src tests",
@@ -43,7 +43,7 @@
     "headless-forms",
     "framework-agnostic"
   ],
-  "author": "paqu.io <hello@paqu.io> (https://paqu.io/)",
+  "author": "paqu technologies <hello@paqu.io> (https://paqu.io/)",
   "contributors": [
     {
       "name": "aragornii"

package/src/authoring/form-authoring.js

@@ -0,0 +1,583 @@
+import { FIELD_SPECS } from '../schema/field-specs.js';
+import { getValidOperators } from '../schema/operators.js';
+import { validateSchema } from '../schema/schema-validator.js';
+import { getAllEventTypes } from '../engine/event-registry.js';
+import { generateKey } from '../utilities/hash.js';
+import { flattenFields } from '../utilities/field-helpers.js';
+import {
+  analyzeCalculationExpression,
+  getCalculationBuiltinCatalog,
+  getCalculationReferenceCatalog,
+} from '../utilities/calculation-editor.js';
+import {
+  analyzeFormEventCode,
+  getFormEventBuiltinCatalog,
+  getFormEventReferenceCatalog,
+} from '../utilities/form-event-editor.js';
+
+const CONTAINER_TYPES = new Set(['Section', 'RepeatableSection', 'BuildingPlanSection']);
+const MUTATION_OPERATIONS = Object.freeze([
+  'updateForm',
+  'addField',
+  'updateField',
+  'moveField',
+  'removeField',
+  'setTitleField',
+  'setStatusField',
+  'setCalculation',
+  'setFormEventCode',
+]);
+
+const CALCULATION_GUIDANCE = Object.freeze({
+  version: 1,
+  preferenceOrder: Object.freeze([
+    'direct-expression',
+    'builtin-expression',
+    'multiline-javascript',
+  ]),
+  multilineResult: Object.freeze({
+    builtin: 'SETRESULT',
+    requiredCalls: 1,
+    placement: 'final-statement',
+  }),
+  nonPreferredPatterns: Object.freeze(['iife']),
+  examples: Object.freeze({
+    direct: '$quantity * $unit_price',
+    builtin: 'IF($eligible, $amount, 0)',
+    multiline: `let age = null;
+if ($birth_date) {
+  const birth = new Date($birth_date);
+  const today = new Date();
+  age = today.getFullYear() - birth.getFullYear();
+  const month = today.getMonth() - birth.getMonth();
+  if (month < 0 || (month === 0 && today.getDate() < birth.getDate())) age--;
+}
+SETRESULT(age);`,
+  }),
+});
+
+const EVENT_GUIDANCE = Object.freeze({
+  version: 1,
+  choiceValues: Object.freeze({
+    single: Object.freeze({
+      fieldTypes: Object.freeze(['SingleChoiceField', 'BooleanField']),
+      builtin: 'CHOICEVALUE',
+    }),
+    multiple: Object.freeze({
+      fieldTypes: Object.freeze(['MultiChoiceField']),
+      builtin: 'CHOICEVALUES',
+    }),
+  }),
+  conditionalMappings: Object.freeze({
+    explicitNamedCases: true,
+    explicitFallback: true,
+  }),
+  examples: Object.freeze({
+    singleChoiceComparison: "CHOICEVALUE($birth_town) === 'loreto'",
+    multipleChoiceComparison: "CHOICEVALUES($interests).includes('music')",
+    conditionalChoiceMapping: `ON('change', 'birth_town', function () {
+  SETVALUE(
+    'comments',
+    IF(
+      CHOICEVALUE($birth_town) === 'loreto',
+      'Hooola!',
+      IF(CHOICEVALUE($birth_town) === 'recanati', 'Ciaooo', '')
+    )
+  );
+});`,
+  }),
+});
+
+function deepClone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function normalizeRootSchema(schema) {
+  if (schema && schema.form && Array.isArray(schema.form.elements)) {
+    return schema;
+  }
+  if (schema && Array.isArray(schema.elements)) {
+    return { form: schema };
+  }
+  throw new Error('Expected a root schema containing form.elements or a form schema');
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, stableValue(value[key])])
+  );
+}
+
+function fnv1a64(input) {
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= BigInt(input.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, '0');
+}
+
+function toSerializable(value) {
+  if (Array.isArray(value)) return value.map(toSerializable);
+  if (!value || typeof value !== 'object') return typeof value === 'function' ? undefined : value;
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const serialized = toSerializable(entry);
+    if (serialized !== undefined) result[key] = serialized;
+  }
+  return result;
+}
+
+function indexFields(elements) {
+  const byKey = new Map();
+  function visit(list, parentKey = null) {
+    if (!Array.isArray(list)) return;
+    list.forEach((field, index) => {
+      if (field?.key) byKey.set(field.key, { field, list, index, parentKey });
+      if (CONTAINER_TYPES.has(field?.type)) visit(field.elements, field.key || null);
+    });
+  }
+  visit(elements);
+  return byKey;
+}
+
+function ensureFieldKeys(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    throw new Error('Field must be an object');
+  }
+  if (!field.key && field.data_name) field.key = generateKey(field.data_name);
+  if (CONTAINER_TYPES.has(field.type)) {
+    if (!Array.isArray(field.elements)) field.elements = [];
+    field.elements.forEach(ensureFieldKeys);
+  }
+  return field;
+}
+
+function getInsertionPoint(form, parentKey, position = {}) {
+  let list = form.elements;
+  if (parentKey) {
+    const parent = indexFields(form.elements).get(parentKey)?.field;
+    if (!parent || !CONTAINER_TYPES.has(parent.type)) {
+      throw new Error(`Parent field '${parentKey}' is not a container`);
+    }
+    if (!Array.isArray(parent.elements)) parent.elements = [];
+    list = parent.elements;
+  }
+
+  if (position.beforeKey || position.afterKey) {
+    const siblingKey = position.beforeKey || position.afterKey;
+    const index = list.findIndex((field) => field?.key === siblingKey);
+    if (index === -1) throw new Error(`Sibling field '${siblingKey}' was not found in the target`);
+    return { list, index: position.beforeKey ? index : index + 1 };
+  }
+  return { list, index: list.length };
+}
+
+function updateConditionReferences(value, oldValues, replacement) {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => updateConditionReferences(entry, oldValues, replacement));
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  if (value.type === 'TitleField' && Array.isArray(value.elements)) {
+    value.elements = value.elements.map((entry) => (oldValues.has(entry) ? replacement : entry));
+  }
+  for (const key of ['field_id', 'field_key', 'destination_field_id', 'form_link_field_key']) {
+    if (oldValues.has(value[key])) value[key] = replacement;
+  }
+  Object.values(value).forEach((entry) => updateConditionReferences(entry, oldValues, replacement));
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function replaceCodeReferences(code, oldKey, oldDataName, newKey, newDataName) {
+  if (typeof code !== 'string') return code;
+  let updated = code.replace(
+    new RegExp(`\\$${escapeRegExp(oldDataName)}(?![A-Za-z0-9_])`, 'g'),
+    `$${newDataName}`
+  );
+  const replacements = [
+    { name: oldDataName, replacement: newDataName },
+    { name: oldKey, replacement: newKey },
+  ].filter(({ name }) => typeof name === 'string' && name.length > 0);
+  for (const { name, replacement } of replacements) {
+    const escaped = escapeRegExp(name);
+    updated = updated.replace(
+      new RegExp(`((?:ON|OFF)\\(\\s*['\"][^'\"]+['\"]\\s*,\\s*)(['\"])${escaped}\\2`, 'g'),
+      `$1$2${replacement}$2`
+    );
+    updated = updated.replace(
+      new RegExp(`((?:SETVALUE)\\(\\s*)(['\"])${escaped}\\2`, 'g'),
+      `$1$2${replacement}$2`
+    );
+  }
+  return updated;
+}
+
+function renameReferences(form, oldField, newField) {
+  const oldValues = new Set([oldField.key, oldField.data_name].filter(Boolean));
+  updateConditionReferences(form, oldValues, newField.key);
+  for (const field of flattenFields(form.elements)) {
+    if (field.type === 'CalculatedField') {
+      field.calculate = replaceCodeReferences(
+        field.calculate,
+        oldField.key,
+        oldField.data_name,
+        newField.key,
+        newField.data_name
+      );
+    }
+  }
+  if (form.events?.code) {
+    form.events.code = replaceCodeReferences(
+      form.events.code,
+      oldField.key,
+      oldField.data_name,
+      newField.key,
+      newField.data_name
+    );
+  }
+}
+
+function hasCodeReference(code, field) {
+  if (typeof code !== 'string') return false;
+  const names = [field.key, field.data_name].filter(Boolean).map(escapeRegExp);
+  return names.some(
+    (name) =>
+      new RegExp(`\\$${name}(?![A-Za-z0-9_])`).test(code) ||
+      new RegExp(`(?:ON|OFF|SETVALUE)\\([^)]*['\"]${name}['\"]`).test(code)
+  );
+}
+
+function findRemovalReferences(form, field) {
+  const references = [];
+  const oldValues = new Set([field.key, field.data_name].filter(Boolean));
+  const scan = (value, path) => {
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => scan(entry, `${path}[${index}]`));
+      return;
+    }
+    if (!value || typeof value !== 'object') return;
+    for (const [key, entry] of Object.entries(value)) {
+      if (
+        ['field_id', 'field_key', 'destination_field_id', 'form_link_field_key'].includes(key) &&
+        oldValues.has(entry)
+      ) {
+        references.push(`${path}.${key}`);
+      }
+      scan(entry, `${path}.${key}`);
+    }
+  };
+  scan(form, 'form');
+  const titleReferences = (value, path) => {
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => titleReferences(entry, `${path}[${index}]`));
+      return;
+    }
+    if (!value || typeof value !== 'object') return;
+    if (value.type === 'TitleField' && value.elements?.some((entry) => oldValues.has(entry))) {
+      references.push(`${path}.elements`);
+    }
+    Object.entries(value).forEach(([key, entry]) => titleReferences(entry, `${path}.${key}`));
+  };
+  titleReferences(form, 'form');
+  for (const candidate of flattenFields(form.elements)) {
+    if (candidate !== field && hasCodeReference(candidate.calculate, field)) {
+      references.push(`CalculatedField:${candidate.data_name}`);
+    }
+  }
+  if (hasCodeReference(form.events?.code, field)) references.push('form.events.code');
+  return [...new Set(references)];
+}
+
+function mutationError(index, operation, error) {
+  return {
+    code: 'mutation_failed',
+    severity: 'error',
+    operationIndex: index,
+    operation: operation?.op || null,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function applyMutation(root, operation) {
+  const form = root.form;
+  const fields = indexFields(form.elements);
+  switch (operation.op) {
+    case 'updateForm': {
+      const forbidden = new Set(['elements', 'events', 'title_field', 'status_field']);
+      for (const key of Object.keys(operation.changes || {})) {
+        if (forbidden.has(key)) throw new Error(`updateForm cannot change '${key}'`);
+      }
+      Object.assign(form, deepClone(operation.changes || {}));
+      return `Updated form attributes`;
+    }
+    case 'addField': {
+      const field = ensureFieldKeys(deepClone(operation.field));
+      if (field.key && fields.has(field.key))
+        throw new Error(`Field key '${field.key}' already exists`);
+      if (
+        field.data_name &&
+        [...fields.values()].some((entry) => entry.field.data_name === field.data_name)
+      ) {
+        throw new Error(`Field data_name '${field.data_name}' already exists`);
+      }
+      const point = getInsertionPoint(form, operation.parentKey || null, operation.position || {});
+      point.list.splice(point.index, 0, field);
+      return `Added ${field.type || 'field'} '${field.data_name || field.key}'`;
+    }
+    case 'updateField': {
+      const target = fields.get(operation.fieldKey);
+      if (!target) throw new Error(`Field '${operation.fieldKey}' was not found`);
+      if (operation.changes?.type && operation.changes.type !== target.field.type) {
+        throw new Error('Field type cannot be changed; remove and add the field explicitly');
+      }
+      const original = deepClone(target.field);
+      const children = target.field.elements;
+      Object.assign(target.field, deepClone(operation.changes || {}));
+      if (
+        target.field.data_name !== original.data_name &&
+        [...fields.values()].some(
+          (entry) =>
+            entry.field !== target.field && entry.field.data_name === target.field.data_name
+        )
+      ) {
+        throw new Error(`Field data_name '${target.field.data_name}' already exists`);
+      }
+      if (CONTAINER_TYPES.has(target.field.type)) target.field.elements = children || [];
+      if (target.field.data_name !== original.data_name) {
+        target.field.key = generateKey(target.field.data_name);
+        renameReferences(form, original, target.field);
+      } else {
+        target.field.key = original.key;
+      }
+      return `Updated field '${original.data_name}'`;
+    }
+    case 'moveField': {
+      const target = fields.get(operation.fieldKey);
+      if (!target) throw new Error(`Field '${operation.fieldKey}' was not found`);
+      const descendants = new Set(
+        flattenFields(target.field.elements || [])
+          .map((field) => field?.key)
+          .filter(Boolean)
+      );
+      if (operation.parentKey && descendants.has(operation.parentKey)) {
+        throw new Error('A field cannot be moved into one of its descendants');
+      }
+      target.list.splice(target.index, 1);
+      const point = getInsertionPoint(form, operation.parentKey || null, operation.position || {});
+      point.list.splice(point.index, 0, target.field);
+      return `Moved field '${target.field.data_name}'`;
+    }
+    case 'removeField': {
+      const target = fields.get(operation.fieldKey);
+      if (!target) throw new Error(`Field '${operation.fieldKey}' was not found`);
+      const references = findRemovalReferences(form, target.field);
+      if (references.length > 0) {
+        throw new Error(
+          `Field '${target.field.data_name}' is still referenced by: ${references.join(', ')}`
+        );
+      }
+      target.list.splice(target.index, 1);
+      return `Removed field '${target.field.data_name}'`;
+    }
+    case 'setTitleField':
+      form.title_field = deepClone(operation.field ?? null);
+      return 'Updated title field';
+    case 'setStatusField':
+      form.status_field = deepClone(operation.field ?? null);
+      return 'Updated status field';
+    case 'setCalculation': {
+      const target = fields.get(operation.fieldKey)?.field;
+      if (!target || target.type !== 'CalculatedField') {
+        throw new Error(`Field '${operation.fieldKey}' is not a CalculatedField`);
+      }
+      target.calculate = operation.expression;
+      return `Updated calculation '${target.data_name}'`;
+    }
+    case 'setFormEventCode':
+      form.events = operation.code ? { ...(form.events || {}), code: operation.code } : null;
+      return 'Updated form event code';
+    default:
+      throw new Error(`Unsupported mutation operation '${operation.op}'`);
+  }
+}
+
+function validateDraft(root, security) {
+  const diagnostics = [];
+  try {
+    validateSchema(root.form);
+  } catch (error) {
+    diagnostics.push({
+      code: 'schema_validation_failed',
+      severity: 'error',
+      message: error.message,
+    });
+  }
+  for (const field of flattenFields(root.form.elements)) {
+    if (field?.type !== 'CalculatedField') continue;
+    const analysis = analyzeCalculationExpression({
+      expression: field.calculate,
+      schema: root,
+      fieldDataName: field.data_name,
+      securityConfig: security,
+    });
+    diagnostics.push(
+      ...analysis.issues.map((issue) => ({ ...issue, source: `calculation:${field.data_name}` }))
+    );
+  }
+  const eventAnalysis = analyzeFormEventCode({
+    code: root.form.events?.code || '',
+    schema: root,
+    securityConfig: security,
+  });
+  diagnostics.push(...eventAnalysis.issues.map((issue) => ({ ...issue, source: 'form-events' })));
+  return diagnostics;
+}
+
+/** Return a deterministic revision for optimistic authoring concurrency. */
+export function getFormSchemaRevision(schema) {
+  const root = normalizeRootSchema(schema);
+  return `form0-${fnv1a64(JSON.stringify(stableValue(root)))}`;
+}
+
+/** Return the installed-version authoring capabilities and complete schema context. */
+export function getFormAuthoringContext({ schema, coreVersion = null }) {
+  const root = normalizeRootSchema(schema);
+  const fieldSpecs = Object.fromEntries(
+    Object.entries(FIELD_SPECS).map(([type, spec]) => [type, toSerializable(spec.attributes)])
+  );
+  const operators = Object.fromEntries(
+    Object.keys(FIELD_SPECS).map((type) => [type, getValidOperators(type)])
+  );
+  const calculations = flattenFields(root.form.elements)
+    .filter((field) => field?.type === 'CalculatedField')
+    .map((field) => ({
+      fieldKey: field.key,
+      fieldDataName: field.data_name,
+      references: getCalculationReferenceCatalog({
+        schema: root,
+        fieldDataName: field.data_name,
+        includeRestricted: true,
+      }),
+    }));
+  return {
+    contractVersion: 3,
+    coreVersion,
+    revision: getFormSchemaRevision(root),
+    schema: deepClone(root),
+    mutationOperations: [...MUTATION_OPERATIONS],
+    fieldSpecs,
+    operators,
+    eventTypes: getAllEventTypes(),
+    eventGuidance: deepClone(EVENT_GUIDANCE),
+    calculationBuiltins: getCalculationBuiltinCatalog(),
+    calculationGuidance: deepClone(CALCULATION_GUIDANCE),
+    eventBuiltins: getFormEventBuiltinCatalog(),
+    eventReferences: getFormEventReferenceCatalog({ schema: root }),
+    calculations,
+  };
+}
+
+/** Resolve whether the complete form may be sent to a cloud AI provider. */
+export function getFormAICloudPolicy(schema) {
+  const root = normalizeRootSchema(schema);
+  const cloudBlockers = [];
+  const consentReasons = [];
+  if (root.form.ai?.allowCloud === false) cloudBlockers.push({ scope: 'form' });
+  if (root.form.ai?.requiresConsent === true) consentReasons.push({ scope: 'form' });
+  for (const field of flattenFields(root.form.elements)) {
+    const identity = field?.key || field?.data_name || 'unknown-field';
+    if (field?.ai?.allowCloud === false) cloudBlockers.push({ scope: 'field', key: identity });
+    if (field?.ai?.requiresConsent === true) consentReasons.push({ scope: 'field', key: identity });
+  }
+  return {
+    allowCloud: cloudBlockers.length === 0,
+    requiresConsent: consentReasons.length > 0,
+    cloudBlockers,
+    consentReasons,
+  };
+}
+
+/** Validate a complete authoring draft without creating or applying mutations. */
+export function validateFormAuthoringSchema({ schema, security }) {
+  const root = normalizeRootSchema(schema);
+  const diagnostics = validateDraft(root, security);
+  return {
+    valid: !diagnostics.some((diagnostic) => diagnostic.severity === 'error'),
+    revision: getFormSchemaRevision(root),
+    diagnostics,
+  };
+}
+
+/** Apply and fully validate a semantic mutation batch without mutating the input schema. */
+export function applyFormMutationBatch({ schema, baseRevision, operations, security }) {
+  const root = normalizeRootSchema(schema);
+  const currentRevision = getFormSchemaRevision(root);
+  if (baseRevision !== currentRevision) {
+    return {
+      valid: false,
+      schema: null,
+      revision: currentRevision,
+      semanticDiff: [],
+      diagnostics: [
+        {
+          code: 'stale_schema_revision',
+          severity: 'error',
+          message: `Expected revision '${currentRevision}', received '${baseRevision}'`,
+        },
+      ],
+    };
+  }
+  if (!Array.isArray(operations) || operations.length === 0) {
+    return {
+      valid: false,
+      schema: null,
+      revision: currentRevision,
+      semanticDiff: [],
+      diagnostics: [
+        {
+          code: 'empty_mutation_batch',
+          severity: 'error',
+          message: 'At least one operation is required',
+        },
+      ],
+    };
+  }
+
+  const draft = deepClone(root);
+  const semanticDiff = [];
+  for (let index = 0; index < operations.length; index += 1) {
+    try {
+      semanticDiff.push({
+        index,
+        op: operations[index]?.op,
+        summary: applyMutation(draft, operations[index]),
+      });
+    } catch (error) {
+      return {
+        valid: false,
+        schema: null,
+        revision: currentRevision,
+        semanticDiff: [],
+        diagnostics: [mutationError(index, operations[index], error)],
+      };
+    }
+  }
+
+  const diagnostics = validateDraft(draft, security);
+  const valid = !diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+  return {
+    valid,
+    schema: valid ? draft : null,
+    revision: valid ? getFormSchemaRevision(draft) : currentRevision,
+    semanticDiff: valid ? semanticDiff : [],
+    diagnostics,
+  };
+}

package/src/builtins/choice/choicevalue.js

@@ -17,7 +17,10 @@ export const CHOICEVALUE_METADATA = defineBuiltinMetadata({
   category: 'choice',
   signature: 'CHOICEVALUE(fieldValue)',
   description: 'Return the selected choice value from a choice field.',
-  examples: ['CHOICEVALUE($city)'],
+  examples: [
+    'CHOICEVALUE($city)',
+    'IF(CHOICEVALUE($city) === "bogota", "Welcome to Bogota!", "Welcome!")',
+  ],
   contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
 });
 

package/src/builtins/choice/choicevalues.js

@@ -17,7 +17,7 @@ export const CHOICEVALUES_METADATA = defineBuiltinMetadata({
   category: 'choice',
   signature: 'CHOICEVALUES(fieldValue)',
   description: 'Return all selected values from a MultiChoiceField.',
-  examples: ['CHOICEVALUES($colors)'],
+  examples: ['CHOICEVALUES($colors)', 'CHOICEVALUES($colors).includes("red")'],
   contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
 });
 

package/src/builtins/control/setresult.js

@@ -42,3 +42,9 @@ export function __consumeResult() {
   _resultValue = undefined;
   return { called, value };
 }
+
+/** Clear calculation result state without consuming it. */
+export function __resetResult() {
+  _resultSet = false;
+  _resultValue = undefined;
+}

package/src/builtins/logical/if.js

@@ -19,7 +19,10 @@ export const IF_METADATA = defineBuiltinMetadata({
   category: 'logical',
   signature: 'IF(condition, trueValue, falseValue)',
   description: 'Return one of two values based on a condition.',
-  examples: ['IF($age >= 18, "adult", "minor")'],
+  examples: [
+    'IF($age >= 18, "adult", "minor")',
+    'IF($country === "US", IF($state === "CA", 8.99, 5.99), 15.99)',
+  ],
   contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
 });
 

package/src/builtins/registry.js

@@ -7,7 +7,12 @@ import { COUNT, COUNT_METADATA } from './logical/count.js';
 import { COUNTA, COUNTA_METADATA } from './logical/counta.js';
 import { COUNTBLANK, COUNTBLANK_METADATA } from './logical/countblank.js';
 import { ARRAY, ARRAY_METADATA } from './logical/array.js';
-import { SETRESULT, SETRESULT_METADATA, __consumeResult } from './control/setresult.js';
+import {
+  SETRESULT,
+  SETRESULT_METADATA,
+  __consumeResult,
+  __resetResult,
+} from './control/setresult.js';
 import { EVAL, EVAL_METADATA } from './control/eval.js';
 import { CHOICEVALUE, CHOICEVALUE_METADATA } from './choice/choicevalue.js';
 import { CHOICELABEL, CHOICELABEL_METADATA } from './choice/choicelabel.js';
@@ -37,7 +42,12 @@ export { COUNT, COUNT_METADATA } from './logical/count.js';
 export { COUNTA, COUNTA_METADATA } from './logical/counta.js';
 export { COUNTBLANK, COUNTBLANK_METADATA } from './logical/countblank.js';
 export { ARRAY, ARRAY_METADATA } from './logical/array.js';
-export { SETRESULT, SETRESULT_METADATA, __consumeResult } from './control/setresult.js';
+export {
+  SETRESULT,
+  SETRESULT_METADATA,
+  __consumeResult,
+  __resetResult,
+} from './control/setresult.js';
 export { EVAL, EVAL_METADATA, __setEvalContext, __clearEvalContext } from './control/eval.js';
 export { CHOICEVALUE, CHOICEVALUE_METADATA } from './choice/choicevalue.js';
 export { CHOICELABEL, CHOICELABEL_METADATA } from './choice/choicelabel.js';

package/src/engine/evaluator.js

@@ -1,4 +1,4 @@
-import { __consumeResult } from '../builtins/registry.js';
+import { __consumeResult, __resetResult } from '../builtins/registry.js';
 import { __setEvalContext, __clearEvalContext } from '../builtins/control/eval.js';
 import { __setDataNamesContext, __clearDataNamesContext } from '../builtins/schema/datanames.js';
 import { validateExpression, createSecureContext, withTimeout } from '../security/validation.js';
@@ -16,6 +16,9 @@ export function runExpression(
   schema = null,
   options = {}
 ) {
+  // SETRESULT uses synchronous evaluation-scoped state. Clear it at both boundaries so a
+  // previously failed expression can never influence this evaluation.
+  __resetResult();
   try {
     // Validate expression based on security mode
     const validation = validateExpression(expr, securityConfig, includeEventBuiltins);
@@ -59,6 +62,7 @@ export function runExpression(
           return consumed.called ? consumed.value : result;
         }
       } finally {
+        __resetResult();
         // Always clear EVAL context after execution
         __clearEvalContext();
         if (schema) {

package/src/index.js

@@ -78,3 +78,10 @@ export {
   getFieldAIChoicePolicy,
   getFieldAIProviderHints,
 } from './utilities/ai-metadata.js';
+export {
+  getFormSchemaRevision,
+  getFormAuthoringContext,
+  getFormAICloudPolicy,
+  validateFormAuthoringSchema,
+  applyFormMutationBatch,
+} from './authoring/form-authoring.js';

package/src/utilities/calculation-editor.js

@@ -80,6 +80,69 @@ function extractFunctionCalls(code) {
   return matches;
 }
 
+function isFinalFunctionCall(code, call) {
+  let index = call.index + call.length;
+  while (index < code.length && /\s/u.test(code[index])) index += 1;
+  if (code[index] !== '(') return false;
+
+  let depth = 0;
+  let state = 'code';
+  for (; index < code.length; index += 1) {
+    const char = code[index];
+    const next = code[index + 1];
+
+    if (state === 'line-comment') {
+      if (char === '\n') state = 'code';
+      continue;
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        index += 1;
+        state = 'code';
+      }
+      continue;
+    }
+    if (state !== 'code') {
+      if (char === '\\') {
+        index += 1;
+      } else if (
+        (state === 'single-quote' && char === "'") ||
+        (state === 'double-quote' && char === '"') ||
+        (state === 'template' && char === '`')
+      ) {
+        state = 'code';
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      state = 'line-comment';
+      index += 1;
+    } else if (char === '/' && next === '*') {
+      state = 'block-comment';
+      index += 1;
+    } else if (char === "'") {
+      state = 'single-quote';
+    } else if (char === '"') {
+      state = 'double-quote';
+    } else if (char === '`') {
+      state = 'template';
+    } else if (char === '(') {
+      depth += 1;
+    } else if (char === ')') {
+      depth -= 1;
+      if (depth === 0) break;
+    }
+  }
+
+  if (depth !== 0) return false;
+  index += 1;
+  while (index < code.length && /\s/u.test(code[index])) index += 1;
+  if (code[index] === ';') index += 1;
+  while (index < code.length && /\s/u.test(code[index])) index += 1;
+  return index === code.length;
+}
+
 function cloneCatalogDefinition(definition) {
   return {
     ...definition,
@@ -519,6 +582,37 @@ export function analyzeCalculationExpression({
     );
   }
 
+  if (isMultilineCalculationExpression(normalizedExpression) && setResultCalls.length === 0) {
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'noncanonical_multiline_result',
+        severity: 'warning',
+        message: 'Multiline calculations should finish with exactly one SETRESULT() call.',
+        index: 0,
+        length: 1,
+      })
+    );
+  } else if (
+    isMultilineCalculationExpression(normalizedExpression) &&
+    setResultCalls.length === 1 &&
+    !isFinalFunctionCall(normalizedExpression, setResultCalls[0])
+  ) {
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'noncanonical_setresult_placement',
+        severity: 'warning',
+        message: 'SETRESULT() should be the final statement in a multiline calculation.',
+        symbol: 'SETRESULT',
+        index: setResultCalls[0].index,
+        length: setResultCalls[0].length,
+      })
+    );
+  }
+
   for (const reference of extractStaticFieldReferenceMatches(normalizedExpression)) {
     if (!referencedFieldNames.has(reference.fieldName)) {
       referencedFieldNames.add(reference.fieldName);

package/src/utilities/form-event-editor.js

@@ -18,6 +18,10 @@ const COMMON_GLOBAL_FUNCTIONS = new Set([
 ]);
 
 const STRUCTURAL_FIELD_TYPES = new Set(['Section', 'RepeatableSection', 'BuildingPlanSection']);
+const SINGLE_CHOICE_FIELD_TYPES = new Set(['SingleChoiceField', 'BooleanField']);
+const MULTI_CHOICE_FIELD_TYPES = new Set(['MultiChoiceField']);
+
+const SCALAR_LITERAL_PATTERN = String.raw`(?:'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"|-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|true|false|null|undefined)`;
 
 const FORM_EVENT_BUILTIN_STATUS_BY_NAME = Object.freeze({
   EVAL: 'advanced',
@@ -142,6 +146,84 @@ function extractFieldReferenceMatches(code) {
   return matches;
 }
 
+function getCodePositions(code) {
+  const positions = new Array(code.length).fill(false);
+  let state = 'code';
+
+  for (let index = 0; index < code.length; index++) {
+    const char = code[index];
+    const next = code[index + 1];
+
+    if (state === 'line-comment') {
+      if (char === '\n') state = 'code';
+      continue;
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        index++;
+        state = 'code';
+      }
+      continue;
+    }
+    if (state !== 'code') {
+      if (char === '\\') {
+        index++;
+      } else if (
+        (state === 'single-quote' && char === "'") ||
+        (state === 'double-quote' && char === '"') ||
+        (state === 'template' && char === '`')
+      ) {
+        state = 'code';
+      }
+      continue;
+    }
+
+    positions[index] = true;
+    if (char === '/' && next === '/') {
+      positions[index] = false;
+      state = 'line-comment';
+      index++;
+    } else if (char === '/' && next === '*') {
+      positions[index] = false;
+      state = 'block-comment';
+      index++;
+    } else if (char === "'") {
+      state = 'single-quote';
+    } else if (char === '"') {
+      state = 'double-quote';
+    } else if (char === '`') {
+      state = 'template';
+    }
+  }
+
+  return positions;
+}
+
+function extractDirectScalarComparisonMatches(code) {
+  const comparisonPattern = new RegExp(
+    String.raw`(?:\$([a-zA-Z_][a-zA-Z0-9_]*)\s*(?:===|!==|==|!=)\s*${SCALAR_LITERAL_PATTERN}|${SCALAR_LITERAL_PATTERN}\s*(?:===|!==|==|!=)\s*\$([a-zA-Z_][a-zA-Z0-9_]*))`,
+    'g'
+  );
+  const codePositions = getCodePositions(code);
+  const matches = [];
+  let match;
+
+  while ((match = comparisonPattern.exec(code)) !== null) {
+    if (!codePositions[match.index]) continue;
+    const fieldName = match[1] || match[2];
+    const reference = `$${fieldName}`;
+    const referenceOffset = match[0].indexOf(reference);
+    matches.push({
+      fieldName,
+      reference,
+      index: match.index + referenceOffset,
+      length: reference.length,
+    });
+  }
+
+  return matches;
+}
+
 function extractLiteralEventTypeMatches(code) {
   const matches = [];
   const eventTypeCallPattern = /\b(ON|OFF)\s*\(\s*(['"])([^'"\\]*(?:\\.[^'"\\]*)*)\2/g;
@@ -302,12 +384,11 @@ export function analyzeFormEventCode({ code, schema, securityConfig = DEFAULT_SE
   const validEventTypes = new Set(getAllEventTypes());
   const normalizedCode = typeof code === 'string' ? code : '';
   const form = normalizeFormSchema(schema);
-  const knownFieldNames = new Set(
-    flattenFields(form.elements)
-      .filter((field) => field && typeof field === 'object')
-      .map((field) => field.data_name)
-      .filter((fieldName) => typeof fieldName === 'string' && fieldName.length > 0)
+  const knownFields = flattenFields(form.elements).filter(
+    (field) => field && typeof field === 'object' && typeof field.data_name === 'string'
   );
+  const knownFieldNames = new Set(knownFields.map((field) => field.data_name));
+  const knownFieldByName = new Map(knownFields.map((field) => [field.data_name, field]));
 
   if (normalizedCode.trim().length > 0) {
     try {
@@ -452,6 +533,29 @@ export function analyzeFormEventCode({ code, schema, securityConfig = DEFAULT_SE
     }
   }
 
+  for (const comparison of extractDirectScalarComparisonMatches(normalizedCode)) {
+    const fieldType = knownFieldByName.get(comparison.fieldName)?.type;
+    const accessor = SINGLE_CHOICE_FIELD_TYPES.has(fieldType)
+      ? 'CHOICEVALUE'
+      : MULTI_CHOICE_FIELD_TYPES.has(fieldType)
+        ? 'CHOICEVALUES'
+        : null;
+    if (!accessor) continue;
+
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'choice_value_accessor_required',
+        severity: 'error',
+        message: `${comparison.reference} is a ${fieldType} value object. Use ${accessor}(${comparison.reference}) when comparing its selected value.`,
+        symbol: comparison.reference,
+        index: comparison.index,
+        length: comparison.length,
+      })
+    );
+  }
+
   for (const eventTypeReference of extractLiteralEventTypeMatches(normalizedCode)) {
     if (validEventTypes.has(eventTypeReference.eventType)) {
       continue;