Skip to main content

Runtime Evaluation

Rune runtime evaluation must match the contract users author in OpenAPI. The system should not split formula behavior between visual design, generated models, and hand-coded runtime shortcuts.

Implemented Runtime​

Gridheim Rune runtime evaluation is implemented by the com.valkyrlabs.valkyrai.runes package in the ValkyrAI server:

ClassRole
RuneRuntime-retained field annotation carrying the formula string.
RuneAspectAspectJ/Spring aspect that intercepts reads of fields annotated with @Rune.
RuneValidationServiceExtracts formula references and validates them against the model class.
RuneContextBuilderResolves references against the target object at runtime.
RuneEvaluationServiceProjects model values into OpenXLS named ranges, evaluates the formula, and adapts the result to the field type.

The compatibility package com.valkyrlabs.gridheim.core still exists for older generated code, but new ThorAPI templates should use com.valkyrlabs.valkyrai.runes.Rune.

Evaluation Flow​

  1. The aspect receives a field-read join point for @Rune.
  2. The formula string is read from the annotation.
  3. Formula references are validated against the target model type.
  4. References resolve from the target object using fields, JavaBean getters, maps, arrays, collections, and nested dot paths.
  5. Collection projections flatten values, so paymentTransactions.credits becomes the list of credit values from the collection elements.
  6. The evaluator creates an OpenXLS workbook, writes resolved values into cells, creates named ranges for the formula references, rewrites the formula to those named ranges, calculates the workbook, and adapts the result to the Java field type.

There is no direct database read and no calculated-value persistence in the Rune evaluator. The object instance supplied to the field read is the runtime context.

Formula Contract​

Formula authoring is OpenXLS/Gridheim-style and stored in OpenAPI as x-gridheim-rune on a component property.

The model-reference bridge supports:

  • scalar fields and JavaBean getters
  • map keys
  • arrays and collections
  • nested dot paths
  • collection projections such as lineItems.extendedAmount

Runtime boundaries:

  • Rune evaluation is deterministic for the same object state.
  • Blank formulas are rejected.
  • Unsupported OpenXLS formulas fail fast.
  • Empty references and empty collections behave as zero in numeric contexts.
  • Integer-like targets are truncated with RoundingMode.DOWN.
  • The React spreadsheet formula engine is still a client-side helper; the server-side Rune runtime is OpenXLS-backed.

Operational Diagnostics​

Current failure behavior:

  • invalid references throw an IllegalStateException containing the formula and model class
  • unsupported formulas, blank formulas, OpenXLS calculation failures, and type conversion failures throw evaluator errors
  • validation accepts primitive numeric/boolean fields, Number, BigDecimal, CharSequence, Boolean, temporal values, and Object

The next useful hardening step is to include the field name and normalized reference list in every runtime failure so a production error points directly back to the OpenAPI property.

Related: