cribra 0.3.0

/*
 * Cribra native C API.
 *
 * Generated from crates/cribra-capi.
 * Do not edit this file manually.
 *
 * The Cribra native ABI is experimental during the 0.3 series.
 * Crate SemVer and native ABI protocol version are intentionally independent.
 */


#ifndef CRIBRA_H
#define CRIBRA_H

/* WARNING: generated by cbindgen. Manual changes will be overwritten. */

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

/**
 * Experimental native ABI major version.
 */
#define ABI_VERSION_MAJOR 0

/**
 * Experimental native ABI minor version.
 */
#define ABI_VERSION_MINOR 1

/**
 * Experimental native ABI patch version.
 */
#define ABI_VERSION_PATCH 0

/**
 * Opaque Rust-owned ordered batch results.
 *
 * Keys are copied into Rust-owned `String` values. Reports retain metadata only;
 * original source text is never stored.
 */
typedef struct CribraBatchResults CribraBatchResults;

/**
 * Opaque native scanner-builder handle.
 */
typedef struct CribraBuilder CribraBuilder;

/**
 * Opaque Rust-owned native error object.
 *
 * The diagnostic message is privacy-safe metadata. It must never contain
 * original source text, matched sensitive values, transformation keys, panic
 * payloads, or other caller secrets.
 */
typedef struct CribraError CribraError;

/**
 * Opaque Rust-owned transformed UTF-8 output.
 *
 * Content is owned by Cribra until [`crate::cribra_output_free`] is called.
 */
typedef struct CribraOutput CribraOutput;

/**
 * Opaque immutable report handle.
 *
 * v0.3.3 deliberately establishes report ownership only. The report read
 * surface is introduced by v0.3.4.
 */
typedef struct CribraReport CribraReport;

/**
 * Opaque immutable scanner handle.
 */
typedef struct CribraScanner CribraScanner;

/**
 * Opaque Rust-owned share-safe transformed batch.
 *
 * The bundle owns cloned source keys, transformed UTF-8 content, and
 * share-safe manifest metadata. It never retains original source text.
 */
typedef struct CribraShareBundle CribraShareBundle;

/**
 * Native ABI status representation.
 *
 * Numeric assignments become part of the C ABI contract once released.
 */
typedef uint32_t CribraStatus;

/**
 * Stable ABI sensitive-candidate kind representation.
 */
typedef uint32_t CribraCandidateKind;

/**
 * Stable ABI candidate-evidence representation.
 */
typedef uint32_t CribraCandidateEvidence;

/**
 * Projection of one report-owned ambiguous sensitive candidate.
 *
 * Candidates remain review-only observations. This view deliberately contains
 * no finding severity, finding confidence, remediation, or source value.
 */
typedef struct CribraCandidateView {
    /**
     * ABI-defined candidate family.
     */
    CribraCandidateKind kind;
    /**
     * Zero-based byte offset at which the candidate begins.
     */
    size_t start;
    /**
     * Zero-based exclusive byte offset at which the candidate ends.
     */
    size_t end;
    /**
     * One-based source line.
     */
    size_t line;
    /**
     * One-based Unicode-scalar column.
     */
    size_t column;
    /**
     * ABI-defined evidence that caused this value to be surfaced for review.
     */
    CribraCandidateEvidence evidence;
} CribraCandidateView;

/**
 * Borrowed UTF-8 string view.
 *
 * The pointed-to bytes are not NUL-terminated. The view does not own memory
 * and is valid only for the lifetime documented by the API that returned it.
 */
typedef struct CribraStringView {
    /**
     * Pointer to the first UTF-8 byte.
     */
    const uint8_t *ptr;
    /**
     * Number of bytes in the string.
     */
    size_t len;
} CribraStringView;

/**
 * Borrowed projection of one ordered batch entry.
 *
 * `key` borrows storage owned by the parent [`crate::CribraBatchResults`].
 * No source text is exposed.
 */
typedef struct CribraBatchEntryView {
    /**
     * Caller-defined UTF-8 source identifier copied into batch-owned storage.
     */
    struct CribraStringView key;
    /**
     * Original source length in bytes.
     */
    size_t source_bytes;
    /**
     * Number of classified findings for this source.
     */
    size_t finding_count;
    /**
     * Number of ambiguous sensitive candidates for this source.
     */
    size_t candidate_count;
} CribraBatchEntryView;

/**
 * Stable ABI severity representation.
 */
typedef uint32_t CribraSeverity;

/**
 * Stable ABI confidence representation.
 */
typedef uint32_t CribraConfidence;

/**
 * Stable ABI remediation representation.
 */
typedef uint32_t CribraRemediation;

/**
 * Borrowed projection of one report-owned finding.
 *
 * `rule_id` borrows storage owned by the report. No field exposes the matched
 * source value.
 */
typedef struct CribraFindingView {
    /**
     * Stable rule identifier.
     */
    struct CribraStringView rule_id;
    /**
     * Zero-based byte offset at which the finding begins.
     */
    size_t start;
    /**
     * Zero-based exclusive byte offset at which the finding ends.
     */
    size_t end;
    /**
     * One-based source line.
     */
    size_t line;
    /**
     * One-based Unicode-scalar column.
     */
    size_t column;
    /**
     * ABI-defined severity code.
     */
    CribraSeverity severity;
    /**
     * ABI-defined confidence code.
     */
    CribraConfidence confidence;
    /**
     * ABI-defined remediation code, or [`CRIBRA_REMEDIATION_NONE`].
     */
    CribraRemediation remediation;
} CribraFindingView;

/**
 * Aggregate metadata for ordered batch results.
 */
typedef struct CribraBatchSummary {
    /**
     * Number of scanned sources.
     */
    size_t sources;
    /**
     * Sum of source lengths in bytes.
     */
    size_t source_bytes;
    /**
     * Total number of classified findings.
     */
    size_t findings;
    /**
     * Total number of ambiguous sensitive candidates.
     */
    size_t candidates;
} CribraBatchSummary;

/**
 * Stable ABI custom-rule family representation.
 */
typedef uint32_t CribraRuleKind;

/**
 * Borrowed configuration used to add one public custom rule.
 *
 * `id` and `value` are copied by [`crate::cribra_builder_add_rule`] before the
 * call returns. Internal validators and capture projection are deliberately not
 * represented here.
 */
typedef struct CribraRuleConfig {
    /**
     * ABI-defined public rule family.
     */
    CribraRuleKind kind;
    /**
     * Stable rule identifier.
     */
    struct CribraStringView id;
    /**
     * Literal, prefix, suffix, or regex source according to `kind`.
     */
    struct CribraStringView value;
    /**
     * ABI-defined severity assigned to findings.
     */
    CribraSeverity severity;
    /**
     * Optional ABI-defined remediation, or [`CRIBRA_REMEDIATION_NONE`].
     */
    CribraRemediation remediation;
} CribraRuleConfig;

/**
 * Stable ABI explanation-kind representation.
 */
typedef uint32_t CribraExplanationKind;

/**
 * Stable ABI detection-mode representation.
 */
typedef uint32_t CribraDetectionMode;

/**
 * Stable typed explanation projection.
 *
 * Exactly one authority-specific payload is meaningful:
 *
 * - classified explanations set `detection_mode`;
 * - ambiguous explanations set `candidate_evidence`.
 *
 * The unused payload remains its corresponding `*_NONE` value.
 */
typedef struct CribraExplanationView {
    /**
     * ABI-defined explanation family.
     */
    CribraExplanationKind kind;
    /**
     * Classified detection mode, or [`CRIBRA_DETECTION_MODE_NONE`].
     */
    CribraDetectionMode detection_mode;
    /**
     * Ambiguous candidate evidence, or [`CRIBRA_CANDIDATE_EVIDENCE_NONE`].
     */
    CribraCandidateEvidence candidate_evidence;
} CribraExplanationView;

/**
 * One borrowed native batch input descriptor.
 *
 * Both views are borrowed only for the duration of
 * [`crate::cribra_scanner_scan_batch`]. `key` is copied into Rust-owned result
 * storage; `source` is scanned in place and is never retained.
 */
typedef struct CribraBatchInput {
    /**
     * Caller-defined UTF-8 source identifier.
     */
    struct CribraStringView key;
    /**
     * UTF-8 source material to scan.
     */
    struct CribraStringView source;
} CribraBatchInput;

/**
 * Stable ABI batch-execution policy.
 */
typedef uint32_t CribraBatchExecution;

/**
 * Stable ABI share-bundle transformation mode.
 */
typedef uint32_t CribraShareMode;

/**
 * Configuration used to build one share-safe batch.
 *
 * `key` is required only for pseudonymization and synthesis and must contain
 * exactly 32 readable bytes. `text` is the pseudonym prefix for
 * pseudonymization and the synthesis marker for synthesis. An empty `text`
 * selects the core default for those modes. `digest_bytes == 0` selects the
 * pseudonymization default; otherwise the value is passed to the core, which
 * clamps it to its supported range.
 *
 * Redact and Template ignore the keyed configuration fields.
 */
typedef struct CribraShareBundleConfig {
    /**
     * ABI-defined share transformation mode.
     */
    CribraShareMode mode;
    /**
     * Pointer to caller-owned key bytes for keyed modes.
     */
    const uint8_t *key;
    /**
     * Number of key bytes. Keyed modes require exactly 32.
     */
    size_t key_len;
    /**
     * Optional mode-specific UTF-8 configuration.
     */
    struct CribraStringView text;
    /**
     * Optional pseudonym digest length in bytes; zero selects the core default.
     */
    size_t digest_bytes;
} CribraShareBundleConfig;

/**
 * Borrowed projection of one transformed share-bundle source.
 *
 * Both `key` and `content` borrow storage owned by the parent
 * [`crate::CribraShareBundle`].
 */
typedef struct CribraShareEntryView {
    /**
     * Copied caller-defined source identifier.
     */
    struct CribraStringView key;
    /**
     * Share-safe transformed UTF-8 content.
     */
    struct CribraStringView content;
} CribraShareEntryView;

/**
 * Full share-safe projection of [`cribra::ScanSummary`].
 *
 * The value contains counters only and never exposes source text, finding
 * values, source keys, or transform keys.
 */
typedef struct CribraScanSummaryView {
    /**
     * Number of scanned sources.
     */
    size_t scanned_sources;
    /**
     * Total number of UTF-8 source bytes scanned.
     */
    size_t scanned_bytes;
    /**
     * Reports containing at least one finding.
     */
    size_t reports_with_findings;
    /**
     * Reports containing no findings.
     */
    size_t reports_without_findings;
    /**
     * Total classified findings.
     */
    size_t total_findings;
    /**
     * Total ambiguous candidates.
     */
    size_t total_candidates;
    /**
     * Reports containing at least one ambiguous candidate.
     */
    size_t reports_with_candidates;
    /**
     * Critical findings.
     */
    size_t critical;
    /**
     * High-severity findings.
     */
    size_t high;
    /**
     * Medium-severity findings.
     */
    size_t medium;
    /**
     * Low-severity findings.
     */
    size_t low;
    /**
     * Informational findings.
     */
    size_t info;
} CribraScanSummaryView;

/**
 * Share-safe manifest projection.
 *
 * Generation time is represented as seconds and nanoseconds since the Unix
 * epoch. No pseudonymization/synthesis key or original source material is
 * represented.
 */
typedef struct CribraShareManifestView {
    /**
     * ABI-defined transformation mode.
     */
    CribraShareMode mode;
    /**
     * Original scan summary copied into the manifest.
     */
    struct CribraScanSummaryView summary;
    /**
     * Whole seconds since the Unix epoch.
     */
    uint64_t generated_at_secs;
    /**
     * Additional nanoseconds within the generated second.
     */
    uint32_t generated_at_nanos;
} CribraShareManifestView;

/**
 * Configuration for deterministic keyed pseudonymization.
 */
typedef struct CribraPseudonymizeConfig {
    /**
     * Pointer to exactly 32 caller-owned key bytes.
     */
    const uint8_t *key;
    /**
     * Number of key bytes. Must be exactly 32.
     */
    size_t key_len;
    /**
     * Verbatim pseudonym prefix.
     */
    struct CribraStringView prefix;
    /**
     * Digest bytes requested from the core; the core clamps this to its supported range.
     */
    size_t digest_bytes;
} CribraPseudonymizeConfig;

/**
 * Configuration for deterministic synthetic-value generation.
 */
typedef struct CribraSynthesizeConfig {
    /**
     * Pointer to exactly 32 caller-owned key bytes.
     */
    const uint8_t *key;
    /**
     * Number of key bytes. Must be exactly 32.
     */
    size_t key_len;
    /**
     * Marker used by contextual and generic synthetic values.
     */
    struct CribraStringView marker;
} CribraSynthesizeConfig;

/**
 * Configuration for semantic template generation.
 */
typedef struct CribraTemplateConfig {
    /**
     * Placeholder namespace.
     */
    struct CribraStringView namespace_;
    /**
     * `0` disables numbering; `1` enables deterministic per-rule numbering.
     */
    uint8_t numbered;
} CribraTemplateConfig;

/**
 * Let Cribra select the available execution strategy.
 *
 * Without the `cribra-capi/parallel` feature this is serial. With that feature
 * enabled, Cribra may use its parallel batch implementation while preserving
 * ordered, semantically equivalent results.
 */
#define CRIBRA_BATCH_EXECUTION_AUTO 0

/**
 * Force serial batch execution.
 */
#define CRIBRA_BATCH_EXECUTION_SERIAL 1

/**
 * Scanner construction failed.
 */
#define CRIBRA_BUILD_ERROR 4

/**
 * No candidate evidence is present.
 */
#define CRIBRA_CANDIDATE_EVIDENCE_NONE 0

/**
 * Structural evidence without enough semantic context for a finding.
 */
#define CRIBRA_CANDIDATE_EVIDENCE_STRUCTURAL 1

/**
 * Candidate evidence is newer than this ABI projection understands.
 */
#define CRIBRA_CANDIDATE_EVIDENCE_UNKNOWN 4294967295

/**
 * No candidate kind is present.
 */
#define CRIBRA_CANDIDATE_KIND_NONE 0

/**
 * Structurally plausible recovery or backup code.
 */
#define CRIBRA_CANDIDATE_KIND_RECOVERY_LIKE_CODE 1

/**
 * A candidate kind is newer than this ABI projection understands.
 */
#define CRIBRA_CANDIDATE_KIND_UNKNOWN 4294967295

/**
 * High-confidence finding.
 */
#define CRIBRA_CONFIDENCE_HIGH 2

/**
 * Low-confidence finding.
 */
#define CRIBRA_CONFIDENCE_LOW 0

/**
 * Medium-confidence finding.
 */
#define CRIBRA_CONFIDENCE_MEDIUM 1

/**
 * Validation also depends on surrounding source context.
 */
#define CRIBRA_DETECTION_MODE_CONTEXTUAL 3

/**
 * Validation depends only on the candidate's own structure.
 */
#define CRIBRA_DETECTION_MODE_DETERMINISTIC 2

/**
 * The matcher itself is authoritative.
 */
#define CRIBRA_DETECTION_MODE_MATCHER_ONLY 1

/**
 * No classified detection mode is present.
 */
#define CRIBRA_DETECTION_MODE_NONE 0

/**
 * A detection mode is newer than this ABI projection understands.
 */
#define CRIBRA_DETECTION_MODE_UNKNOWN 4294967295

/**
 * Explanation for an ambiguous review-only candidate.
 */
#define CRIBRA_EXPLANATION_AMBIGUOUS 2

/**
 * Explanation for a classified rule-backed finding.
 */
#define CRIBRA_EXPLANATION_CLASSIFIED 1

/**
 * No explanation is present.
 */
#define CRIBRA_EXPLANATION_NONE 0

/**
 * An explanation kind is newer than this ABI projection understands.
 */
#define CRIBRA_EXPLANATION_UNKNOWN 4294967295

/**
 * An unexpected panic was contained inside the native adapter.
 */
#define CRIBRA_INTERNAL_ERROR 255

/**
 * A required pointer or other argument was invalid.
 */
#define CRIBRA_INVALID_ARGUMENT 1

/**
 * A length-delimited input buffer was not valid UTF-8.
 */
#define CRIBRA_INVALID_UTF8 2

/**
 * Operation completed successfully.
 */
#define CRIBRA_OK 0

/**
 * An index was outside the bounds of the requested report collection.
 */
#define CRIBRA_OUT_OF_RANGE 6

/**
 * No remediation metadata is attached.
 */
#define CRIBRA_REMEDIATION_NONE 0

/**
 * Remove the sensitive value.
 */
#define CRIBRA_REMEDIATION_REMOVE_SENSITIVE_VALUE 5

/**
 * Replace the exposed private key.
 */
#define CRIBRA_REMEDIATION_REPLACE_PRIVATE_KEY 4

/**
 * Review whether the hash is appropriate to expose.
 */
#define CRIBRA_REMEDIATION_REVIEW_SENSITIVE_HASH 6

/**
 * Revoke the credential and issue a replacement.
 */
#define CRIBRA_REMEDIATION_REVOKE_AND_ROTATE_CREDENTIAL 1

/**
 * Rotate the credential.
 */
#define CRIBRA_REMEDIATION_ROTATE_CREDENTIAL 2

/**
 * Rotate the password or passphrase.
 */
#define CRIBRA_REMEDIATION_ROTATE_PASSWORD 3

/**
 * A remediation variant is newer than this ABI projection understands.
 */
#define CRIBRA_REMEDIATION_UNKNOWN 4294967295

/**
 * A custom rule definition could not be accepted.
 */
#define CRIBRA_RULE_ERROR 3

/**
 * Exact literal matching.
 */
#define CRIBRA_RULE_KIND_LITERAL 0

/**
 * Full regex-match span projection.
 */
#define CRIBRA_RULE_KIND_PATTERN 3

/**
 * Token-prefix matching.
 */
#define CRIBRA_RULE_KIND_PREFIX 1

/**
 * Token-suffix matching.
 */
#define CRIBRA_RULE_KIND_SUFFIX 2

/**
 * Critical finding.
 */
#define CRIBRA_SEVERITY_CRITICAL 4

/**
 * High-severity finding.
 */
#define CRIBRA_SEVERITY_HIGH 3

/**
 * Informational finding.
 */
#define CRIBRA_SEVERITY_INFO 0

/**
 * Low-severity finding.
 */
#define CRIBRA_SEVERITY_LOW 1

/**
 * Medium-severity finding.
 */
#define CRIBRA_SEVERITY_MEDIUM 2

/**
 * Deterministic keyed pseudonymization.
 */
#define CRIBRA_SHARE_MODE_PSEUDONYMIZE 2

/**
 * Conservative `[REDACTED]` replacement.
 */
#define CRIBRA_SHARE_MODE_REDACT 0

/**
 * Deterministic synthetic-value generation.
 */
#define CRIBRA_SHARE_MODE_SYNTHESIZE 3

/**
 * Semantic `<CRIBRA:rule-id>` placeholder generation.
 */
#define CRIBRA_SHARE_MODE_TEMPLATE 1

/**
 * A manifest mode is newer than this ABI projection understands.
 */
#define CRIBRA_SHARE_MODE_UNKNOWN 4294967295

/**
 * A source transformation could not be applied safely.
 */
#define CRIBRA_TRANSFORM_ERROR 5

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Returns the native ABI major version.
 */
uint32_t cribra_abi_version_major(void);

/**
 * Returns the native ABI minor version.
 */
uint32_t cribra_abi_version_minor(void);

/**
 * Returns the native ABI patch version.
 */
uint32_t cribra_abi_version_patch(void);

/**
 * Returns one ambiguous candidate from an ordered batch entry.
 *
 * No child report handle is created.
 *
 * # Safety
 *
 * `results` must be a live batch-results handle. `out_candidate` must point to
 * writable memory for one [`CribraCandidateView`].
 */
CribraStatus cribra_batch_results_candidate_at(const struct CribraBatchResults *results,
                                               size_t entry_index,
                                               size_t candidate_index,
                                               struct CribraCandidateView *out_candidate);

/**
 * Returns the number of source entries in ordered batch results.
 *
 * # Safety
 *
 * `results` must be a live batch-results handle. `out_count` must point to
 * writable memory for one `size_t`-compatible value.
 */
CribraStatus cribra_batch_results_count(const struct CribraBatchResults *results,
                                        size_t *out_count);

/**
 * Returns a borrowed metadata projection for one ordered batch entry.
 *
 * The returned key view borrows storage owned by `results` and remains valid
 * only while that parent handle remains alive.
 *
 * # Safety
 *
 * `results` must be a live batch-results handle. `out_entry` must point to
 * writable memory for one [`CribraBatchEntryView`].
 */
CribraStatus cribra_batch_results_entry_at(const struct CribraBatchResults *results,
                                           size_t index,
                                           struct CribraBatchEntryView *out_entry);

/**
 * Returns one classified finding from an ordered batch entry.
 *
 * No child report handle is created; the returned view remains subordinate to
 * the parent batch-results lifetime.
 *
 * # Safety
 *
 * `results` must be a live batch-results handle. `out_finding` must point to
 * writable memory for one [`CribraFindingView`].
 */
CribraStatus cribra_batch_results_finding_at(const struct CribraBatchResults *results,
                                             size_t entry_index,
                                             size_t finding_index,
                                             struct CribraFindingView *out_finding);

/**
 * Releases ordered batch results. Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `results` must be a live batch-results handle that has not already
 * been freed.
 */
void cribra_batch_results_free(struct CribraBatchResults *results);

/**
 * Returns aggregate metadata for ordered batch results.
 *
 * # Safety
 *
 * `results` must be a live batch-results handle. `out_summary` must point to
 * writable memory for one [`CribraBatchSummary`].
 */
CribraStatus cribra_batch_results_summary(const struct CribraBatchResults *results,
                                          struct CribraBatchSummary *out_summary);

/**
 * Adds Cribra's current canonical built-in catalog to a builder.
 *
 * This allows native consumers to combine the standard catalog with custom
 * rules while preserving scanner-wide rule-ID validation.
 *
 * # Safety
 *
 * `builder` must be a live builder handle returned by [`cribra_builder_new`].
 */
CribraStatus cribra_builder_add_current_builtins(struct CribraBuilder *builder);

/**
 * Adds one public custom rule to a scanner builder.
 *
 * `id` and `value` are copied into Rust-owned rule storage before this function
 * returns. Literal, prefix and suffix rules retain the core's existing deferred
 * empty-value validation. Pattern syntax and zero-length-capable patterns are
 * rejected while constructing the rule.
 *
 * Internal validators and capture projection are intentionally unavailable
 * through this ABI.
 *
 * # Safety
 *
 * `builder` must be a live builder handle. `config` must point to a readable
 * [`CribraRuleConfig`]. Each non-empty string view in `config` must reference
 * readable bytes for the duration of this call.
 */
CribraStatus cribra_builder_add_rule(struct CribraBuilder *builder,
                                     const struct CribraRuleConfig *config,
                                     struct CribraError **out_error);

/**
 * Consumes a builder and compiles an immutable scanner.
 *
 * The builder is consumed by every non-null build attempt.
 *
 * # Safety
 *
 * `builder` must be a live handle returned by [`cribra_builder_new`] and must
 * not be used after this call. `out_scanner` must point to writable memory for
 * one scanner pointer.
 */
CribraStatus cribra_builder_build(struct CribraBuilder *builder,
                                  struct CribraScanner **out_scanner,
                                  struct CribraError **out_error);

/**
 * Releases a scanner builder. Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `builder` must be a live builder handle that has not already been
 * consumed or freed.
 */
void cribra_builder_free(struct CribraBuilder *builder);

/**
 * Creates an empty scanner builder.
 *
 * # Safety
 *
 * `out_builder` must point to writable memory for one builder pointer. The
 * returned handle must eventually be released with [`cribra_builder_free`] or
 * consumed by [`cribra_builder_build`].
 */
CribraStatus cribra_builder_new(struct CribraBuilder **out_builder);

/**
 * Releases an owned native error object.
 *
 * Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `error` must be a live handle returned by the Cribra native ABI
 * and must not already have been freed.
 */
void cribra_error_free(struct CribraError *error);

/**
 * Returns a borrowed UTF-8 diagnostic message.
 *
 * The returned bytes are not NUL-terminated and remain valid only while
 * `error` remains alive. The caller must not free the returned view.
 *
 * # Safety
 *
 * `error` must be a live [`CribraError`] handle. `out_message` must point to
 * writable memory for one [`CribraStringView`].
 */
CribraStatus cribra_error_message(const struct CribraError *error,
                                  struct CribraStringView *out_message);

/**
 * Returns the coarse status represented by an error object.
 *
 * # Safety
 *
 * `error` must be a live [`CribraError`] handle. `out_status` must point to
 * writable memory for one [`CribraStatus`] value.
 */
CribraStatus cribra_error_status(const struct CribraError *error, CribraStatus *out_status);

/**
 * Releases one Rust-owned transformed output. Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `output` must be a live handle returned by a transform function
 * and must not already have been freed.
 */
void cribra_output_free(struct CribraOutput *output);

/**
 * Borrows the UTF-8 bytes owned by a transformed output handle.
 *
 * The returned view remains valid only until [`cribra_output_free`] is called.
 *
 * # Safety
 *
 * `output` must be live and `out_view` must be writable.
 */
CribraStatus cribra_output_view(const struct CribraOutput *output,
                                struct CribraStringView *out_view);

/**
 * Returns a projection of one ambiguous sensitive candidate by index.
 *
 * The candidate view contains presentation-safe metadata only and never
 * contains the candidate's source value.
 *
 * # Safety
 *
 * `report` must be a live report handle. `out_candidate` must point to writable
 * memory for one [`CribraCandidateView`].
 */
CribraStatus cribra_report_candidate_at(const struct CribraReport *report,
                                        size_t index,
                                        struct CribraCandidateView *out_candidate);

/**
 * Returns the number of ambiguous sensitive candidates in a report.
 *
 * Candidates are distinct from classified findings and do not contribute to
 * [`cribra_report_finding_count`].
 *
 * # Safety
 *
 * `report` must be a live report handle. `out_count` must point to writable
 * memory for one `size_t`-compatible value.
 */
CribraStatus cribra_report_candidate_count(const struct CribraReport *report, size_t *out_count);

/**
 * Returns typed explanation facts for one ambiguous candidate.
 *
 * Candidate explanation is derived directly from the candidate's existing
 * evidence. It never acquires finding severity, confidence, remediation, or
 * source content.
 *
 * # Safety
 *
 * `report` must be a live immutable report handle. `out_explanation` must point
 * to writable memory for one [`CribraExplanationView`].
 */
CribraStatus cribra_report_explain_candidate(const struct CribraReport *report,
                                             size_t index,
                                             struct CribraExplanationView *out_explanation);

/**
 * Returns a borrowed projection of one classified finding by index.
 *
 * The returned `rule_id` view borrows report-owned storage and remains valid
 * only while `report` remains alive and unmodified. Reports are immutable.
 *
 * # Safety
 *
 * `report` must be a live report handle. `out_finding` must point to writable
 * memory for one [`CribraFindingView`].
 */
CribraStatus cribra_report_finding_at(const struct CribraReport *report,
                                      size_t index,
                                      struct CribraFindingView *out_finding);

/**
 * Returns the number of classified findings in a report.
 *
 * Candidates are intentionally excluded from this count and receive their own
 * API in v0.3.5.
 *
 * # Safety
 *
 * `report` must be a live report handle. `out_count` must point to writable
 * memory for one `size_t`-compatible value.
 */
CribraStatus cribra_report_finding_count(const struct CribraReport *report, size_t *out_count);

/**
 * Releases an immutable report. Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `report` must be a live report handle that has not already been
 * freed.
 */
void cribra_report_free(struct CribraReport *report);

/**
 * Resolves typed explanation facts for one classified finding.
 *
 * Explanation authority remains scanner-owned. If `scanner` cannot resolve
 * metadata compatible with the selected finding, this function fails closed
 * with [`CRIBRA_INVALID_ARGUMENT`] and leaves `out_explanation` empty.
 *
 * # Safety
 *
 * `scanner` and `report` must be live immutable handles. `out_explanation`
 * must point to writable memory for one [`CribraExplanationView`].
 */
CribraStatus cribra_scanner_explain_finding(const struct CribraScanner *scanner,
                                            const struct CribraReport *report,
                                            size_t index,
                                            struct CribraExplanationView *out_explanation,
                                            struct CribraError **out_error);

/**
 * Releases an immutable scanner. Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `scanner` must be a live scanner handle that has not already been
 * freed.
 */
void cribra_scanner_free(struct CribraScanner *scanner);

/**
 * Creates a scanner using Cribra's current canonical built-in catalog.
 *
 * # Safety
 *
 * `out_scanner` must point to writable memory for one scanner pointer. The
 * returned handle must eventually be released with [`cribra_scanner_free`].
 */
CribraStatus cribra_scanner_new_current(struct CribraScanner **out_scanner);

/**
 * Scans one caller-owned UTF-8 source and returns an owned report.
 *
 * The source is borrowed only for this call and is never retained. Null plus a
 * zero length is accepted as an empty source.
 *
 * # Safety
 *
 * `scanner` must be a live scanner handle. For non-empty input, `source` must
 * reference at least `source_len` readable bytes for the duration of this call.
 * `out_report` must point to writable memory for one report pointer.
 */
CribraStatus cribra_scanner_scan(const struct CribraScanner *scanner,
                                 const uint8_t *source,
                                 size_t source_len,
                                 struct CribraReport **out_report,
                                 struct CribraError **out_error);

/**
 * Scans an ordered batch of caller-owned UTF-8 sources.
 *
 * The input descriptor array and all pointed-to bytes are borrowed only for
 * this call. Keys are copied into Rust-owned result storage. Source text is
 * never retained. Successful results preserve input order exactly.
 *
 * If any descriptor contains invalid pointer/UTF-8 input, the whole call fails
 * before scanning and `out_results` remains null; partial results are never
 * returned.
 *
 * `execution` accepts [`CRIBRA_BATCH_EXECUTION_AUTO`] or
 * [`CRIBRA_BATCH_EXECUTION_SERIAL`]. AUTO remains semantically identical to
 * SERIAL and may use Cribra's parallel implementation only when the adapter is
 * built with its optional `parallel` feature.
 *
 * `inputs == NULL` with `input_count == 0` is accepted as an empty batch.
 *
 * # Safety
 *
 * `scanner` must be a live scanner handle. When `input_count > 0`, `inputs`
 * must reference at least `input_count` readable [`CribraBatchInput`] values.
 * Every non-empty string view must reference readable bytes for the duration of
 * this call. `out_results` must point to writable memory for one batch-results
 * pointer.
 */
CribraStatus cribra_scanner_scan_batch(const struct CribraScanner *scanner,
                                       const struct CribraBatchInput *inputs,
                                       size_t input_count,
                                       CribraBatchExecution execution,
                                       struct CribraBatchResults **out_results,
                                       struct CribraError **out_error);

/**
 * Builds a share-safe transformed batch from ordered scan results.
 *
 * `sources` must contain the same logical UTF-8 sources, in the same order,
 * that produced `results`. The core validates source count and byte lengths
 * before transformation. Source text is borrowed only for this call and is
 * never retained.
 *
 * On success, the returned bundle owns cloned source keys, transformed content,
 * and share-safe manifest metadata. It must eventually be released with
 * [`cribra_share_bundle_free`].
 *
 * # Safety
 *
 * `results` must be a live batch-results handle. `config` must point to a
 * readable [`CribraShareBundleConfig`]. When `source_count > 0`, `sources` must
 * reference at least `source_count` readable [`CribraStringView`] values. Every
 * non-empty source/config text view must reference readable bytes for the
 * duration of this call. `out_bundle` must point to writable memory for one
 * share-bundle pointer.
 */
CribraStatus cribra_share_bundle_build(const struct CribraBatchResults *results,
                                       const struct CribraStringView *sources,
                                       size_t source_count,
                                       const struct CribraShareBundleConfig *config,
                                       struct CribraShareBundle **out_bundle,
                                       struct CribraError **out_error);

/**
 * Returns the number of transformed sources in a share bundle.
 *
 * # Safety
 *
 * `bundle` must be a live share-bundle handle. `out_count` must point to
 * writable memory for one `size_t`-compatible value.
 */
CribraStatus cribra_share_bundle_count(const struct CribraShareBundle *bundle, size_t *out_count);

/**
 * Returns one borrowed transformed-source projection.
 *
 * Both returned string views remain valid only while `bundle` remains alive.
 *
 * # Safety
 *
 * `bundle` must be a live share-bundle handle. `out_entry` must point to
 * writable memory for one [`CribraShareEntryView`].
 */
CribraStatus cribra_share_bundle_entry_at(const struct CribraShareBundle *bundle,
                                          size_t index,
                                          struct CribraShareEntryView *out_entry);

/**
 * Releases a share bundle. Passing null is a no-op.
 *
 * # Safety
 *
 * A non-null `bundle` must be a live share-bundle handle that has not already
 * been freed.
 */
void cribra_share_bundle_free(struct CribraShareBundle *bundle);

/**
 * Returns the share-safe bundle manifest.
 *
 * The projection contains only transformation kind, aggregate counters, and
 * generation time. It never contains source text or keyed-transform secrets.
 *
 * # Safety
 *
 * `bundle` must be a live share-bundle handle. `out_manifest` must point to
 * writable memory for one [`CribraShareManifestView`].
 */
CribraStatus cribra_share_bundle_manifest(const struct CribraShareBundle *bundle,
                                          struct CribraShareManifestView *out_manifest);

/**
 * Pseudonymizes findings with a mandatory caller-provided 32-byte key.
 *
 * # Safety
 *
 * `config` and its referenced key/prefix bytes must remain readable for this
 * call. Other pointer contracts match [`cribra_transform_redact`].
 */
CribraStatus cribra_transform_pseudonymize(const uint8_t *source,
                                           size_t source_len,
                                           const struct CribraReport *report,
                                           const struct CribraPseudonymizeConfig *config,
                                           struct CribraOutput **out_output,
                                           struct CribraError **out_error);

/**
 * Redacts all classified finding spans using Cribra's standard marker.
 *
 * The returned output is Rust-owned and must be released exactly once with
 * [`cribra_output_free`].
 *
 * # Safety
 *
 * `report` must be live. `source` follows the same UTF-8 buffer contract as
 * [`cribra_scanner_scan`]. `out_output` must be writable.
 */
CribraStatus cribra_transform_redact(const uint8_t *source,
                                     size_t source_len,
                                     const struct CribraReport *report,
                                     struct CribraOutput **out_output,
                                     struct CribraError **out_error);

/**
 * Redacts findings using a caller-selected UTF-8 replacement.
 *
 * # Safety
 *
 * Pointer contracts are identical to [`cribra_transform_redact`]. `replacement`
 * is borrowed only for this call.
 */
CribraStatus cribra_transform_redact_with(const uint8_t *source,
                                          size_t source_len,
                                          const struct CribraReport *report,
                                          const uint8_t *replacement,
                                          size_t replacement_len,
                                          struct CribraOutput **out_output,
                                          struct CribraError **out_error);

/**
 * Synthesizes deterministic share-safe values with a caller-provided key.
 *
 * # Safety
 *
 * `config` and its referenced key/marker bytes must remain readable for this
 * call. Other pointer contracts match [`cribra_transform_redact`].
 */
CribraStatus cribra_transform_synthesize(const uint8_t *source,
                                         size_t source_len,
                                         const struct CribraReport *report,
                                         const struct CribraSynthesizeConfig *config,
                                         struct CribraOutput **out_output,
                                         struct CribraError **out_error);

/**
 * Generates semantic placeholders using default template options.
 *
 * # Safety
 *
 * Pointer contracts are identical to [`cribra_transform_redact`].
 */
CribraStatus cribra_transform_template(const uint8_t *source,
                                       size_t source_len,
                                       const struct CribraReport *report,
                                       struct CribraOutput **out_output,
                                       struct CribraError **out_error);

/**
 * Generates semantic placeholders using explicit configuration.
 *
 * `numbered` accepts only `0` or `1`.
 *
 * # Safety
 *
 * `config` must be readable for this call. Its namespace view is borrowed only
 * for this call. Other pointer contracts match [`cribra_transform_redact`].
 */
CribraStatus cribra_transform_template_with(const uint8_t *source,
                                            size_t source_len,
                                            const struct CribraReport *report,
                                            const struct CribraTemplateConfig *config,
                                            struct CribraOutput **out_output,
                                            struct CribraError **out_error);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* CRIBRA_H */