form0-core 0.6.0 → 0.8.0

package/src/engine/evaluator.js

@@ -3,6 +3,7 @@ import { __setEvalContext } from '../builtins/control/eval.js';
 import { __setDataNamesContext } from '../builtins/schema/datanames.js';
 import { validateExpression, createSecureContext, withTimeout } from '../security/validation.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
+import { compileExpression } from './expression-compilation.js';
 import {
   isMultilineCalculationExpression,
   normalizeInlineCalculationExpression,
@@ -54,8 +55,6 @@ export function runExpression(
 
     // Create secure context based on security mode
     const secureContext = createSecureContext(context, securityConfig);
-    const keys = Object.keys(secureContext);
-    const values = Object.values(secureContext);
 
     // Execute expression
     const executeExpression = () => {
@@ -70,9 +69,10 @@ export function runExpression(
           isMultilineCalculationExpression(sourceExpression);
 
         if (isMultiLine) {
-          // Execute as code block (recompile each time for now)
+          // Reuse a factory-owned compilation cache when supplied; values stay per evaluation.
           phase = 'syntax';
-          const fn = new Function(...keys, expr);
+          const { fn, keys } = compileExpression(expr, secureContext, 'body', options.compileCache);
+          const values = keys.map((key) => secureContext[key]);
           phase = 'runtime';
           const result = fn(...values);
           // Check for consumed result from SETRESULT() calls in multiline code
@@ -85,7 +85,13 @@ export function runExpression(
           // Execute as expression (existing behavior)
           const inlineExpression = normalizeInlineCalculationExpression(expr);
           phase = 'syntax';
-          const fn = new Function(...keys, `return (${inlineExpression});`);
+          const { fn, keys } = compileExpression(
+            inlineExpression,
+            secureContext,
+            'expression',
+            options.compileCache
+          );
+          const values = keys.map((key) => secureContext[key]);
           phase = 'runtime';
           const result = fn(...values);
           const consumed = __consumeResult();

package/src/engine/event-operation-scope.js

@@ -2,8 +2,11 @@ import {
   __invokeBoundEventBuiltin,
   __runWithEventOperationScope,
 } from '../builtins/event/event-operations-collector.js';
+import { EVENT_BUILTIN_DEFINITIONS } from '../builtins/builtin-definitions.js';
 
-const EVENT_OPERATION_BUILTINS = ['ALERT', 'SETVALUE', 'ON', 'OFF', 'INVALID'];
+const EVENT_OPERATION_BUILTINS = EVENT_BUILTIN_DEFINITIONS.filter((entry) => entry.operation).map(
+  (entry) => entry.name
+);
 
 /**
  * Create an operation scope owned by one synchronous event execution.
@@ -36,9 +39,10 @@ export function createEventOperationScope(onLateOperation) {
 /**
  * Bind canonical event operation builtins to their originating scope.
  * Intentional helper overrides are left untouched.
+ * ownsContext is private: only a fresh context owned by this execution may be modified.
  */
-export function bindEventBuiltins(context, canonicalBuiltins, scope) {
-  const boundContext = { ...context };
+export function bindEventBuiltins(context, canonicalBuiltins, scope, ownsContext = false) {
+  const boundContext = ownsContext ? context : { ...context };
 
   for (const name of EVENT_OPERATION_BUILTINS) {
     const builtin = canonicalBuiltins[name];

package/src/engine/event-policy.js

@@ -0,0 +1,61 @@
+import { BUILTIN_DEFINITIONS } from '../builtins/builtin-definitions.js';
+
+const operations = new Map(
+  BUILTIN_DEFINITIONS.filter((entry) => entry.operation).map((entry) => [
+    entry.name,
+    entry.operation,
+  ])
+);
+const knownEffects = new Set(['record-write', 'presentation', 'listeners', 'validation']);
+
+export function validateInteractionMode(mode) {
+  if (mode !== 'edit' && mode !== 'readonly') throw new Error('mode must be "edit" or "readonly".');
+  return mode;
+}
+
+/** Shared descriptor policy; permission comes from the engine, never event metadata. */
+export function eventOperationIssue(operation, mode, eventType) {
+  const declaration = operations.get(operation?.operation);
+  if (
+    !declaration ||
+    declaration.type !== operation?.type ||
+    !declaration.effects.length ||
+    declaration.effects.some((effect) => !knownEffects.has(effect))
+  )
+    return {
+      code: 'invalid_operation',
+      message: 'Event operations require declared, supported effects.',
+    };
+  const validation = /^(validate)-/.test(eventType);
+  const closing = /^(cancel|unload)-/.test(eventType);
+  if (declaration.effects.includes('validation')) {
+    return validation
+      ? null
+      : {
+          code: 'invalid_context',
+          message: 'INVALID() is only available during managed validation.',
+        };
+  }
+  if (validation || closing)
+    return {
+      code: 'operation_not_allowed',
+      message: 'Validation and close handlers cannot perform value, listener or UI operations.',
+    };
+  if (mode === 'readonly' && declaration.effects.includes('record-write'))
+    return {
+      code: 'readonly_operation_not_allowed',
+      message:
+        'View-mode handlers cannot change record data. Guard SETVALUE() with event.mode or move writable initialization to a new/edit handler.',
+    };
+  return null;
+}
+
+export function reportEventOperationIssue(warningSystem, issue, eventType) {
+  warningSystem.emitWarning({
+    type: 'EVENT_OPERATION_WARNING',
+    reason: issue.code,
+    severity: 'error',
+    message: issue.message,
+    executionContext: { type: 'event', eventType, fieldName: null },
+  });
+}

package/src/engine/event-registration.js

@@ -0,0 +1,38 @@
+import { parse } from 'acorn';
+import { ON } from '../builtins/event/control/on.js';
+
+/**
+ * Canonical ON calls with literal routes only create handlers; their bodies are not executed.
+ * Anything else needs the complete initialization context. Do not restrict handler body syntax.
+ */
+export function isLiteralEventRegistration(code, on) {
+  if (on !== ON || typeof code !== 'string') return false;
+  try {
+    const tree = parse(code, { ecmaVersion: 'latest', sourceType: 'commonjs' });
+    return (
+      tree.body.length > 0 &&
+      tree.body.every((statement) => {
+        const call = statement.expression;
+        if (
+          statement.type !== 'ExpressionStatement' ||
+          call.type !== 'CallExpression' ||
+          call.optional ||
+          call.callee.type !== 'Identifier' ||
+          call.callee.name !== 'ON' ||
+          ![2, 3].includes(call.arguments.length)
+        )
+          return false;
+        const callback = call.arguments.at(-1);
+        return (
+          ['FunctionExpression', 'ArrowFunctionExpression'].includes(callback.type) &&
+          call.arguments
+            .slice(0, -1)
+            .every((argument) => argument.type === 'Literal' && typeof argument.value === 'string')
+        );
+      })
+    );
+  } catch {
+    // Existing validation/execution owns syntax diagnostics.
+    return false;
+  }
+}

package/src/engine/event-source.js

@@ -1,10 +1,46 @@
 import { parse } from 'acorn';
 
 /** Retains authored callback source without depending on engine-specific toString output. */
-export function createEventSourceRegistry() {
+export function createEventSourceRegistry(preparationCache = new Map()) {
   const sources = new WeakMap();
 
-  function prepare(code, context) {
+  function bindPrepared(prepared, context, ownsContext) {
+    const propertyNames = new Map();
+    const capture = (callback, source, name) => {
+      sources.set(callback, source);
+      if (name && !callback.name)
+        Object.defineProperty(callback, 'name', { value: name, configurable: true });
+      return callback;
+    };
+    capture.key = (value, id) => {
+      const key = Reflect.ownKeys({ [value]: null })[0];
+      propertyNames.set(
+        id,
+        typeof key === 'symbol'
+          ? key.description === undefined
+            ? ''
+            : `[${key.description}]`
+          : key
+      );
+      return key;
+    };
+    capture.nameFor = (id) => propertyNames.get(id);
+
+    const captured = ownsContext ? context : { ...context };
+    Object.defineProperty(captured, prepared.captureName, {
+      value: capture,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+    return { code: prepared.code, context: captured };
+  }
+
+  // Metadata may be attached in place only to an execution-owned context, never host/engine state.
+  function prepare(code, context, ownsContext = false) {
+    const cached = preparationCache?.get(code);
+    if (cached && !Object.hasOwn(context, cached.captureName))
+      return bindPrepared(cached, context, ownsContext);
     let tree;
     try {
       // Event scripts are Function bodies, rather than modules or global scripts.
@@ -27,7 +63,6 @@ export function createEventSourceRegistry() {
     let captureName = '__form0CaptureEventSource';
     while (identifiers.has(captureName) || Object.hasOwn(context, captureName)) captureName += '_';
     const edits = [];
-    const propertyNames = new Map();
 
     function inferredName(node, parent) {
       if (node.id) return '';
@@ -120,33 +155,9 @@ export function createEventSourceRegistry() {
       prepared = prepared.slice(0, position) + text + prepared.slice(position);
     }
 
-    const capture = (callback, source, name) => {
-      sources.set(callback, source);
-      if (name && !callback.name)
-        Object.defineProperty(callback, 'name', { value: name, configurable: true });
-      return callback;
-    };
-    capture.key = (value, id) => {
-      const key = Reflect.ownKeys({ [value]: null })[0];
-      propertyNames.set(
-        id,
-        typeof key === 'symbol'
-          ? key.description === undefined
-            ? ''
-            : `[${key.description}]`
-          : key
-      );
-      return key;
-    };
-    capture.nameFor = (id) => propertyNames.get(id);
-
-    return {
-      code: prepared,
-      context: {
-        ...context,
-        [captureName]: capture,
-      },
-    };
+    const result = { code: prepared, captureName };
+    preparationCache?.set(code, result);
+    return bindPrepared(result, context, ownsContext);
   }
 
   function getSource(callback) {

package/src/engine/events.js

@@ -3,6 +3,7 @@ import { eventBuiltins } from '../builtins/registry.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
 import { createEventSourceRegistry } from './event-source.js';
+import { eventOperationIssue, reportEventOperationIssue } from './event-policy.js';
 import {
   bindEventBuiltins,
   closeEventOperationScope,
@@ -17,7 +18,7 @@ const _loggedHandlers = new Set();
  * EventManager handles form event registration and execution
  */
 export class EventManager {
-  constructor(schema = null, contextResolver = null, warningSystem = null) {
+  constructor(schema = null, contextResolver = null, warningSystem = null, preparation = {}) {
     this.listeners = new Map(); // eventType -> Map<fieldKey, callback[]>
     this.eventContext = null;
     this.securityConfig = null;
@@ -26,7 +27,9 @@ export class EventManager {
     this.contextResolver = contextResolver || (schema ? new ContextResolver(schema) : null);
     this.warningSystem = warningSystem || new WarningSystem();
     this.schema = schema;
-    this.callbackSources = createEventSourceRegistry();
+    this.callbackSources = createEventSourceRegistry(preparation.sourceCache);
+    this.compilationCache = preparation.compilationCache;
+    this.referenceSourceCache = preparation.referenceSourceCache;
     this.initializationIssues = [];
   }
 
@@ -61,10 +64,11 @@ export class EventManager {
 
     try {
       // Execute the code to register event listeners (same security as calculated fields).
-      const prepared = this.callbackSources.prepare(code, scopedContext);
+      const prepared = this.callbackSources.prepare(code, scopedContext, true);
       const result = runInEventOperationScope(scope, () =>
         runExpression(prepared.code, prepared.context, this.securityConfig, true, this.schema, {
           sourceExpression: code,
+          compileCache: this.compilationCache,
           onDiagnostic: (diagnostic) =>
             this.initializationIssues.push({
               code: 'initialization_failed',
@@ -298,13 +302,18 @@ export class EventManager {
       };
     }
 
-    contextWithEvent = bindEventBuiltins(contextWithEvent, eventBuiltins, scope);
+    // Each branch above supplies a private execution context; the manager base stays untouched.
+    contextWithEvent = bindEventBuiltins(contextWithEvent, eventBuiltins, scope, true);
 
     // Execute the callback function with the scoped context
     // This ensures EVAL() and other builtins have access to field values
     const functionCall = `(${callbackCode})(event)`;
+    // Retain nested ON callbacks created during a handler without depending on toString (Hermes).
+    const prepared = this.callbackSources.prepare(functionCall, contextWithEvent, true);
     return runInEventOperationScope(scope, () =>
-      runExpression(functionCall, contextWithEvent, this.securityConfig, true, this.schema, {
+      runExpression(prepared.code, prepared.context, this.securityConfig, true, this.schema, {
+        sourceExpression: functionCall,
+        compileCache: this.compilationCache,
         evaluateAsExpression: true,
         ...(managed?.reporting || {}),
       })
@@ -483,8 +492,10 @@ export class EventManager {
    * @param {Object} eventMetadata - Additional event metadata
    * @returns {Array} Array of operation descriptors
    */
-  trigger(eventType, fieldKey, eventMetadata) {
+  trigger(eventType, fieldKey, eventMetadata, mode = 'edit') {
     const operations = [];
+    const registrations = [];
+    let rejectedBatch = false;
     const eventMap = this.listeners.get(eventType);
 
     if (!eventMap) return operations;
@@ -496,6 +507,7 @@ export class EventManager {
       timestamp: Date.now(),
       // TODO: Add more metadata as needed
       ...eventMetadata,
+      mode,
     };
 
     // Create execution context for operation validation
@@ -517,35 +529,51 @@ export class EventManager {
       try {
         // Execute the callback with current form context
         // This ensures EVAL() and other builtins have access to field values
-        result = this.executeHandlerWithContext(callback, event, scope);
+        result = this.executeHandlerWithContext(callback, { ...event, mode }, scope);
       } catch (error) {
         // Simple error message for now
         console.warn(`[form0] Event listener failed: ${error.message}`);
       } finally {
         collectedOps = closeEventOperationScope(scope);
-        const runtimeOps = collectedOps.filter(
-          (operation) => operation?.type !== 'EVENT_OPERATION'
-        );
+        const runtimeOps = [];
+        for (const operation of collectedOps) {
+          const rejected = eventOperationIssue(operation, mode, eventType);
+          if (rejected) {
+            rejectedBatch = true;
+            reportEventOperationIssue(this.warningSystem, rejected, eventType);
+          } else if (operation.type === 'EVENT_OPERATION') registrations.push(operation);
+          else runtimeOps.push(operation);
+        }
 
         // Validate operations against context restrictions before adding them
         const validOps = this.validateOperations(runtimeOps, executionContext);
         operations.push(...validOps);
 
-        // EVENT_OPERATION processing is initialization-only. ON/OFF calls inside a handler neither
-        // mutate the listener registry nor leak internal registration descriptors to the host.
+        // Listener updates are committed after the entire permitted dispatch, never sent to hosts.
       }
 
       try {
         this.reportAsyncHandlerResult(result, executionContext, handlerName);
         // For backward compatibility, still handle returned operations
-        if (result && result.type === 'UI_OPERATION' && !collectedOps.includes(result)) {
-          operations.push(result);
+        if (
+          typeof result?.type === 'string' &&
+          result.type.endsWith('_OPERATION') &&
+          !collectedOps.includes(result)
+        ) {
+          const rejected = eventOperationIssue(result, mode, eventType);
+          if (rejected) {
+            rejectedBatch = true;
+            reportEventOperationIssue(this.warningSystem, rejected, eventType);
+          } else if (result.type === 'EVENT_OPERATION') registrations.push(result);
+          else operations.push(...this.validateOperations([result], executionContext));
         }
       } catch (error) {
         console.warn(`[form0] Event listener failed: ${error.message}`);
       }
     });
 
+    if (rejectedBatch) return [];
+    this.processEventOperations(registrations);
     return operations;
   }
 

package/src/engine/expression-compilation.js

@@ -0,0 +1,39 @@
+// Owned by the supplied compilation cache. Keep parameter names and functions only;
+// never retain record values, helper closures, permissions or diagnostic callbacks.
+const layoutsByCache = new WeakMap();
+
+export function compileExpression(code, context, mode, cache) {
+  const incomingKeys = Object.keys(context);
+  const body = mode === 'body' ? code : `return (${code});`;
+  if (!cache) return { keys: incomingKeys, fn: new Function(...incomingKeys, body) };
+
+  let expressions = layoutsByCache.get(cache);
+  if (!expressions) {
+    expressions = new Map();
+    layoutsByCache.set(cache, expressions);
+  }
+  const expressionKey = JSON.stringify([mode, code]);
+  const layouts = expressions.get(expressionKey) || [];
+  const index = layouts.findIndex(
+    (layout) =>
+      layout.incomingKeys.length === incomingKeys.length &&
+      layout.incomingKeys.every((key, position) => key === incomingKeys[position])
+  );
+  const existing = layouts[index];
+  // Respect explicit clearing/replacement of the caller-owned compilation cache.
+  if (existing && cache.get(existing.cacheKey) === existing.fn) return existing;
+
+  const keys = [...incomingKeys].sort();
+  const cacheKey = JSON.stringify([mode, keys, code]);
+  const fn = cache.get(cacheKey) ?? new Function(...keys, body);
+  cache.set(cacheKey, fn);
+  const layout = { incomingKeys, keys, cacheKey, fn };
+  const replacement =
+    index >= 0 ? index : layouts.findIndex((entry) => entry.cacheKey === cacheKey);
+  if (replacement >= 0) layouts[replacement] = layout;
+  else {
+    layouts.push(layout);
+  }
+  expressions.set(expressionKey, layouts);
+  return layout;
+}

package/src/engine/form-engine.js

@@ -17,6 +17,9 @@ import { buildCalculationDependencyPlan } from '../utilities/calculation-depende
 import { createCalculationDiagnostics } from './calculation-diagnostics.js';
 import { formatLocalDate } from '../utilities/date-utils.js';
 import { createManagedEventDispatcher } from './managed-events.js';
+import { validateInteractionMode } from './event-policy.js';
+import { copyRecordData } from '../utilities/record-data.js';
+import { areStructuredValuesEqual } from '../utilities/value-equality.js';
 
 /**
  * @typedef {Object} CalculationDiagnostic
@@ -53,6 +56,7 @@ import { createManagedEventDispatcher } from './managed-events.js';
  * @param {Object} [options.initialValues]
  * @param {Object} [options.helpers]
  * @param {Object} [options.security]
+ * @param {'edit'|'readonly'} [options.mode='edit'] View preserves supplied calculations/defaults.
  * @param {WarningSystem} [options.warningSystem]
  * @param {Array} [options.runtimeDiagnostics] Deprecated append-only compatibility adapter.
  * Use getDiagnostics() for the latest snapshot or onDiagnostics for evaluation notifications.
@@ -75,15 +79,18 @@ export function createFormEngine({
   diagnostics = {},
   onDiagnostics = null,
   eventScope = { instancePath: [] },
+  mode = 'edit',
 }) {
+  let interactionMode = validateInteractionMode(mode);
   const { schema: preparedSchema, buildingPlanMeta } = expandBuildingPlanSchema(schema);
 
   const contextResolver = new ContextResolver(preparedSchema.form);
   validateSchemaWithContext(preparedSchema.form, contextResolver);
 
   const { form } = preparedSchema;
-  const values = { ...initialValues };
+  const values = copyRecordData(initialValues);
   const allFields = flattenFields(form.elements);
+  const pendingDefaults = new Map();
 
   // Create a lookup map for choice fields
   const choiceFieldMap = new Map();
@@ -104,7 +111,11 @@ export function createFormEngine({
   for (const field of allFields) {
     if (!(field.data_name in values)) {
       // Initialize field with default value if specified
-      values[field.data_name] = getDefaultValue(field);
+      values[field.data_name] = getDefaultValue(
+        interactionMode === 'readonly' ? { ...field, default_value: null } : field
+      );
+      if (interactionMode === 'readonly')
+        pendingDefaults.set(field, copyRecordData(values[field.data_name]));
     } else if (field.type === 'SingleChoiceField' || field.type === 'BooleanField') {
       // Enrich SingleChoiceField and BooleanField values with labels from schema
       const fieldValue = values[field.data_name];
@@ -163,11 +174,16 @@ export function createFormEngine({
   const eventManager = new EventManager(form, contextResolver, sharedWarningSystem);
   eventManager.securityConfig = security; // Pass security config
   const eventHelpers = { ...eventBuiltins, ...helpers };
-  const dispatchManagedEvent = createManagedEventDispatcher(eventManager, eventScope);
+  const getMode = () => interactionMode;
+  const dispatchManagedEvent = createManagedEventDispatcher(eventManager, eventScope, getMode);
 
   // Initialize event code if present
   if (form.events && form.events.code) {
-    const eventContext = buildEventContext(values, eventHelpers, {});
+    const eventContext = buildEventContext(
+      interactionMode === 'readonly' ? copyRecordData(values) : values,
+      eventHelpers,
+      {}
+    );
     eventManager.initializeEventCode(form.events.code, eventContext);
   }
 
@@ -187,17 +203,18 @@ export function createFormEngine({
   function evalForm() {
     const frame = calculationDiagnostics.begin();
     try {
-      evaluateCalculatedFields(
-        form,
-        values,
-        allHelpers,
-        security,
-        contextResolver,
-        sharedWarningSystem,
-        runtimeDiagnostics,
-        calculationPlan,
-        calculationDiagnostics
-      );
+      if (interactionMode === 'edit')
+        evaluateCalculatedFields(
+          form,
+          values,
+          allHelpers,
+          security,
+          contextResolver,
+          sharedWarningSystem,
+          runtimeDiagnostics,
+          calculationPlan,
+          calculationDiagnostics
+        );
       evaluateRequirement(form, values, required, conditionContext);
       evaluateVisibility(form, values, visible, conditionContext);
       evaluateReadOnly(form, values, read_only, conditionContext);
@@ -211,19 +228,35 @@ export function createFormEngine({
 
   function trigger(eventType, fieldKey, metadata = {}) {
     // Update event context with current values for event execution
-    const eventContext = buildEventContext(values, eventHelpers, {
-      eventType,
-      fieldKey,
-      ...metadata,
-    });
+    const eventContext = buildEventContext(
+      interactionMode === 'readonly' ? copyRecordData(values) : values,
+      eventHelpers,
+      {
+        eventType,
+        fieldKey,
+        ...metadata,
+      }
+    );
     eventManager.eventContext = eventContext; // Update the event context
-    return eventManager.trigger(eventType, fieldKey, metadata);
+    return eventManager.trigger(eventType, fieldKey, metadata, interactionMode);
   }
 
   function getState() {
     return { values, errors, visible, required, read_only };
   }
 
+  /** Host-owned mode changes do not replay events, restore a record or evaluate implicitly. */
+  function setMode(nextMode) {
+    interactionMode = validateInteractionMode(nextMode);
+    if (interactionMode === 'edit') {
+      for (const [field, placeholder] of pendingDefaults) {
+        if (areStructuredValuesEqual(values[field.data_name], placeholder))
+          values[field.data_name] = copyRecordData(getDefaultValue(field));
+      }
+      pendingDefaults.clear();
+    }
+  }
+
   /**
    * Dispatch synchronously within this engine's construction scope. No operations are applied.
    * @param {string} eventType Registered event name.
@@ -238,6 +271,8 @@ export function createFormEngine({
 
   return {
     eval: evalForm,
+    getMode,
+    setMode,
     trigger,
     triggerDetailed,
     getState,
@@ -249,7 +284,7 @@ export function createFormEngine({
   };
 }
 
-function getDefaultValue(field) {
+export function getDefaultValue(field) {
   const spec = FIELD_SPECS[field.type];
   if (spec && spec.defaultProducer) {
     return spec.defaultProducer(field);