Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C
35.0 KB
Raw Blame
#ifndef COLIBRI_BACKEND_XDNA_H
#define COLIBRI_BACKEND_XDNA_H

/* Optional AMD XDNA2 (Ryzen AI NPU) compute lane -- host-side binding only.
 *
 * XDNA is an OPTIONAL lane, never an engine. Colibri keeps model semantics,
 * routing, expert identity, weight ownership, scheduling and fallback; the
 * helper only ever executes one already-selected, already-qualified operation.
 *
 * This header and backend_xdna.c are the C-side owners and they NEVER include
 * or link XRT. XRT lives exclusively behind an optional native helper DLL
 * (coli_xdna.dll), resolved at runtime the way backend_loader.c resolves the
 * GPU backend. An ordinary Colibri build has no XRT dependency at all, and a
 * machine with no helper, no XRT and no NPU is a normal machine, not a broken
 * one.
 *
 * Scope of THIS slice (W2-N7-I1): binding only. Nothing here opens a device,
 * reads an artifact, prepares a weight or executes anything -- see the state
 * comment on ColiXdnaBinding.
 */

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Host-side ABI generation. A helper reporting a different value is refused
 * outright: there is no partial acceptance and no speculative forward
 * compatibility, because neither could be tested here. Bump this when the
 * required entry-point set or any signature changes.
 *
 * Generation 2 (W2-N7-I5) is a DELIBERATE COMPATIBILITY BREAK. Generation 1
 * required two entry points and could only answer "a helper exists"; generation
 * 2 requires seven and can open a device, wrap a weight and execute. A
 * generation-1 helper is refused outright rather than partially used: it cannot
 * perform any of the new work, and silently binding it would produce a helper
 * that reports availability and then cannot execute. */
#define COLI_XDNA_ABI_VERSION 2u

/* Symbols the helper must export, all prefixed coli_xdna_helper_ so they can
 * never collide with the host-side coli_xdna_ names in this header. */
#define COLI_XDNA_HELPER_DLL "coli_xdna.dll"

/* Directory, relative to the executable, holding the qualified artifacts of the
 * optional XDNA package. A fixed relative name, joined to an absolute
 * executable directory -- never searched for. */
#define COLI_XDNA_ARTIFACT_DIR "xdna"

/* Prepared-host pointer alignment required by the qualified Windows XRT
 * userptr path. Scoped to that path deliberately: it is not a claim about
 * every XRT implementation. The payload SIZE need not be a page multiple. */
#define COLI_XDNA_PREPARED_ALIGNMENT 4096u

/* Loader verdict. This describes the HELPER BINDING and nothing else.
 *
 * COLI_XDNA_AVAILABLE means HELPER_ABI_AVAILABLE: a compatible helper is loaded
 * and every entry point this host requires resolved. It does NOT mean a device
 * is present, an artifact is usable, or any operation is eligible -- those are
 * separate concerns owned by later slices, deliberately not conflated here. */
typedef enum {
    COLI_XDNA_UNPROBED = 0,      /* no probe attempted yet */
    COLI_XDNA_AVAILABLE,         /* compatible helper bound (ABI only) */
    COLI_XDNA_ABSENT,            /* no helper file where we looked */
    COLI_XDNA_LOAD_FAILED,       /* file present, but it would not load */
    COLI_XDNA_ABI_INCOMPATIBLE,  /* loaded, reported a different ABI generation */
    COLI_XDNA_SYMBOL_INCOMPLETE  /* loaded and compatible, but an entry point is missing */
} ColiXdnaBinding;

/* Probe once, then answer from the cached verdict. The probe is LAZY: an
 * ordinary run that never asks pays nothing, and a run that asks pays one
 * LoadLibrary at most. Every outcome other than COLI_XDNA_AVAILABLE simply
 * means the lane is unavailable; none of them is an error the caller must
 * handle beyond continuing on its current path. */
ColiXdnaBinding coli_xdna_binding(void);

/* Stable, allocation-free label for diagnostics and tests. */
const char *coli_xdna_binding_text(ColiXdnaBinding state);

/* Release the helper. Safe when never probed, safe after a failed probe, and
 * safe to call repeatedly. Callable pointers are cleared before the module is
 * released, so no entry point can outlive the module that provided it. */
void coli_xdna_shutdown(void);

/* -- test seams -----------------------------------------------------------
 * Mirrors the coli_loader_test_* convention in backend_loader.c: exercised by
 * c/tests/test_backend_loader.py against synthetic helpers that contain no
 * XRT, so the whole binding contract is qualified without an NPU. */

/* Point the loader at a specific helper file instead of the default lookup.
 * Resets any cached verdict so the next query re-probes. */
void coli_xdna_test_set_helper_path(const char *path);

/* Cached verdict WITHOUT triggering a probe. */
ColiXdnaBinding coli_xdna_test_state(void);

/* How many times a module load has actually been attempted. The sticky verdict
 * contract is that this never exceeds 1 for a given path. */
int coli_xdna_test_load_attempts(void);

/* 1 only when a complete, compatible entry-point set is currently callable. A
 * rejected helper must leave this 0 -- binding is all-or-nothing. */
int coli_xdna_test_entry_points_bound(void);

/* -- artifact registry ----------------------------------------------------
 *
 * Colibri owns which artifact answers which semantic operation, and whether
 * that artifact is trustworthy. The helper owns none of it: it will eventually
 * be handed an already-selected, already-verified artifact and nothing more.
 *
 * "Qualified" here is a research fact, recovered from the sealed N6 evidence
 * chain, not a runtime observation. A program that compiled, loaded and
 * dispatched successfully can still be numerically wrong -- N6 measured exactly
 * that -- so compilation and dispatch success are deliberately NOT inputs. */

typedef enum {
    COLI_XDNA_DT_NONE = 0,
    COLI_XDNA_DT_BF16 = 1,
    COLI_XDNA_DT_F32  = 2
} ColiXdnaDtype;

typedef enum {
    COLI_XDNA_TARGET_NONE  = 0,
    COLI_XDNA_TARGET_XDNA2 = 1      /* AMD XDNA2 / Strix Halo class NPU */
} ColiXdnaTarget;

/* Engine-owned semantic identity of an operation. This is what makes artifact
 * selection a decision the engine makes rather than one inferred from a shape:
 * two operations with identical M/K/N are still different operations, and one
 * may never inherit the other's qualification. */
typedef enum {
    COLI_XDNA_FAMILY_NONE = 0,
    COLI_XDNA_FAMILY_MOE_SHARED_GATE_UP = 1   /* MoE shared-expert gate/up projection */
} ColiXdnaFamily;

/* One qualified artifact. Every field is a fact about the artifact; none is a
 * fact about the device, the weight, the request, or whether running here would
 * be a good idea. */
typedef struct {
    ColiXdnaFamily  family;
    const char     *research_family;   /* N6 shape-family label, e.g. "F3" */
    unsigned        artifact_m;        /* the program's M, exactly as qualified */
    unsigned        k, n;
    ColiXdnaDtype   in_dtype;          /* activation dtype the program expects */
    ColiXdnaDtype   weight_dtype;      /* prepared-weight dtype */
    ColiXdnaDtype   out_dtype;
    ColiXdnaTarget  target;
    const char     *xclbin_name;       /* logical name, resolved under a root */
    const char     *xclbin_sha256;     /* 64 lowercase hex chars */
    const char     *insts_name;
    const char     *insts_sha256;
    /* Research qualifications. All four must hold; see the enum comment. */
    unsigned char   runtime_weight_qualified;
    unsigned char   correctness_qualified;
    unsigned char   userptr_qualified;
    unsigned char   structural_qualified;
} ColiXdnaArtifact;

/* What the engine asks about. Deliberately free of expert id, layer index,
 * model name, router state and any reuse or economic term: those would
 * over-specialize artifact identity, and economics is a separate decision. */
typedef struct {
    ColiXdnaFamily family;
    unsigned       m, k, n;
    ColiXdnaDtype  in_dtype, weight_dtype, out_dtype;
} ColiXdnaRequest;

/* STATIC verdict. The strongest value here is COLI_XDNA_STATIC_QUALIFIED, which
 * means: Colibri knows this operation, holds a matching qualified artifact
 * definition, and the bytes on disk are the bytes the research programme
 * qualified.
 *
 * It does NOT mean a device exists, a context can be created, a weight has been
 * prepared, a pointer is aligned, memory is available, or that running here
 * would be preferable. Those gates do not exist yet, and no enumerator here
 * may be read as implying them. */
typedef enum {
    COLI_XDNA_STATIC_QUALIFIED = 0,
    COLI_XDNA_STATIC_HELPER_UNAVAILABLE,
    COLI_XDNA_STATIC_UNKNOWN_FAMILY,
    COLI_XDNA_STATIC_UNSUPPORTED_SHAPE_OR_BUCKET,
    COLI_XDNA_STATIC_UNSUPPORTED_FORMAT,
    COLI_XDNA_STATIC_ARTIFACT_UNAVAILABLE,
    COLI_XDNA_STATIC_ARTIFACT_INTEGRITY_FAILED,
    COLI_XDNA_STATIC_ARTIFACT_UNQUALIFIED,
    COLI_XDNA_STATIC_REGISTRY_INVALID
} ColiXdnaStatic;

const char *coli_xdna_static_text(ColiXdnaStatic state);

/* Resolve a request to a qualified artifact definition, or NULL. Matching is on
 * the full key -- family, bucket, shape and dtypes -- never on shape alone. */
const ColiXdnaArtifact *coli_xdna_registry_lookup(const ColiXdnaRequest *req);

/* 1 when every row is well formed and no two rows share a lookup key. Callers
 * must treat 0 as "the registry may not be used". */
int coli_xdna_registry_validate(void);

/* Artifact-only verdict: does a trustworthy artifact exist for this request?
 * Independent of the helper on purpose -- artifact trust is a property of the
 * artifact. artifact_root is the directory logical names resolve under; NULL
 * yields COLI_XDNA_STATIC_ARTIFACT_UNAVAILABLE rather than a search. */
ColiXdnaStatic coli_xdna_artifact_status(const ColiXdnaRequest *req,
                                         const char *artifact_root);

/* Combined static verdict: helper binding AND artifact status. Still static;
 * see the ColiXdnaStatic comment for what it does not mean. */
ColiXdnaStatic coli_xdna_static_eligibility(const ColiXdnaRequest *req,
                                            const char *artifact_root);

/* SHA-256 (FIPS 180-4). Self-contained so the registry stays portable and the
 * host acquires no new link dependency; see the audit in this slice's evidence. */
void coli_xdna_sha256(const void *data, size_t len, unsigned char out[32]);
/* 1 on success, 0 when the file cannot be read. */
int  coli_xdna_sha256_file(const char *path, unsigned char out[32]);

/* -- prepared host state --------------------------------------------------
 *
 * The prepared BF16 image is DERIVED, DISPOSABLE, accelerator-specific HOST
 * state. The stored fmt=4 tensor remains authoritative and is never touched,
 * replaced or freed by anything here.
 *
 * Three properties vary independently and must never be collapsed into one
 * flag: whether memory is ALLOCATED, whether its contents are VALID, and how
 * many host bytes are consumed. An invalid buffer still costs memory, and no
 * amount of successful allocation makes contents valid. */

typedef enum {
    COLI_XDNA_PREP_UNPREPARED = 0,  /* no contents; may or may not hold capacity */
    COLI_XDNA_PREP_PREPARING,       /* a producer owns the destination */
    COLI_XDNA_PREP_VALID,           /* a producer published complete success */
    COLI_XDNA_PREP_INVALID          /* preparation failed, or contents revoked */
    /* A future IN_FLIGHT / PINNED value belongs here; the state is a field
     * rather than a boolean precisely so it can be added. */
} ColiXdnaPrepState;

/* Opaque: the layout is an implementation detail of backend_xdna.c, so callers
 * cannot reach past the transition helpers and set a state directly. */
typedef struct ColiXdnaPrepared ColiXdnaPrepared;

const char *coli_xdna_prep_text(ColiXdnaPrepState state);

/* Create an empty object. Allocates no payload: creation is not preparation. */
ColiXdnaPrepared *coli_xdna_prepared_create(void);

/* Free payload and object, clear the caller's handle. Safe on NULL, on a
 * never-allocated object, mid-PREPARING, on INVALID, on VALID, and repeatedly. */
void coli_xdna_prepared_release(ColiXdnaPrepared **p);

/* Begin a complete preparation cycle for a BF16 B[K,N] image. Allocates or
 * reuses capacity, guarantees 4096-byte pointer alignment, and moves to
 * PREPARING. Returns 0 without changing state on a rejected request.
 *
 * Beginning is the ONLY way to reach PREPARING, and publication is the only way
 * out, so a caller cannot arrive at VALID by allocating. */
int coli_xdna_prepare_begin(ColiXdnaPrepared *p, unsigned k, unsigned n,
                            ColiXdnaDtype prepared_dtype);

/* The writable destination, and only while PREPARING. NULL in every other
 * state, so a published image cannot be rewritten behind its own back. */
void *coli_xdna_prepare_dest(ColiXdnaPrepared *p);

/* PREPARING -> VALID. Refused from any other state: an INVALID image can never
 * shortcut to VALID, it must go through a complete new cycle. */
int coli_xdna_prepare_publish_success(ColiXdnaPrepared *p);

/* PREPARING -> INVALID. Capacity is retained; the bytes stay accounted. */
void coli_xdna_prepare_publish_failure(ColiXdnaPrepared *p);

/* VALID -> INVALID, keeping capacity. For a later weight replacement, format
 * change or eviction; this slice implements no trigger for it. */
int coli_xdna_prepared_invalidate(ColiXdnaPrepared *p);

/* Drop retained capacity, returning the object to UNPREPARED with zero bytes.
 * Validity and allocation lifetime are separate, so this is separate too. */
void coli_xdna_prepared_free_buffer(ColiXdnaPrepared *p);

/* -- fmt4 -> BF16 preparation ---------------------------------------------
 *
 * Turns the authoritative fmt=4 grouped-int4 weight into the prepared BF16
 * B[K,N] image, writing straight into the aligned destination above. The source
 * is read and never modified.
 *
 * This is engine representation logic and stays on the C side: the helper knows
 * nothing about nibble packing, group scales or tensor semantics. */

typedef enum {
    COLI_XDNA_PREP_OK = 0,
    COLI_XDNA_PREP_ERR_UNSUPPORTED_FORMAT,  /* not fmt=4 */
    COLI_XDNA_PREP_ERR_INVALID_SOURCE,      /* NULL pointers, zero dims, bad gs */
    COLI_XDNA_PREP_ERR_SIZE,                /* dimensions not representable */
    COLI_XDNA_PREP_ERR_ALLOC,               /* destination could not be obtained */
    COLI_XDNA_PREP_ERR_FAILED,              /* conversion failed after it began */
    COLI_XDNA_PREP_ERR_STATE                /* no object, or it cannot begin */
} ColiXdnaPrepResult;

const char *coli_xdna_prep_result_text(ColiXdnaPrepResult r);

/* Prepared dimensions derive from the tensor: K = I, N = O. They are not
 * caller-supplied, so they cannot silently disagree with the source.
 *
 * Publishes VALID only after the whole conversion succeeds. Any failure after
 * the cycle opens leaves PREPARED_INVALID with whatever partial bytes were
 * written -- which carry no authority, because state decides validity, not
 * contents. Never returns while still PREPARING. */
ColiXdnaPrepResult coli_xdna_prepare_from_fmt4(ColiXdnaPrepared *p,
                                               int fmt,
                                               const unsigned char *q4,
                                               const float *scale,
                                               int I, int O, int gs);

/* The prepared image, readable only when the state is VALID. NULL otherwise, so
 * an unpublished or revoked image cannot be consumed by accident. */
const void *coli_xdna_prepared_image(const ColiXdnaPrepared *p);

ColiXdnaPrepState coli_xdna_prepared_state(const ColiXdnaPrepared *p);
/* Logical payload bytes currently allocated: K*N*sizeof(bf16), not a rounded
 * allocator reservation. Non-zero for a retained INVALID buffer. */
size_t   coli_xdna_prepared_bytes(const ColiXdnaPrepared *p);
unsigned coli_xdna_prepared_k(const ColiXdnaPrepared *p);
unsigned coli_xdna_prepared_n(const ColiXdnaPrepared *p);

/* Publication generation: incremented every time this object publishes a VALID
 * image. Two images can occupy the same address -- retained capacity is reused
 * in place -- so an address alone does not identify contents. Anything that
 * caches a view of the prepared bytes must key on (pointer, generation).
 *
 * W2-N7-I6 added this because the I5 lane keyed its userptr wrapper on the
 * pointer alone. Re-preparing a different weight into the same buffer therefore
 * skipped the re-wrap, and the device -- which snapshots at wrap time -- kept
 * computing against a view that no longer matched the engine's image. Confirmed
 * on real XDNA2 hardware, not merely reasoned about. */
unsigned long long coli_xdna_prepared_generation(const ColiXdnaPrepared *p);

/* Defensive validator. The allocator guarantees alignment, but a buffer that
 * arrives from elsewhere, from a pool, or at an offset does not -- and a
 * misaligned pointer fails at the XRT boundary with a message about video
 * memory, which points at entirely the wrong subsystem. */
int coli_xdna_pointer_alignment_ok(const void *p);

/* Engine-side host accounting. These are HOST bytes: not VRAM, not NPU memory,
 * not an XRT device allocation. */
size_t coli_xdna_prepared_total_bytes(void);
int    coli_xdna_prepared_live_objects(void);

/* -- full hard eligibility and native execution ---------------------------
 *
 * I2 could only answer STATIC_ARTIFACT_QUALIFIED: does a trustworthy artifact
 * exist? This is the first slice that can answer the whole question:
 *
 *     CAN this operation safely run on XDNA, right now, on this machine?
 *
 * It still does NOT answer "should it". Hard eligibility and economic
 * preference are separate decisions with separate owners, and nothing here
 * consults, computes or caches a cost. Automatic selection belongs to a later
 * slice; this one executes only when an internal test control asks it to. */

typedef enum {
    COLI_XDNA_HARD_ELIGIBLE = 0,
    /* engine-side semantic gates, evaluated before anything is opened */
    COLI_XDNA_HARD_FAMILY_UNSUPPORTED,
    COLI_XDNA_HARD_M_OUT_OF_RANGE,
    COLI_XDNA_HARD_SHAPE_UNSUPPORTED,
    COLI_XDNA_HARD_FORMAT_UNSUPPORTED,      /* stored tensor is not fmt=4 */
    COLI_XDNA_HARD_GROUP_SIZE_UNSUPPORTED,  /* fmt=4 but gs is not the qualified 64 */
    COLI_XDNA_HARD_LAYOUT_UNSUPPORTED,      /* fmt=4 pair layout expected; bytes are planar */
    /* artifact gates -- kept distinct because they mean different things
     * operationally: "this build does not ship that artifact", "the bytes are
     * not the bytes that were qualified", and "we never qualified this one"
     * lead to different actions, and collapsing them loses the difference
     * exactly where an operator needs it most. */
    COLI_XDNA_HARD_ARTIFACT_UNAVAILABLE,
    COLI_XDNA_HARD_ARTIFACT_INTEGRITY_FAILED,
    COLI_XDNA_HARD_ARTIFACT_UNQUALIFIED,
    COLI_XDNA_HARD_REGISTRY_INVALID,
    /* representation gates */
    COLI_XDNA_HARD_PREPARED_INVALID,
    COLI_XDNA_HARD_ALIGNMENT_INVALID,
    /* runtime gates */
    COLI_XDNA_HARD_HELPER_UNAVAILABLE,       /* absent, or would not load */
    COLI_XDNA_HARD_HELPER_ABI_INCOMPATIBLE,  /* loaded, wrong generation or incomplete */
    COLI_XDNA_HARD_DEVICE_UNAVAILABLE,
    COLI_XDNA_HARD_ARTIFACT_RUNTIME_UNAVAILABLE,
    COLI_XDNA_HARD_WEIGHT_WRAP_UNAVAILABLE
} ColiXdnaHard;

const char *coli_xdna_hard_text(ColiXdnaHard h);

/* The qualified source group size. I4's converter accepts any gs>0 as a generic
 * representation transform; that breadth is a property of the CONVERTER, not a
 * statement about what the device was qualified on. A PREPARED_VALID image
 * built from another gs is a perfectly good host image and is still refused
 * here, because no artifact was ever correctness-qualified against one. */
#define COLI_XDNA_QUALIFIED_GROUP_SIZE 64

/* The logical-M range this lane implements, and the artifact buckets serving it.
 *
 * Row padding is legitimate because C = A x B is row-independent: output row i
 * depends only on input row i and on B. N6-A2-A1A qualified the strategy
 * physically -- 13 logical M values against an unmodified fixed-M artifact, all
 * bit-exact, with zeros written into every padded row. That argument is a
 * property of PURE GEMM and must never be extended to attention, normalisation
 * or routing.
 *
 * Row TILING (logical M above the largest bucket) is equally qualified as a
 * strategy and deliberately NOT implemented: one dispatch, one artifact.
 * Anything above the largest bucket declines to the current path.
 *
 * TWO buckets are served, and they are BUCKETS, not a range to interpolate
 * across. An M bucket is a separately compiled program: N6 saw `wa F6 M256`
 * fail to compile where its M64 sibling compiled, so a bucket that was never
 * built cannot be synthesised by rounding. Selection is therefore an exact
 * lookup of the smallest qualified bucket that holds the logical rows, and a
 * request between the buckets uses the larger one with zero padding -- never an
 * unbuilt M128. */
#define COLI_XDNA_LOGICAL_M_MIN 1
#define COLI_XDNA_BUCKET_M_SMALL 64
#define COLI_XDNA_BUCKET_M_LARGE 256
#define COLI_XDNA_LOGICAL_M_MAX COLI_XDNA_BUCKET_M_LARGE

/* Kept as the historical I5 names so the qualified-range vocabulary of the
 * earlier slices still resolves. _MAX was BOTH the range end and the bucket
 * when only one bucket existed; M1 split those meanings, and the name that
 * used to mean both now means only the small bucket. */
#define COLI_XDNA_I5_LOGICAL_M_MIN COLI_XDNA_LOGICAL_M_MIN
#define COLI_XDNA_I5_LOGICAL_M_MAX COLI_XDNA_BUCKET_M_SMALL

typedef enum {
    COLI_XDNA_EXEC_OK = 0,
    COLI_XDNA_EXEC_DECLINED,             /* not hard-eligible; not an error */
    COLI_XDNA_EXEC_DEVICE_INIT_FAILED,
    COLI_XDNA_EXEC_ARTIFACT_OPEN_FAILED,
    COLI_XDNA_EXEC_WEIGHT_PREPARE_FAILED,
    COLI_XDNA_EXEC_WEIGHT_WRAP_FAILED,
    COLI_XDNA_EXEC_ACTIVATION_FAILED,
    COLI_XDNA_EXEC_EXECUTE_FAILED,       /* dispatch refused or threw */
    COLI_XDNA_EXEC_COMPLETION_FAILED     /* dispatched, did not complete cleanly */
} ColiXdnaExec;

/* Lane health. The narrowest model the observed failures justify, and no retry,
 * backoff or quarantine policy beyond it.
 *
 * Most failures are SINGLE-OPERATION: a wrap, a dispatch or a completion can
 * fail without saying anything about the next operation. A device that will not
 * initialise is different -- the sealed A5 taxonomy classifies it PROCESS-scoped,
 * and re-attempting it per operation is pure cost -- so it marks the lane
 * unavailable for the remainder of the process. Loader verdicts are already
 * sticky and are reported through ColiXdnaBinding, not here. */
typedef enum {
    COLI_XDNA_LANE_UNINITIALIZED = 0,  /* nothing has been attempted yet */
    COLI_XDNA_LANE_HEALTHY,            /* usable, or at worst failed per-operation */
    COLI_XDNA_LANE_UNAVAILABLE         /* device unusable for this process */
} ColiXdnaLaneHealth;

ColiXdnaLaneHealth coli_xdna_lane_health(void);
const char *coli_xdna_lane_health_text(ColiXdnaLaneHealth h);

const char *coli_xdna_exec_text(ColiXdnaExec e);

/* The production candidate, called from the GLM shared gate/up sites and
 * nowhere else. Deliberately shaped like the existing optional-lane idiom
 * (vk_matmul_qt): returns 1 when it has fully written y, 0 when the caller must
 * run its current path.
 *
 *     if(!coli_xdna_try_matmul(...)) matmul_qt(y, x, w, S);
 *
 * It NEVER calls matmul_qt itself, so there is no recursion, no double dispatch
 * and no path on which a failure here suppresses the current path.
 *
 * `family` is passed explicitly by the call site. It is never inferred from the
 * shape: two operations with identical M/K/N are different operations, and one
 * may not inherit the other's qualification.
 *
 * `slot` is the engine-owned prepared-state handle (QT::xdna), created lazily on
 * first use. The tensor's authoritative fmt=4 bytes are read and never modified.
 *
 * y is written ONLY after the helper reports successful completion, so a failure
 * at any stage leaves the caller's output buffer untouched for matmul_qt to
 * overwrite. */
int coli_xdna_try_matmul(ColiXdnaFamily family,
                         ColiXdnaPrepared **slot,
                         int fmt, const unsigned char *q4, const float *scale,
                         int I, int O, int gs, int planar,
                         float *y, const float *x, int S);

/* Release helper-owned runtime state and the transient staging buffers. Safe
 * when nothing was ever initialised, and safe to repeat. */
void coli_xdna_execution_shutdown(void);

/* -- explicit product policy (W2-N7-P1) -----------------------------------
 *
 * The ONLY non-test way to permit this lane. It is set from an explicit user
 * request parsed by Colibri (`coli --xdna` -> COLI_XDNA=1), never from hardware
 * discovery, never from a helper, never from an economic comparison, and never
 * by default.
 *
 * "Permit" is exact. Enabling does NOT force anything onto the device: every
 * hard gate still decides, and an operation this lane was not qualified for
 * still runs the current path. The user is authorising a qualified
 * reduced-precision lane, not overriding eligibility.
 *
 * Kept separate from the test seam on purpose. The test control forces
 * execution for qualification runs; this one expresses product intent. They
 * must not be the same switch, because a test seam that could be reached from
 * a user-facing option would be a way to enable unqualified behaviour in
 * production. */
/* -- optional package provisioning (W2-N7-P1-A1) ---------------------------
 *
 * Where the qualified artifact bytes come from in a shipped build.
 *
 * V1 contract: an OPTIONAL sidecar package installed beside the executable.
 *
 *     <exe-dir>\coli_xdna.dll          the helper
 *     <exe-dir>\xdna\<registry names>  the qualified artifacts
 *
 * The artifact root is derived from the executable path exactly as the helper
 * path already is: absolute, and NOT a search. No PATH, no working directory,
 * no recursive lookup, no first-match. W1 established that a same-basename
 * module already loaded beats a later absolute-path load, and the same
 * reasoning applies to artifacts: a search order here would be unsafe and
 * unpredictable. A package that is not where we look is simply ABSENT.
 *
 * Provisioning answers "where are the qualified bytes?". It does NOT answer
 * "should XDNA run?" -- a complete, valid, hash-perfect package enables
 * nothing on its own. That remains the explicit policy above. */

/* Product-facing provisioning verdict.
 *
 * The execution path keeps its coarser hard/exec codes; this exists so the
 * DIAGNOSTIC layer can tell a user which of several very different problems
 * they have. "Your build lacks the feature", "install the optional package",
 * and "your package is corrupt" have three different fixes, and collapsing
 * them into one ARTIFACT_UNAVAILABLE line tells the user nothing actionable. */
typedef enum {
    COLI_XDNA_PROV_READY = 0,        /* every required byte present and verified */
    COLI_XDNA_PROV_NOT_REQUESTED,    /* explicit policy is off; nothing resolved */
    COLI_XDNA_PROV_PACKAGE_MISSING,  /* the artifact directory is not there */
    COLI_XDNA_PROV_PACKAGE_INCOMPLETE, /* directory present, a required file is not */
    COLI_XDNA_PROV_INTEGRITY_FAILED, /* file present, bytes are not the qualified bytes */
    COLI_XDNA_PROV_HELPER_UNAVAILABLE, /* no compatible helper beside the executable */
    COLI_XDNA_PROV_REGISTRY_INVALID  /* the compiled registry itself is unusable */
} ColiXdnaProvision;

/* Stable label, allocation-free. */
const char *coli_xdna_provision_text(ColiXdnaProvision p);

/* The absolute artifact root this build will use: <exe-dir>\xdna.
 * Returns 0 if the executable path cannot be determined. Pure resolution --
 * it touches no file and enables nothing. */
int coli_xdna_product_artifact_root(char *out, size_t cap);

/* Resolve the package and verify EVERY artifact the currently qualified
 * product lane needs, against the SHA256 values compiled into the registry.
 *
 * Verifies the whole set, not the first row: a package missing only the M256
 * artifact would otherwise look READY until a long request arrived, which is
 * exactly the class of failure that should surface at activation instead.
 *
 * `missing_name`, when non-NULL, receives a pointer to the static registry
 * filename responsible for a non-READY verdict, so a diagnostic can name it.
 * The pointer is into the compiled registry and outlives any caller. */
ColiXdnaProvision coli_xdna_provision_status(const char **missing_name);

void coli_xdna_set_explicit_enabled(int on);
int  coli_xdna_explicit_enabled(void);

/* -- the two internal execution modes -------------------------------------
 *
 * AF0 froze two conceptual modes and I6 defines both mechanically. Neither is
 * public: there is no --xdna flag and no COLI_XDNA variable, and the AUTO-like
 * mode is additionally inert unless the internal force control is set.
 *
 *   AUTO-LIKE   coli_xdna_try_matmul(). Any decline or failure returns 0 and
 *               the caller runs its current path. This is the production seam.
 *
 *   EXPLICIT    coli_xdna_test_attempt(). Returns the failure class instead of
 *               a handled flag, and implies NO fallback: a caller in this mode
 *               asked for XDNA specifically and gets a classified failure
 *               rather than a silent substitution. Deliberately a separate
 *               entry point rather than a mode flag, so no global state can
 *               leave the production seam in a no-fallback configuration.
 *
 * Both share one implementation, so their gate order and classification cannot
 * drift apart. */
ColiXdnaExec coli_xdna_test_attempt(ColiXdnaFamily family,
                                    ColiXdnaPrepared **slot,
                                    int fmt, const unsigned char *q4, const float *scale,
                                    int I, int O, int gs, int planar,
                                    float *y, const float *x, int S);

/* 1 only after an attempt reported successful completion. Any failure -- at any
 * stage, including one that occurs after the helper has already written output
 * bytes -- leaves this 0. No property of the bytes themselves (finite, non-NaN,
 * non-poison, plausible) can raise it: validity is a state, not a measurement. */
int coli_xdna_test_output_valid(void);

/* The lane's output staging buffer, so a test can observe that a failing helper
 * really did write real bytes into it before the failure was reported. Never
 * read by production code, which copies from it only after success. */
const float *coli_xdna_test_output_staging(size_t *floats);

/* Install a registry for tests; NULL restores the production table. */
void coli_xdna_test_set_registry(const ColiXdnaArtifact *rows, int count);

/* -- internal execution controls ------------------------------------------
 *
 * These are the ONLY way to reach the native path, and they are deliberately
 * test seams rather than user-facing controls: there is no --xdna flag, no
 * COLI_XDNA environment variable and no automatic policy anywhere in this
 * slice, so an ordinary build with a helper, a device and valid artifacts
 * present still runs exactly the path it runs today.
 *
 * Forcing bypasses ECONOMIC preference only -- which does not exist yet, so
 * today it bypasses nothing at all. It cannot bypass any hard gate: family,
 * format, group size, shape, bucket, artifact integrity, qualification,
 * prepared validity, alignment, helper ABI or device availability. */
void coli_xdna_test_set_force_execution(int on);
/* Where logical artifact names resolve. NULL (the default, and the only
 * production value) means no artifact is reachable and every request declines.
 * Artifact distribution is an open question this slice does not close. */
void coli_xdna_test_set_artifact_root(const char *root);

/* The last hard-eligibility verdict, for tests and diagnostics. */
ColiXdnaHard coli_xdna_test_last_hard(void);
/* The last execution verdict. */
ColiXdnaExec coli_xdna_test_last_exec(void);
int coli_xdna_test_dispatches(void);      /* successful helper executions */
int coli_xdna_test_completions(void);     /* of those, cleanly completed */
int coli_xdna_test_artifact_opens(void);
int coli_xdna_test_activation_preparations(void);
int coli_xdna_test_padded_operations(void);
int coli_xdna_test_fallbacks(void);       /* candidate returned 0 */

/* PER-BUCKET accounting.
 *
 * With one bucket, a single padded_ops total was unambiguous. With two it is
 * not: an S=200 operation padded to 256 and an S=40 operation padded to 64 are
 * both "padded" and waste 56 rows versus 24. Worse, the aggregate cannot say
 * WHICH artifact ran. Every accessor below takes the artifact M so the caller
 * names the bucket it is asking about; an unknown bucket returns 0 rather than
 * silently aggregating.
 *
 * padded_ROWS is reported as well as padded_OPS because the two answer
 * different questions: how many operations padded at all, and how much padding
 * was actually computed. Only the second scales with the waste.
 *
 * These are qualification diagnostics, not a product interface. */
int coli_xdna_test_bucket_dispatches(unsigned artifact_m);
int coli_xdna_test_bucket_completions(unsigned artifact_m);
int coli_xdna_test_bucket_padded_operations(unsigned artifact_m);
long long coli_xdna_test_bucket_padded_rows(unsigned artifact_m);
int coli_xdna_test_bucket_artifact_opens(unsigned artifact_m);
int coli_xdna_test_bucket_hard_eligible(unsigned artifact_m);
/* Logical M above the largest qualified bucket: the new first-decline class. */
int coli_xdna_test_m_above_range_declines(void);
/* Bucket transitions actually taken by the lane, counted on artifact reopen. */
int coli_xdna_test_bucket_switches(unsigned from_m, unsigned to_m);
/* The bucket the lane would select for a logical M, or 0 if none serves it.
 * Pure function of the compiled bucket set; touches no device and no registry. */
unsigned coli_xdna_test_bucket_for(int logical_m);
/* Zero every per-bucket counter. Tests measure one scenario at a time, and a
 * cumulative total silently turns "this scenario dispatched once" into "some
 * earlier scenario also dispatched". */
void coli_xdna_test_reset_bucket_counters(void);
/* Wrapper accounting. stale_rejects counts the case that made I6 necessary:
 * the same address carrying a NEW image, which must force a re-wrap rather
 * than be reused. */
int coli_xdna_test_wrapper_reuses(void);
int coli_xdna_test_wrapper_releases(void);
int coli_xdna_test_stale_wrapper_rejects(void);

/* Deterministic mid-conversion fault injection, for tests only. 0 disables it;
 * 1..99 fails after approximately that percentage of the conversion's rows.
 * Named coli_xdna_test_* like every other seam here, and never referenced by
 * production paths -- there is no environment variable or CLI flag that can
 * reach it. */
void coli_xdna_test_set_convert_fail_pct(int pct);
/* The destination regardless of state, so a test can inspect the partial bytes
 * a failed conversion left behind. Production code uses
 * coli_xdna_prepared_image(), which returns NULL unless the image is VALID. */
const void *coli_xdna_prepared_image_unchecked(const ColiXdnaPrepared *p);
/* Device opens, helper calls and userptr wraps became reachable in W2-N7-I5 and
 * are 0 only on paths that never reach the native lane. Conversions became
 * reachable in I4. */
int coli_xdna_test_device_opens(void);
int coli_xdna_test_helper_calls(void);
int coli_xdna_test_userptr_wraps(void);
int coli_xdna_test_conversions(void);

#ifdef __cplusplus
}
#endif

#endif /* COLIBRI_BACKEND_XDNA_H */