kglite-c 0.10.3

/*
 * kglite-c — C ABI for the kglite knowledge graph engine.
 *
 * Generated by cbindgen. Do NOT edit by hand. To regenerate:
 *   cargo build -p kglite-c
 * (the crate's build.rs runs cbindgen automatically).
 *
 * Conventions: see docs/rust/c-abi.md in the kglite repo.
 *   https://github.com/kkollsga/kglite/blob/main/docs/rust/c-abi.md
 */

#ifndef KGLITE_H_INCLUDED
#define KGLITE_H_INCLUDED

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

/**
 * C-ABI-side error code. Variants 1-16 map 1:1 to
 * [`kglite::api::KgErrorCode`]; variants 100+ are C-ABI-specific
 * (invalid UTF-8 at the boundary, null pointer, OOM — conditions
 * that don't have a corresponding `KgErrorCode` because they
 * can't arise from inside the engine).
 */
enum KgliteStatusCode {
  KGLITE_STATUS_CODE_OK = 0,
  KGLITE_STATUS_CODE_CYPHER_SYNTAX = 1,
  KGLITE_STATUS_CODE_CYPHER_TIMEOUT = 2,
  KGLITE_STATUS_CODE_CYPHER_EXECUTION = 3,
  KGLITE_STATUS_CODE_CYPHER_TYPE_MISMATCH = 4,
  KGLITE_STATUS_CODE_SCHEMA = 5,
  KGLITE_STATUS_CODE_VALIDATION = 6,
  KGLITE_STATUS_CODE_EXPR = 7,
  KGLITE_STATUS_CODE_NODE_NOT_FOUND = 8,
  KGLITE_STATUS_CODE_CONNECTION_NOT_FOUND = 9,
  KGLITE_STATUS_CODE_PROPERTY_NOT_FOUND = 10,
  KGLITE_STATUS_CODE_FILE_NOT_FOUND = 11,
  KGLITE_STATUS_CODE_FILE_FORMAT = 12,
  KGLITE_STATUS_CODE_FILE_IO = 13,
  KGLITE_STATUS_CODE_INVALID_ARGUMENT = 14,
  KGLITE_STATUS_CODE_MISSING_ARGUMENT = 15,
  KGLITE_STATUS_CODE_INTERNAL = 16,
  /**
   * A string argument failed UTF-8 validation. The C-side
   * caller passed a `*const c_char` whose bytes didn't decode
   * as UTF-8 — typically a corrupted buffer or a non-UTF-8
   * locale string. kglite is UTF-8 throughout.
   */
  KGLITE_STATUS_CODE_INVALID_UTF8 = 100,
  /**
   * A required pointer argument was null. The function
   * can't proceed; check your call site.
   */
  KGLITE_STATUS_CODE_NULL_POINTER = 101,
};
typedef uint32_t KgliteStatusCode;

/**
 * The ABI version that this build of `kglite-c` exposes. Tracks
 * the engine crate's package version (semver minor-aligned).
 */
typedef struct KgliteAbiVersion {
  uint32_t major;
  uint32_t minor;
  uint32_t patch;
} KgliteAbiVersion;

#if defined(KGLITE_FEATURE_SEC)
/**
 * Opaque handle for a SEC HTTP client (rate-limited, user-agent
 * validating). See [`KgliteGraph`](crate::KgliteGraph) for the
 * rationale on the empty `#[repr(C)]` facade pattern.
 */
typedef struct KgliteSecClient {
  uint8_t _opaque[0];
} KgliteSecClient;
#endif

/**
 * Opaque handle for an embedder. See
 * [`KgliteGraph`](crate::KgliteGraph) for the rationale on the
 * empty `#[repr(C)]` facade pattern — cbindgen renders only a
 * forward declaration; the actual state lives in
 * [`EmbedderState`].
 */
typedef struct KgliteEmbedder {
  uint8_t _opaque[0];
} KgliteEmbedder;

/**
 * Opaque handle for a session. See [`KgliteGraph`](crate::KgliteGraph)
 * for the rationale on the empty `#[repr(C)]` facade pattern.
 */
typedef struct KgliteSession {
  uint8_t _opaque[0];
} KgliteSession;

/**
 * Opaque handle for a knowledge graph. The C-side caller only
 * ever sees `KgliteGraph*`; allocation, deallocation, and field
 * access happen inside `kglite-c`.
 *
 * cbindgen sees the `#[repr(C)]` empty struct and renders only a
 * forward declaration in `kglite.h`. The actual state lives in
 * the private [`GraphState`] sidecar: every `*mut KgliteGraph`
 * the C side holds is really a `*mut GraphState` cast through
 * the opaque facade.
 */
typedef struct KgliteGraph {
  uint8_t _opaque[0];
} KgliteGraph;

/**
 * Opaque handle for a Cypher result. See
 * [`KgliteGraph`](crate::KgliteGraph) for the rationale on the
 * empty `#[repr(C)]` facade pattern — cbindgen renders only a
 * forward declaration; the actual state lives in [`ResultState`].
 */
typedef struct KgliteCypherResult {
  uint8_t _opaque[0];
} KgliteCypherResult;

/**
 * Return the C ABI version this library was built against.
 * Bindings should call this on startup and refuse to proceed if
 * the major version doesn't match what they were compiled
 * against — a mismatched major risks segfaults from changed
 * struct layouts or removed functions.
 *
 * Conventions within a major version: additive only (new
 * functions, new status codes, new opaque types). Existing
 * function signatures and struct layouts never change.
 *
 * # Examples
 *
 * ```c
 * KgliteAbiVersion v = kglite_abi_version();
 * if (v.major != KGLITE_EXPECTED_MAJOR) {
 *     fprintf(stderr, "kglite ABI mismatch: expected %u.x, got %u.%u.%u\n",
 *                     KGLITE_EXPECTED_MAJOR, v.major, v.minor, v.patch);
 *     return 1;
 * }
 * ```
 */
 struct KgliteAbiVersion kglite_abi_version(void);

#if defined(KGLITE_FEATURE_SODIR)
/**
 * Fetch all Sodir (Norwegian Continental Shelf) datasets the
 * caller asks for. Sync wrapper around the engine's
 * [`fetch_all_blocking`] entry point — spins up a single-thread
 * tokio runtime per call, fetches missing/stale CSVs from the
 * ArcGIS FactMaps REST API, applies preprocessing (FK fixups),
 * returns a report.
 *
 * # Arguments
 *
 * - `workdir_path` (in, borrowed): directory under which CSVs
 *   land. Layout: `<root>/csv/<dataset>.csv`,
 *   `<root>/index.json`. Created on first use; subsequent
 *   calls reuse the layout.
 * - `datasets_json` (in, borrowed): JSON array of dataset
 *   stem names the caller wants — e.g.
 *   `["field", "wellbore_exploration", "production_profile"]`.
 *   Must not be null. Pass `"[]"` for no datasets.
 * - `index_cooldown_days` (in): how long the workdir's
 *   `index.json` is trusted before re-probing the catalog.
 *   Wheel default: 7.
 * - `dataset_cooldown_days` (in): how long an already-fetched
 *   CSV is trusted before re-fetching. Wheel default: 30.
 * - `concurrency` (in): max parallel HTTP fetches. Wheel
 *   default: 10.
 * - `out_report_json` (out, owned): on success, set to a
 *   JSON object string with the report fields. Caller must
 *   free via [`kglite_free_string`](crate::kglite_free_string).
 *   Shape:
 *   ```json
 *   {
 *     "refresh": {
 *       "fetched": ["..."],
 *       "unchanged": ["..."],
 *       "user_supplied": ["..."],
 *       "cached": ["..."],
 *       "unfetchable": ["..."],
 *       "errors": [["stem", "message"], ...]
 *     },
 *     "preprocess": {
 *       "petreg_licence_pk": null | <int>,
 *       "seismic_progress_fk": null | <int>,
 *       "chrono_parent_fk": null | <int>,
 *       "announced_block_fk": null | <int>
 *     }
 *   }
 *   ```
 * - `out_error_msg` (out, owned, may be null): on failure,
 *   set to an owned error message string. Caller must free
 *   via [`kglite_free_string`](crate::kglite_free_string).
 *
 * # Errors
 *
 * - `KGLITE_STATUS_CODE_NULL_POINTER` — required pointer is null
 * - `KGLITE_STATUS_CODE_INVALID_UTF8` — input string isn't valid UTF-8
 * - `KGLITE_STATUS_CODE_INVALID_ARGUMENT` — `datasets_json` isn't a
 *   JSON array of strings
 * - `KGLITE_STATUS_CODE_FILE_IO` — workdir creation or CSV write failed
 * - `KGLITE_STATUS_CODE_INTERNAL` — REST API call failed, tokio
 *   runtime build failed, or other engine-level error
 *
 * # Safety
 *
 * `workdir_path` and `datasets_json` must be null-terminated
 * UTF-8 strings. `out_report_json` must be a valid writable
 * pointer to a `*const c_char` slot.
 */

KgliteStatusCode kglite_datasets_sodir_fetch_all(const char *workdir_path,
                                                 const char *datasets_json,
                                                 int64_t index_cooldown_days,
                                                 int64_t dataset_cooldown_days,
                                                 uintptr_t concurrency,
                                                 const char **out_report_json,
                                                 const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Construct a SEC HTTP client. The `user_agent` is mandatory and
 * must be non-empty — SEC's fair-access policy requires a
 * descriptive identifier with contact info (e.g.
 * `"Acme Corp research@example.com"`).
 *
 * # Arguments
 *
 * - `user_agent` (in, borrowed): UTF-8 string, non-empty after trim.
 * - `out_client` (out, owned): on success, set to a client handle.
 *   Caller must free via [`kglite_datasets_sec_client_free`].
 * - `out_error_msg` (out, owned, may be null): on failure, set to
 *   an error message string.
 *
 * # Errors
 *
 * - `KGLITE_STATUS_CODE_NULL_POINTER` — required pointer is null
 * - `KGLITE_STATUS_CODE_INVALID_UTF8` — `user_agent` isn't valid UTF-8
 * - `KGLITE_STATUS_CODE_INVALID_ARGUMENT` — `user_agent` is empty
 *   after trim
 *
 * # Safety
 *
 * `user_agent` must be null-terminated UTF-8.
 * `out_client` must be a valid writable pointer.
 */

KgliteStatusCode kglite_datasets_sec_client_new(const char *user_agent,
                                                struct KgliteSecClient **out_client,
                                                const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Free a SEC client handle. Idempotent on null.
 *
 * # Safety
 *
 * `client` must be either null or a valid pointer previously
 * returned by [`kglite_datasets_sec_client_new`].
 */
 void kglite_datasets_sec_client_free(struct KgliteSecClient *client);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Fetch the quarterly `master.idx` files covering a year range,
 * landing them in `<workdir>/raw/master_idx/`. Returns counts of
 * files written and files skipped (already present).
 *
 * # Arguments
 *
 * - `client` (in, borrowed): SEC HTTP client.
 * - `workdir_path` (in, borrowed): root for the layout.
 * - `year_start`, `year_end` (in): inclusive year range. EDGAR's
 *   earliest quarter is 1993 Q3; quarters before that are skipped.
 * - `current_year`, `current_quarter` (in): the "now" reference
 *   so the fetcher knows to skip future quarters. Callers
 *   typically pass the system clock's year + (month/3 + 1).
 * - `out_pair_json` (out, owned): on success, set to a 2-element
 *   JSON array `[fetched_count, skipped_count]`.
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Safety
 *
 * `client` and the string args must be valid. `out_pair_json`
 * must be a valid writable pointer.
 */

KgliteStatusCode kglite_datasets_sec_fetch_quarterly_master_idx(const struct KgliteSecClient *client,
                                                                const char *workdir_path,
                                                                uint16_t year_start,
                                                                uint16_t year_end,
                                                                uint16_t current_year,
                                                                uint8_t current_quarter,
                                                                const char **out_pair_json,
                                                                const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Fetch the bulk-download `submissions.zip` (all companies' filing
 * metadata in one archive). Lands at
 * `<workdir>/raw/bulk/submissions.zip`. Returns `true` if a fresh
 * download landed (mtime older than `staleness_hours`, or
 * `force_refetch`), `false` if the existing file was reused.
 *
 * # Arguments
 *
 * - `client` (in, borrowed).
 * - `workdir_path` (in, borrowed).
 * - `staleness_hours` (in): how stale the cached zip can be before
 *   re-fetching. SEC publishes nightly so 24 is a reasonable default.
 * - `force_refetch` (in): non-zero forces re-download regardless of
 *   staleness.
 * - `out_fetched` (out): set to 1 if downloaded fresh, 0 if reused.
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Safety
 *
 * `client` and `workdir_path` must be valid. `out_fetched` must be
 * a valid writable pointer.
 */

KgliteStatusCode kglite_datasets_sec_fetch_submissions_bulk(const struct KgliteSecClient *client,
                                                            const char *workdir_path,
                                                            uint64_t staleness_hours,
                                                            uint8_t force_refetch,
                                                            uint8_t *out_fetched,
                                                            const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Fetch the `company_tickers.json` mapping (TICKER → CIK).
 * Lands at `<workdir>/raw/company_tickers.json`. Returns `true`
 * if a fresh download landed.
 *
 * # Safety
 *
 * Same shape as [`kglite_datasets_sec_fetch_submissions_bulk`].
 */

KgliteStatusCode kglite_datasets_sec_fetch_company_tickers(const struct KgliteSecClient *client,
                                                           const char *workdir_path,
                                                           uint8_t force_refetch,
                                                           uint8_t *out_fetched,
                                                           const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Fetch the XBRL `companyfacts/CIK<cik>.json` file (a single
 * company's full XBRL fact history). Lands at
 * `<workdir>/raw/company_facts/CIK<cik>.json`. Returns `true` if
 * a fresh download landed.
 *
 * # Arguments
 *
 * - `client`, `workdir_path`: see other fetchers.
 * - `cik` (in): the company's CIK as an integer (no zero-padding).
 * - `force_refetch` (in): non-zero forces re-download.
 *
 * # Safety
 *
 * Same shape as the other fetchers.
 */

KgliteStatusCode kglite_datasets_sec_fetch_company_facts(const struct KgliteSecClient *client,
                                                         const char *workdir_path,
                                                         uint64_t cik,
                                                         uint8_t force_refetch,
                                                         uint8_t *out_fetched,
                                                         const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Resolve a list of user-supplied form-type strings into the
 * per-filing-fetcher buckets needed to cover them, plus a list of
 * unrecognized form types the caller should warn about.
 *
 * Pure-CPU — no I/O, no client. Mirrors
 * `kglite::api::datasets::sec::resolve_fetch_buckets`.
 *
 * # Arguments
 *
 * - `form_types_json` (in, borrowed): JSON array of form-type strings
 *   (e.g. `["10-K", "4", "13F-HR"]`), or the literal `"null"`
 *   for "use the lean default set".
 * - `out_active_json` (out, owned): JSON array of bucket name
 *   strings, e.g. `["form4", "13f"]`.
 * - `out_unmatched_json` (out, owned): JSON array of strings that
 *   didn't match any bucket.
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Errors
 *
 * - `KGLITE_STATUS_CODE_INVALID_ARGUMENT` — `form_types_json` isn't
 *   a JSON array of strings (or null).
 *
 * # Safety
 *
 * All input strings must be null-terminated UTF-8.
 */

KgliteStatusCode kglite_datasets_sec_resolve_fetch_buckets(const char *form_types_json,
                                                           const char **out_active_json,
                                                           const char **out_unmatched_json,
                                                           const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Parse SEC's `company_tickers.json` shape into a TICKER → CIK
 * map. Pure-CPU, no I/O. Returns the map as JSON object string.
 *
 * # Arguments
 *
 * - `tickers_json` (in, borrowed): the raw JSON from SEC's published
 *   `company_tickers.json`.
 * - `out_map_json` (out, owned): JSON object `{"AAPL": 320193, ...}`.
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Errors
 *
 * - `KGLITE_STATUS_CODE_INVALID_ARGUMENT` — `tickers_json` isn't
 *   valid JSON.
 *
 * # Safety
 *
 * `tickers_json` must be null-terminated UTF-8.
 */

KgliteStatusCode kglite_datasets_sec_parse_tickers_json(const char *tickers_json,
                                                        const char **out_map_json,
                                                        const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_SEC)
/**
 * Run the SEC extract pipeline — reads `<workdir>/raw/` (the
 * downloaded artifacts) and produces `<workdir>/processed/`
 * CSVs (`company.csv`, `filing_index.csv`, `form4_transaction.csv`,
 * `holding.csv`, etc.).
 *
 * # Arguments
 *
 * - `workdir_path` (in, borrowed).
 * - `slice_json` (in, borrowed, may be null): JSON object with
 *   optional filters:
 *   ```json
 *   {
 *     "cik_list":   [320193, 789019],
 *     "form_types": ["10-K", "10-Q"],
 *     "year_range": [2020, 2024]
 *   }
 *   ```
 *   Any missing / null field means "no restriction on that axis".
 *   Pass null or `"{}"` for fully unrestricted.
 * - `force` (in): non-zero re-runs even when the
 *   `<workdir>/processed/holding.csv` sentinel says we already
 *   extracted.
 * - `out_report_json` (out, owned): JSON object with extract
 *   stats. Caller frees via `kglite_free_string`.
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Safety
 *
 * `workdir_path` and (if non-null) `slice_json` must be
 * null-terminated UTF-8.
 */

KgliteStatusCode kglite_datasets_sec_run_all(const char *workdir_path,
                                             const char *slice_json,
                                             uint8_t force,
                                             const char **out_report_json,
                                             const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_WIKIDATA)
/**
 * Ensure the Wikidata `latest-truthy.nt.bz2` dump is present
 * under `<workdir>/cache/`. Resumable: a partially-downloaded
 * file gets continued via HTTP `Range` requests. Cooldown:
 * fully-present files within `cooldown_days` of their mtime
 * skip the re-fetch entirely.
 *
 * # Arguments
 *
 * - `workdir_path` (in, borrowed): root for the workdir layout.
 * - `cooldown_days` (in): how stale the cached dump can be before
 *   re-fetching. Wheel default: 7.
 * - `verbose` (in): non-zero turns on the engine's progress
 *   logging.
 * - `out_dump_path` (out, owned): JSON-encoded path string to the
 *   downloaded dump (e.g. `"\"<workdir>/cache/latest-truthy.nt.bz2\""`).
 *   We JSON-encode the path because filesystem paths can contain
 *   characters that need escaping in some downstream consumers.
 * - `out_remote_mtime_iso` (out, owned, may be null): if the
 *   server returned a `Last-Modified` header, the ISO 8601
 *   timestamp string. Set to null if the probe failed.
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Safety
 *
 * `workdir_path` must be null-terminated UTF-8. The out-pointers
 * must be valid writable slots.
 */

KgliteStatusCode kglite_datasets_wikidata_ensure_dump(const char *workdir_path,
                                                      int64_t cooldown_days,
                                                      uint8_t verbose,
                                                      const char **out_dump_path,
                                                      const char **out_remote_mtime_iso,
                                                      const char **out_error_msg);
#endif

#if defined(KGLITE_FEATURE_WIKIDATA)
/**
 * Sync HEAD-request probe for the dump's `Last-Modified` header.
 * Returns the timestamp as RFC 3339 / ISO 8601 string, or null if
 * the probe failed (network down, server returned no header,
 * etc.).
 *
 * # Arguments
 *
 * - `out_iso` (out, owned, may be null): ISO 8601 string on
 *   success; null on probe failure. Caller frees via
 *   [`kglite_free_string`](crate::kglite_free_string).
 *
 * # Safety
 *
 * `out_iso` must be a valid writable pointer.
 */
 KgliteStatusCode kglite_datasets_wikidata_remote_last_modified(const char **out_iso);
#endif

#if defined(KGLITE_FEATURE_WIKIDATA)
/**
 * Run the cache-freshness decision tree. Pure-CPU; the only I/O
 * is the file-mtime stat that the engine's `decide()` performs
 * internally on the two meta-paths. Returns a JSON object:
 *
 * ```json
 * {"decision": "build" | "load" | "rebuild", "reason": "..." }
 * ```
 *
 * # Arguments
 *
 * - `force_rebuild` (in): non-zero → always `Build("force_rebuild")`.
 * - `graph_meta_path` (in, borrowed): path to
 *   `<graph_dir>/disk_graph_meta.json`. Missing file →
 *   `Build("no_cache")`.
 * - `source_meta_path` (in, borrowed): path to
 *   `<graph_dir>/wikidata_source.json`. May be missing on graphs
 *   built before source-meta stamping landed.
 * - `cooldown_days` (in): graphs younger than this skip the
 *   remote probe.
 * - `remote_mtime_iso` (in, borrowed, may be null): RFC 3339 /
 *   ISO 8601 timestamp from a prior call to
 *   [`kglite_datasets_wikidata_remote_last_modified`]. Null →
 *   probe was skipped or failed.
 * - `out_decision_json` (out, owned).
 * - `out_error_msg` (out, owned, may be null).
 *
 * # Safety
 *
 * All input strings must be null-terminated UTF-8.
 * `out_decision_json` must be a valid writable pointer.
 */

KgliteStatusCode kglite_datasets_wikidata_decide_cache(uint8_t force_rebuild,
                                                       const char *graph_meta_path,
                                                       const char *source_meta_path,
                                                       int64_t cooldown_days,
                                                       const char *remote_mtime_iso,
                                                       const char **out_decision_json,
                                                       const char **out_error_msg);
#endif

/**
 * Free an embedder handle. Idempotent on null.
 *
 * # Safety
 *
 * `embedder` must be either null or a valid pointer previously
 * returned by a `kglite_embedder_*_new` factory and not yet
 * freed. Calling twice on the same pointer is UB.
 *
 * **Do NOT free** an embedder that has been handed to
 * [`kglite_session_set_embedder`] — the session retains a clone
 * of the inner Arc; you may free your handle after the call to
 * set_embedder (the Arc keeps the embedder alive until the
 * session drops). For symmetry with other handles, the safest
 * pattern is: factory → set_embedder → free_embedder. Once the
 * Arc is shared, the original handle is no longer special.
 */
 void kglite_embedder_free(struct KgliteEmbedder *embedder);

/**
 * Attach an embedder to a session. The session retains a clone
 * of the embedder's inner `Arc`, so subsequent
 * [`kglite_session_execute_read`](crate::kglite_session_execute_read)
 * calls have access to `text_score()` and other embedder-backed
 * Cypher functions.
 *
 * The caller may free the embedder handle after this call
 * returns — the `Arc` clone keeps the underlying embedder
 * alive for the session's lifetime.
 *
 * # Safety
 *
 * `session` and `embedder` must be valid handles previously
 * returned by `kglite_session_new` and a `kglite_embedder_*_new`
 * factory respectively, neither yet freed.
 */

KgliteStatusCode kglite_session_set_embedder(struct KgliteSession *session,
                                             const struct KgliteEmbedder *embedder);

#if defined(KGLITE_FEATURE_FASTEMBED)
/**
 * Construct a fastembed-rs-backed embedder.
 *
 * fastembed-rs downloads ONNX model weights on first
 * `embed()` call (cached at `~/.cache/fastembed/`). The factory
 * does NOT block on download — model name validation only. The
 * first Cypher query using `text_score()` triggers the download.
 *
 * # Arguments
 *
 * - `model_name` (in, borrowed): a known fastembed model name,
 *   e.g. `"BAAI/bge-m3"`, `"sentence-transformers/all-MiniLM-L6-v2"`.
 *   See fastembed-rs's TextEmbedding::list_supported_models() for
 *   the full list.
 * - `out_embedder` (out, owned): on success, set to an embedder
 *   handle. Caller must free via [`kglite_embedder_free`] (or
 *   transfer ownership via [`kglite_session_set_embedder`]).
 * - `out_error_msg` (out, owned, may be null): on failure, set to
 *   an owned error string.
 *
 * # Errors
 *
 * - `KGLITE_STATUS_CODE_NULL_POINTER` — required pointer is null
 * - `KGLITE_STATUS_CODE_INVALID_UTF8` — `model_name` isn't valid UTF-8
 * - `KGLITE_STATUS_CODE_INVALID_ARGUMENT` — `model_name` isn't a known
 *   fastembed model
 *
 * # Feature gate
 *
 * Available only when `kglite-c` is built with the `fastembed`
 * Cargo feature.
 *
 * # Safety
 *
 * `model_name` must be a null-terminated UTF-8 string.
 * `out_embedder` must be a valid writable pointer.
 */

KgliteStatusCode kglite_embedder_fastembed_new(const char *model_name,
                                               struct KgliteEmbedder **out_embedder,
                                               const char **out_error_msg);
#endif

/**
 * Load a knowledge graph from disk. Accepts `.kgl` files
 * (single-file mmap format) and directories (disk-backed CSR
 * layout) — the loader picks the right path based on what's at
 * `path`.
 *
 * # Arguments
 *
 * - `path` (in, borrowed): UTF-8 file path, null-terminated.
 * - `out_graph` (out, owned): set to the loaded graph handle on
 *   success; caller must free via [`kglite_graph_free`]. Set to
 *   null on failure.
 * - `out_error_msg` (out, owned): set to an owned error message
 *   on failure; caller must free via
 *   [`kglite_free_string`](crate::kglite_free_string). Set to
 *   null on success.
 *
 * # Errors
 *
 * - `KGLITE_ERR_NULL_POINTER` — `path` or `out_graph` is null
 * - `KGLITE_ERR_INVALID_UTF8` — `path` isn't valid UTF-8
 * - `KGLITE_ERR_FILE_NOT_FOUND` — `path` doesn't exist
 * - `KGLITE_ERR_FILE_FORMAT` — file isn't a valid `.kgl` /
 *   disk-graph directory
 * - `KGLITE_ERR_FILE_IO` — I/O failure during read
 *
 * # Safety
 *
 * `path` must point to a null-terminated UTF-8 string.
 * `out_graph` must be a valid writable pointer to a
 * `*mut KgliteGraph` slot. `out_error_msg` may be null (the
 * caller doesn't care about the message); otherwise it must
 * point to a valid writable `*const c_char` slot.
 */

KgliteStatusCode kglite_load_file(const char *path,
                                  struct KgliteGraph **out_graph,
                                  const char **out_error_msg);

/**
 * Save a knowledge graph to disk. The on-disk format depends on
 * the underlying storage mode — in-memory and mapped graphs
 * produce a `.kgl` single-file; disk-backed graphs produce / fill
 * a directory.
 *
 * # Arguments
 *
 * - `graph` (in, borrowed): the graph to save.
 * - `path` (in, borrowed): UTF-8 destination path,
 *   null-terminated.
 * - `out_error_msg` (out, owned): set to an owned error message
 *   on failure; caller must free via
 *   [`kglite_free_string`](crate::kglite_free_string). Set to
 *   null on success.
 *
 * # Errors
 *
 * - `KGLITE_ERR_NULL_POINTER` — `graph` or `path` is null
 * - `KGLITE_ERR_INVALID_UTF8` — `path` isn't valid UTF-8
 * - `KGLITE_ERR_FILE_IO` — write failed
 *
 * # Safety
 *
 * `graph` must be a valid `*mut KgliteGraph` previously returned
 * by a `kglite_*` function and not yet freed. `path` must be a
 * null-terminated UTF-8 string.
 */

KgliteStatusCode kglite_save_graph(struct KgliteGraph *graph,
                                   const char *path,
                                   const char **out_error_msg);

/**
 * Free a graph handle. Idempotent on null (no-op).
 *
 * # Safety
 *
 * `graph` must be either null or a pointer previously returned by
 * [`kglite_load_file`] (or any future `kglite_*` function that
 * returns a `*mut KgliteGraph`) and not yet freed. Calling twice
 * on the same pointer is UB.
 *
 * **Do NOT free** a graph handle that has been handed to
 * [`kglite_session_new`](crate::kglite_session_new) — the session
 * takes ownership and frees on its own teardown.
 */
 void kglite_graph_free(struct KgliteGraph *graph);

/**
 * Return the column names as a JSON array string:
 * `["col1", "col2", ...]`.
 *
 * The returned string is OWNED by the caller and must be freed
 * via [`kglite_free_string`](crate::kglite_free_string). Returns
 * null on serialization failure (shouldn't happen — column names
 * are always serializable).
 */
 const char *kglite_cypher_result_columns_json(const struct KgliteCypherResult *result);

/**
 * Return all rows as a JSON array of objects keyed by column
 * name: `[{"col1": v1, "col2": v2}, ...]`.
 *
 * For large result sets this materializes the entire JSON blob
 * in memory. Future v2 will add pull-row-by-row accessors; for
 * now this is fine for the common-case query sizes.
 *
 * The returned string is OWNED by the caller and must be freed
 * via [`kglite_free_string`](crate::kglite_free_string). Returns
 * null on serialization failure.
 */
 const char *kglite_cypher_result_rows_json(const struct KgliteCypherResult *result);

/**
 * Return the number of rows in the result. Useful for callers
 * that want to size buffers before requesting the JSON blob.
 */
 uintptr_t kglite_cypher_result_row_count(const struct KgliteCypherResult *result);

/**
 * Free a result handle. Idempotent on null (no-op).
 *
 * # Safety
 *
 * `result` must be either null or a valid pointer previously
 * returned by [`kglite_session_execute_read`](crate::kglite_session_execute_read)
 * or [`kglite_session_execute_mut`](crate::kglite_session_execute_mut)
 * and not yet freed.
 */
 void kglite_cypher_result_free(struct KgliteCypherResult *result);

/**
 * Create a new session from a graph handle. The session takes
 * ownership of the graph — the caller MUST NOT call
 * [`kglite_graph_free`](crate::kglite_graph_free) on the handle
 * after this call. Free the session via
 * [`kglite_session_free`] when done.
 *
 * # Arguments
 *
 * - `graph` (in, MOVED): graph handle. After this call, the
 *   pointer is no longer valid for any other use.
 * - `out_session` (out, owned): set to the session handle on
 *   success; caller must free via [`kglite_session_free`].
 *
 * # Errors
 *
 * - `KGLITE_ERR_NULL_POINTER` — `graph` or `out_session` is null
 *
 * # Safety
 *
 * `graph` must be a valid `*mut KgliteGraph` previously returned
 * by [`kglite_load_file`](crate::kglite_load_file) and not yet
 * freed or moved into another session. `out_session` must be a
 * valid writable pointer to a `*mut KgliteSession` slot.
 */
 KgliteStatusCode kglite_session_new(struct KgliteGraph *graph, struct KgliteSession **out_session);

/**
 * Run a read-only Cypher query.
 *
 * # Arguments
 *
 * - `session` (in, borrowed): the session.
 * - `query` (in, borrowed): UTF-8 Cypher query, null-terminated.
 * - `params_json` (in, borrowed, may be null): JSON object of
 *   parameter bindings. Pass null or `"{}"` for no params.
 * - `out_result` (out, owned): on success, set to the result
 *   handle; caller must free via [`kglite_cypher_result_free`].
 * - `out_error_msg` (out, owned, may be null): on failure, set
 *   to the error message; caller must free via
 *   [`kglite_free_string`](crate::kglite_free_string).
 *
 * # Errors
 *
 * Any `KgErrorCode` variant — Cypher syntax / type mismatch /
 * timeout / execution error / node-not-found / argument
 * validation. The error message describes the specific failure.
 *
 * # Safety
 *
 * `session` must be valid. `query` and (if non-null) `params_json`
 * must be null-terminated UTF-8 strings.
 */

KgliteStatusCode kglite_session_execute_read(const struct KgliteSession *session,
                                             const char *query,
                                             const char *params_json,
                                             struct KgliteCypherResult **out_result,
                                             const char **out_error_msg);

/**
 * Run a mutating Cypher query. Same shape as
 * [`kglite_session_execute_read`] but accepts CREATE / SET /
 * DELETE / REMOVE / MERGE statements. The session's underlying
 * graph is auto-committed after a successful execute (no
 * explicit begin/commit in v1 — explicit transactions land in
 * a future ABI version once a binding needs them).
 *
 * # Safety
 *
 * Same as [`kglite_session_execute_read`] except `session` is
 * declared as `*mut` (the call mutates the session's interior
 * graph via commit-swap).
 */

KgliteStatusCode kglite_session_execute_mut(struct KgliteSession *session,
                                            const char *query,
                                            const char *params_json,
                                            struct KgliteCypherResult **out_result,
                                            const char **out_error_msg);

/**
 * Free a session handle. Idempotent on null (no-op).
 *
 * # Safety
 *
 * `session` must be either null or a valid pointer previously
 * returned by [`kglite_session_new`] and not yet freed.
 */
 void kglite_session_free(struct KgliteSession *session);

/**
 * Return the canonical human-readable name of a status code (e.g.
 * `"CypherSyntax"`, `"NodeNotFound"`, `"InvalidUtf8"`).
 *
 * The returned string is OWNED by the caller and must be freed
 * via [`kglite_free_string`](crate::kglite_free_string). Returns
 * null on `Ok` (no error to name).
 */
 const char *kglite_status_code_name(KgliteStatusCode code);

/**
 * Return the Neo4j wire status code for a status code (e.g.
 * `"Neo.ClientError.Statement.SyntaxError"`). Useful for bindings
 * implementing the Neo4j Bolt wire protocol or compatible HTTP
 * APIs.
 *
 * The returned string is OWNED by the caller and must be freed
 * via [`kglite_free_string`](crate::kglite_free_string). Returns
 * null on `Ok` or on C-ABI-only error codes that have no Neo4j
 * counterpart (`InvalidUtf8`, `NullPointer`).
 */
 const char *kglite_status_code_neo4j_status(KgliteStatusCode code);

/**
 * Return the HTTP status code mapping for a status code (e.g.
 * 400 for `CypherSyntax`, 404 for `NodeNotFound`, 500 for
 * `Internal`). Useful for REST/gRPC bindings.
 *
 * Returns 0 for `Ok` and 500 for C-ABI-only codes (`InvalidUtf8`
 * = 400 / bad request from caller, `NullPointer` = 400).
 */
 uint16_t kglite_status_code_http_status(KgliteStatusCode code);

/**
 * Free a string previously returned by any `kglite_*` function.
 *
 * Safety: `s` must be either null or a pointer previously returned
 * by a `kglite_*` function (these all flow through
 * [`alloc_c_string`]). Calling twice on the same pointer is UB.
 * Calling with a pointer to a string allocated by the C caller's
 * own `malloc` is UB.
 *
 * Passing null is safe (treated as a no-op).
 *
 * # Examples
 *
 * ```c
 * const char* col_json = kglite_cypher_result_columns_json(result);
 * printf("%s\n", col_json);
 * kglite_free_string(col_json);
 * ```
 */
 void kglite_free_string(const char *s);

#endif  /* KGLITE_H_INCLUDED */