form0-core 0.4.0 → 0.5.0

package/README.md

@@ -79,13 +79,51 @@ 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.
+events; `triggerDetailed()` for managed events and custom validation; and `getState()` for current
+values and evaluated field state.
 
 Schema event callbacks retain their authored source, so ordinary functions and arrows defined in
 `form.events.code` also work on Hermes. Each dispatch uses current scoped field values; initialization
 runs once. Local initialization variables are not captured. Callbacks supplied by host helpers still
 require executable `toString()` output; unavailable source produces an event warning.
 
+## Managed events and custom validation
+
+Use synchronous `engine.triggerDetailed(eventType, fieldDataName, metadata)` to receive defensive
+`operations`, `validationIssues` and execution `issues`. It does not evaluate, apply operations,
+persist or close an editor. Inspect issues before applying a batch; execution failures return no
+applicable operations. The existing `trigger()` operation-array interface retains its legacy behavior.
+
+```js
+// In schema.form.events.code:
+ON('validate-record', function (event) {
+  if ($amount < 4) INVALID('Amount must be at least four.');
+});
+
+// In the host, after evaluating the intended snapshot:
+const result = engine.triggerDetailed('validate-record', undefined, {
+  isDraft: false,
+  isValid: true,
+});
+console.log(result.validationIssues);
+```
+
+`INVALID()` requires a nonempty string and is valid only during managed validation. Findings remain
+separate from intrinsic field errors and calculation diagnostics. Validation handlers cannot return
+value or UI operations; cancel/unload handlers are read-only notifications. Promise-returning schema
+handlers are rejected, and late operations cannot enter a later dispatch.
+
+Root scope defaults to `[]`. Headless row engines must provide `eventScope.instancePath` at creation,
+using complete repeatable keys and existing IDs (or explicit positional identity). Managed row
+handlers can read current, ancestor and main fields supplied by the host, but `SETVALUE()` writes
+only current-row fields. Dispatch metadata cannot replace engine scope or event identity.
+
+See [the maintained event contract](https://github.com/paqu-io/form0-core/blob/main/EVENT_CONTRACT.md)
+for routing, supported events, metadata,
+failure behavior and the subsequent binding adoption. Core does not introduce automatic renderer
+lifecycle or save preparation by itself. Applications retain persistence and closing ownership;
+`save-*` events are pre-save, with no `saved-*` schema events.
+
 ## Calculation diagnostics
 
 Diagnostics are collected automatically, including when console reporting is disabled:
@@ -172,6 +210,18 @@ Record utilities follow this contract:
 
 Record status remains top-level as `@status`; it is not stored inside `form_values`.
 
+## Authoring mutation validation
+
+`getFormAuthoringContext({ schema })` includes `mutationOperationCatalog`: the installed operation
+formats, required parameters, and examples. `mutationOperations` remains the list of supported names.
+Use these formats with `applyFormMutationBatch`; for example, a rename uses
+`{ op: 'updateForm', changes: { name: 'Renamed form' } }`, not a `patch` parameter.
+
+Malformed operations, unknown operation parameters, and empty change objects are rejected atomically
+with diagnostics, rather than silently ignored. Clearing a title/status field, calculation, or event
+code requires its explicit parameter (for example, `field: null`), not an omitted value. Valid
+idempotent batches remain valid in core; consumers should check actual changes before offering to save.
+
 ## ✅ Requirements
 
 - Node.js 22 or newer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
@@ -12,9 +12,9 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "test": "node tests/form0-core.test.js && node tests/conditions.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/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",
+    "test": "node tests/form0-core.test.js && node tests/conditions.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",
+    "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",

package/src/authoring/form-authoring.js

@@ -16,17 +16,77 @@ import {
 } 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 FIELD_KEY_PARAMETER = Object.freeze({ type: 'string', minLength: 1 });
+const CHANGES_PARAMETER = Object.freeze({ type: 'object', minProperties: 1 });
+const PLACEMENT_PARAMETERS = Object.freeze({
+  parentKey: { type: ['string', 'null'], minLength: 1 },
+  position: {
+    type: ['object', 'null'],
+    properties: { beforeKey: FIELD_KEY_PARAMETER, afterKey: FIELD_KEY_PARAMETER },
+    maxProperties: 1,
+    description: 'Use one sibling key, or omit position to append in the target container.',
+  },
+});
+const MUTATION_OPERATION_CATALOG = Object.freeze([
+  {
+    op: 'updateForm',
+    description:
+      'Update form attributes; elements, events, title_field and status_field use dedicated operations.',
+    required: ['changes'],
+    parameters: { changes: CHANGES_PARAMETER },
+    example: { op: 'updateForm', changes: { name: 'Renamed form' } },
+  },
+  {
+    op: 'addField',
+    description: 'Add a complete field matching fieldSpecs; missing keys are generated.',
+    required: ['field'],
+    parameters: { field: { type: 'object', minProperties: 1 }, ...PLACEMENT_PARAMETERS },
+  },
+  {
+    op: 'updateField',
+    description: 'Update an existing field by key; type changes require remove/add.',
+    required: ['fieldKey', 'changes'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER, changes: CHANGES_PARAMETER },
+    example: { op: 'updateField', fieldKey: 'existing-field-key', changes: { label: 'New label' } },
+  },
+  {
+    op: 'moveField',
+    description: 'Move an existing field by key to a container/sibling position.',
+    required: ['fieldKey'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER, ...PLACEMENT_PARAMETERS },
+  },
+  {
+    op: 'removeField',
+    description: 'Remove an existing field by key only if it is unreferenced.',
+    required: ['fieldKey'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER },
+  },
+  {
+    op: 'setTitleField',
+    description: 'Set a complete title field, or explicitly pass field: null to clear it.',
+    required: ['field'],
+    parameters: { field: { type: ['object', 'null'] } },
+  },
+  {
+    op: 'setStatusField',
+    description: 'Set a complete status field, or explicitly pass field: null to clear it.',
+    required: ['field'],
+    parameters: { field: { type: ['object', 'null'] } },
+  },
+  {
+    op: 'setCalculation',
+    description: 'Set a CalculatedField expression by key; null explicitly clears it.',
+    required: ['fieldKey', 'expression'],
+    parameters: { fieldKey: FIELD_KEY_PARAMETER, expression: { type: ['string', 'null'] } },
+  },
+  {
+    op: 'setFormEventCode',
+    description: 'Set form event code; an empty string or null explicitly clears it.',
+    required: ['code'],
+    parameters: { code: { type: ['string', 'null'] } },
+  },
 ]);
+const MUTATION_OPERATIONS = Object.freeze(MUTATION_OPERATION_CATALOG.map(({ op }) => op));
 
 const CALCULATION_GUIDANCE = Object.freeze({
   version: 1,
@@ -306,16 +366,66 @@ function mutationError(index, operation, error) {
   };
 }
 
+function validateMutationParameter(value, spec, path) {
+  const type = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+  const types = Array.isArray(spec.type) ? spec.type : [spec.type];
+  if (!types.includes(type)) throw new Error(`${path} must be ${types.join(' or ')}`);
+  if (value === null) return;
+  if (spec.minLength && value.length < spec.minLength) {
+    throw new Error(`${path} must not be empty`);
+  }
+  if (spec.minProperties && Object.keys(value).length < spec.minProperties) {
+    throw new Error(`${path} must be a non-empty object`);
+  }
+  if (spec.maxProperties && Object.keys(value).length > spec.maxProperties) {
+    throw new Error(`${path} must specify at most one property`);
+  }
+  if (spec.properties) {
+    for (const key of Object.keys(value)) {
+      if (!Object.hasOwn(spec.properties, key)) {
+        throw new Error(`Unexpected mutation parameter '${path}.${key}'`);
+      }
+      validateMutationParameter(value[key], spec.properties[key], `${path}.${key}`);
+    }
+  }
+}
+
+function validateMutationOperation(operation) {
+  if (!operation || typeof operation !== 'object' || Array.isArray(operation)) {
+    throw new Error('A mutation operation must be an object with an op property');
+  }
+  const definition = MUTATION_OPERATION_CATALOG.find(({ op }) => op === operation.op);
+  if (!definition) throw new Error(`Unsupported mutation operation '${operation.op}'`);
+  for (const name of definition.required) {
+    if (!Object.hasOwn(operation, name) || operation[name] === undefined) {
+      const example = definition.example ? ` Example: ${JSON.stringify(definition.example)}` : '';
+      throw new Error(`${operation.op} requires '${name}'.${example}`);
+    }
+  }
+  for (const name of Object.keys(operation)) {
+    if (name === 'op') continue;
+    if (!Object.hasOwn(definition.parameters, name)) {
+      throw new Error(`Unexpected ${operation.op} parameter '${name}'`);
+    }
+    validateMutationParameter(
+      operation[name],
+      definition.parameters[name],
+      `${operation.op}.${name}`
+    );
+  }
+}
+
 function applyMutation(root, operation) {
+  validateMutationOperation(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 || {})) {
+      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 || {}));
+      Object.assign(form, deepClone(operation.changes));
       return `Updated form attributes`;
     }
     case 'addField': {
@@ -340,7 +450,7 @@ function applyMutation(root, operation) {
       }
       const original = deepClone(target.field);
       const children = target.field.elements;
-      Object.assign(target.field, deepClone(operation.changes || {}));
+      Object.assign(target.field, deepClone(operation.changes));
       if (
         target.field.data_name !== original.data_name &&
         [...fields.values()].some(
@@ -473,6 +583,7 @@ export function getFormAuthoringContext({ schema, coreVersion = null }) {
     revision: getFormSchemaRevision(root),
     schema: deepClone(root),
     mutationOperations: [...MUTATION_OPERATIONS],
+    mutationOperationCatalog: deepClone(MUTATION_OPERATION_CATALOG),
     fieldSpecs,
     operators,
     eventTypes: getAllEventTypes(),

package/src/builtins/builtin-definitions.js

@@ -272,6 +272,18 @@ export const OFF_METADATA = defineBuiltinMetadata({
   contexts: [BUILTIN_CONTEXTS.EVENT],
 });
 
+export const INVALID_METADATA = defineBuiltinMetadata({
+  name: 'INVALID',
+  category: 'event',
+  signature: 'INVALID(message)',
+  description:
+    'Report a scope-level custom validation message during managed validate-record or validate-repeatable execution. Requires a nonempty string; does not modify field errors.',
+  examples: [
+    "ON('validate-record', function(event) { if ($amount < 4) INVALID('Amount must be at least four.'); })",
+  ],
+  contexts: [BUILTIN_CONTEXTS.EVENT],
+});
+
 export const BUILTIN_DEFINITIONS = Object.freeze([
   IF_METADATA,
   AND_METADATA,
@@ -302,6 +314,7 @@ export const BUILTIN_DEFINITIONS = Object.freeze([
   SETVALUE_METADATA,
   ON_METADATA,
   OFF_METADATA,
+  INVALID_METADATA,
 ]);
 
 function filterDefinitionsByContext(context) {

package/src/builtins/event/control/invalid.js

@@ -0,0 +1,17 @@
+import { __collectEventOperation } from '../event-operations-collector.js';
+export { INVALID_METADATA } from '../../builtin-definitions.js';
+
+/**
+ * @builtin INVALID
+ * See builtin-definitions.js for the authoritative catalog entry.
+ * @param {string} message
+ * @returns {Object} Validation descriptor consumed by managed validation execution.
+ */
+export function INVALID(message) {
+  if (typeof message !== 'string' || !message.trim()) {
+    throw new Error('INVALID() requires a nonempty string.');
+  }
+  const operation = { type: 'VALIDATION_OPERATION', operation: 'INVALID', params: { message } };
+  if (!__collectEventOperation(operation)) throw new Error('INVALID() requires an event scope.');
+  return operation;
+}

package/src/builtins/event/event-operations-collector.js

@@ -8,6 +8,7 @@ let boundScope = null;
 export function __collectEventOperation(operation) {
   const scope = boundScope || activeScope;
   scope?.collect(operation);
+  return Boolean(scope);
 }
 
 /**

package/src/builtins/registry.js

@@ -44,6 +44,7 @@ import { ALERT, ALERT_METADATA } from './event/ui/alert.js';
 import { SETVALUE, SETVALUE_METADATA } from './event/field/setvalue.js';
 import { ON, ON_METADATA } from './event/control/on.js';
 import { OFF, OFF_METADATA } from './event/control/off.js';
+import { INVALID, INVALID_METADATA } from './event/control/invalid.js';
 
 export { IF, IF_METADATA } from './logical/if.js';
 export { AND, AND_METADATA } from './logical/and.js';
@@ -86,6 +87,7 @@ export { ALERT, ALERT_METADATA } from './event/ui/alert.js';
 export { SETVALUE, SETVALUE_METADATA } from './event/field/setvalue.js';
 export { ON, ON_METADATA } from './event/control/on.js';
 export { OFF, OFF_METADATA } from './event/control/off.js';
+export { INVALID, INVALID_METADATA } from './event/control/invalid.js';
 
 const RUNTIME_ENTRIES = Object.freeze([
   { implementation: IF, definition: IF_METADATA },
@@ -117,6 +119,7 @@ const RUNTIME_ENTRIES = Object.freeze([
   { implementation: SETVALUE, definition: SETVALUE_METADATA },
   { implementation: ON, definition: ON_METADATA },
   { implementation: OFF, definition: OFF_METADATA },
+  { implementation: INVALID, definition: INVALID_METADATA },
 ]);
 
 function buildBuiltinObject(context) {

package/src/engine/event-field-references.js

@@ -0,0 +1,127 @@
+import { parse } from 'acorn';
+
+const isFunction = (node) =>
+  ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(node?.type);
+
+function bindPattern(node, names) {
+  if (!node) return;
+  if (node.type === 'Identifier') names.add(node.name);
+  else if (node.type === 'RestElement') bindPattern(node.argument, names);
+  else if (node.type === 'AssignmentPattern') bindPattern(node.left, names);
+  else if (node.type === 'ArrayPattern')
+    node.elements.forEach((element) => bindPattern(element, names));
+  else if (node.type === 'ObjectPattern')
+    node.properties.forEach((property) =>
+      bindPattern(property.type === 'RestElement' ? property.argument : property.value, names)
+    );
+}
+
+function children(node, visit) {
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) value.forEach((child) => child?.type && visit(child));
+    else if (value?.type) visit(value);
+  }
+}
+
+function bindVars(node, names) {
+  if (
+    !node ||
+    isFunction(node) ||
+    ['ClassDeclaration', 'ClassExpression', 'StaticBlock'].includes(node.type)
+  )
+    return;
+  if (node.type === 'VariableDeclaration' && node.kind === 'var')
+    node.declarations.forEach((declaration) => bindPattern(declaration.id, names));
+  children(node, (child) => bindVars(child, names));
+}
+
+function bindDeclarations(statements, names) {
+  for (const statement of statements) {
+    if (statement.type === 'VariableDeclaration' && statement.kind !== 'var')
+      statement.declarations.forEach((declaration) => bindPattern(declaration.id, names));
+    else if (['ClassDeclaration', 'FunctionDeclaration'].includes(statement.type))
+      bindPattern(statement.id, names);
+  }
+}
+
+/** Free $field identifiers only: strings, comments, property names and local bindings are excluded. */
+export function getEventFieldReferences(source) {
+  const tree = parse(`(${source})`, { ecmaVersion: 'latest' });
+  const references = new Set();
+  const newScope = (parent) => ({ names: new Set(), parent });
+  function bound(scope, name) {
+    return scope && (scope.names.has(name) || bound(scope.parent, name));
+  }
+  function patternExpressions(node, scope) {
+    if (!node || node.type === 'Identifier') return;
+    if (node.type === 'AssignmentPattern') {
+      patternExpressions(node.left, scope);
+      walk(node.right, scope);
+    } else if (node.type === 'RestElement') patternExpressions(node.argument, scope);
+    else if (node.type === 'ArrayPattern')
+      node.elements.forEach((element) => patternExpressions(element, scope));
+    else if (node.type === 'ObjectPattern')
+      node.properties.forEach((property) => {
+        if (property.computed) walk(property.key, scope);
+        patternExpressions(
+          property.type === 'RestElement' ? property.argument : property.value,
+          scope
+        );
+      });
+  }
+  function walk(node, scope) {
+    if (!node) return;
+    if (isFunction(node)) {
+      const local = newScope(scope);
+      bindPattern(node.id, local.names);
+      node.params.forEach((param) => bindPattern(param, local.names));
+      node.params.forEach((param) => patternExpressions(param, local));
+      bindVars(node.body, local.names);
+      walk(node.body, local);
+    } else if (node.type === 'BlockStatement' || node.type === 'StaticBlock') {
+      const local = newScope(scope);
+      if (node.type === 'StaticBlock') node.body.forEach((part) => bindVars(part, local.names));
+      bindDeclarations(node.body, local.names);
+      node.body.forEach((statement) => walk(statement, local));
+    } else if (['ForStatement', 'ForOfStatement', 'ForInStatement'].includes(node.type)) {
+      const local = newScope(scope);
+      const declaration = node.init || node.left;
+      if (declaration?.type === 'VariableDeclaration')
+        declaration.declarations.forEach((part) => bindPattern(part.id, local.names));
+      children(node, (child) => walk(child, local));
+    } else if (node.type === 'SwitchStatement') {
+      walk(node.discriminant, scope);
+      const local = newScope(scope);
+      bindDeclarations(
+        node.cases.flatMap((part) => part.consequent),
+        local.names
+      );
+      node.cases.forEach((part) => walk(part, local));
+    } else if (node.type === 'CatchClause') {
+      const local = newScope(scope);
+      bindPattern(node.param, local.names);
+      walk(node.body, local);
+    } else if (node.type === 'VariableDeclarator') {
+      patternExpressions(node.id, scope);
+      walk(node.init, scope);
+    } else if (node.type === 'LabeledStatement') {
+      walk(node.body, scope);
+    } else if (node.type === 'BreakStatement' || node.type === 'ContinueStatement') {
+      return;
+    } else if (
+      ['MemberExpression', 'Property', 'PropertyDefinition', 'MethodDefinition'].includes(node.type)
+    ) {
+      if (node.computed) walk(node.property || node.key, scope);
+      walk(node.object || node.value, scope);
+    } else if (node.type === 'ClassExpression' || node.type === 'ClassDeclaration') {
+      const local = newScope(scope);
+      bindPattern(node.id, local.names);
+      walk(node.superClass, scope);
+      walk(node.body, local);
+    } else if (node.type === 'Identifier') {
+      if (node.name.startsWith('$') && !bound(scope, node.name)) references.add(node.name.slice(1));
+    } else children(node, (child) => walk(child, scope));
+  }
+  walk(tree, newScope(null));
+  return references;
+}

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

@@ -3,7 +3,7 @@ import {
   __runWithEventOperationScope,
 } from '../builtins/event/event-operations-collector.js';
 
-const EVENT_OPERATION_BUILTINS = ['ALERT', 'SETVALUE', 'ON', 'OFF'];
+const EVENT_OPERATION_BUILTINS = ['ALERT', 'SETVALUE', 'ON', 'OFF', 'INVALID'];
 
 /**
  * Create an operation scope owned by one synchronous event execution.

package/src/engine/event-registry.js

@@ -23,6 +23,9 @@ export const EVENT_REGISTRY = {
   'new-record': { category: 'record', scope: 'main' },
   'save-record': { category: 'record', scope: 'main' },
   'validate-record': { category: 'record', scope: 'main' },
+  'unload-record': { category: 'record', scope: 'main' },
+  'cancel-record': { category: 'record', scope: 'main' },
+  'change-status': { category: 'record', scope: 'main' },
 
   // Field-level events (contextual scope)
   change: { category: 'field', scope: 'contextual' },
@@ -36,6 +39,8 @@ export const EVENT_REGISTRY = {
   'edit-repeatable': { category: 'repeatable', scope: 'repeatable' },
   'save-repeatable': { category: 'repeatable', scope: 'repeatable' },
   'validate-repeatable': { category: 'repeatable', scope: 'repeatable' },
+  'unload-repeatable': { category: 'repeatable', scope: 'repeatable' },
+  'cancel-repeatable': { category: 'repeatable', scope: 'repeatable' },
 };
 
 /**
@@ -44,7 +49,9 @@ export const EVENT_REGISTRY = {
  * @returns {Object} Event info with category and scope, or default for unknown events
  */
 export function getEventInfo(eventType) {
-  return EVENT_REGISTRY[eventType] || { category: 'unknown', scope: 'main' };
+  return Object.hasOwn(EVENT_REGISTRY, eventType)
+    ? EVENT_REGISTRY[eventType]
+    : { category: 'unknown', scope: 'main' };
 }
 
 /**
@@ -53,7 +60,7 @@ export function getEventInfo(eventType) {
  * @returns {boolean} True if the event type is registered
  */
 export function isValidEventType(eventType) {
-  return eventType in EVENT_REGISTRY;
+  return Object.hasOwn(EVENT_REGISTRY, eventType);
 }
 
 /**

package/src/engine/events.js

@@ -27,6 +27,7 @@ export class EventManager {
     this.warningSystem = warningSystem || new WarningSystem();
     this.schema = schema;
     this.callbackSources = createEventSourceRegistry();
+    this.initializationIssues = [];
   }
 
   /**
@@ -64,11 +65,28 @@ export class EventManager {
       const result = runInEventOperationScope(scope, () =>
         runExpression(prepared.code, prepared.context, this.securityConfig, true, this.schema, {
           sourceExpression: code,
+          onDiagnostic: (diagnostic) =>
+            this.initializationIssues.push({
+              code: 'initialization_failed',
+              message: diagnostic.message,
+            }),
         })
       );
-      this.reportAsyncHandlerResult(result, executionContext, 'form.events.code');
+      if (this.reportAsyncHandlerResult(result, executionContext, 'form.events.code')) {
+        this.initializationIssues.push({
+          code: 'async_handler_unsupported',
+          message: 'Event initialization must be synchronous.',
+        });
+      }
     } finally {
-      this.processEventOperations(closeEventOperationScope(scope));
+      const operations = closeEventOperationScope(scope);
+      if (operations.some((operation) => operation?.operation === 'INVALID')) {
+        this.initializationIssues.push({
+          code: 'invalid_context',
+          message: 'INVALID() cannot run while registering event handlers.',
+        });
+      }
+      this.processEventOperations(operations);
     }
   }
 
@@ -114,7 +132,7 @@ export class EventManager {
       then = result.then;
     } catch {
       this.emitHandlerWarning('async_handler_rejected', executionContext, handlerName);
-      return;
+      return true;
     }
 
     if (typeof then !== 'function') return;
@@ -123,6 +141,7 @@ export class EventManager {
     Promise.resolve(result).catch(() => {
       this.emitHandlerWarning('async_handler_rejected', executionContext, handlerName);
     });
+    return true;
   }
 
   /**
@@ -249,7 +268,7 @@ export class EventManager {
    * @param {Object} event - The event object
    * @returns {*} The result of the event handler
    */
-  executeHandlerWithContext(callback, event, scope) {
+  executeHandlerWithContext(callback, event, scope, managed = null) {
     // Create execution context for this event
     const executionContext = {
       type: 'event',
@@ -258,11 +277,13 @@ export class EventManager {
     };
 
     // Get the callback code for field reference analysis
-    const callbackCode = this.callbackSources.getSource(callback);
+    const callbackCode = managed?.source ?? this.callbackSources.getSource(callback);
 
     // Build scoped context if context resolver is available
     let contextWithEvent;
-    if (this.contextResolver && this.warningSystem) {
+    if (managed) {
+      contextWithEvent = managed.context;
+    } else if (this.contextResolver && this.warningSystem) {
       contextWithEvent = this.buildScopedEventContext(
         this.eventContext,
         executionContext,
@@ -285,6 +306,7 @@ export class EventManager {
     return runInEventOperationScope(scope, () =>
       runExpression(functionCall, contextWithEvent, this.securityConfig, true, this.schema, {
         evaluateAsExpression: true,
+        ...(managed?.reporting || {}),
       })
     );
   }

package/src/engine/form-engine.js

@@ -15,6 +15,7 @@ import { expandBuildingPlanSchema } from '../schema/building-plan-expander.js';
 import { buildCalculationDependencyPlan } from '../utilities/calculation-dependencies.js';
 import { createCalculationDiagnostics } from './calculation-diagnostics.js';
 import { formatLocalDate } from '../utilities/date-utils.js';
+import { createManagedEventDispatcher } from './managed-events.js';
 
 /**
  * @typedef {Object} CalculationDiagnostic
@@ -27,6 +28,23 @@ import { formatLocalDate } from '../utilities/date-utils.js';
  * @property {Object} context JSON-safe metadata; no expression source, values or stack.
  */
 
+/**
+ * @typedef {Object} ManagedValidationIssue
+ * @property {string} message Scope-level message, without an invented field association.
+ * @property {Object[]} instancePath Complete engine-owned row ancestry; [] for root.
+ *
+ * @typedef {Object} ManagedEventIssue
+ * @property {string} code Stable execution failure identifier.
+ * @property {string} message
+ * @property {string|null} eventType Null for a malformed event-type argument.
+ * @property {Object[]} instancePath
+ *
+ * @typedef {Object} ManagedEventResult
+ * @property {Object[]} operations Defensive accepted operation batch; [] on execution failure.
+ * @property {ManagedValidationIssue[]} validationIssues Fresh findings for this attempt.
+ * @property {ManagedEventIssue[]} issues Execution failures, separate from validation findings.
+ */
+
 /**
  * Create a form engine. Calculations collect diagnostics independently of validation.
  * @param {Object} options
@@ -40,6 +58,9 @@ import { formatLocalDate } from '../utilities/date-utils.js';
  * @param {{console?: boolean}} [options.diagnostics] Omit console to preserve legacy reporting.
  * @param {(snapshot: CalculationDiagnostic[]) => (void|Promise<void>)} [options.onDiagnostics]
  * Called once per completed evaluation, including empty/identical snapshots. Failures are isolated.
+ * @param {{scopeId?: string, instancePath: Array<{repeatableKey: string, instanceId: string|number|null, index: number, identity: 'id'|'position'}>}} [options.eventScope]
+ * Managed event ownership, fixed for this engine lifetime. Root is []; headless row engines must
+ * provide the complete repeatable path. triggerDetailed() never evaluates or applies operations.
  * @returns {Object} Engine with getDiagnostics(): defensive copy of latest evaluation (initially []).
  */
 
@@ -52,6 +73,7 @@ export function createFormEngine({
   runtimeDiagnostics = null,
   diagnostics = {},
   onDiagnostics = null,
+  eventScope = { instancePath: [] },
 }) {
   const { schema: preparedSchema, buildingPlanMeta } = expandBuildingPlanSchema(schema);
 
@@ -139,6 +161,7 @@ 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);
 
   // Initialize event code if present
   if (form.events && form.events.code) {
@@ -199,9 +222,22 @@ export function createFormEngine({
     return { values, errors, visible, required, read_only };
   }
 
+  /**
+   * Dispatch synchronously within this engine's construction scope. No operations are applied.
+   * @param {string} eventType Registered event name.
+   * @param {string} [fieldKey] Field/repeatable data_name; omitted for record lifecycle events.
+   * @param {Object} [metadata] Portable host metadata; dispatcher-owned identity is authoritative.
+   * @returns {ManagedEventResult}
+   */
+  function triggerDetailed(eventType, fieldKey, metadata = {}) {
+    eventManager.eventContext = buildEventContext(values, eventHelpers, {});
+    return dispatchManagedEvent(eventType, fieldKey, metadata);
+  }
+
   return {
     eval: evalForm,
     trigger,
+    triggerDetailed,
     getState,
     getDiagnostics: calculationDiagnostics.getSnapshot,
     getWarningSystem: () => sharedWarningSystem,

package/src/engine/managed-events.js

@@ -0,0 +1,238 @@
+import { getEventInfo, isValidEventType } from './event-registry.js';
+import { closeEventOperationScope, createEventOperationScope } from './event-operation-scope.js';
+import { getEventFieldReferences } from './event-field-references.js';
+
+// Portable defensive copies also work in runtimes without structuredClone (including Hermes).
+function copy(value, seen = new Map()) {
+  if (typeof value === 'function' || typeof value === 'symbol')
+    throw new Error('Event data must not contain functions or symbols.');
+  if (value === null || typeof value !== 'object') return value;
+  if (seen.has(value)) return seen.get(value);
+  if (value instanceof Date) return new Date(value.getTime());
+  if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    throw new Error('Event data must use plain objects, arrays or dates.');
+  const result = Array.isArray(value) ? [] : {};
+  seen.set(value, result);
+  for (const key of Object.keys(value)) {
+    Object.defineProperty(result, key, {
+      value: copy(value[key], seen),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return result;
+}
+
+/** Internal adapter; the public synchronous API is engine.triggerDetailed(). */
+export function createManagedEventDispatcher(manager, constructionScope) {
+  const instancePath = copy(constructionScope?.instancePath);
+  const scopeId = constructionScope?.scopeId;
+  if (scopeId !== undefined && (typeof scopeId !== 'string' || !scopeId.trim()))
+    throw new Error('eventScope.scopeId must be a nonempty string when supplied.');
+  const resolver = manager.contextResolver;
+  const fields = new Map(resolver.fieldOwnership);
+  const statusField = manager.schema?.status_field;
+  if (statusField?.enabled && typeof statusField.data_name === 'string')
+    fields.set(statusField.data_name, { field: statusField, parentPath: [] });
+  if (!Array.isArray(instancePath)) throw new Error('eventScope.instancePath must be an array.');
+  const ownershipPath = [];
+  for (const segment of instancePath) {
+    const repeatable = [...resolver.repeatableSectionTree.values()].find(
+      (entry) =>
+        entry.preferredKey === segment?.repeatableKey &&
+        JSON.stringify(entry.parentPath) === JSON.stringify(ownershipPath)
+    );
+    if (
+      !repeatable ||
+      JSON.stringify(repeatable.parentPath) !== JSON.stringify(ownershipPath) ||
+      !Number.isInteger(segment.index) ||
+      segment.index < 0 ||
+      !['id', 'position'].includes(segment.identity) ||
+      (segment.identity === 'id'
+        ? !(typeof segment.instanceId === 'string' && segment.instanceId.trim()) &&
+          !(typeof segment.instanceId === 'number' && Number.isFinite(segment.instanceId))
+        : segment.instanceId !== null)
+    ) {
+      throw new Error(
+        'eventScope.instancePath must describe a complete repeatable ancestry with an ID or explicit positional identity.'
+      );
+    }
+    ownershipPath.push(repeatable.preferredKey);
+  }
+  const same = (path) => JSON.stringify(path) === JSON.stringify(ownershipPath);
+  const readable = (path) =>
+    path.length <= ownershipPath.length && path.every((key, index) => ownershipPath[index] === key);
+  const ownedField = (name) => fields.get(name) || resolver.repeatableSectionTree.get(name);
+  const referenceCache = new WeakMap();
+  return function dispatch(eventType, fieldKey, metadata = {}) {
+    const result = { operations: [], validationIssues: [], issues: [] };
+    const issue = (code, message) =>
+      result.issues.push({
+        code,
+        message,
+        eventType: typeof eventType === 'string' ? eventType : null,
+        instancePath: copy(instancePath),
+      });
+    if (
+      typeof eventType !== 'string' ||
+      !isValidEventType(eventType) ||
+      !metadata ||
+      typeof metadata !== 'object' ||
+      Array.isArray(metadata)
+    ) {
+      issue('invalid_request', 'A registered event type and metadata object are required.');
+      return result;
+    }
+    const info = getEventInfo(eventType);
+    const target = ownedField(fieldKey);
+    const routeValid =
+      info.category === 'record'
+        ? ownershipPath.length === 0 &&
+          (fieldKey === undefined ||
+            fieldKey === null ||
+            (eventType === 'change-status' &&
+              statusField?.enabled &&
+              fieldKey === statusField.data_name))
+        : info.category === 'repeatable'
+          ? resolver.repeatableSectionTree.has(fieldKey) && same(target.currentPath)
+          : typeof fieldKey === 'string' && target && same(target.parentPath);
+    if (!routeValid) {
+      issue(
+        'invalid_routing_context',
+        'The event target is not owned by the executing engine scope.'
+      );
+      return result;
+    }
+    for (const initializationIssue of manager.initializationIssues)
+      issue(initializationIssue.code, initializationIssue.message);
+    if (result.issues.length) return result;
+    let event;
+    try {
+      event = {
+        ...copy(metadata),
+        type: eventType,
+        fieldKey,
+        timestamp: Date.now(),
+        instancePath: copy(instancePath),
+        scopeId,
+      };
+    } catch {
+      issue('invalid_request', 'Event metadata must contain portable data.');
+      return result;
+    }
+    const validation = eventType === 'validate-record' || eventType === 'validate-repeatable';
+    const closing = /^(cancel|unload)-/.test(eventType);
+    const eventMap = manager.listeners.get(eventType);
+    const listeners = [...(eventMap?.get(fieldKey) || []), ...(eventMap?.get('*') || [])];
+    for (const callback of listeners) {
+      const scope = createEventOperationScope((operationName) => {
+        // Late async work cannot mutate this completed result or break another dispatch.
+        try {
+          manager.emitHandlerWarning(
+            'late_event_operation_discarded',
+            { type: 'event', eventType, fieldName: fieldKey || null },
+            callback.name || '<anonymous>',
+            operationName
+          );
+        } catch {
+          /* Reporting is observational. */
+        }
+      });
+      let returned;
+      let collected;
+      try {
+        const source = manager.callbackSources.getSource(callback);
+        if (referenceCache.get(callback)?.source !== source)
+          referenceCache.set(callback, { source, references: getEventFieldReferences(source) });
+        let rejectedReference = false;
+        for (const name of referenceCache.get(callback).references) {
+          const field = fields.get(name);
+          if (!field || !readable(field.parentPath)) {
+            issue(
+              'read_scope_restricted',
+              `Field '${name}' is not readable from the executing scope.`
+            );
+            rejectedReference = true;
+          }
+        }
+        if (rejectedReference) continue;
+        const context = { event: copy(event) };
+        for (const [key, value] of Object.entries(manager.eventContext)) {
+          if (!key.startsWith('$')) context[key] = value;
+          else {
+            const field = fields.get(key.slice(1));
+            if (field && readable(field.parentPath)) context[key] = copy(value);
+          }
+        }
+        context.event = copy(event);
+        returned = manager.executeHandlerWithContext(callback, event, scope, {
+          source,
+          context,
+          reporting: {
+            suppressConsoleWarning: true,
+            onDiagnostic: (diagnostic) => issue('handler_failed', diagnostic.message),
+            evalReporting: {
+              suppressConsole: true,
+              onDiagnostic: (diagnostic) => issue('read_scope_restricted', diagnostic.message),
+            },
+          },
+        });
+        if (returned && typeof returned.then === 'function') {
+          issue('async_handler_unsupported', 'Managed schema handlers must be synchronous.');
+          Promise.resolve(returned).catch(() => {});
+        }
+      } catch {
+        issue('handler_failed', 'The managed event handler failed.');
+      } finally {
+        collected = closeEventOperationScope(scope);
+      }
+      try {
+        if (returned?.type === 'UI_OPERATION' && !collected.includes(returned))
+          collected.push(copy(returned));
+      } catch {
+        issue('invalid_operation', 'The returned event operation must contain portable data.');
+      }
+      for (const operation of collected) {
+        if (operation?.type === 'EVENT_OPERATION') continue;
+        if (operation?.operation === 'INVALID') {
+          if (!validation)
+            issue('invalid_context', 'INVALID() is only available during managed validation.');
+          else
+            result.validationIssues.push({
+              message: operation.params.message,
+              instancePath: copy(instancePath),
+            });
+        } else if (validation || closing) {
+          issue(
+            'operation_not_allowed',
+            'Validation and close handlers cannot perform value or UI operations.'
+          );
+        } else if (operation?.type === 'FIELD_OPERATION' && operation.operation === 'SETVALUE') {
+          const field = fields.get(operation.params?.fieldDataName);
+          if (!field || !same(field.parentPath))
+            issue(
+              'write_scope_restricted',
+              'SETVALUE() may only write fields owned by the executing scope.'
+            );
+          else {
+            try {
+              result.operations.push(copy(operation));
+            } catch {
+              issue('invalid_operation', 'Event operations must contain portable data.');
+            }
+          }
+        } else {
+          try {
+            result.operations.push(copy(operation));
+          } catch {
+            issue('invalid_operation', 'Event operations must contain portable data.');
+          }
+        }
+      }
+    }
+    // A failed managed dispatch is not a partially applicable operation batch.
+    if (result.issues.length) result.operations = [];
+    return copy(result);
+  };
+}

package/src/engine/warning-system.js

@@ -195,13 +195,22 @@ export class WarningSystem {
    * @param {Object} warning - Warning object
    */
   notifyCustomHandlers(warning, options = {}) {
+    const reportFailure = (error) => {
+      if (options.console ?? this.enableConsoleWarnings) {
+        try {
+          console.error('[form0] Warning handler failed:', error);
+        } catch {
+          // Reporting is observational, including a failed console adapter.
+        }
+      }
+    };
     for (const handler of this.warningHandlers) {
       try {
-        handler(warning);
+        const result = handler(warning);
+        if (result && typeof result.then === 'function')
+          Promise.resolve(result).catch(reportFailure);
       } catch (err) {
-        if (options.console ?? this.enableConsoleWarnings) {
-          console.error('[form0] Warning handler failed:', err);
-        }
+        reportFailure(err);
         // Don't remove the handler automatically - let the user decide
       }
     }

package/src/index.js

@@ -85,3 +85,4 @@ export {
   validateFormAuthoringSchema,
   applyFormMutationBatch,
 } from './authoring/form-authoring.js';
+export { INVALID } from './builtins/event/control/invalid.js';