rustd_ffi 0.1.1

#ifndef RUSTD_FFI_H
#define RUSTD_FFI_H

#pragma once

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * Result structure for compilation operations
 */
typedef struct RustDCompileResult {
  /**
   * Whether compilation succeeded
   */
  bool success;
  /**
   * Error message (if failed, null if succeeded)
   */
  char *error_msg;
  /**
   * Compiled bytecode (if succeeded, null if failed)
   */
  uint8_t *bytecode;
  /**
   * Length of bytecode
   */
  uintptr_t bytecode_len;
} RustDCompileResult;

/**
 * Result structure for general operations
 */
typedef struct RustDResult {
  /**
   * Whether operation succeeded
   */
  bool success;
  /**
   * Error message (if failed)
   */
  char *error_msg;
} RustDResult;

/**
 * Entity in extracted results
 */
typedef struct RustDEntity {
  /**
   * Entity text
   */
  char *text;
  /**
   * Entity type (symptom, medication, etc.)
   */
  char *entity_type;
  /**
   * Start position in text
   */
  uintptr_t start;
  /**
   * End position in text
   */
  uintptr_t end;
} RustDEntity;

/**
 * List of extracted entities
 */
typedef struct RustDEntityList {
  /**
   * Array of entities
   */
  struct RustDEntity *entities;
  /**
   * Number of entities
   */
  uintptr_t count;
} RustDEntityList;

/**
 * Audit trail structure
 */
typedef struct RustDAudit {
  /**
   * Audit trail JSON
   */
  char *audit_json;
  /**
   * Length of JSON string
   */
  uintptr_t json_len;
} RustDAudit;

/**
 * Compile RustD source code to bytecode
 *
 * # Arguments
 * * `source_code` - Pointer to source code string
 * * `source_len` - Length of source code
 *
 * # Returns
 * RustDCompileResult with bytecode or error message
 *
 * # Safety
 * The caller must ensure:
 * - source_code points to valid UTF-8 data
 * - source_len matches the actual length
 * - The returned result is freed with rustd_free_compile_result
 */
struct RustDCompileResult rustd_compile(const char *source_code, uintptr_t source_len);

/**
 * Execute compiled RustD bytecode
 *
 * # Arguments
 * * `bytecode` - Pointer to compiled bytecode
 * * `bytecode_len` - Length of bytecode
 *
 * # Returns
 * RustDResult indicating success or failure
 *
 * # Safety
 * The caller must ensure:
 * - bytecode points to valid data
 * - bytecode_len matches the actual length
 */
struct RustDResult rustd_execute(const uint8_t *bytecode, uintptr_t bytecode_len);

/**
 * Extract clinical entities from text
 *
 * # Arguments
 * * `text` - Pointer to text string
 * * `text_len` - Length of text
 *
 * # Returns
 * RustDEntityList with extracted entities
 *
 * # Safety
 * The caller must ensure:
 * - text points to valid UTF-8 data
 * - text_len matches the actual length
 * - The returned list is freed with rustd_free_entity_list
 */
struct RustDEntityList rustd_extract_entities(const char *text, uintptr_t text_len);

/**
 * Create a deterministic audit trail
 *
 * # Arguments
 * * `note_id` - Pointer to note identifier
 * * `note_id_len` - Length of note_id
 * * `entities_json` - Pointer to JSON-serialized entities
 * * `entities_json_len` - Length of entities_json
 *
 * # Returns
 * RustDAudit with the audit trail JSON
 */
struct RustDAudit rustd_create_audit(const char *note_id,
                                     uintptr_t note_id_len,
                                     const char *entities_json,
                                     uintptr_t entities_json_len);

/**
 * Verify an audit trail's integrity
 *
 * # Arguments
 * * `audit_json` - Pointer to audit JSON
 * * `audit_json_len` - Length of audit JSON
 * * `entities_json` - Pointer to entities JSON
 * * `entities_json_len` - Length of entities JSON
 *
 * # Returns
 * True if hash matches, false otherwise
 */
bool rustd_verify_audit(const char *audit_json,
                        uintptr_t audit_json_len,
                        const char *entities_json,
                        uintptr_t entities_json_len);

/**
 * Free a compile result
 *
 * # Safety
 * The result must have been created by rustd_compile
 */
void rustd_free_compile_result(struct RustDCompileResult result);

/**
 * Free a general result
 */
void rustd_free_result(struct RustDResult result);

/**
 * Free an audit trail
 */
void rustd_free_audit(struct RustDAudit audit);

/**
 * Free an entity list
 */
void rustd_free_entity_list(struct RustDEntityList list);

/**
 * Get RustD version
 */
const char *rustd_version(void);

#endif /* RUSTD_FFI_H */