Crate semq_sys 

Raw FFI declarations for the SEMQ core.

Mirrors include/semq.h one-to-one: the constants, every enum value, the plain structs, the opaque handles and all exported functions. Nothing here is safe; the semq crate builds the safe API on top. The declarations are written by hand so the build needs no libclang; layout tests pin the structs whose size and offsets the ABI depends on.

C enums are declared as u32 aliases with one constant per value. Every function that can fail returns a semq_status_t and fills the semq_error_t it is given, when non-null.

Structs

semq_codec_t

Opaque codec handle (struct semq_codec).

semq_config_t

A codec configuration. op is a semq_operator_t; p1 is scale (orbit), sectors (phase) or bins (quant); p2 is the rule revision.

semq_diff_t

Opaque diff handle (struct semq_diff).

semq_encoding_t

Opaque encoding handle (struct semq_encoding).

semq_error_t

Error report. status is the returned status; which is set only for SEMQ_ERR_INTEGRITY; row and field are SEMQ_NONE when they do not apply. message is always NUL-terminated and never contains input data.

semq_floor_t

Opaque floor handle (struct semq_floor).

semq_ids_t

Identifiers of n rows, in input order (any order; the core sorts). For SEMQ_ID_U64 pass u64 (n entries). For SEMQ_ID_UTF8 pass utf8_offsets (n + 1 entries, offsets[0] = 0, non-decreasing) and utf8_bytes (offsets[n] bytes): id i is bytes[offsets[i] .. offsets[i+1]).

semq_manifest_change_t

A change to one manifest key. has_before/has_after are 0 when the key is absent on that side; the pointers are then NULL.

semq_pair_t

One manifest pair. Keys and values are UTF-8 bytes, not NUL-terminated.

semq_part_t

One borrowed part of the file image.

semq_verdict_t

Opaque verdict handle (struct semq_verdict).

Constants

SEMQ_CHECK_PER_ROW

SEMQ_CONFIG_BYTES

Size of the canonical config form in bytes.

SEMQ_DIGEST_BYTES

Size of each identity (content_digest, state_id) in bytes.

SEMQ_ERR_FORMAT

A file image is not a valid v2 image.

SEMQ_ERR_INCOMPATIBLE

Two states differ in config or id kind.

SEMQ_ERR_INTEGRITY

A file image’s digest does not match.

SEMQ_ERR_INTERNAL

A defect in the core; report it.

SEMQ_ERR_INVALID_INPUT

An argument violates its contract.

SEMQ_ERR_NOMEM

An allocation failed.

SEMQ_ERR_UNSUPPORTED

The operation or FP environment is not supported.

SEMQ_FIELD_DIM

SEMQ_FIELD_OPERATOR

SEMQ_FIELD_P1

scale, sectors or bins.

SEMQ_FIELD_P2

SEMQ_FILE_VERSION

File format version written and accepted by this core.

SEMQ_ID_MAX_BYTES

Largest utf8 id, in bytes. Ids are at least one byte.

SEMQ_ID_U64

SEMQ_ID_UTF8

SEMQ_LIST_ADDED

SEMQ_LIST_CHANGED

SEMQ_LIST_REMOVED

SEMQ_MANIFEST_KEY_MAX

SEMQ_MANIFEST_MAX_PAIRS

Manifest limits.

SEMQ_MANIFEST_SECTION_MAX

SEMQ_MANIFEST_VALUE_MAX

SEMQ_MAX_DIM

Largest accepted vector dimension.

SEMQ_NONE

Sentinel for “no row” / “no field” in semq_error_t and index lookups.

SEMQ_OK

SEMQ_ORBIT

SEMQ_PHASE

SEMQ_QUANT

SEMQ_REASON_CHANGED_RATIO

SEMQ_REASON_ENCODER

SEMQ_REASON_HAMMING

SEMQ_REASON_NO_COMMON_ROWS

SEMQ_REASON_REMOVED_ROWS

SEMQ_REASON_ROW_ABOVE_MAX

SEMQ_RULE_REVISION

Operator rule revision written into every config (p2).

SEMQ_SECTION_CONFIG

SEMQ_SECTION_FOOTER

SEMQ_SECTION_FRAMING

SEMQ_SECTION_IDS

SEMQ_SECTION_MANIFEST

SEMQ_SECTION_ROWS

SEMQ_SECTION_SIZES

SEMQ_WHICH_CONTENT

SEMQ_WHICH_NONE

SEMQ_WHICH_STATE

Functions

semq_backend_name^⚠

Effective kernel for an operator on this host (“scalar”, “neon”, …).

semq_build_id^⚠

Compile-time build recipe identifier. Not a provenance proof.

semq_codec_backend^⚠

Name of the kernel this codec runs (“scalar”, “neon”, “avx2”, …).

semq_codec_config^⚠

semq_codec_create^⚠

semq_codec_decode^⚠

Representatives, n x dim float32, row i for ids[i].

semq_codec_encode^⚠

semq_codec_free^⚠

semq_codec_unpack^⚠

Symbols, n x units_per_row bytes, one per unit.

semq_config_bytes_per_vector^⚠

semq_config_equal^⚠

1 when the two configs have the same canonical bytes.

semq_config_from_bytes^⚠

Parse a 13-byte canonical form.

semq_config_max_magnitude^⚠

quant only: (float)(2.0 / sqrt((double)dim)); 0 for other operators.

semq_config_orbit^⚠

semq_config_phase^⚠

semq_config_quant^⚠

semq_config_to_bytes^⚠

Write the 13-byte canonical form. cfg must be valid.

semq_config_units_per_row^⚠

semq_config_validate^⚠

semq_core_version^⚠

Core version string, from the repository VERSION file.

semq_diff_candidate_id^⚠

semq_diff_config^⚠

semq_diff_count^⚠

semq_diff_evaluate^⚠

With checks == 0, passed equals semq_diff_within; an unknown bit is SEMQ_ERR_INVALID_INPUT. SEMQ_ERR_INCOMPATIBLE for a floor of another context, or for SEMQ_CHECK_PER_ROW on a floor without max_hamming.

semq_diff_free^⚠

The Diff keeps both Encodings alive until it is freed.

semq_diff_hamming^⚠

Hamming distance of changed id i (units whose symbol differs).

semq_diff_id^⚠

Id i of a list, in canonical order. For u64 kinds *out_u64 is set; for utf8 kinds *bytes/*len are set.

semq_diff_id_kind^⚠

semq_diff_manifest_change^⚠

semq_diff_manifest_changes^⚠

semq_diff_n_unchanged^⚠

semq_diff_reference_id^⚠

semq_diff_units_u64^⚠

Differing units of an id present on both sides. Writes up to cap entries and the total count into *count. Pass cap = 0 to query.

semq_diff_units_utf8^⚠

semq_diff_within^⚠

*out = 1 iff the diff is within the floor (exact integer arithmetic). The floor must match the diff’s config, id kind and reference state_id (SEMQ_ERR_INCOMPATIBLE otherwise).

semq_encoding_concat^⚠

Merge k Encodings with the same config, id kind and manifest and pairwise-disjoint ids.

semq_encoding_config^⚠

semq_encoding_content_digest^⚠

semq_encoding_create^⚠

semq_encoding_diff^⚠

reference.diff(candidate).

semq_encoding_file_size^⚠

Total size of the file image.

semq_encoding_find_u64^⚠

Row index of an id, or SEMQ_NONE when absent.

semq_encoding_find_utf8^⚠

semq_encoding_free^⚠

semq_encoding_id_kind^⚠

semq_encoding_ids_u64^⚠

Sorted ids. u64 kinds: n values.

semq_encoding_ids_utf8_bytes^⚠

utf8 kinds: the id bytes.

semq_encoding_ids_utf8_offsets^⚠

utf8 kinds: n + 1 offsets.

semq_encoding_len^⚠

semq_encoding_load^⚠

Parse a complete file image. The bytes are copied.

semq_encoding_manifest_len^⚠

Manifest pairs in canonical (bytewise key) order.

semq_encoding_manifest_pair^⚠

semq_encoding_rows^⚠

Rows in id order, n x bytes_per_vector bytes.

semq_encoding_save^⚠

Write the whole file image into out (cap >= file size).

semq_encoding_save_parts^⚠

The file image as 5 ordered parts owned by the handle. Returns 5.

semq_encoding_state_id^⚠

semq_floor_changed_rows^⚠

semq_floor_config^⚠

The config, owned by the handle.

semq_floor_create^⚠

A floor from its fields. config must validate, id_kind must be 0 or 1, reference_id is 32 bytes, nulls >= 1, total_rows >= 1, changed_rows <= total_rows and hamming <= units_per_row(config); otherwise SEMQ_ERR_INVALID_INPUT.

semq_floor_distinct_nulls^⚠

Distinct null states among the nulls; SEMQ_NONE when not recorded.

semq_floor_free^⚠

semq_floor_hamming^⚠

semq_floor_id_kind^⚠

0 = u64, 1 = utf8.

semq_floor_json_size^⚠

Length in bytes of the floor’s JSON form.

semq_floor_load^⚠

Reads a floor from its JSON form; strict on the schema’s keys, other keys ignored. SEMQ_ERR_INVALID_INPUT on any violation.

semq_floor_max_hamming^⚠

SEMQ_NONE for a floor without per-row data.

semq_floor_measure^⚠

Envelope of k >= 1 null diffs; every input diff is within the result. All nulls must share config, id kind and reference state_id (SEMQ_ERR_INCOMPATIBLE, field = the offending index) and each must be a valid null (SEMQ_ERR_INVALID_INPUT, field = index).

semq_floor_measure_for^⚠

semq_floor_measure that also records what the checks (SEMQ_CHECK_* flags) need: with SEMQ_CHECK_PER_ROW, max_hamming and distinct_nulls. An unknown bit is SEMQ_ERR_INVALID_INPUT.

semq_floor_nulls^⚠

semq_floor_reference_id^⚠

Writes the 32-byte state_id of the reference into out.

semq_floor_save^⚠

Writes the floor’s JSON form into out (cap >= semq_floor_json_size).

semq_floor_total_rows^⚠

semq_sha256^⚠

SHA-256 (FIPS 180-4) of len bytes.

semq_status_name^⚠

Static name of a status code (“ok”, “invalid_input”, …).

semq_verdict_free^⚠

semq_verdict_passed^⚠

semq_verdict_reasons^⚠

SEMQ_REASON_* flags; 0 when the verdict passed.

semq_verdict_row^⚠

Index in the diff’s changed list; SEMQ_NONE when out of range.

semq_verdict_row_count^⚠

Type Aliases

semq_check_t

Checks beyond those of semq_diff_within: flags combined with |, for semq_floor_measure_for and semq_diff_evaluate.

semq_config_field_t

Config fields named by field in SEMQ_ERR_INVALID_INPUT errors raised by the config constructors.

semq_id_kind_t

Identifier kinds. Values are pinned: they appear in files.

semq_list_t

Which id list of a Diff an accessor refers to.

semq_operator_t

Operators. Values are pinned: they appear in the canonical config form.

semq_reason_t

Why a verdict failed: flags combined with |.

semq_section_t

File sections named by field in SEMQ_ERR_FORMAT errors.

semq_status_t

Status codes. Each maps to exactly one host error type.

semq_which_t

Which integrity check failed on load.