Maestro Runtime API

This document is a standalone reference for the public runtime-facing Maestro API.

Related API docs:

• api-common.md
• api-compile.md
• ../extension-guide.md

Canonical umbrella header:

• ../../include/maestro/maestro.h

Direct runtime headers:

• ../../include/maestro/runtime.h
• ../../include/maestro/runtime-helpers.h
• ../../include/maestro/common.h

Model

The public runtime API is intentionally opaque:

• maestro_ctx is an opaque runtime context
• maestro_value is an opaque runtime value

Callers create and destroy these objects only through public functions.

Common Types

Runtime code commonly uses:

• maestro_int_t
• maestro_float_t
• maestro_output
• maestro_alloc_fn
• maestro_free_fn

These are declared in ../../include/maestro/common.h and are also summarized in api-common.md.

Runtime Context Lifecycle

maestro_ctx_new

maestro_ctx *maestro_ctx_new(void);

Creates a new runtime context with default output functions and default allocation hooks.

maestro_ctx_free

void maestro_ctx_free(maestro_ctx *ctx);

Destroys a runtime context and releases runtime-owned context state.

Runtime Context Configuration

maestro_ctx_set_output

int maestro_ctx_set_output(maestro_ctx *ctx, maestro_output print_fn,
                           maestro_output log_fn);

Sets the program-visible print and log sinks.

maestro_ctx_set_vm_logger

int maestro_ctx_set_vm_logger(maestro_ctx *ctx, maestro_output fn);

Sets the VM-internal logging sink.

Runtime execution failures are reported through this logger as ERROR: ... messages when the runtime detects them. This includes invalid builtin use, invalid JSON snippet evaluation, missing runtime entry states, and other execution-time failures. Once the runtime detects such an execution error, the current run aborts immediately.

maestro_ctx_set_allocator

int maestro_ctx_set_allocator(maestro_ctx *ctx, maestro_alloc_fn alloc,
                              maestro_free_fn dealloc);

Overrides the allocator pair used for runtime-owned allocations created after the change.

maestro_ctx_set_capability

void maestro_ctx_set_capability(maestro_ctx *ctx, uint64_t vm_cap);

Sets the runtime capability bitmap used by validation.

maestro_ctx_set_log_flags

void maestro_ctx_set_log_flags(maestro_ctx *ctx, uint64_t flags);

Sets VM logging verbosity flags.

maestro_register_fn

int maestro_register_fn(maestro_ctx *ctx, const char *name, maestro_fn fn);

Registers one external function binding by name.

The registered callback receives borrowed input argument handles and returns a runtime-owned result handle through result.

maestro_ctx_load_dll

int maestro_ctx_load_dll(maestro_ctx *ctx, const char *path);

Loads a POSIX .so extension library, resolves MAESTRO_DLL_INIT_SYMBOL, and invokes the exported initializer.

The library remains attached to the context until maestro_ctx_free() releases it.

Loading and Validation

maestro_load

int maestro_load(maestro_ctx *ctx, const void *src);

Loads a packed .mstro image into the runtime context. The runtime uses the image zero-copy.

maestro_ctx_set_image_len

void maestro_ctx_set_image_len(maestro_ctx *ctx, size_t len);

Sets the loaded image size for stricter validation.

maestro_validate

uint64_t maestro_validate(maestro_ctx *ctx, FILE *err);

Validates the loaded image and current runtime bindings. Errors are reported as bit flags and may also be written to err.

maestro_list_externals

size_t maestro_list_externals(maestro_ctx *ctx, const char ***names);

Returns the required external function names recorded in the artifact.

Program Execution

maestro_run

int maestro_run(maestro_ctx *ctx, const char *module_path,
                maestro_value **args, size_t argc,
                maestro_value **result);

Runs the program identified by module_path.

module_path is a space-separated logical module path, for example:

app caller
tests modules worker

Input argument rules:

• args may be NULL only when argc == 0
• each input argument is a borrowed maestro_value *
• callers must keep the argument values alive and unchanged until maestro_run returns
• the runtime clones values that must escape into longer-lived runtime state

Result rules:

• result receives a runtime-allocated maestro_value *
• the caller owns that returned handle
• the caller must release it with maestro_value_free(ctx, result_value)

For .so extension callbacks, the same result ownership rule applies: the callback creates a runtime-owned result handle and the runtime later frees it after use.

Value Construction

These APIs create runtime values associated with a context.

maestro_value_new_invalid

maestro_value *maestro_value_new_invalid(maestro_ctx *ctx);

Creates an invalid value handle.

maestro_value_new_int

maestro_value *maestro_value_new_int(maestro_ctx *ctx, maestro_int_t v);

Creates an integer value.

maestro_value_new_float

maestro_value *maestro_value_new_float(maestro_ctx *ctx, maestro_float_t v);

Creates a float value.

maestro_value_new_bool

maestro_value *maestro_value_new_bool(maestro_ctx *ctx, bool v);

Creates a boolean value.

maestro_value_new_string

maestro_value *maestro_value_new_string(maestro_ctx *ctx, const char *s);

Creates a string value.

maestro_value_new_symbol

maestro_value *maestro_value_new_symbol(maestro_ctx *ctx, const char *s);

Creates a symbol value.

maestro_value_new_list

maestro_value *maestro_value_new_list(maestro_ctx *ctx);

Creates an empty list value.

maestro_value_new_json

maestro_value *maestro_value_new_json(maestro_ctx *ctx,
                                      const char *json_snippet);

Parses a static JSON snippet into a Maestro value. This is the public object-construction path. The input must be a valid JSON object text.

maestro_value_free

void maestro_value_free(maestro_ctx *ctx, maestro_value *v);

Releases a runtime-owned value handle.

Value Helpers

maestro_list_push

int maestro_list_push(maestro_ctx *ctx, maestro_value *list, maestro_value *v);

Appends one value to a Maestro list.

The pushed value is conceptually copied into the list; callers still own their original handle.

Value Accessors

maestro_value_type

int maestro_value_type(const maestro_value *v);

Returns the runtime value type tag.

maestro_value_as_int

int maestro_value_as_int(const maestro_value *v, maestro_int_t *out);

Reads an integer value.

maestro_value_as_float

int maestro_value_as_float(const maestro_value *v, maestro_float_t *out);

Reads a float value.

maestro_value_as_bool

int maestro_value_as_bool(const maestro_value *v, bool *out);

Reads a boolean value.

maestro_value_as_string

const char *maestro_value_as_string(const maestro_value *v);

Returns the string contents for a string value, or NULL otherwise.

maestro_value_as_symbol

const char *maestro_value_as_symbol(const maestro_value *v);

Returns the symbol contents for a symbol value, or NULL otherwise.

maestro_value_list_len

size_t maestro_value_list_len(const maestro_value *v);

Returns the list length, or 0 for non-list values.

maestro_value_list_get

maestro_value *maestro_value_list_get(const maestro_value *v, size_t idx);

Returns a borrowed handle to the list element at idx, or NULL if the value is not a list or the index is out of range.

Notes

• Include ../../include/maestro/maestro.h if you want the whole public API.
• Include only ../../include/maestro/runtime.h and ../../include/maestro/runtime-helpers.h if you want a narrower runtime-only surface.
• Shared constants and typedefs are covered in api-common.md.