Math Engine Reference: Expression Program

문서 탐색

개요

Caller-owned expression semantic analysis, bytecode and native registry C ABI.

Programs contain no callback, session, GUI, Python or backend pointer. Variables, pending assignment commits, RNG state and custom callbacks are supplied through an evaluation frame. 프로그램과 직렬화 형식은 pointer-free이며 모든 array는 caller-owned다. 함수가 별도로 허용하지 않는 한 입력, workspace와 출력 array는 서로 겹치지 않아야 한다.

실행 원본: include/math_engine/math_engine_expression_program.h
분류: 식·CAS·계산기·plot

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_expression_program.h>

Type과 callback

`math_engine_expression_function_provider_t`

Built-in 또는 caller 함수 구현을 소유하는 provider 식별자다.

typedef enum math_engine_expression_function_provider {
    MATH_ENGINE_EXPRESSION_PROVIDER_INVALID = 0, /**< 등록된 구현이 없는 zero/sentinel provider다. */
    MATH_ENGINE_EXPRESSION_PROVIDER_MATH_FUNCTION = 1, /**< 정적 math-function catalog가 구현을 소유한다. */
    MATH_ENGINE_EXPRESSION_PROVIDER_NUMBER_THEORY = 2, /**< Bounded integer/number-theory provider가 구현한다. */
    MATH_ENGINE_EXPRESSION_PROVIDER_RNG = 3, /**< Evaluation frame의 mutable RNG state를 소비한다. */
    MATH_ENGINE_EXPRESSION_PROVIDER_USER = 4 /**< Caller binding의 동기 C callback으로 구현한다. */
} math_engine_expression_function_provider_t;

math_engine_expression_function_provider_t.MATH_ENGINE_EXPRESSION_PROVIDER_INVALID
등록된 구현이 없는 zero/sentinel provider다.
```
MATH_ENGINE_EXPRESSION_PROVIDER_INVALID = 0,
```
math_engine_expression_function_provider_t.MATH_ENGINE_EXPRESSION_PROVIDER_MATH_FUNCTION
정적 math-function catalog가 구현을 소유한다.
```
MATH_ENGINE_EXPRESSION_PROVIDER_MATH_FUNCTION = 1,
```
math_engine_expression_function_provider_t.MATH_ENGINE_EXPRESSION_PROVIDER_NUMBER_THEORY
Bounded integer/number-theory provider가 구현한다.
```
MATH_ENGINE_EXPRESSION_PROVIDER_NUMBER_THEORY = 2,
```
math_engine_expression_function_provider_t.MATH_ENGINE_EXPRESSION_PROVIDER_RNG
Evaluation frame의 mutable RNG state를 소비한다.
```
MATH_ENGINE_EXPRESSION_PROVIDER_RNG = 3,
```
math_engine_expression_function_provider_t.MATH_ENGINE_EXPRESSION_PROVIDER_USER
Caller binding의 동기 C callback으로 구현한다.
```
MATH_ENGINE_EXPRESSION_PROVIDER_USER = 4,
```

`math_engine_expression_number_theory_function_t`

Expression registry가 노출하는 number-theory 함수 식별자다.

typedef enum math_engine_expression_number_theory_function {
    MATH_ENGINE_EXPRESSION_NUMBER_THEORY_IS_PRIME = 1, /**< Integer 인수 하나를 0/1 primality 값으로 매핑한다. */
    MATH_ENGINE_EXPRESSION_NUMBER_THEORY_NEXT_PRIME = 2, /**< Integer 인수 이상/이후의 bounded next prime을 구한다. */
    MATH_ENGINE_EXPRESSION_NUMBER_THEORY_GCD = 3, /**< 두 integer 인수의 nonnegative 최대공약수를 구한다. */
    MATH_ENGINE_EXPRESSION_NUMBER_THEORY_PERMUTATION = 4, /**< 두 integer =n,r=의 ordered permutation 수를 구한다. */
    MATH_ENGINE_EXPRESSION_NUMBER_THEORY_LCM = 5 /**< 두 integer 인수의 nonnegative 최소공배수를 구한다. */
} math_engine_expression_number_theory_function_t;

math_engine_expression_number_theory_function_t.MATH_ENGINE_EXPRESSION_NUMBER_THEORY_IS_PRIME
Integer 인수 하나를 0/1 primality 값으로 매핑한다.
```
MATH_ENGINE_EXPRESSION_NUMBER_THEORY_IS_PRIME = 1,
```
math_engine_expression_number_theory_function_t.MATH_ENGINE_EXPRESSION_NUMBER_THEORY_NEXT_PRIME
Integer 인수 이상/이후의 bounded next prime을 구한다.
```
MATH_ENGINE_EXPRESSION_NUMBER_THEORY_NEXT_PRIME = 2,
```
math_engine_expression_number_theory_function_t.MATH_ENGINE_EXPRESSION_NUMBER_THEORY_GCD
두 integer 인수의 nonnegative 최대공약수를 구한다.
```
MATH_ENGINE_EXPRESSION_NUMBER_THEORY_GCD = 3,
```
math_engine_expression_number_theory_function_t.MATH_ENGINE_EXPRESSION_NUMBER_THEORY_PERMUTATION
두 integer n,r 의 ordered permutation 수를 구한다.
```
MATH_ENGINE_EXPRESSION_NUMBER_THEORY_PERMUTATION = 4,
```
math_engine_expression_number_theory_function_t.MATH_ENGINE_EXPRESSION_NUMBER_THEORY_LCM
두 integer 인수의 nonnegative 최소공배수를 구한다.
```
MATH_ENGINE_EXPRESSION_NUMBER_THEORY_LCM = 5,
```

`math_engine_expression_rng_function_t`

Expression registry가 노출하는 stateful RNG 함수 식별자다.

typedef enum math_engine_expression_rng_function {
    MATH_ENGINE_EXPRESSION_RNG_UNIFORM = 1, /**< Frame RNG를 전진시켜 [0,1) uniform binary 값을 만든다. */
    MATH_ENGINE_EXPRESSION_RNG_NORMAL = 2 /**< Frame RNG를 전진시켜 표준정규 binary 값을 만든다. */
} math_engine_expression_rng_function_t;

math_engine_expression_rng_function_t.MATH_ENGINE_EXPRESSION_RNG_UNIFORM
Frame RNG를 전진시켜 [0,1) uniform binary 값을 만든다.
```
MATH_ENGINE_EXPRESSION_RNG_UNIFORM = 1,
```
math_engine_expression_rng_function_t.MATH_ENGINE_EXPRESSION_RNG_NORMAL
Frame RNG를 전진시켜 표준정규 binary 값을 만든다.
```
MATH_ENGINE_EXPRESSION_RNG_NORMAL = 2,
```

`math_engine_expression_opcode_t`

Pointer-free program instruction의 opcode다.

typedef enum math_engine_expression_opcode {
    MATH_ENGINE_EXPRESSION_OPCODE_PUSH_CONSTANT = 1, /**< =constants[operand]= runtime value를 stack에 push한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_LOAD_VALUE = 2, /**< =frame.values[operand]=를 type constant =auxiliary=로 검증해 push한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_POSITIVE = 3, /**< Stack top에 unary plus/type normalization을 적용한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_NEGATE = 4, /**< Stack top quantity의 부호를 반전한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_ADD = 5, /**< Stack의 두 top operand를 더해 하나로 줄인다. */
    MATH_ENGINE_EXPRESSION_OPCODE_SUBTRACT = 6, /**< Stack의 두 top operand를 left-right로 뺀다. */
    MATH_ENGINE_EXPRESSION_OPCODE_MULTIPLY = 7, /**< Stack의 두 top operand와 unit을 곱한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_DIVIDE = 8, /**< Stack의 두 top operand를 left/right로 나눈다. */
    MATH_ENGINE_EXPRESSION_OPCODE_MODULO = 9, /**< Stack의 두 top operand에 mode별 remainder를 적용한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_POWER = 10, /**< Stack base/exponent에 bounded power 연산을 적용한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_CALL = 11, /**< =registry_id= 함수를 stack top =arity= arguments로 동기 호출한다. */
    MATH_ENGINE_EXPRESSION_OPCODE_STORE_VALUE = 12 /**< Stack top을 =value_slot= pending assignment로 기록한다. */
} math_engine_expression_opcode_t;

math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_PUSH_CONSTANT
constants[operand] runtime value를 stack에 push한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_PUSH_CONSTANT = 1,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_LOAD_VALUE
frame.values[operand] 를 type constant auxiliary 로 검증해 push한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_LOAD_VALUE = 2,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_POSITIVE
Stack top에 unary plus/type normalization을 적용한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_POSITIVE = 3,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_NEGATE
Stack top quantity의 부호를 반전한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_NEGATE = 4,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_ADD
Stack의 두 top operand를 더해 하나로 줄인다.
```
MATH_ENGINE_EXPRESSION_OPCODE_ADD = 5,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_SUBTRACT
Stack의 두 top operand를 left-right로 뺀다.
```
MATH_ENGINE_EXPRESSION_OPCODE_SUBTRACT = 6,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_MULTIPLY
Stack의 두 top operand와 unit을 곱한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_MULTIPLY = 7,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_DIVIDE
Stack의 두 top operand를 left/right로 나눈다.
```
MATH_ENGINE_EXPRESSION_OPCODE_DIVIDE = 8,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_MODULO
Stack의 두 top operand에 mode별 remainder를 적용한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_MODULO = 9,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_POWER
Stack base/exponent에 bounded power 연산을 적용한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_POWER = 10,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_CALL
registry_id 함수를 stack top arity arguments로 동기 호출한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_CALL = 11,
```
math_engine_expression_opcode_t.MATH_ENGINE_EXPRESSION_OPCODE_STORE_VALUE
Stack top을 value_slot pending assignment로 기록한다.
```
MATH_ENGINE_EXPRESSION_OPCODE_STORE_VALUE = 12,
```

`math_engine_expression_semantic_diagnostic_code_t`

Registry, compile 또는 evaluate 실패의 구조화 semantic 진단 code다.

typedef enum math_engine_expression_semantic_diagnostic_code {
    MATH_ENGINE_EXPRESSION_SEMANTIC_UNRESOLVED_SYMBOL = 1, /**< Source name이 symbol/constant/function catalog에 없다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_DUPLICATE_SYMBOL = 2, /**< Symbol 이름, stable ID 또는 value slot이 중복된다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_DUPLICATE_REGISTRY_ID = 3, /**< Custom function 둘이 같은 high-bit registry ID를 쓴다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_AMBIGUOUS_FUNCTION = 4, /**< 이름과 arity가 둘 이상의 descriptor와 일치한다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_ARITY_MISMATCH = 5, /**< 함수 argument 수가 descriptor min/max 범위 밖이다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_UNSUPPORTED_MODE = 6, /**< Provider/함수가 현재 math mode bit를 지원하지 않는다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_NUMERIC_KIND = 7, /**< Quantity 또는 program numeric backend kind가 일치하지 않는다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_DIMENSION_MISMATCH = 8, /**< Unit dimension이 operator/function 계약과 맞지 않는다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_READ_ONLY_ASSIGNMENT = 9, /**< Assignment target symbol에 WRITABLE bit가 없다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_STATEFUL_DISABLED = 10, /**< Stateful function을 compile option이 금지했다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_INSTRUCTION_LIMIT = 11, /**< 생성 instruction 수가 configured ceiling에 닿았다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_CONSTANT_LIMIT = 12, /**< 생성 constant 수가 configured ceiling에 닿았다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_STACK_LIMIT = 13, /**< 정적 계산한 operand stack depth가 ceiling을 넘는다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_INVALID_AST = 14, /**< Node order/index/span 또는 root 구조가 compile 계약을 위반한다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_STALE_REGISTRY = 15, /**< Program과 frame custom registry fingerprint가 다르다. */
    MATH_ENGINE_EXPRESSION_SEMANTIC_STALE_UNIT_CATALOG = 16 /**< Program의 unit catalog fingerprint가 runtime과 다르다. */
} math_engine_expression_semantic_diagnostic_code_t;

math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_UNRESOLVED_SYMBOL
Source name이 symbol/constant/function catalog에 없다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_UNRESOLVED_SYMBOL = 1,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_DUPLICATE_SYMBOL
Symbol 이름, stable ID 또는 value slot이 중복된다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_DUPLICATE_SYMBOL = 2,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_DUPLICATE_REGISTRY_ID
Custom function 둘이 같은 high-bit registry ID를 쓴다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_DUPLICATE_REGISTRY_ID = 3,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_AMBIGUOUS_FUNCTION
이름과 arity가 둘 이상의 descriptor와 일치한다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_AMBIGUOUS_FUNCTION = 4,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_ARITY_MISMATCH
함수 argument 수가 descriptor min/max 범위 밖이다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_ARITY_MISMATCH = 5,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_UNSUPPORTED_MODE
Provider/함수가 현재 math mode bit를 지원하지 않는다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_UNSUPPORTED_MODE = 6,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_NUMERIC_KIND
Quantity 또는 program numeric backend kind가 일치하지 않는다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_NUMERIC_KIND = 7,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_DIMENSION_MISMATCH
Unit dimension이 operator/function 계약과 맞지 않는다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_DIMENSION_MISMATCH = 8,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_READ_ONLY_ASSIGNMENT
Assignment target symbol에 WRITABLE bit가 없다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_READ_ONLY_ASSIGNMENT = 9,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_STATEFUL_DISABLED
Stateful function을 compile option이 금지했다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_STATEFUL_DISABLED = 10,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_INSTRUCTION_LIMIT
생성 instruction 수가 configured ceiling에 닿았다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_INSTRUCTION_LIMIT = 11,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_CONSTANT_LIMIT
생성 constant 수가 configured ceiling에 닿았다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_CONSTANT_LIMIT = 12,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_STACK_LIMIT
정적 계산한 operand stack depth가 ceiling을 넘는다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_STACK_LIMIT = 13,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_INVALID_AST
Node order/index/span 또는 root 구조가 compile 계약을 위반한다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_INVALID_AST = 14,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_STALE_REGISTRY
Program과 frame custom registry fingerprint가 다르다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_STALE_REGISTRY = 15,
```
math_engine_expression_semantic_diagnostic_code_t.MATH_ENGINE_EXPRESSION_SEMANTIC_STALE_UNIT_CATALOG
Program의 unit catalog fingerprint가 runtime과 다르다.
```
MATH_ENGINE_EXPRESSION_SEMANTIC_STALE_UNIT_CATALOG = 16,
```

`math_engine_expression_function_descriptor_t`

함수 이름, arity, mode, 특성과 안정 registry ID를 담는 pointer-free descriptor다.

typedef struct math_engine_expression_function_descriptor {
    uint32_t struct_size; /**< ABI byte 크기이며 정확히 =sizeof(math_engine_expression_function_descriptor_t)=다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_FUNCTION_DESCRIPTOR_VERSION_1=이어야 한다. */
    uint32_t provider; /**< Registry ID의 구현 영역을 나타내는 function-provider enum 값이다. */
    uint32_t provider_function_id; /**< Provider 내부의 stable nonzero function 식별자다. */
    uint64_t registry_id; /**< Instruction CALL이 참조하는 stable ID; user ID는 high bit가 반드시 1이다. */
    uint32_t minimum_arity; /**< 허용 argument element 수의 포함 하한이며 0..8이다. */
    uint32_t maximum_arity; /**< 허용 argument element 수의 포함 상한이며 =minimum_arity..8=이다. */
    uint32_t flags; /**< =MATH_ENGINE_EXPRESSION_FUNCTION_*= 특성 bit의 유효한 OR다. */
    uint32_t mode_mask; /**< 지원 =math_engine_math_mode_t= 각각에 대응하는 nonzero bit mask다. */
    uint32_t name_size; /**< =name=의 ASCII byte 수이며 1..31이고 끝 NUL은 세지 않는다. */
    uint32_t reserved32; /**< Caller는 0으로 두며 V1 registry validation이 nonzero를 거부한다. */
    char name[MATH_ENGINE_EXPRESSION_NAME_CAPACITY]; /**< Descriptor가 소유하는 NUL-terminated 32-byte 이름 buffer다. */
    uint64_t descriptor_fingerprint; /**< Provider/ID/arity/flags/mode/name payload의 결정적 hash다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하는 ABI 확장 word 두 개다. */
} math_engine_expression_function_descriptor_t;

math_engine_expression_function_descriptor_t.struct_size
ABI byte 크기이며 정확히 sizeof(math_engine_expression_function_descriptor_t) 다.
```
uint32_t struct_size;
```
math_engine_expression_function_descriptor_t.version
MATH_ENGINE_EXPRESSION_FUNCTION_DESCRIPTOR_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_function_descriptor_t.provider
Registry ID의 구현 영역을 나타내는 function-provider enum 값이다.
```
uint32_t provider;
```
math_engine_expression_function_descriptor_t.provider_function_id
Provider 내부의 stable nonzero function 식별자다.
```
uint32_t provider_function_id;
```
math_engine_expression_function_descriptor_t.registry_id
Instruction CALL이 참조하는 stable ID; user ID는 high bit가 반드시 1이다.
```
uint64_t registry_id;
```
math_engine_expression_function_descriptor_t.minimum_arity
허용 argument element 수의 포함 하한이며 0..8이다.
```
uint32_t minimum_arity;
```
math_engine_expression_function_descriptor_t.maximum_arity
허용 argument element 수의 포함 상한이며 minimum_arity..8 이다.
```
uint32_t maximum_arity;
```
math_engine_expression_function_descriptor_t.flags
MATH_ENGINE_EXPRESSION_FUNCTION_* 특성 bit의 유효한 OR다.
```
uint32_t flags;
```
math_engine_expression_function_descriptor_t.mode_mask
지원 math_engine_math_mode_t 각각에 대응하는 nonzero bit mask다.
```
uint32_t mode_mask;
```
math_engine_expression_function_descriptor_t.name_size
name 의 ASCII byte 수이며 1..31이고 끝 NUL은 세지 않는다.
```
uint32_t name_size;
```
math_engine_expression_function_descriptor_t.reserved32
Caller는 0으로 두며 V1 registry validation이 nonzero를 거부한다.
```
uint32_t reserved32;
```
math_engine_expression_function_descriptor_t.name
Descriptor가 소유하는 NUL-terminated 32-byte 이름 buffer다.
```
char name[MATH_ENGINE_EXPRESSION_NAME_CAPACITY];
```
math_engine_expression_function_descriptor_t.descriptor_fingerprint
Provider/ID/arity/flags/mode/name payload의 결정적 hash다.
```
uint64_t descriptor_fingerprint;
```
math_engine_expression_function_descriptor_t.reserved
Caller가 0으로 두어야 하는 ABI 확장 word 두 개다.
```
uint64_t reserved[2];
```

`math_engine_expression_function_callback_t`

사용자 함수를 동기 호출해 dimensionless quantity 하나를 계산한다.

매개변수 arguments: 호출 descriptor의 arity와 같은 수의 borrowed quantity 배열.
매개변수 argument_count: arguments 의 element 수이며 descriptor의 arity 범위 안이어야 한다.
매개변수 context: 현재 evaluation에 사용 중인 borrowed 계산 context.
매개변수 user_data: binding에 저장된 caller-owned opaque pointer.
매개변수 out_value: 성공 시 dimensionless 결과를 완전히 기록할 caller-provided storage.
반환: 성공이면 MATH_ENGINE_STATUS_OK, 실패이면 평가를 중단할 음수 상태 code.

이 함수는 matching user CALL instruction이 실제 실행될 때마다 evaluator를 실행한 같은 thread에서 정확히 한 번 동기 호출되며 registry 검증이나 compile 중에는 호출되지 않는다. arguments/context/out_value는 callback return까지만 유효하고 engine은 callback, binding, user_data 또는 인수 pointer를 보관하지 않는다. Callback은 C++ exception/SEH unwind를 C ABI 경계 밖으로 전파하지 말고 status로 변환해야 하며, 재진입과 user_data 동기화 책임은 caller에 있다. OK를 반환한 quantity는 완전 초기화되고 program numeric kind와 일치하는 dimensionless 값이어야 한다. 실패 시 out_value 내용은 engine이 읽거나 commit하지 않는다.

Math Engine ownership: arguments=borrowed context=borrowed user_data=borrowed out_value=caller
Math Engine nullable: arguments=false context=false user_data=true out_value=false
Math Engine thread_safety: conditional
Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef math_engine_status_t (*math_engine_expression_function_callback_t)(
    const math_engine_quantity_t* arguments,
    size_t argument_count,
    const math_engine_context_t* context,
    void* user_data,
    math_engine_quantity_t* out_value);

`math_engine_expression_function_binding_t`

User registry descriptor, 동기 callback과 caller-owned user_data의 borrowed binding이다.

typedef struct math_engine_expression_function_binding {
    uint32_t struct_size; /**< ABI byte 크기이며 정확히 =sizeof(math_engine_expression_function_binding_t)=다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_FUNCTION_BINDING_VERSION_1=이어야 한다. */
    math_engine_expression_function_descriptor_t descriptor; /**< Binding이 값으로 소유하는 validated USER provider descriptor다. */
    math_engine_expression_function_callback_t callback; /**< Non-NULL borrowed callback; binding이 frame에 있는 모든 evaluate 호출 동안 유효하고 보관되지 않는다. */
    void* user_data; /**< Nullable caller-owned opaque state; callback return까지 borrowed되며 engine이 해제·복사·보관하지 않는다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하고 registry validation이 검사하는 ABI 확장 word다. */
} math_engine_expression_function_binding_t;

math_engine_expression_function_binding_t.struct_size
ABI byte 크기이며 정확히 sizeof(math_engine_expression_function_binding_t) 다.
```
uint32_t struct_size;
```
math_engine_expression_function_binding_t.version
MATH_ENGINE_EXPRESSION_FUNCTION_BINDING_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_function_binding_t.descriptor
Binding이 값으로 소유하는 validated USER provider descriptor다.
```
math_engine_expression_function_descriptor_t descriptor;
```
math_engine_expression_function_binding_t.callback
Non-NULL borrowed callback; binding이 frame에 있는 모든 evaluate 호출 동안 유효하고 보관되지 않는다.
```
math_engine_expression_function_callback_t callback;
```
math_engine_expression_function_binding_t.user_data
Nullable caller-owned opaque state; callback return까지 borrowed되며 engine이 해제·복사·보관하지 않는다.
```
void* user_data;
```
math_engine_expression_function_binding_t.reserved
Caller가 0으로 두어야 하고 registry validation이 검사하는 ABI 확장 word다.
```
uint64_t reserved[2];
```

`math_engine_expression_symbol_descriptor_t`

Source symbol을 value frame slot, numeric kind와 단위에 연결하는 descriptor다.

typedef struct math_engine_expression_symbol_descriptor {
    uint32_t struct_size; /**< ABI byte 크기이며 정확히 symbol descriptor =sizeof=다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_SYMBOL_DESCRIPTOR_VERSION_1=이어야 한다. */
    uint32_t flags; /**< WRITABLE/INPUT bit의 OR이며 그 밖의 bit는 0이다. */
    uint32_t name_size; /**< =name=의 ASCII byte 수 1..31이며 NUL terminator는 제외한다. */
    uint64_t stable_id; /**< Source-independent nonzero symbol ID이며 배열 안에서 유일해야 한다. */
    uint32_t value_slot; /**< Evaluation 시 =frame.values[value_slot]=에 연결되는 유일한 zero-based index다. */
    uint32_t numeric_kind; /**< Slot quantity와 compile result가 따라야 할 =math_engine_quantity_numeric_kind_t= 값이다. */
    char name[MATH_ENGINE_EXPRESSION_NAME_CAPACITY]; /**< Descriptor가 소유하는 NUL-terminated fixed ASCII 이름이다. */
    math_engine_unit_t unit; /**< Slot 값의 차원, scale과 offset을 규정하는 값 소유 unit descriptor다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하는 ABI 확장 word 두 개다. */
} math_engine_expression_symbol_descriptor_t;

math_engine_expression_symbol_descriptor_t.struct_size
ABI byte 크기이며 정확히 symbol descriptor sizeof 다.
```
uint32_t struct_size;
```
math_engine_expression_symbol_descriptor_t.version
MATH_ENGINE_EXPRESSION_SYMBOL_DESCRIPTOR_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_symbol_descriptor_t.flags
WRITABLE/INPUT bit의 OR이며 그 밖의 bit는 0이다.
```
uint32_t flags;
```
math_engine_expression_symbol_descriptor_t.name_size
name 의 ASCII byte 수 1..31이며 NUL terminator는 제외한다.
```
uint32_t name_size;
```
math_engine_expression_symbol_descriptor_t.stable_id
Source-independent nonzero symbol ID이며 배열 안에서 유일해야 한다.
```
uint64_t stable_id;
```
math_engine_expression_symbol_descriptor_t.value_slot
Evaluation 시 frame.values[value_slot] 에 연결되는 유일한 zero-based index다.
```
uint32_t value_slot;
```
math_engine_expression_symbol_descriptor_t.numeric_kind
Slot quantity와 compile result가 따라야 할 math_engine_quantity_numeric_kind_t 값이다.
```
uint32_t numeric_kind;
```
math_engine_expression_symbol_descriptor_t.name
Descriptor가 소유하는 NUL-terminated fixed ASCII 이름이다.
```
char name[MATH_ENGINE_EXPRESSION_NAME_CAPACITY];
```
math_engine_expression_symbol_descriptor_t.unit
Slot 값의 차원, scale과 offset을 규정하는 값 소유 unit descriptor다.
```
math_engine_unit_t unit;
```
math_engine_expression_symbol_descriptor_t.reserved
Caller가 0으로 두어야 하는 ABI 확장 word 두 개다.
```
uint64_t reserved[2];
```

`math_engine_expression_compile_options_t`

결과 backend, 허용 기능과 compile resource 상한을 고정하는 정책이다.

typedef struct math_engine_expression_compile_options {
    uint32_t struct_size; /**< Caller가 정확한 compile-options byte 크기로 설정한다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_COMPILE_OPTIONS_VERSION_1=이어야 한다. */
    uint32_t flags; /**< ALLOW_ASSIGNMENT/ALLOW_STATEFUL/FOLD_EXACT 정책 bit의 OR다. */
    uint32_t result_numeric_kind; /**< 모든 runtime quantity와 result에 사용할 지원 numeric backend kind다. */
    int32_t fixed_scale; /**< Fixed-decimal coefficient의 base-10 fractional digit 수 0..18; 다른 kind에도 canonical metadata로 유지된다. */
    uint32_t rounding; /**< Decimal conversion/arithmetic에 적용할 =math_engine_decimal_rounding_t= 값이다. */
    uint32_t maximum_instructions; /**< 생성 가능한 instruction element 수의 nonzero ceiling이다. */
    uint32_t maximum_constants; /**< Runtime/type-only constant element 수의 nonzero ceiling이다. */
    uint32_t maximum_stack; /**< 정적 operand stack depth의 nonzero element ceiling이다. */
    uint32_t maximum_pending_stores; /**< 한 성공 평가가 원자 commit할 assignment 수의 nonzero ceiling이다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두고 V1 validation이 nonzero를 거부하는 ABI word다. */
} math_engine_expression_compile_options_t;

math_engine_expression_compile_options_t.struct_size
Caller가 정확한 compile-options byte 크기로 설정한다.
```
uint32_t struct_size;
```
math_engine_expression_compile_options_t.version
MATH_ENGINE_EXPRESSION_COMPILE_OPTIONS_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_compile_options_t.flags
ALLOW_ASSIGNMENT/ALLOW_STATEFUL/FOLD_EXACT 정책 bit의 OR다.
```
uint32_t flags;
```
math_engine_expression_compile_options_t.result_numeric_kind
모든 runtime quantity와 result에 사용할 지원 numeric backend kind다.
```
uint32_t result_numeric_kind;
```
math_engine_expression_compile_options_t.fixed_scale
Fixed-decimal coefficient의 base-10 fractional digit 수 0..18; 다른 kind에도 canonical metadata로 유지된다.
```
int32_t fixed_scale;
```
math_engine_expression_compile_options_t.rounding
Decimal conversion/arithmetic에 적용할 math_engine_decimal_rounding_t 값이다.
```
uint32_t rounding;
```
math_engine_expression_compile_options_t.maximum_instructions
생성 가능한 instruction element 수의 nonzero ceiling이다.
```
uint32_t maximum_instructions;
```
math_engine_expression_compile_options_t.maximum_constants
Runtime/type-only constant element 수의 nonzero ceiling이다.
```
uint32_t maximum_constants;
```
math_engine_expression_compile_options_t.maximum_stack
정적 operand stack depth의 nonzero element ceiling이다.
```
uint32_t maximum_stack;
```
math_engine_expression_compile_options_t.maximum_pending_stores
한 성공 평가가 원자 commit할 assignment 수의 nonzero ceiling이다.
```
uint32_t maximum_pending_stores;
```
math_engine_expression_compile_options_t.reserved
Caller가 0으로 두고 V1 validation이 nonzero를 거부하는 ABI word다.
```
uint64_t reserved[2];
```

`math_engine_expression_compile_node_t`

Caller scratch for one AST node. Content is unspecified after a failed compile.

typedef struct math_engine_expression_compile_node {
    uint32_t struct_size; /**< Compiler가 각 scratch element에 exact =sizeof=를 기록한다. */
    uint32_t version; /**< Compiler가 =MATH_ENGINE_EXPRESSION_COMPILE_NODE_VERSION_1=을 기록한다. */
    uint32_t flags; /**< 내부 constant/skip-emission 상태 bit이며 호출 후 해석을 보장하지 않는다. */
    uint32_t reference_count; /**< Postorder AST에서 이 node를 참조한 부모 edge 수다. */
    uint64_t instruction_begin; /**< 이 AST subtree instruction의 zero-based 시작 offset이다. */
    uint64_t constant_begin; /**< 이 AST subtree가 처음 생성한 constant offset이다. */
    uint64_t maximum_stack; /**< Subtree 평가에 필요한 최대 quantity stack element 수다. */
    uint64_t registry_id; /**< CALL node에서 해소한 stable function ID, 아니면 0이다. */
    uint32_t value_slot; /**< Symbol/assignment에서 해소한 frame slot, 해당 없으면 0 scratch 값이다. */
    uint32_t argument_count; /**< CALL node의 child argument 수, 해당 없으면 0이다. */
    math_engine_quantity_t constant_value; /**< Constant-folded subtree 값; constant flag가 없으면 내용은 scratch다. */
    uint64_t reserved[2]; /**< Compiler가 0으로 쓰는 ABI 확장 word이며 caller는 해석하지 않는다. */
} math_engine_expression_compile_node_t;

math_engine_expression_compile_node_t.struct_size
Compiler가 각 scratch element에 exact sizeof 를 기록한다.
```
uint32_t struct_size;
```
math_engine_expression_compile_node_t.version
Compiler가 MATH_ENGINE_EXPRESSION_COMPILE_NODE_VERSION_1 을 기록한다.
```
uint32_t version;
```
math_engine_expression_compile_node_t.flags
내부 constant/skip-emission 상태 bit이며 호출 후 해석을 보장하지 않는다.
```
uint32_t flags;
```
math_engine_expression_compile_node_t.reference_count
Postorder AST에서 이 node를 참조한 부모 edge 수다.
```
uint32_t reference_count;
```
math_engine_expression_compile_node_t.instruction_begin
이 AST subtree instruction의 zero-based 시작 offset이다.
```
uint64_t instruction_begin;
```
math_engine_expression_compile_node_t.constant_begin
이 AST subtree가 처음 생성한 constant offset이다.
```
uint64_t constant_begin;
```
math_engine_expression_compile_node_t.maximum_stack
Subtree 평가에 필요한 최대 quantity stack element 수다.
```
uint64_t maximum_stack;
```
math_engine_expression_compile_node_t.registry_id
CALL node에서 해소한 stable function ID, 아니면 0이다.
```
uint64_t registry_id;
```
math_engine_expression_compile_node_t.value_slot
Symbol/assignment에서 해소한 frame slot, 해당 없으면 0 scratch 값이다.
```
uint32_t value_slot;
```
math_engine_expression_compile_node_t.argument_count
CALL node의 child argument 수, 해당 없으면 0이다.
```
uint32_t argument_count;
```
math_engine_expression_compile_node_t.constant_value
Constant-folded subtree 값; constant flag가 없으면 내용은 scratch다.
```
math_engine_quantity_t constant_value;
```
math_engine_expression_compile_node_t.reserved
Compiler가 0으로 쓰는 ABI 확장 word이며 caller는 해석하지 않는다.
```
uint64_t reserved[2];
```

`math_engine_expression_instruction_t`

외부 pointer 없이 opcode, operand와 source span을 담는 직렬화 가능 instruction이다.

typedef struct math_engine_expression_instruction {
    uint32_t struct_size; /**< ABI/wire validation용 byte 크기이며 exact instruction =sizeof=다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_INSTRUCTION_VERSION_1=이어야 한다. */
    uint32_t opcode; /**< Stack effect와 활성 operand를 정하는 =math_engine_expression_opcode_t= 값이다. */
    uint32_t flags; /**< V1 instruction에는 정의된 bit가 없어 반드시 0이다. */
    uint32_t operand; /**< PUSH의 constant index, LOAD/STORE의 value slot 등 opcode별 주 index다. */
    uint32_t auxiliary; /**< LOAD/STORE type-check constant index 등 opcode별 보조 index다. */
    uint32_t arity; /**< CALL이 stack에서 소비하는 argument 수; 다른 opcode에서는 0이다. */
    uint32_t reserved32; /**< Wire 호환 ABI 확장용이며 producer는 0, validator는 nonzero를 거부한다. */
    uint64_t registry_id; /**< CALL provider/function을 고르는 stable registry ID; 다른 opcode에서는 0이다. */
    math_engine_expression_span_t source_span; /**< 이 instruction을 생성한 UTF-8 source의 반열린 byte span이다. */
} math_engine_expression_instruction_t;

math_engine_expression_instruction_t.struct_size
ABI/wire validation용 byte 크기이며 exact instruction sizeof 다.
```
uint32_t struct_size;
```
math_engine_expression_instruction_t.version
MATH_ENGINE_EXPRESSION_INSTRUCTION_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_instruction_t.opcode
Stack effect와 활성 operand를 정하는 math_engine_expression_opcode_t 값이다.
```
uint32_t opcode;
```
math_engine_expression_instruction_t.flags
V1 instruction에는 정의된 bit가 없어 반드시 0이다.
```
uint32_t flags;
```
math_engine_expression_instruction_t.operand
PUSH의 constant index, LOAD/STORE의 value slot 등 opcode별 주 index다.
```
uint32_t operand;
```
math_engine_expression_instruction_t.auxiliary
LOAD/STORE type-check constant index 등 opcode별 보조 index다.
```
uint32_t auxiliary;
```
math_engine_expression_instruction_t.arity
CALL이 stack에서 소비하는 argument 수; 다른 opcode에서는 0이다.
```
uint32_t arity;
```
math_engine_expression_instruction_t.reserved32
Wire 호환 ABI 확장용이며 producer는 0, validator는 nonzero를 거부한다.
```
uint32_t reserved32;
```
math_engine_expression_instruction_t.registry_id
CALL provider/function을 고르는 stable registry ID; 다른 opcode에서는 0이다.
```
uint64_t registry_id;
```
math_engine_expression_instruction_t.source_span
이 instruction을 생성한 UTF-8 source의 반열린 byte span이다.
```
math_engine_expression_span_t source_span;
```

`math_engine_expression_constant_t`

Runtime 값 또는 type-check 전용 quantity constant다.

typedef struct math_engine_expression_constant {
    uint32_t struct_size; /**< ABI/wire validation용 byte 크기이며 exact constant =sizeof=다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_CONSTANT_VERSION_1=이어야 한다. */
    uint32_t flags; /**< VALUE 또는 TYPE_ONLY 중 정확히 하나의 bit만 설정한다. */
    uint32_t reserved32; /**< Producer는 0으로 쓰고 V1 validator가 nonzero를 거부한다. */
    math_engine_quantity_t value; /**< Record가 값으로 소유하는 validated scalar/unit quantity다. */
    math_engine_expression_span_t source_span; /**< Constant 또는 type template의 원본 반열린 UTF-8 byte span이다. */
} math_engine_expression_constant_t;

math_engine_expression_constant_t.struct_size
ABI/wire validation용 byte 크기이며 exact constant sizeof 다.
```
uint32_t struct_size;
```
math_engine_expression_constant_t.version
MATH_ENGINE_EXPRESSION_CONSTANT_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_constant_t.flags
VALUE 또는 TYPE_ONLY 중 정확히 하나의 bit만 설정한다.
```
uint32_t flags;
```
math_engine_expression_constant_t.reserved32
Producer는 0으로 쓰고 V1 validator가 nonzero를 거부한다.
```
uint32_t reserved32;
```
math_engine_expression_constant_t.value
Record가 값으로 소유하는 validated scalar/unit quantity다.
```
math_engine_quantity_t value;
```
math_engine_expression_constant_t.source_span
Constant 또는 type template의 원본 반열린 UTF-8 byte span이다.
```
math_engine_expression_span_t source_span;
```

`math_engine_expression_program_t`

Instruction/constant 배열의 개수, resource 요구량과 logical fingerprint를 담는 program header다.

typedef struct math_engine_expression_program {
    uint32_t struct_size; /**< ABI/wire validation용 byte 크기이며 exact program-header =sizeof=다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_PROGRAM_VERSION_1=이어야 한다. */
    uint32_t flags; /**< 실제 program이 사용하는 assignment/stateful compile-policy bit다. */
    uint32_t numeric_kind; /**< 모든 instruction result/frame slot이 따라야 할 quantity numeric kind다. */
    int32_t fixed_scale; /**< Fixed-decimal backend의 base-10 scale 0..18이며 다른 kind에도 직렬화된다. */
    uint32_t rounding; /**< Conversion/arithmetic에 고정된 decimal rounding enum 값이다. */
    uint64_t instruction_count; /**< Borrowed instruction 배열의 필수 유효 prefix element 수이며 1 이상이다. */
    uint64_t constant_count; /**< Borrowed constant 배열의 유효 prefix element 수이며 0일 수 있다. */
    uint64_t value_slot_count; /**< Frame =values=가 제공해야 하는 최소 element 수다. */
    uint64_t maximum_stack; /**< Eval workspace =stack_capacity=가 만족할 최소 element 수다. */
    uint64_t maximum_pending_stores; /**< Eval workspace pending-store 최소 capacity와 성공 assignment 수다. */
    uint64_t source_fingerprint; /**< Compile에 사용한 정확한 source byte열의 결정적 hash다. */
    uint64_t registry_fingerprint; /**< Built-in catalog와 custom descriptor 집합의 순서 독립 hash다. */
    uint64_t unit_catalog_fingerprint; /**< Compile 시점 authoritative unit catalog revision hash다. */
    uint64_t program_fingerprint; /**< Header logical fields와 exact instruction/constant prefixes의 hash다. */
    math_engine_expression_span_t root_span; /**< Program 결과를 생성하는 root AST의 반열린 source byte span이다. */
    uint64_t reserved[2]; /**< Producer는 0으로 쓰고 V1 validator가 검사하는 ABI 확장 word다. */
} math_engine_expression_program_t;

math_engine_expression_program_t.struct_size
ABI/wire validation용 byte 크기이며 exact program-header sizeof 다.
```
uint32_t struct_size;
```
math_engine_expression_program_t.version
MATH_ENGINE_EXPRESSION_PROGRAM_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_program_t.flags
실제 program이 사용하는 assignment/stateful compile-policy bit다.
```
uint32_t flags;
```
math_engine_expression_program_t.numeric_kind
모든 instruction result/frame slot이 따라야 할 quantity numeric kind다.
```
uint32_t numeric_kind;
```
math_engine_expression_program_t.fixed_scale
Fixed-decimal backend의 base-10 scale 0..18이며 다른 kind에도 직렬화된다.
```
int32_t fixed_scale;
```
math_engine_expression_program_t.rounding
Conversion/arithmetic에 고정된 decimal rounding enum 값이다.
```
uint32_t rounding;
```
math_engine_expression_program_t.instruction_count
Borrowed instruction 배열의 필수 유효 prefix element 수이며 1 이상이다.
```
uint64_t instruction_count;
```
math_engine_expression_program_t.constant_count
Borrowed constant 배열의 유효 prefix element 수이며 0일 수 있다.
```
uint64_t constant_count;
```
math_engine_expression_program_t.value_slot_count
Frame values 가 제공해야 하는 최소 element 수다.
```
uint64_t value_slot_count;
```
math_engine_expression_program_t.maximum_stack
Eval workspace stack_capacity 가 만족할 최소 element 수다.
```
uint64_t maximum_stack;
```
math_engine_expression_program_t.maximum_pending_stores
Eval workspace pending-store 최소 capacity와 성공 assignment 수다.
```
uint64_t maximum_pending_stores;
```
math_engine_expression_program_t.source_fingerprint
Compile에 사용한 정확한 source byte열의 결정적 hash다.
```
uint64_t source_fingerprint;
```
math_engine_expression_program_t.registry_fingerprint
Built-in catalog와 custom descriptor 집합의 순서 독립 hash다.
```
uint64_t registry_fingerprint;
```
math_engine_expression_program_t.unit_catalog_fingerprint
Compile 시점 authoritative unit catalog revision hash다.
```
uint64_t unit_catalog_fingerprint;
```
math_engine_expression_program_t.program_fingerprint
Header logical fields와 exact instruction/constant prefixes의 hash다.
```
uint64_t program_fingerprint;
```
math_engine_expression_program_t.root_span
Program 결과를 생성하는 root AST의 반열린 source byte span이다.
```
math_engine_expression_span_t root_span;
```
math_engine_expression_program_t.reserved
Producer는 0으로 쓰고 V1 validator가 검사하는 ABI 확장 word다.
```
uint64_t reserved[2];
```

`math_engine_expression_semantic_diagnostic_t`

실패 위치, 관련 ID와 expected/actual 값을 선택적으로 전달하는 진단 record다.

typedef struct math_engine_expression_semantic_diagnostic {
    uint32_t struct_size; /**< Caller가 exact diagnostic byte 크기로 미리 설정한다. */
    uint32_t version; /**< Caller가 =MATH_ENGINE_EXPRESSION_SEMANTIC_DIAGNOSTIC_VERSION_1=로 설정한다. */
    uint32_t code; /**< 실패 분류인 =math_engine_expression_semantic_diagnostic_code_t= 값이다. */
    uint32_t reserved32; /**< Library가 0으로 commit하고 reader가 무시하는 ABI 확장 slot이다. */
    math_engine_expression_span_t primary_span; /**< 오류가 직접 발생한 반열린 UTF-8 byte span이다. */
    math_engine_expression_span_t related_span; /**< Duplicate/관계 오류의 둘째 span이며 해당 없으면 zero span이다. */
    uint64_t registry_id; /**< 관련 function registry ID이며 해당 없는 code에서는 0이다. */
    uint64_t symbol_id; /**< 관련 stable symbol ID이며 해당 없는 code에서는 0이다. */
    uint32_t expected; /**< Code별 기대 arity/mode/kind/resource ceiling 값이다. */
    uint32_t actual; /**< Code별 관측 arity/mode/kind/resource 사용량 값이다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 reader가 무시하는 ABI 확장 word다. */
} math_engine_expression_semantic_diagnostic_t;

math_engine_expression_semantic_diagnostic_t.struct_size
Caller가 exact diagnostic byte 크기로 미리 설정한다.
```
uint32_t struct_size;
```
math_engine_expression_semantic_diagnostic_t.version
Caller가 MATH_ENGINE_EXPRESSION_SEMANTIC_DIAGNOSTIC_VERSION_1 로 설정한다.
```
uint32_t version;
```
math_engine_expression_semantic_diagnostic_t.code
실패 분류인 math_engine_expression_semantic_diagnostic_code_t 값이다.
```
uint32_t code;
```
math_engine_expression_semantic_diagnostic_t.reserved32
Library가 0으로 commit하고 reader가 무시하는 ABI 확장 slot이다.
```
uint32_t reserved32;
```
math_engine_expression_semantic_diagnostic_t.primary_span
오류가 직접 발생한 반열린 UTF-8 byte span이다.
```
math_engine_expression_span_t primary_span;
```
math_engine_expression_semantic_diagnostic_t.related_span
Duplicate/관계 오류의 둘째 span이며 해당 없으면 zero span이다.
```
math_engine_expression_span_t related_span;
```
math_engine_expression_semantic_diagnostic_t.registry_id
관련 function registry ID이며 해당 없는 code에서는 0이다.
```
uint64_t registry_id;
```
math_engine_expression_semantic_diagnostic_t.symbol_id
관련 stable symbol ID이며 해당 없는 code에서는 0이다.
```
uint64_t symbol_id;
```
math_engine_expression_semantic_diagnostic_t.expected
Code별 기대 arity/mode/kind/resource ceiling 값이다.
```
uint32_t expected;
```
math_engine_expression_semantic_diagnostic_t.actual
Code별 관측 arity/mode/kind/resource 사용량 값이다.
```
uint32_t actual;
```
math_engine_expression_semantic_diagnostic_t.reserved
Library가 0으로 기록하고 reader가 무시하는 ABI 확장 word다.
```
uint64_t reserved[2];
```

`math_engine_expression_eval_frame_t`

평가마다 caller가 제공하는 mutable value slots, RNG와 custom registry view다.

typedef struct math_engine_expression_eval_frame {
    uint32_t struct_size; /**< Caller가 exact evaluation-frame byte 크기로 설정한다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_EVAL_FRAME_VERSION_1=이어야 한다. */
    uint32_t flags; /**< V1 frame에는 정의된 bit가 없어 반드시 0이다. */
    uint32_t reserved32; /**< Caller는 0으로 두며 evaluator가 nonzero를 거부한다. */
    math_engine_quantity_t* values; /**< Caller-owned mutable slot 배열; NULL은 =value_count==0=일 때만 허용되고 evaluate 동안 독점 유효하다. */
    uint64_t value_count; /**< =values= element 수이며 =program.value_slot_count= 이상이어야 한다. */
    math_engine_rng_t* rng; /**< Nullable caller-owned mutable RNG; stateful RNG CALL 전체 동안 유효하며 engine은 보관하지 않는다. */
    const math_engine_expression_function_binding_t* custom_functions; /**< Borrowed binding 배열; NULL은 count 0일 때만 허용되고 callback을 포함해 evaluate return까지 유효하다. */
    uint64_t custom_function_count; /**< =custom_functions= element 수이며 program registry fingerprint와 일치해야 한다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하는 ABI 확장 word 두 개다. */
} math_engine_expression_eval_frame_t;

math_engine_expression_eval_frame_t.struct_size
Caller가 exact evaluation-frame byte 크기로 설정한다.
```
uint32_t struct_size;
```
math_engine_expression_eval_frame_t.version
MATH_ENGINE_EXPRESSION_EVAL_FRAME_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_eval_frame_t.flags
V1 frame에는 정의된 bit가 없어 반드시 0이다.
```
uint32_t flags;
```
math_engine_expression_eval_frame_t.reserved32
Caller는 0으로 두며 evaluator가 nonzero를 거부한다.
```
uint32_t reserved32;
```
math_engine_expression_eval_frame_t.values
Caller-owned mutable slot 배열; NULL은 =value_count==0=일 때만 허용되고 evaluate 동안 독점 유효하다.
```
math_engine_quantity_t* values;
```
math_engine_expression_eval_frame_t.value_count
values element 수이며 program.value_slot_count 이상이어야 한다.
```
uint64_t value_count;
```
math_engine_expression_eval_frame_t.rng
Nullable caller-owned mutable RNG; stateful RNG CALL 전체 동안 유효하며 engine은 보관하지 않는다.
```
math_engine_rng_t* rng;
```
math_engine_expression_eval_frame_t.custom_functions
Borrowed binding 배열; NULL은 count 0일 때만 허용되고 callback을 포함해 evaluate return까지 유효하다.
```
const math_engine_expression_function_binding_t* custom_functions;
```
math_engine_expression_eval_frame_t.custom_function_count
custom_functions element 수이며 program registry fingerprint와 일치해야 한다.
```
uint64_t custom_function_count;
```
math_engine_expression_eval_frame_t.reserved
Caller가 0으로 두어야 하는 ABI 확장 word 두 개다.
```
uint64_t reserved[2];
```

`math_engine_expression_pending_store_t`

성공 시 value frame에 원자적으로 반영할 assignment 하나를 보관하는 scratch다.

typedef struct math_engine_expression_pending_store {
    uint32_t struct_size; /**< Evaluator가 exact pending-store record byte 크기를 쓴다. */
    uint32_t version; /**< Evaluator가 =MATH_ENGINE_EXPRESSION_PENDING_STORE_VERSION_1=을 쓴다. */
    uint32_t value_slot; /**< 성공 시 =frame.values[value_slot]=에 commit할 zero-based index다. */
    uint32_t reserved32; /**< ABI 확장용이며 evaluator가 0으로 기록하고 caller가 무시한다. */
    math_engine_quantity_t value; /**< Evaluation 성공 뒤 해당 slot에 값으로 복사할 완전한 quantity다. */
} math_engine_expression_pending_store_t;

math_engine_expression_pending_store_t.struct_size
Evaluator가 exact pending-store record byte 크기를 쓴다.
```
uint32_t struct_size;
```
math_engine_expression_pending_store_t.version
Evaluator가 MATH_ENGINE_EXPRESSION_PENDING_STORE_VERSION_1 을 쓴다.
```
uint32_t version;
```
math_engine_expression_pending_store_t.value_slot
성공 시 frame.values[value_slot] 에 commit할 zero-based index다.
```
uint32_t value_slot;
```
math_engine_expression_pending_store_t.reserved32
ABI 확장용이며 evaluator가 0으로 기록하고 caller가 무시한다.
```
uint32_t reserved32;
```
math_engine_expression_pending_store_t.value
Evaluation 성공 뒤 해당 slot에 값으로 복사할 완전한 quantity다.
```
math_engine_quantity_t value;
```

`math_engine_expression_eval_workspace_t`

Program header가 요구하는 stack과 pending-store caller workspace다.

typedef struct math_engine_expression_eval_workspace {
    uint32_t struct_size; /**< Caller가 exact eval-workspace byte 크기로 설정한다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_EVAL_WORKSPACE_VERSION_1=이어야 한다. */
    math_engine_quantity_t* stack; /**< Caller-owned mutable operand array; NULL은 capacity 0일 때만 허용되고 evaluate 동안 독점 사용된다. */
    uint64_t stack_capacity; /**< =stack= element capacity이며 =program.maximum_stack= 이상이다. */
    math_engine_expression_pending_store_t* pending_stores; /**< Caller-owned mutable atomic-commit scratch; NULL은 capacity 0일 때만 허용되고 호출 뒤 내용은 scratch다. */
    uint64_t pending_store_capacity; /**< 배열 element capacity이며 =program.maximum_pending_stores= 이상이다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두고 evaluator가 검사하는 ABI 확장 word다. */
} math_engine_expression_eval_workspace_t;

math_engine_expression_eval_workspace_t.struct_size
Caller가 exact eval-workspace byte 크기로 설정한다.
```
uint32_t struct_size;
```
math_engine_expression_eval_workspace_t.version
MATH_ENGINE_EXPRESSION_EVAL_WORKSPACE_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_eval_workspace_t.stack
Caller-owned mutable operand array; NULL은 capacity 0일 때만 허용되고 evaluate 동안 독점 사용된다.
```
math_engine_quantity_t* stack;
```
math_engine_expression_eval_workspace_t.stack_capacity
stack element capacity이며 program.maximum_stack 이상이다.
```
uint64_t stack_capacity;
```
math_engine_expression_eval_workspace_t.pending_stores
Caller-owned mutable atomic-commit scratch; NULL은 capacity 0일 때만 허용되고 호출 뒤 내용은 scratch다.
```
math_engine_expression_pending_store_t* pending_stores;
```
math_engine_expression_eval_workspace_t.pending_store_capacity
배열 element capacity이며 program.maximum_pending_stores 이상이다.
```
uint64_t pending_store_capacity;
```
math_engine_expression_eval_workspace_t.reserved
Caller가 0으로 두고 evaluator가 검사하는 ABI 확장 word다.
```
uint64_t reserved[2];
```

`math_engine_expression_eval_result_t`

성공한 평가의 값, 사용량과 결정적 fingerprint다.

typedef struct math_engine_expression_eval_result {
    uint32_t struct_size; /**< Caller가 exact eval-result byte 크기로 미리 설정한다. */
    uint32_t version; /**< Caller가 =MATH_ENGINE_EXPRESSION_EVAL_RESULT_VERSION_1=로 설정한다. */
    uint32_t flags; /**< 성공한 program의 assignment/stateful 사용 bit를 복사하며 미정의 bit는 0이다. */
    uint32_t reserved32; /**< Library가 0으로 commit하고 reader가 무시하는 ABI slot이다. */
    uint64_t instructions_executed; /**< 성공 평가에서 순서대로 실행한 instruction 수다. */
    uint64_t maximum_stack_used; /**< 실행 중 동시에 유효했던 stack element의 최대 수다. */
    uint64_t pending_store_count; /**< 성공 뒤 frame에 원자 commit한 assignment 수다. */
    uint64_t evaluation_fingerprint; /**< 실행 opcode와 intermediate/result quantity를 결합한 결정적 hash다. */
    math_engine_quantity_t value; /**< 최종 stack top의 validated quantity 결과를 값으로 소유한다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 reader가 무시하는 ABI 확장 word다. */
} math_engine_expression_eval_result_t;

math_engine_expression_eval_result_t.struct_size
Caller가 exact eval-result byte 크기로 미리 설정한다.
```
uint32_t struct_size;
```
math_engine_expression_eval_result_t.version
Caller가 MATH_ENGINE_EXPRESSION_EVAL_RESULT_VERSION_1 로 설정한다.
```
uint32_t version;
```
math_engine_expression_eval_result_t.flags
성공한 program의 assignment/stateful 사용 bit를 복사하며 미정의 bit는 0이다.
```
uint32_t flags;
```
math_engine_expression_eval_result_t.reserved32
Library가 0으로 commit하고 reader가 무시하는 ABI slot이다.
```
uint32_t reserved32;
```
math_engine_expression_eval_result_t.instructions_executed
성공 평가에서 순서대로 실행한 instruction 수다.
```
uint64_t instructions_executed;
```
math_engine_expression_eval_result_t.maximum_stack_used
실행 중 동시에 유효했던 stack element의 최대 수다.
```
uint64_t maximum_stack_used;
```
math_engine_expression_eval_result_t.pending_store_count
성공 뒤 frame에 원자 commit한 assignment 수다.
```
uint64_t pending_store_count;
```
math_engine_expression_eval_result_t.evaluation_fingerprint
실행 opcode와 intermediate/result quantity를 결합한 결정적 hash다.
```
uint64_t evaluation_fingerprint;
```
math_engine_expression_eval_result_t.value
최종 stack top의 validated quantity 결과를 값으로 소유한다.
```
math_engine_quantity_t value;
```
math_engine_expression_eval_result_t.reserved
Library가 0으로 기록하고 reader가 무시하는 ABI 확장 word다.
```
uint64_t reserved[2];
```

`math_engine_expression_program_serialization_result_t`

Wire 처리량과 필요 instruction/constant capacity를 전달하는 결과다.

typedef struct math_engine_expression_program_serialization_result {
    uint32_t struct_size; /**< Caller가 exact serialization-result byte 크기로 미리 설정한다. */
    uint32_t version; /**< =MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_RESULT_VERSION_1=이어야 한다. */
    uint32_t flags; /**< V1 wire 결과에는 정의된 bit가 없어 library가 0을 기록한다. */
    uint32_t reserved32; /**< Library가 0으로 commit하고 reader가 무시하는 ABI slot이다. */
    uint64_t instruction_count; /**< 성공 시 wire에 썼거나 wire에서 읽은 instruction element 수다. */
    uint64_t constant_count; /**< 성공 시 wire에 썼거나 wire에서 읽은 constant element 수다. */
    uint64_t bytes_consumed; /**< 성공 시 작성/소비한 MEBP byte 수; trailing byte는 허용하지 않는다. */
    uint64_t payload_fingerprint; /**< Wire header가 인증하는 payload byte열의 결정적 hash다. */
    uint64_t required_instruction_count; /**< Deserialize 성공/부족 시 필요한 instruction capacity다. */
    uint64_t required_constant_count; /**< Deserialize 성공/부족 시 필요한 constant capacity다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 reader가 무시하는 ABI 확장 word다. */
} math_engine_expression_program_serialization_result_t;

math_engine_expression_program_serialization_result_t.struct_size
Caller가 exact serialization-result byte 크기로 미리 설정한다.
```
uint32_t struct_size;
```
math_engine_expression_program_serialization_result_t.version
MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_RESULT_VERSION_1 이어야 한다.
```
uint32_t version;
```
math_engine_expression_program_serialization_result_t.flags
V1 wire 결과에는 정의된 bit가 없어 library가 0을 기록한다.
```
uint32_t flags;
```
math_engine_expression_program_serialization_result_t.reserved32
Library가 0으로 commit하고 reader가 무시하는 ABI slot이다.
```
uint32_t reserved32;
```
math_engine_expression_program_serialization_result_t.instruction_count
성공 시 wire에 썼거나 wire에서 읽은 instruction element 수다.
```
uint64_t instruction_count;
```
math_engine_expression_program_serialization_result_t.constant_count
성공 시 wire에 썼거나 wire에서 읽은 constant element 수다.
```
uint64_t constant_count;
```
math_engine_expression_program_serialization_result_t.bytes_consumed
성공 시 작성/소비한 MEBP byte 수; trailing byte는 허용하지 않는다.
```
uint64_t bytes_consumed;
```
math_engine_expression_program_serialization_result_t.payload_fingerprint
Wire header가 인증하는 payload byte열의 결정적 hash다.
```
uint64_t payload_fingerprint;
```
math_engine_expression_program_serialization_result_t.required_instruction_count
Deserialize 성공/부족 시 필요한 instruction capacity다.
```
uint64_t required_instruction_count;
```
math_engine_expression_program_serialization_result_t.required_constant_count
Deserialize 성공/부족 시 필요한 constant capacity다.
```
uint64_t required_constant_count;
```
math_engine_expression_program_serialization_result_t.reserved
Library가 0으로 기록하고 reader가 무시하는 ABI 확장 word다.
```
uint64_t reserved[2];
```

Anonymous enum

`anonymous_enum_at_line_96`

함수의 순수성, 결정성, state와 dimension 제약 flag다.

enum {
    MATH_ENGINE_EXPRESSION_FUNCTION_PURE = 1u << 0, /**< Bit 0: 같은 인수 외의 observable state를 읽거나 쓰지 않는다. */
    MATH_ENGINE_EXPRESSION_FUNCTION_DETERMINISTIC = 1u << 1, /**< Bit 1: 같은 context/인수에 같은 bitwise 결과를 낸다. */
    MATH_ENGINE_EXPRESSION_FUNCTION_STATEFUL = 1u << 2, /**< Bit 2: RNG 또는 caller user_data 상태를 변경할 수 있다. */
    MATH_ENGINE_EXPRESSION_FUNCTION_EMBEDDED = 1u << 3, /**< Bit 3: embedded expression profile에서도 제공된다. */
    MATH_ENGINE_EXPRESSION_FUNCTION_DIMENSIONLESS_ARGUMENTS = 1u << 4, /**< Bit 4: 모든 argument unit이 dimensionless여야 한다. */
    MATH_ENGINE_EXPRESSION_FUNCTION_DIMENSIONLESS_RESULT = 1u << 5 /**< Bit 5: 반환 quantity unit이 dimensionless여야 한다. */
};

MATH_ENGINE_EXPRESSION_FUNCTION_PURE
Bit 0: 같은 인수 외의 observable state를 읽거나 쓰지 않는다.
```
MATH_ENGINE_EXPRESSION_FUNCTION_PURE = 1u << 0,
```
MATH_ENGINE_EXPRESSION_FUNCTION_DETERMINISTIC
Bit 1: 같은 context/인수에 같은 bitwise 결과를 낸다.
```
MATH_ENGINE_EXPRESSION_FUNCTION_DETERMINISTIC = 1u << 1,
```
MATH_ENGINE_EXPRESSION_FUNCTION_STATEFUL
Bit 2: RNG 또는 caller user_data 상태를 변경할 수 있다.
```
MATH_ENGINE_EXPRESSION_FUNCTION_STATEFUL = 1u << 2,
```
MATH_ENGINE_EXPRESSION_FUNCTION_EMBEDDED
Bit 3: embedded expression profile에서도 제공된다.
```
MATH_ENGINE_EXPRESSION_FUNCTION_EMBEDDED = 1u << 3,
```
MATH_ENGINE_EXPRESSION_FUNCTION_DIMENSIONLESS_ARGUMENTS
Bit 4: 모든 argument unit이 dimensionless여야 한다.
```
MATH_ENGINE_EXPRESSION_FUNCTION_DIMENSIONLESS_ARGUMENTS = 1u << 4,
```
MATH_ENGINE_EXPRESSION_FUNCTION_DIMENSIONLESS_RESULT
Bit 5: 반환 quantity unit이 dimensionless여야 한다.
```
MATH_ENGINE_EXPRESSION_FUNCTION_DIMENSIONLESS_RESULT = 1u << 5,
```

`anonymous_enum_at_line_106`

Symbol value slot의 쓰기 가능 여부와 input 역할 flag다.

enum {
    MATH_ENGINE_EXPRESSION_SYMBOL_WRITABLE = 1u << 0, /**< Bit 0: STORE_VALUE assignment target으로 compile할 수 있다. */
    MATH_ENGINE_EXPRESSION_SYMBOL_INPUT = 1u << 1 /**< Bit 1: 외부에서 frame slot을 채우는 입력 symbol임을 표시한다. */
};

MATH_ENGINE_EXPRESSION_SYMBOL_WRITABLE
Bit 0: STORE_VALUE assignment target으로 compile할 수 있다.
```
MATH_ENGINE_EXPRESSION_SYMBOL_WRITABLE = 1u << 0,
```
MATH_ENGINE_EXPRESSION_SYMBOL_INPUT
Bit 1: 외부에서 frame slot을 채우는 입력 symbol임을 표시한다.
```
MATH_ENGINE_EXPRESSION_SYMBOL_INPUT = 1u << 1,
```

`anonymous_enum_at_line_112`

Compile에서 assignment/stateful 함수/exact folding을 허용하는 정책 flag다.

enum {
    MATH_ENGINE_EXPRESSION_COMPILE_ALLOW_ASSIGNMENT = 1u << 0, /**< Bit 0: writable symbol에 대한 assignment AST를 허용한다. */
    MATH_ENGINE_EXPRESSION_COMPILE_ALLOW_STATEFUL = 1u << 1, /**< Bit 1: RNG/custom stateful CALL opcode 생성을 허용한다. */
    MATH_ENGINE_EXPRESSION_COMPILE_FOLD_EXACT_ARITHMETIC = 1u << 2 /**< Bit 2: compile-time exact 상수 산술을 constant 하나로 접는다. */
};

MATH_ENGINE_EXPRESSION_COMPILE_ALLOW_ASSIGNMENT
Bit 0: writable symbol에 대한 assignment AST를 허용한다.
```
MATH_ENGINE_EXPRESSION_COMPILE_ALLOW_ASSIGNMENT = 1u << 0,
```
MATH_ENGINE_EXPRESSION_COMPILE_ALLOW_STATEFUL
Bit 1: RNG/custom stateful CALL opcode 생성을 허용한다.
```
MATH_ENGINE_EXPRESSION_COMPILE_ALLOW_STATEFUL = 1u << 1,
```
MATH_ENGINE_EXPRESSION_COMPILE_FOLD_EXACT_ARITHMETIC
Bit 2: compile-time exact 상수 산술을 constant 하나로 접는다.
```
MATH_ENGINE_EXPRESSION_COMPILE_FOLD_EXACT_ARITHMETIC = 1u << 2,
```

`anonymous_enum_at_line_270`

Constant record가 runtime 값인지 type-check 전용 값인지 구분하는 flag다.

enum {
    MATH_ENGINE_EXPRESSION_CONSTANT_VALUE = 1u << 0, /**< Bit 0 단독: PUSH_CONSTANT가 runtime 값으로 사용한다. */
    MATH_ENGINE_EXPRESSION_CONSTANT_TYPE_ONLY = 1u << 1 /**< Bit 1 단독: LOAD/STORE의 numeric-kind/unit 검증 template다. */
};

MATH_ENGINE_EXPRESSION_CONSTANT_VALUE
Bit 0 단독: PUSH_CONSTANT가 runtime 값으로 사용한다.
```
MATH_ENGINE_EXPRESSION_CONSTANT_VALUE = 1u << 0,
```
MATH_ENGINE_EXPRESSION_CONSTANT_TYPE_ONLY
Bit 1 단독: LOAD/STORE의 numeric-kind/unit 검증 template다.
```
MATH_ENGINE_EXPRESSION_CONSTANT_TYPE_ONLY = 1u << 1,
```

Macro와 constant

`MATH_ENGINE_EXPRESSION_COMPILE_NODE_VERSION_1`

Compile scratch-node V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_COMPILE_NODE_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_COMPILE_OPTIONS_VERSION_1`

Compile options V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_COMPILE_OPTIONS_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_CONSTANT_VERSION_1`

Constant record V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_CONSTANT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_EVAL_FRAME_VERSION_1`

Mutable evaluation frame V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_EVAL_FRAME_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_EVAL_RESULT_VERSION_1`

Evaluation result V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_EVAL_RESULT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_EVAL_WORKSPACE_VERSION_1`

Evaluation workspace V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_EVAL_WORKSPACE_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_FUNCTION_BINDING_VERSION_1`

Function binding V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_FUNCTION_BINDING_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_FUNCTION_DESCRIPTOR_VERSION_1`

Function descriptor V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_FUNCTION_DESCRIPTOR_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_INSTRUCTION_VERSION_1`

Pointer-free instruction V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_INSTRUCTION_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_NAME_CAPACITY`

함수·symbol 이름 storage의 byte 수다. 유효한 이름은 끝 NUL을 제외하고 1..31 byte다.

#define MATH_ENGINE_EXPRESSION_NAME_CAPACITY UINT32_C(32)

`MATH_ENGINE_EXPRESSION_PENDING_STORE_VERSION_1`

Pending assignment V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_PENDING_STORE_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_RESULT_VERSION_1`

Serialization result V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_RESULT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_VERSION_1`

MEBP little-endian wire schema의 최초 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_PROGRAM_VERSION_1`

Compiled program header V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_PROGRAM_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_SEMANTIC_DIAGNOSTIC_VERSION_1`

Semantic diagnostic V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_SEMANTIC_DIAGNOSTIC_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_SYMBOL_DESCRIPTOR_VERSION_1`

Symbol descriptor V1 layout에 기록하는 unsigned version 값 1이다.

#define MATH_ENGINE_EXPRESSION_SYMBOL_DESCRIPTOR_VERSION_1 UINT32_C(1)

`MATH_ENGINE_EXPRESSION_USER_REGISTRY_ID_MIN`

Caller registry ID의 포함 하한 2^63 (0x8000000000000000); bit 63이 1인 namespace다.

#define MATH_ENGINE_EXPRESSION_USER_REGISTRY_ID_MIN UINT64_C(0x8000000000000000)

Function

`math_engine_expression_function_count`

현재 build에 내장된 expression 함수 descriptor 수를 반환한다.

반환: Built-in math, number-theory와 RNG 함수의 합계.
Math Engine thread_safety: safe

MATH_ENGINE_API uint32_t math_engine_expression_function_count(void);

`math_engine_expression_registry_fingerprint`

Built-in catalog와 custom descriptor 집합의 순서 독립 fingerprint를 계산한다.

매개변수 custom_functions: 검증할 caller-owned binding 배열. count가 0이면 NULL 가능하다.
매개변수 custom_function_count: 배열 항목 수.
반환: 유효하면 0이 아닌 fingerprint, registry가 유효하지 않으면 0.
Math Engine ownership: custom_functions=borrowed
Math Engine nullable: custom_functions=count_zero_only
Math Engine thread_safety: safe

MATH_ENGINE_API uint64_t math_engine_expression_registry_fingerprint(
    const math_engine_expression_function_binding_t* custom_functions,
    size_t custom_function_count);

`math_engine_expression_function_at`

Built-in 함수 descriptor를 catalog index로 복사한다.

매개변수 index: 0부터 시작하는 built-in index.
매개변수 out_descriptor: 성공 시 descriptor를 받는 caller-owned 출력. 실패하면 보존된다.
반환: 성공하면 OK, 범위 밖 또는 NULL이면 INVALID_ARGUMENT.
Math Engine ownership: out_descriptor=caller
Math Engine nullable: out_descriptor=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_expression_function_at(
    uint32_t index,
    math_engine_expression_function_descriptor_t* out_descriptor);

`math_engine_expression_function_find`

이름 byte열과 arity가 정확히 일치하는 built-in/custom 함수를 찾는다.

매개변수 name: NUL 종료에 의존하지 않는 함수 이름 byte열.
매개변수 name_size: 1..31 범위의 이름 byte 수.
매개변수 arity: 0..8 범위의 호출 인수 수.
매개변수 custom_functions: 추가 binding 배열. count가 0이면 NULL 가능하다.
매개변수 custom_function_count: 추가 binding 수.
매개변수 out_descriptor: 유일하게 찾은 descriptor를 받는 출력. 실패하면 보존된다.
반환: 유일한 match면 OK, 없음·중복·registry·인수 오류면 INVALID_ARGUMENT 계열 status.
Math Engine ownership: name=borrowed custom_functions=borrowed out_descriptor=caller
Math Engine nullable: name=false custom_functions=count_zero_only out_descriptor=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_expression_function_find(
    const char* name,
    size_t name_size,
    uint32_t arity,
    const math_engine_expression_function_binding_t* custom_functions,
    size_t custom_function_count,
    math_engine_expression_function_descriptor_t* out_descriptor);

`math_engine_expression_registry_validate`

Custom binding의 ABI, callback, ID, 이름/arity 중복과 fingerprint를 검증한다.

매개변수 custom_functions: 검증할 binding 배열. count가 0이면 NULL 가능하다.
매개변수 custom_function_count: 배열 항목 수. Embedded profile에서는 0만 지원한다.
매개변수 out_diagnostic: 중복 ID/함수 진단을 선택적으로 받을 출력.
반환: 유효하면 OK, 잘못된 binding이면 INVALID_ARGUMENT, profile 제한이면 UNSUPPORTED.
Math Engine ownership: custom_functions=borrowed out_diagnostic=caller
Math Engine nullable: custom_functions=count_zero_only out_diagnostic=true
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_expression_registry_validate(
    const math_engine_expression_function_binding_t* custom_functions,
    size_t custom_function_count,
    math_engine_expression_semantic_diagnostic_t* out_diagnostic);

`math_engine_expression_compile_options_init`

현재 build profile의 기본 compile option과 resource 상한을 초기화한다.

매개변수 out_options: 성공 시 기본값을 받는 caller-owned 출력.
반환: 성공하면 OK, NULL이면 INVALID_ARGUMENT.
Math Engine ownership: out_options=caller
Math Engine nullable: out_options=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_expression_compile_options_init(
    math_engine_expression_compile_options_t* out_options);

`math_engine_expression_compile_utf8`

Parser AST를 검증하고 caller buffer에 pointer-free program을 compile한다.

매개변수 source: NUL 종료에 의존하지 않는 원본 UTF-8 byte열.
매개변수 source_size: 0보다 큰 source byte 수.
매개변수 nodes: 후위 순서 AST node 배열. root_index는 node_count-1이어야 한다.
매개변수 node_count: AST node 수.
매개변수 root_index: root node index.
매개변수 symbols: source symbol descriptor 배열. symbol_count가 0이면 NULL 가능하다.
매개변수 symbol_count: symbol 수.
매개변수 custom_functions: custom binding 배열. count가 0이면 NULL 가능하다.
매개변수 custom_function_count: custom binding 수.
매개변수 options: 초기화하고 검증한 compile 정책.
매개변수 context: mode, budget과 선택적 cancel callback을 제공하는 읽기 전용 context.
매개변수 node_workspace: node_count개 compile scratch. 실패 후 내용은 지정되지 않는다.
매개변수 node_workspace_count: scratch 항목 capacity. node_count 이상이어야 한다.
매개변수 instructions: 생성 instruction 배열. capacity가 0이면 NULL 가능하다.
매개변수 instruction_capacity: instruction 항목 capacity.
매개변수 constants: 생성 constant 배열. capacity가 0이면 NULL 가능하다.
매개변수 constant_capacity: constant 항목 capacity.
매개변수 out_program: 성공 시에만 commit되는 program header.
매개변수 out_diagnostic: semantic 실패 진단을 선택적으로 받을 출력.
반환: 성공하면 OK, semantic/모드 오류 또는 부족한 출력 capacity면 해당 status.
Math Engine ownership: source=borrowed nodes=borrowed symbols=borrowed custom_functions=borrowed options=borrowed context=borrowed node_workspace=caller instructions=caller constants=caller out_program=caller out_diagnostic=caller
Math Engine nullable: source=false nodes=false symbols=count_zero_only custom_functions=count_zero_only options=false context=false node_workspace=false instructions=capacity_zero_only constants=capacity_zero_only out_program=false out_diagnostic=true
Math Engine thread_safety: conditional

@details 입력 배열, 세 출력/scratch 배열과 out_program은 서로 겹치면 안 된다. 실패하면 out_program은 보존되지만 node_workspace/instructions/constants는 부분 변경될 수 있다.

MATH_ENGINE_API math_engine_status_t math_engine_expression_compile_utf8(
    const char* source,
    size_t source_size,
    const math_engine_expression_node_t* nodes,
    size_t node_count,
    uint32_t root_index,
    const math_engine_expression_symbol_descriptor_t* symbols,
    size_t symbol_count,
    const math_engine_expression_function_binding_t* custom_functions,
    size_t custom_function_count,
    const math_engine_expression_compile_options_t* options,
    const math_engine_context_t* context,
    math_engine_expression_compile_node_t* node_workspace,
    size_t node_workspace_count,
    math_engine_expression_instruction_t* instructions,
    size_t instruction_capacity,
    math_engine_expression_constant_t* constants,
    size_t constant_capacity,
    math_engine_expression_program_t* out_program,
    math_engine_expression_semantic_diagnostic_t* out_diagnostic);

`math_engine_expression_program_validate`

Pointer-free program 전체의 ABI, stack 흐름, count와 logical fingerprint를 검증한다.

매개변수 program: 검증할 읽기 전용 program header.
매개변수 instructions: program.instruction_count개 읽기 전용 instruction 배열.
매개변수 instruction_count: 전달한 instruction 항목 수. 0은 유효하지 않다.
매개변수 constants: program.constant_count개 읽기 전용 constant 배열. count가 0이면 NULL 가능하다.
매개변수 constant_count: 전달한 constant 항목 수.
반환: 유효하면 OK, 크기·버전·opcode·stack·fingerprint 오류면 해당 status.
Math Engine ownership: program=borrowed instructions=borrowed constants=borrowed
Math Engine nullable: program=false instructions=false constants=count_zero_only
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_expression_program_validate(
    const math_engine_expression_program_t* program,
    const math_engine_expression_instruction_t* instructions,
    size_t instruction_count,
    const math_engine_expression_constant_t* constants,
    size_t constant_count);

`math_engine_expression_evaluate`

Immutable program을 다시 parse하지 않고 caller frame과 workspace에서 평가한다.

매개변수 program: 검증할 program header.
매개변수 instructions: program의 읽기 전용 instruction 배열.
매개변수 instruction_count: instruction 항목 수.
매개변수 constants: program의 읽기 전용 constant 배열. count가 0이면 NULL 가능하다.
매개변수 constant_count: constant 항목 수.
매개변수 context: mode, budget과 선택적 cancel callback의 읽기 전용 context.
매개변수 frame: caller-owned value slots, 선택적 RNG와 custom callback binding. 성공한 STORE만 변경한다.
매개변수 workspace: program maximum_stack/pending_stores 이상인 caller-owned scratch view.
매개변수 out_result: 성공 시 평가값과 사용량을 받는 미리 초기화한 출력. 실패하면 보존된다.
매개변수 out_diagnostic: stale registry/unit 또는 semantic 진단을 선택적으로 받는 출력.
반환: 성공하면 OK, 검증·workspace·callback·budget·취소·산술 오류면 해당 status.
Math Engine ownership: program=borrowed instructions=borrowed constants=borrowed context=borrowed frame=caller workspace=borrowed out_result=caller out_diagnostic=caller
Math Engine nullable: program=false instructions=false constants=count_zero_only context=false frame=false workspace=false out_result=false out_diagnostic=true
Math Engine thread_safety: conditional

@details Frame values, RNG, custom user_data와 workspace를 다른 호출과 공유하면 호출자가 직렬화한다. 실패하면 STORE_VALUE는 반영되지 않지만 RNG, callback user_data와 workspace scratch는 이미 변경될 수 있다.

MATH_ENGINE_API math_engine_status_t math_engine_expression_evaluate(
    const math_engine_expression_program_t* program,
    const math_engine_expression_instruction_t* instructions,
    size_t instruction_count,
    const math_engine_expression_constant_t* constants,
    size_t constant_count,
    const math_engine_context_t* context,
    math_engine_expression_eval_frame_t* frame,
    const math_engine_expression_eval_workspace_t* workspace,
    math_engine_expression_eval_result_t* out_result,
    math_engine_expression_semantic_diagnostic_t* out_diagnostic);

`math_engine_expression_program_serialized_size`

MEBP v1 little-endian wire 표현의 정확한 byte 수를 계산한다.

매개변수 instruction_count: 0보다 큰 instruction 수.
매개변수 constant_count: constant 수. 0 가능.
매개변수 out_size: 성공 시 필요한 wire byte 수를 받는 출력. 실패하면 보존된다.
반환: 성공하면 OK, 0 instruction이면 INVALID_ARGUMENT, 산술 overflow면 OVERFLOW.
Math Engine ownership: out_size=caller
Math Engine nullable: out_size=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_expression_program_serialized_size(
    size_t instruction_count,
    size_t constant_count,
    size_t* out_size);

`math_engine_expression_program_serialize`

검증된 pointer-free program을 MEBP v1 little-endian wire로 직렬화한다.

매개변수 program: 직렬화할 검증된 program header.
매개변수 instructions: instruction 배열.
매개변수 instruction_count: instruction 항목 수.
매개변수 constants: constant 배열. count가 0이면 NULL 가능하다.
매개변수 constant_count: constant 항목 수.
매개변수 output: wire를 받을 caller buffer. capacity가 0이면 NULL 가능하다.
매개변수 output_capacity: output의 byte 용량.
매개변수 out_result: 처리량과 필요 크기를 받는 출력. 작은 buffer에서도 commit된다.
반환: 성공하면 OK, 작은 buffer면 INSUFFICIENT_BUFFER, program 검증 오류면 해당 status.
Math Engine ownership: program=borrowed instructions=borrowed constants=borrowed output=caller out_result=caller
Math Engine nullable: program=false instructions=false constants=count_zero_only output=capacity_zero_only out_result=false
Math Engine thread_safety: safe

@details output은 program/instructions/constants/out_result와 겹치면 안 된다. INSUFFICIENT_BUFFER에서는 output을 변경하지 않고 out_result에 필요량을 기록한다.

MATH_ENGINE_API math_engine_status_t math_engine_expression_program_serialize(
    const math_engine_expression_program_t* program,
    const math_engine_expression_instruction_t* instructions,
    size_t instruction_count,
    const math_engine_expression_constant_t* constants,
    size_t constant_count,
    unsigned char* output,
    size_t output_capacity,
    math_engine_expression_program_serialization_result_t* out_result);

`math_engine_expression_program_deserialize`

MEBP v1의 magic, schema, 크기, payload와 logical fingerprint를 검증해 복원한다.

매개변수 input: 완전한 wire byte 배열.
매개변수 input_size: wire의 정확한 byte 수. trailing byte를 허용하지 않는다.
매개변수 instructions: 복원 instruction 배열. capacity가 0이면 NULL 가능하다.
매개변수 instruction_capacity: instruction 항목 capacity.
매개변수 constants: 복원 constant 배열. capacity가 0이면 NULL 가능하다.
매개변수 constant_capacity: constant 항목 capacity.
매개변수 out_program: 성공 시 복원 program header를 받는 출력.
매개변수 out_result: 처리량과 필요 capacity를 받는 출력. workspace 부족에서도 commit된다.
반환: 성공하면 OK, capacity 부족이면 INSUFFICIENT_WORKSPACE, wire 오류면 검증 status.
Math Engine ownership: input=borrowed instructions=caller constants=caller out_program=caller out_result=caller
Math Engine nullable: input=false instructions=capacity_zero_only constants=capacity_zero_only out_program=false out_result=false
Math Engine thread_safety: safe

@details input과 모든 출력은 겹치면 안 된다. 전체 검증 뒤에만 arrays/out_program을 commit하며 부족한 경우에는 out_result만 변경한다.

MATH_ENGINE_API math_engine_status_t math_engine_expression_program_deserialize(
    const unsigned char* input,
    size_t input_size,
    math_engine_expression_instruction_t* instructions,
    size_t instruction_capacity,
    math_engine_expression_constant_t* constants,
    size_t constant_capacity,
    math_engine_expression_program_t* out_program,
    math_engine_expression_program_serialization_result_t* out_result);

Math Engine Reference: Expression Program

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_expression_function_provider_t

math_engine_expression_number_theory_function_t

math_engine_expression_rng_function_t

math_engine_expression_opcode_t

math_engine_expression_semantic_diagnostic_code_t

math_engine_expression_function_descriptor_t

math_engine_expression_function_callback_t

math_engine_expression_function_binding_t

math_engine_expression_symbol_descriptor_t

math_engine_expression_compile_options_t

math_engine_expression_compile_node_t

math_engine_expression_instruction_t

math_engine_expression_constant_t

math_engine_expression_program_t

math_engine_expression_semantic_diagnostic_t

math_engine_expression_eval_frame_t

math_engine_expression_pending_store_t

math_engine_expression_eval_workspace_t

math_engine_expression_eval_result_t

math_engine_expression_program_serialization_result_t

Anonymous enum

anonymous_enum_at_line_96

anonymous_enum_at_line_106

anonymous_enum_at_line_112

anonymous_enum_at_line_270

Macro와 constant

MATH_ENGINE_EXPRESSION_COMPILE_NODE_VERSION_1

MATH_ENGINE_EXPRESSION_COMPILE_OPTIONS_VERSION_1

MATH_ENGINE_EXPRESSION_CONSTANT_VERSION_1

MATH_ENGINE_EXPRESSION_EVAL_FRAME_VERSION_1

MATH_ENGINE_EXPRESSION_EVAL_RESULT_VERSION_1

MATH_ENGINE_EXPRESSION_EVAL_WORKSPACE_VERSION_1

MATH_ENGINE_EXPRESSION_FUNCTION_BINDING_VERSION_1

MATH_ENGINE_EXPRESSION_FUNCTION_DESCRIPTOR_VERSION_1

MATH_ENGINE_EXPRESSION_INSTRUCTION_VERSION_1

MATH_ENGINE_EXPRESSION_NAME_CAPACITY

MATH_ENGINE_EXPRESSION_PENDING_STORE_VERSION_1

MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_RESULT_VERSION_1

MATH_ENGINE_EXPRESSION_PROGRAM_SERIALIZATION_VERSION_1

MATH_ENGINE_EXPRESSION_PROGRAM_VERSION_1

MATH_ENGINE_EXPRESSION_SEMANTIC_DIAGNOSTIC_VERSION_1

MATH_ENGINE_EXPRESSION_SYMBOL_DESCRIPTOR_VERSION_1

MATH_ENGINE_EXPRESSION_USER_REGISTRY_ID_MIN