form0-core 0.6.0 → 0.8.0

package/README.md

@@ -256,3 +256,53 @@ See [SUPPORT.md](https://github.com/paqu-io/form0-core/blob/main/SUPPORT.md) for
 ## 📄 License
 
 [MIT](./LICENSE)
+
+### Record-tree evaluation and submission preparation (unreleased)
+
+`createRecordEvaluator()` coordinates root and nested accepted records without changing the caller's
+snapshot. It shares the existing calculation executor and scope/security rules; `engine.eval()` keeps
+its intrinsic evaluation contract.
+
+```js
+import { createRecordEvaluator, validateSubmission } from 'form0-core';
+
+const evaluator = createRecordEvaluator({ schema });
+const accepted = await evaluator.evaluate(snapshot); // retained child calculations
+const refreshed = await evaluator.evaluate(snapshot, { mode: 'refresh' });
+const prepared = await evaluator.prepareSubmission(snapshot);
+// Persist only when prepared.eligible; persistence and save hooks belong to the host.
+const summary = validateSubmission({ schema, snapshot: refreshed.snapshot });
+```
+
+The runtime snapshot is `{ values, repeatable }`, using existing row objects with `id`, `values`,
+nested `repeatable` and metadata. `REPEATABLEVALUES($tasks, 'cost')` and
+`REPEATABLESUM($tasks, 'cost')` require this record-tree context and are calculation-only.
+
+`form.repeatable_recalculation` accepts `automatic` (default) or `confirm`. A changed child proposal
+in confirm mode returns `status: 'requires_decision'`, `reviewId`, `proposal`, `changes` and no selected
+snapshot. Resume with the current snapshot and
+`{ decision: { reviewId, action: 'refresh' } }`; `retain` additionally requires `allowRetain: true` on
+both preparation calls. Decisions are single-use and reject obsolete inputs/configuration.
+
+Draft preparation uses `{ intent: 'draft' }`, retains child values without confirmation, and permits
+ordinary validation failures. Persist the returned `freshness` companion separately from the record
+and supply it to the host on reopening; do not clear stored pending status before persistence succeeds.
+`managedEvents: true` enables root and participating closed-row custom validation only. No save or
+closed-row lifecycle hooks are replayed. Renderer/worker/Native/CLI UI adoption is separate work.
+
+For an open editor, `await evaluator.evaluateScope(snapshot, { instancePath: [] })` evaluates only
+that record. Use complete ancestry to target a child. It reads current supplied ancestors and accepted
+other rows, returning the selected `state`, built-in validation summary, changes and separate
+execution issues/diagnostics without another complete tree. It leaves caller inputs and closed-row
+calculations unchanged. See [the record evaluation contract](analyses/RECORD_EVALUATION_CONTRACT.md).
+
+For accepted-snapshot viewing, supply `{ interactionMode: 'readonly' }` to `evaluateScope()`. It
+computes field state and intrinsic/submission findings from supplied values without running
+calculations or applying missing schema defaults. Editing is the default. Whole-tree evaluation and
+submission preparation retain their accepted/refresh policies.
+
+Scalar engines accept `mode: 'readonly' | 'edit'` (default `edit`) and expose `getMode()`/`setMode()`.
+Call `eval()` after a host mode change. Events receive authoritative `event.mode`; view-time data
+writes fail before host delegation. Load remains available for reads, alerts and scoped ON/OFF
+registration. Move writable initialization to new/edit handlers when it must run after View → Edit.
+See [the event contract](EVENT_CONTRACT.md) for permissions, lifecycle order and migration guidance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -12,14 +12,16 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/conditions.test.js && node tests/condition-scope.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/builtin-import-isolation.test.js && node tests/builtin-catalog-examples.test.js && node tests/date-builtins.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/calculation-dependency-engine.test.js && node tests/calculation-diagnostics.characterization.test.js && node tests/calculation-diagnostics.test.js && node tests/calculation-missing-result.test.js && node tests/evaluator-reentry.test.js && node tests/event-compatibility.characterization.test.js && node tests/event-hermes.test.js && node tests/event-async-isolation.test.js && node tests/managed-events.test.js && node tests/security-test.js",
+    "test": "node tests/form0-core.test.js && node tests/conditions.test.js && node tests/condition-scope.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/builtin-import-isolation.test.js && node tests/builtin-catalog-examples.test.js && node tests/date-builtins.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/calculation-dependency-engine.test.js && node tests/calculation-diagnostics.characterization.test.js && node tests/calculation-diagnostics.test.js && node tests/calculation-missing-result.test.js && node tests/evaluator-reentry.test.js && node tests/expression-compilation.test.js && node tests/event-compatibility.characterization.test.js && node tests/event-hermes.test.js && node tests/event-async-isolation.test.js && node tests/managed-events.test.js && node tests/security-test.js && node tests/record-evaluator.test.js && node tests/complex-record-evaluator.test.js && node tests/record-scope.test.js",
     "format": "prettier --write \"src/**/*.{js,jsx}\" \"tests/**/*.{js,jsx}\" \"scripts/**/*.{js,mjs}\" package.json README.md EVENT_CONTRACT.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 EVENT_CONTRACT.md SECURITY.md SUPPORT.md CONTRIBUTING.md eslint.config.js .github/workflows/ci.yml .github/workflows/publish.yml",
     "lint:check": "eslint src tests",
     "package:check": "node scripts/check-package-contents.mjs",
     "security:audit:prod": "npm audit --omit=dev --omit=peer --audit-level=high",
     "check": "npm run format:check && npm run lint:check && npm test",
-    "release:check": "npm run check && npm run security:audit:prod && npm run package:check"
+    "release:check": "npm run check && npm run security:audit:prod && npm run package:check",
+    "benchmark:records": "node scripts/benchmark-record-evaluator.mjs",
+    "benchmark:records:complex": "node scripts/benchmark-complex-records.mjs"
   },
   "exports": {
     ".": {
@@ -50,6 +52,7 @@
     }
   ],
   "license": "MIT",
+  "funding": "https://opencollective.com/form0",
   "bugs": {
     "url": "https://github.com/paqu-io/form0-core/issues"
   },

package/src/authoring/form-authoring.js

@@ -1,3 +1,5 @@
+import { getFormSchemaRevision } from '../utilities/schema-revision.js';
+export { getFormSchemaRevision } from '../utilities/schema-revision.js';
 import { FIELD_SPECS } from '../schema/field-specs.js';
 import { getValidOperators } from '../schema/operators.js';
 import { validateSchema } from '../schema/schema-validator.js';
@@ -162,25 +164,6 @@ function normalizeRootSchema(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;
@@ -551,12 +534,6 @@ function validateDraft(root, security) {
   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);
@@ -575,6 +552,7 @@ export function getFormAuthoringContext({ schema, coreVersion = null }) {
         schema: root,
         fieldDataName: field.data_name,
         includeRestricted: true,
+        includeCollections: true,
       }),
     }));
   return {
@@ -589,7 +567,19 @@ export function getFormAuthoringContext({ schema, coreVersion = null }) {
     eventTypes: getAllEventTypes(),
     eventGuidance: deepClone(EVENT_GUIDANCE),
     calculationBuiltins: getCalculationBuiltinCatalog(),
-    calculationGuidance: deepClone(CALCULATION_GUIDANCE),
+    calculationGuidance: {
+      ...deepClone(CALCULATION_GUIDANCE),
+      repeatableCollections: {
+        context: 'calculation-only',
+        requiresRecordEvaluator: true,
+        directSectionReference: true,
+        literalTargetDataName: true,
+        examples: ["REPEATABLEVALUES($tasks, 'cost')", "REPEATABLESUM($tasks, 'cost')"],
+      },
+    },
+    formSettings: {
+      repeatable_recalculation: { values: ['automatic', 'confirm'], default: 'automatic' },
+    },
     eventBuiltins: getFormEventBuiltinCatalog(),
     eventReferences: getFormEventReferenceCatalog({ schema: root }),
     calculations,

package/src/builtins/builtin-definitions.js

@@ -238,6 +238,7 @@ export const SETRESULT_METADATA = defineBuiltinMetadata({
 
 export const ALERT_METADATA = defineBuiltinMetadata({
   name: 'ALERT',
+  operation: { type: 'UI_OPERATION', effects: ['presentation'] },
   category: 'event',
   signature: "ALERT(title, message = '')",
   description: 'Display an alert from a form event handler.',
@@ -247,6 +248,7 @@ export const ALERT_METADATA = defineBuiltinMetadata({
 
 export const SETVALUE_METADATA = defineBuiltinMetadata({
   name: 'SETVALUE',
+  operation: { type: 'FIELD_OPERATION', effects: ['record-write'] },
   category: 'event',
   signature: 'SETVALUE(fieldDataName, valueToSet)',
   description: 'Set a field value from a form event handler.',
@@ -256,6 +258,7 @@ export const SETVALUE_METADATA = defineBuiltinMetadata({
 
 export const ON_METADATA = defineBuiltinMetadata({
   name: 'ON',
+  operation: { type: 'EVENT_OPERATION', effects: ['listeners'] },
   category: 'event',
   signature: 'ON(eventType, fieldKeyOrCallback, callback)',
   description: 'Register an event handler within form event code.',
@@ -265,6 +268,7 @@ export const ON_METADATA = defineBuiltinMetadata({
 
 export const OFF_METADATA = defineBuiltinMetadata({
   name: 'OFF',
+  operation: { type: 'EVENT_OPERATION', effects: ['listeners'] },
   category: 'event',
   signature: 'OFF(eventType, fieldKeyOrCallback, callback)',
   description: 'Remove event handlers within form event code.',
@@ -274,6 +278,7 @@ export const OFF_METADATA = defineBuiltinMetadata({
 
 export const INVALID_METADATA = defineBuiltinMetadata({
   name: 'INVALID',
+  operation: { type: 'VALIDATION_OPERATION', effects: ['validation'] },
   category: 'event',
   signature: 'INVALID(message)',
   description:
@@ -284,6 +289,26 @@ export const INVALID_METADATA = defineBuiltinMetadata({
   contexts: [BUILTIN_CONTEXTS.EVENT],
 });
 
+export const REPEATABLEVALUES_METADATA = defineBuiltinMetadata({
+  name: 'REPEATABLEVALUES',
+  category: 'repeatable',
+  signature: 'REPEATABLEVALUES($repeatable_data_name, target_data_name)',
+  description:
+    'Collect accepted or refreshed row values from the named RepeatableSection in record-tree context. Preserves row order and grouping; requires a literal target data_name.',
+  examples: ["REPEATABLEVALUES($tasks, 'cost')"],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION],
+});
+
+export const REPEATABLESUM_METADATA = defineBuiltinMetadata({
+  name: 'REPEATABLESUM',
+  category: 'repeatable',
+  signature: 'REPEATABLESUM($repeatable_data_name, target_data_name)',
+  description:
+    'Sum finite NumericField or CalculatedField row values in record-tree context. Skips missing values, returns zero for no rows, and never coerces strings.',
+  examples: ["REPEATABLESUM($tasks, 'cost')"],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION],
+});
+
 export const BUILTIN_DEFINITIONS = Object.freeze([
   IF_METADATA,
   AND_METADATA,
@@ -315,6 +340,8 @@ export const BUILTIN_DEFINITIONS = Object.freeze([
   ON_METADATA,
   OFF_METADATA,
   INVALID_METADATA,
+  REPEATABLEVALUES_METADATA,
+  REPEATABLESUM_METADATA,
 ]);
 
 function filterDefinitionsByContext(context) {

package/src/builtins/builtin-metadata.js

@@ -8,6 +8,7 @@
  * @property {string} description
  * @property {string[]} examples
  * @property {BuiltinContext[]} contexts
+ * @property {{type: string, effects: string[]}} [operation] Declared descriptor effects.
  */
 
 export const BUILTIN_CONTEXTS = Object.freeze({
@@ -26,6 +27,14 @@ export function defineBuiltinMetadata(definition) {
     ...definition,
     examples: Object.freeze([...(definition.examples ?? [])]),
     contexts: Object.freeze([...(definition.contexts ?? [])]),
+    ...(definition.operation
+      ? {
+          operation: Object.freeze({
+            ...definition.operation,
+            effects: Object.freeze([...definition.operation.effects]),
+          }),
+        }
+      : {}),
   });
 }
 
@@ -40,5 +49,8 @@ export function cloneBuiltinMetadata(definition) {
     ...definition,
     examples: [...definition.examples],
     contexts: [...definition.contexts],
+    ...(definition.operation
+      ? { operation: { ...definition.operation, effects: [...definition.operation.effects] } }
+      : {}),
   };
 }

package/src/builtins/control/eval.js

@@ -1,3 +1,4 @@
+import { extractStaticFieldReferences } from '../../utilities/calculation-dependencies.js';
 import { validateExpression } from '../../security/validation.js';
 import { SAFE_SECURITY_CONFIG } from '../../security/config.js';
 export { EVAL_METADATA } from '../builtin-definitions.js';
@@ -182,7 +183,9 @@ function evaluateHybridExpression(expression, formContext) {
 
     if (isFieldReference(expression)) {
       // Field reference - resolve from context
-      const fieldValue = formContext?.[expression];
+      const fieldValue = _evalReporting?.resolveReference
+        ? _evalReporting.resolveReference(expression)
+        : formContext?.[expression];
       if (fieldValue !== undefined) {
         logDebug('[form0] EVAL() resolved field reference:', expression, '→', fieldValue);
         return fieldValue;
@@ -208,6 +211,10 @@ function evaluateHybridExpression(expression, formContext) {
 
     // Step 3c: Add form context for variable access
     Object.assign(basicContext, formContext || {});
+    if (_evalReporting?.resolveReference) {
+      for (const name of extractStaticFieldReferences(expression))
+        basicContext[`$${name}`] = _evalReporting.resolveReference(`$${name}`);
+    }
 
     // Step 3d: Evaluate expression for string building
     const keys = Object.keys(basicContext);
@@ -221,7 +228,9 @@ function evaluateHybridExpression(expression, formContext) {
     // Step 3e: Check if result should be resolved as field reference
     if (typeof result === 'string' && result.startsWith('$')) {
       // This is a field reference - resolve it from context
-      const fieldValue = formContext?.[result];
+      const fieldValue = _evalReporting?.resolveReference
+        ? _evalReporting.resolveReference(result)
+        : formContext?.[result];
       if (fieldValue !== undefined) {
         logDebug(
           '[form0] EVAL() resolved field reference:',

package/src/builtins/registry.js

@@ -1,3 +1,5 @@
+import { REPEATABLEVALUES, REPEATABLEVALUES_METADATA } from './repeatable/repeatablevalues.js';
+import { REPEATABLESUM, REPEATABLESUM_METADATA } from './repeatable/repeatablesum.js';
 import { cloneBuiltinMetadata, BUILTIN_CONTEXTS } from './builtin-metadata.js';
 import { BUILTIN_DEFINITIONS } from './builtin-definitions.js';
 
@@ -115,6 +117,8 @@ const RUNTIME_ENTRIES = Object.freeze([
   { implementation: DAYS, definition: DAYS_METADATA },
   { implementation: UPPER, definition: UPPER_METADATA },
   { implementation: SETRESULT, definition: SETRESULT_METADATA },
+  { implementation: REPEATABLEVALUES, definition: REPEATABLEVALUES_METADATA },
+  { implementation: REPEATABLESUM, definition: REPEATABLESUM_METADATA },
   { implementation: ALERT, definition: ALERT_METADATA },
   { implementation: SETVALUE, definition: SETVALUE_METADATA },
   { implementation: ON, definition: ON_METADATA },

package/src/builtins/repeatable/repeatablesum.js

@@ -0,0 +1,12 @@
+export { REPEATABLESUM_METADATA } from '../builtin-definitions.js';
+
+/**
+ * @builtin REPEATABLESUM
+ * Metadata: builtin-definitions.js.
+ * @param {*} source
+ * @param {string} target
+ * @returns {number}
+ */
+export function REPEATABLESUM() {
+  throw new Error('REPEATABLESUM requires record-tree context from createRecordEvaluator().');
+}

package/src/builtins/repeatable/repeatablevalues.js

@@ -0,0 +1,12 @@
+export { REPEATABLEVALUES_METADATA } from '../builtin-definitions.js';
+
+/**
+ * @builtin REPEATABLEVALUES
+ * Metadata: builtin-definitions.js.
+ * @param {*} source
+ * @param {string} target
+ * @returns {Array}
+ */
+export function REPEATABLEVALUES() {
+  throw new Error('REPEATABLEVALUES requires record-tree context from createRecordEvaluator().');
+}

package/src/engine/calculation-bindings.js

@@ -0,0 +1,76 @@
+// Private conservative fast path for scalar expressions in a schema-bound record evaluator.
+// Unknown calls, EVAL, arguments, member access and complex JavaScript retain full bindings.
+import { parse } from 'acorn';
+import { calculationBuiltins } from '../builtins/registry.js';
+// These two canonical operations never consult ambient field context or invoke author callbacks.
+// Other builtins keep full bindings, including math functions that can be overridden by a host.
+const pureCalls = new Set(['SETRESULT', 'IF']);
+export function prepareScalarBindings(code) {
+  const names = new Set(),
+    calls = new Set();
+  function visit(node) {
+    if (!node) return true;
+    switch (node.type) {
+      case 'Program':
+        return node.body.length === 1 && visit(node.body[0]);
+      case 'ExpressionStatement':
+        return visit(node.expression);
+      case 'Literal':
+        return !node.regex;
+      case 'Identifier':
+        if (!node.name.startsWith('$') && !['undefined', 'NaN', 'Infinity'].includes(node.name))
+          return false;
+        names.add(node.name);
+        return true;
+      case 'UnaryExpression':
+        return node.operator !== 'delete' && visit(node.argument);
+      case 'BinaryExpression':
+      case 'LogicalExpression':
+        return visit(node.left) && visit(node.right);
+      case 'ConditionalExpression':
+        return visit(node.test) && visit(node.consequent) && visit(node.alternate);
+      case 'CallExpression':
+        if (node.optional || node.callee.type !== 'Identifier' || !pureCalls.has(node.callee.name))
+          return false;
+        names.add(node.callee.name);
+        calls.add(node.callee.name);
+        return node.arguments.every(visit);
+      default:
+        return false;
+    }
+  }
+  try {
+    return visit(parse(code, { ecmaVersion: 'latest' }))
+      ? { names, calls, fieldCount: [...names].filter((name) => name.startsWith('$')).length }
+      : null;
+  } catch {
+    return null;
+  }
+}
+export function selectScalarBindings(preparation, values, helpers) {
+  const plan = preparation.scalar;
+  if (!plan) return null;
+  for (const name of plan.calls) if (helpers[name] !== calculationBuiltins[name]) return null;
+  const bindings = (preparation.scalarBindings ??= preparation.bindings.filter(([, identifier]) =>
+    plan.names.has(identifier)
+  ));
+  // Missing/restricted names can fall through to host globals in legacy JavaScript.
+  // Specialize only when every field identifier resolves to a captured primitive value.
+  if (bindings.length !== plan.fieldCount) return null;
+  for (const [name] of bindings)
+    if (
+      !Object.hasOwn(values, name) ||
+      (values[name] !== null &&
+        !['undefined', 'string', 'number', 'boolean', 'bigint'].includes(typeof values[name]))
+    )
+      return null;
+  for (const name of plan.names)
+    if (
+      Object.hasOwn(helpers, name) &&
+      helpers[name] !== calculationBuiltins[name] &&
+      helpers[name] !== null &&
+      !['undefined', 'string', 'number', 'boolean', 'bigint'].includes(typeof helpers[name])
+    )
+      return null;
+  return { names: plan.names, bindings };
+}

package/src/engine/calculation.js

@@ -1,3 +1,5 @@
+import { prepareScalarBindings, selectScalarBindings } from './calculation-bindings.js';
+import { analyzeRepeatableCollections } from '../utilities/repeatable-collections.js';
 import { runExpression } from './evaluator.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
@@ -107,32 +109,70 @@ function buildScopedContext(
   contextResolver,
   warningSystem,
   expressionCode,
-  diagnostics
+  diagnostics,
+  preparation = null
 ) {
-  const ctx = { ...helpers };
+  let ctx;
 
-  const referencedFields = extractStaticFieldReferences(expressionCode);
+  const referencedFields = preparation?.references ?? extractStaticFieldReferences(expressionCode);
+  const access = (fieldName) => {
+    if (
+      !preparation ||
+      (!contextResolver.elementOwnership.has(fieldName) && !referencedFields.has(fieldName))
+    )
+      return contextResolver.resolveFieldAccess(executionContext, fieldName);
+    if (!preparation.access.has(fieldName))
+      preparation.access.set(
+        fieldName,
+        contextResolver.resolveFieldAccess(executionContext, fieldName)
+      );
+    return preparation.access.get(fieldName);
+  };
   const restrictedAccessedFields = [];
   const notFoundAccessedFields = [];
 
-  for (const [fieldName, value] of Object.entries(values)) {
-    const accessLevel = contextResolver.resolveFieldAccess(executionContext, fieldName);
-
-    if (accessLevel === 'accessible') {
-      ctx[`$${fieldName}`] = value;
-    } else if (accessLevel === 'restricted') {
-      if (referencedFields.has(fieldName)) {
-        ctx[`$${fieldName}`] = undefined;
-        restrictedAccessedFields.push(fieldName);
+  if (preparation) {
+    // The record evaluator has one immutable schema. Enumerate permitted bindings once,
+    // then read their CURRENT values on every execution (including all EVAL-accessible fields).
+    preparation.bindings ??= [...contextResolver.fieldOwnership.keys()]
+      .filter((name) => access(name) === 'accessible')
+      .map((name) => [name, `$${name}`]);
+    // Use fewer parameters only when syntax and current primitive bindings prove it safe.
+    // Keep the full context for dynamic expressions, helper overrides and object inputs.
+    const scalar = selectScalarBindings(preparation, values, helpers);
+    ctx = scalar
+      ? Object.fromEntries(
+          [...scalar.names]
+            .filter((name) => Object.hasOwn(helpers, name))
+            .map((name) => [name, helpers[name]])
+        )
+      : { ...helpers };
+    for (const [name, identifier] of scalar?.bindings ?? preparation.bindings)
+      if (Object.hasOwn(values, name)) ctx[identifier] = values[name];
+  } else {
+    ctx = { ...helpers };
+    for (const [fieldName, value] of Object.entries(values)) {
+      const accessLevel = access(fieldName);
+
+      if (accessLevel === 'accessible') {
+        ctx[`$${fieldName}`] = value;
+      } else if (accessLevel === 'restricted') {
+        if (referencedFields.has(fieldName)) {
+          ctx[`$${fieldName}`] = undefined;
+          restrictedAccessedFields.push(fieldName);
+        }
       }
     }
   }
 
   for (const fieldName of referencedFields) {
-    if (!(fieldName in values)) {
-      const accessLevel = contextResolver.resolveFieldAccess(executionContext, fieldName);
-      if (accessLevel === 'not_found') {
+    if (preparation || !(fieldName in values)) {
+      const accessLevel = access(fieldName);
+      if (accessLevel === 'not_found' && !(fieldName in values)) {
         notFoundAccessedFields.push(fieldName);
+      } else if (accessLevel === 'restricted') {
+        ctx[`$${fieldName}`] = undefined;
+        restrictedAccessedFields.push(fieldName);
       }
     }
   }
@@ -255,7 +295,7 @@ function emitDependencyPlanWarnings(plan, warningSystem, runtimeDiagnostics, dia
   });
 }
 
-function evaluateCalculatedField(
+export function evaluateCalculatedField(
   field,
   schema,
   values,
@@ -264,14 +304,28 @@ function evaluateCalculatedField(
   resolver,
   warnings,
   runtimeDiagnostics,
-  diagnostics
+  diagnostics,
+  execution = {}
 ) {
   if (!field?.data_name || !field.calculate) {
     return { changed: false, hasError: false };
   }
 
   try {
-    const executionContext = buildCalculationExecutionContext(schema, field.data_name, resolver);
+    // Factory-owned metadata only: never retain instance values, diagnostics or permissions
+    // from a different schema. The ordinary engine path continues without this private cache.
+    let preparation = execution.preparationCache?.get(field.data_name);
+    if (!preparation && execution.preparationCache) {
+      preparation = {
+        context: buildCalculationExecutionContext(schema, field.data_name, resolver),
+        references: extractStaticFieldReferences(field.calculate),
+        access: new Map(),
+        scalar: prepareScalarBindings(field.calculate),
+      };
+      execution.preparationCache.set(field.data_name, preparation);
+    }
+    const executionContext =
+      preparation?.context ?? buildCalculationExecutionContext(schema, field.data_name, resolver);
     const context = buildScopedContext(
       values,
       helpers,
@@ -279,30 +333,52 @@ function evaluateCalculatedField(
       resolver,
       warnings,
       field.calculate,
-      diagnostics
+      diagnostics,
+      preparation
     );
     const previousValue = values[field.data_name];
-    const nextValue = runExpression(field.calculate, context, securityConfig, false, schema, {
-      requireResult: true,
-      fieldName: field.data_name,
-      suppressConsoleWarning:
-        diagnostics?.consoleOverride !== undefined || Array.isArray(runtimeDiagnostics),
-      onDiagnostic: (diagnostic) => diagnostics?.record(field.data_name, diagnostic),
-      evalReporting: {
-        suppressConsole: diagnostics?.consoleOverride !== undefined,
+    const collection =
+      execution.expression === undefined
+        ? analyzeRepeatableCollections(field.calculate, resolver, field.data_name)
+        : null;
+    if (collection?.issues.length) {
+      values[field.data_name] = null;
+      for (const issue of collection.issues)
+        diagnostics?.record(field.data_name, { ...issue, phase: 'validation' });
+      return { changed: previousValue !== null, hasError: true };
+    }
+    const nextValue = runExpression(
+      execution.expression ?? collection?.expression ?? field.calculate,
+      context,
+      securityConfig,
+      false,
+      schema,
+      {
+        sourceExpression: field.calculate,
+        compileCache: execution.compileCache,
+        requireResult: true,
+        fieldName: field.data_name,
+        suppressConsoleWarning:
+          diagnostics?.consoleOverride !== undefined || Array.isArray(runtimeDiagnostics),
         onDiagnostic: (diagnostic) => diagnostics?.record(field.data_name, diagnostic),
-      },
-      onError: (error) => {
-        pushRuntimeDiagnostic(
-          runtimeDiagnostics,
-          field.data_name,
-          error instanceof Error && error.message
-            ? error.message
-            : 'Unknown calculation runtime error.'
-        );
-      },
-    });
+        evalReporting: {
+          resolveReference: execution.resolveReference,
+          suppressConsole: diagnostics?.consoleOverride !== undefined,
+          onDiagnostic: (diagnostic) => diagnostics?.record(field.data_name, diagnostic),
+        },
+        onError: (error) => {
+          pushRuntimeDiagnostic(
+            runtimeDiagnostics,
+            field.data_name,
+            error instanceof Error && error.message
+              ? error.message
+              : 'Unknown calculation runtime error.'
+          );
+        },
+      }
+    );
     values[field.data_name] = nextValue;
+    execution.writeValue?.(nextValue);
 
     return {
       changed: !areStructuredValuesEqual(previousValue, nextValue),