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
32.8 KB
Raw Blame
/* clef_head.h -- Clef (Cloudflare, Apache-2.0): a joint schema head over a
 * decoder's final hidden states, and the rendering of a DECIDE record into
 * that decoder's input. docs/clef.md.
 *
 * Clef is Qwen3.8-27B, post-trained, plus a small transformer that reads the
 * backbone's last hidden states and scores every option of every question in
 * one pass. The specification is the checkpoint's own joint_schema_model.py;
 * each step below names the function it follows:
 *
 *   rendering    encode_record        clef_render(): the chat-shaped prompt,
 *                                     the state, then one FIELD per question
 *                                     with its options as JSON; every piece
 *                                     tokenized on its own, the state cut from
 *                                     the end to fit max_length
 *   head         JointSchemaHead      clef_head_forward(): LayerNorm over the
 *                                     hidden states, span means for questions
 *                                     and options, lexical option vectors from
 *                                     the LM head's rows, two evidence routing
 *                                     layers, four decoder layers over the
 *                                     fields, the prior + gated joint score
 *   answer       systemone            a softmax per question, nothing fitted
 *                                     on top (Clef ships no temperature)
 *
 * The engine owns the backbone: it renders with clef_render() through its own
 * tokenizer, runs the prompt, hands the final-normed hidden state of every
 * position to clef_head_forward(), and reads the logits back in the record's
 * option order. Everything here is f32; the reference runs in bf16.
 *
 * Needs decide_serve.h (the record) and matmul_f32.h (the one GEMM). */
#ifndef COLI_CLEF_HEAD_H
#define COLI_CLEF_HEAD_H

#include <math.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "decide_serve.h"
#include "matmul_f32.h"

/* encode_record(max_length=16384), the default systemone() calls it with */
#define CLEF_MAX_LENGTH 16384

/* joint_schema_model.SYSTEM_PROMPT and the fixed pieces of encode_record */
#define CLEF_SYSTEM_PROMPT "Read the complete state and schema. Decide every field jointly. " \
                           "Each answer must be exactly one of that field's allowed options."
#define CLEF_PREFIX "<|im_start|>system\n" CLEF_SYSTEM_PROMPT "<|im_end|>\n<|im_start|>user\nSTATE:\n"
#define CLEF_SUFFIX "\n<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\nJOINT SCHEMA DECISIONS:"
#define CLEF_NOUL_TRUE  "The proposition is true or the answer is yes."
#define CLEF_NOUL_FALSE "The proposition is false or the answer is no."

/* joint_schema_model.QUESTION_TYPES */
enum { CLEF_NOUL = 0, CLEF_CHOICE = 1, CLEF_SCORE = 2 };

/* ------------------------------------------------------------ rendering */

/* text -> token ids, the engine's tokenizer (added tokens matched, as
 * tokenizer(text, add_special_tokens=False) does). Returns 0 on failure. */
typedef int (*ClefEncodeFn)(void *ctx, const char *text, int **ids, int *count);

typedef struct {
    int type;            /* CLEF_NOUL | CLEF_CHOICE | CLEF_SCORE */
    int qs, qe;          /* the instruction's tokens, [qs, qe) */
    int n;               /* options */
    int *os, *oe;        /* each option's JSON, [os, oe), in the reference's order */
    int *record_index;   /* reference option k is the record's option record_index[k] */
} ClefQuestion;

typedef struct {
    int *ids, n;                     /* the model input */
    ClefQuestion *q; int n_q;        /* in the record's (= the request's) order */
    int state_tokens, state_used;    /* the state's tokens before and after the cut */
} ClefInput;

static void clef_input_free(ClefInput *in)
{
    if (!in) return;
    for (int i = 0; i < in->n_q; i++) {
        free(in->q[i].os); free(in->q[i].oe); free(in->q[i].record_index);
    }
    free(in->q); free(in->ids);
    memset(in, 0, sizeof(*in));
}

typedef struct { int *v; int n, cap, failed; } ClefIds;

static void clef_ids_push(ClefIds *a, const int *v, int n)
{
    if (a->failed || n <= 0) return;
    if (a->n + n > a->cap) {
        int cap = a->cap ? a->cap : 256;
        while (cap < a->n + n) cap *= 2;
        int *grown = (int *)realloc(a->v, (size_t)cap * sizeof(int));
        if (!grown) { a->failed = 1; return; }
        a->v = grown; a->cap = cap;
    }
    memcpy(a->v + a->n, v, (size_t)n * sizeof(int));
    a->n += n;
}

/* _tokens(tokenizer, text): one piece, tokenized on its own and appended */
static int clef_tokens(ClefIds *out, ClefEncodeFn encode, void *ctx, const char *text)
{
    int *ids = NULL, n = 0;
    if (!encode(ctx, text, &ids, &n)) return 0;
    clef_ids_push(out, ids, n);
    free(ids);
    return !out->failed;
}

/* json.dumps(text, ensure_ascii=False) of a string: Python's escapes (\" \\ \b
 * \f \n \r \t, \u00XX for the other control characters, lowercase hex),
 * everything else as it is. */
static void clef_json_string(DecideBuf *b, const char *text)
{
    decide_buf_put(b, "\"", 1);
    for (const unsigned char *p = (const unsigned char *)text; *p; p++) {
        const char *esc = NULL;
        switch (*p) {
        case '"': esc = "\\\""; break;
        case '\\': esc = "\\\\"; break;
        case '\b': esc = "\\b"; break;
        case '\f': esc = "\\f"; break;
        case '\n': esc = "\\n"; break;
        case '\r': esc = "\\r"; break;
        case '\t': esc = "\\t"; break;
        default: break;
        }
        if (esc) decide_buf_put(b, esc, 2);
        else if (*p < 0x20) decide_buf_printf(b, "\\u%04x", *p);
        else decide_buf_put(b, (const char *)p, 1);
    }
    decide_buf_put(b, "\"", 1);
}

/* render({"option_id": id, "description": description}): sort_keys puts the
 * description first; a description of None is left out. */
static char *clef_option_json(const DecideQuestion *q, const DecideOption *o)
{
    DecideBuf b = {0};
    const char *text = o->text;
    int is_json = o->text_json;
    if (q->type == DECIDE_NOUL && !o->has_text) {
        /* question_options(): the defaults, updated by what the caller gave */
        text = !strcmp(o->label, "true") ? CLEF_NOUL_TRUE : CLEF_NOUL_FALSE;
        is_json = 0;
    }
    decide_buf_put(&b, "{", 1);
    if (text) {
        decide_buf_put(&b, "\"description\":", 14);
        if (is_json) decide_buf_put(&b, text, strlen(text));
        else clef_json_string(&b, text);
        decide_buf_put(&b, ",", 1);
    }
    decide_buf_put(&b, "\"option_id\":", 12);
    clef_json_string(&b, o->label);
    decide_buf_put(&b, "}", 1);
    if (b.failed) { free(b.data); return NULL; }
    return b.data;
}

static int clef_cmp_labels(const void *a, const void *b, void *labels)
{
    const DecideOption *o = (const DecideOption *)labels;
    return strcmp(o[*(const int *)a].label, o[*(const int *)b].label);
}

/* A small insertion sort with a context: qsort_r is not portable, and a
 * question has at most 255 options. sorted() on str compares code points,
 * which strcmp on UTF-8 does too. */
static void clef_sort_options(int *order, int n, const DecideOption *options)
{
    for (int i = 1; i < n; i++) {
        int v = order[i], j = i - 1;
        while (j >= 0 && clef_cmp_labels(&order[j], &v, (void *)options) > 0) { order[j + 1] = order[j]; j--; }
        order[j + 1] = v;
    }
}

/* encode_record(tokenizer, record, max_length): the record must be in the raw
 * form (the caller's own values; decide_serve.h). Returns 1, or 0 with `err`
 * starting with the field ("questions: ...") when the record does not fit. */
static int clef_render(const DecideRecord *rec, ClefEncodeFn encode, void *ctx, int max_length,
                       ClefInput *out, char *err, size_t cap)
{
    memset(out, 0, sizeof(*out));
    if (!rec->raw)
        return decide_fail(err, cap, "record: Clef reads the raw form (CAPS decide_record=raw), "
                                     "this one is the default form");
    ClefIds schema = {0}, prefix = {0}, state = {0}, suffix = {0};
    out->q = (ClefQuestion *)calloc((size_t)rec->n_questions, sizeof(ClefQuestion));
    if (!out->q) return decide_fail(err, cap, "out of memory");
    out->n_q = rec->n_questions;
    int ok = clef_tokens(&schema, encode, ctx, "\n\nSCHEMA FIELDS:\n");
    char line[64];
    for (int i = 0; ok && i < rec->n_questions; i++) {
        const DecideQuestion *q = &rec->questions[i];
        ClefQuestion *cq = &out->q[i];
        cq->type = q->type == DECIDE_NOUL ? CLEF_NOUL : q->type == DECIDE_CHOICE ? CLEF_CHOICE : CLEF_SCORE;
        DecideBuf head = {0};
        decide_buf_printf(&head, "\nFIELD %d\nID: ", i + 1);
        decide_buf_put(&head, q->id, strlen(q->id));
        decide_buf_printf(&head, "\nTYPE: %s\nINSTRUCTION: ", decide_type_name(q->type));
        ok = !head.failed && clef_tokens(&schema, encode, ctx, head.data);
        free(head.data);
        if (!ok) break;
        cq->qs = schema.n;
        /* instructions None or "": the question id */
        ok = clef_tokens(&schema, encode, ctx,
                         q->has_instructions && q->instructions[0] ? q->instructions : q->id);
        cq->qe = schema.n;
        ok = ok && clef_tokens(&schema, encode, ctx, "\nALLOWED OPTIONS:\n");
        if (!ok) break;
        cq->n = q->n_options;
        cq->os = (int *)calloc((size_t)cq->n, sizeof(int));
        cq->oe = (int *)calloc((size_t)cq->n, sizeof(int));
        cq->record_index = (int *)calloc((size_t)cq->n, sizeof(int));
        if (!cq->os || !cq->oe || !cq->record_index) { ok = 0; break; }
        /* question_options(): noul true then false (the record has false, true),
         * choice sorted by label, score in level order */
        for (int k = 0; k < cq->n; k++) cq->record_index[k] = k;
        if (q->type == DECIDE_NOUL) { cq->record_index[0] = 1; cq->record_index[1] = 0; }
        else if (q->type == DECIDE_CHOICE) clef_sort_options(cq->record_index, cq->n, q->options);
        for (int k = 0; ok && k < cq->n; k++) {
            snprintf(line, sizeof(line), "OPTION %d: ", k + 1);
            ok = clef_tokens(&schema, encode, ctx, line);
            char *json = ok ? clef_option_json(q, &q->options[cq->record_index[k]]) : NULL;
            cq->os[k] = schema.n;
            ok = json && clef_tokens(&schema, encode, ctx, json);
            cq->oe[k] = schema.n;
            free(json);
            ok = ok && clef_tokens(&schema, encode, ctx, "\n");
            if (ok && cq->oe[k] <= cq->os[k]) ok = 0;
        }
        ok = ok && clef_tokens(&schema, encode, ctx, "END FIELD\n");
        if (ok && cq->qe <= cq->qs) ok = 0;
    }
    ok = ok && clef_tokens(&prefix, encode, ctx, CLEF_PREFIX) &&
         clef_tokens(&suffix, encode, ctx, CLEF_SUFFIX) &&
         clef_tokens(&state, encode, ctx, rec->state);
    if (!ok) {
        free(schema.v); free(prefix.v); free(state.v); free(suffix.v);
        clef_input_free(out);
        return decide_fail(err, cap, "the record could not be tokenized");
    }
    int fixed = prefix.n + schema.n + suffix.n;
    if (fixed > max_length) {
        free(schema.v); free(prefix.v); free(state.v); free(suffix.v);
        clef_input_free(out);
        return decide_fail(err, cap, "questions: the schema requires %d tokens before the state; "
                                     "the maximum is %d", fixed, max_length);
    }
    out->state_tokens = state.n;
    out->state_used = state.n < max_length - fixed ? state.n : max_length - fixed;
    int offset = prefix.n + out->state_used;
    ClefIds all = {0};
    clef_ids_push(&all, prefix.v, prefix.n);
    clef_ids_push(&all, state.v, out->state_used);
    clef_ids_push(&all, schema.v, schema.n);
    clef_ids_push(&all, suffix.v, suffix.n);
    free(schema.v); free(prefix.v); free(state.v); free(suffix.v);
    if (all.failed) { free(all.v); clef_input_free(out); return decide_fail(err, cap, "out of memory"); }
    for (int i = 0; i < out->n_q; i++) {
        ClefQuestion *cq = &out->q[i];
        cq->qs += offset; cq->qe += offset;
        for (int k = 0; k < cq->n; k++) { cq->os[k] += offset; cq->oe[k] += offset; }
    }
    out->ids = all.v;
    out->n = all.n;
    return 1;
}

/* ---------------------------------------------------------------- the head */

typedef struct { float *w, *b; } ClefNorm;                 /* nn.LayerNorm, eps 1e-5 */
typedef struct { float *in_w, *in_b, *out_w, *out_b; } ClefAttn;   /* nn.MultiheadAttention */

typedef struct {               /* EvidenceRoutingLayer */
    ClefNorm query_norm, memory_norm, ff_norm;
    ClefAttn attn;
    float *ff1_w, *ff1_b, *ff2_w, *ff2_b;
} ClefRoute;

typedef struct {               /* nn.TransformerDecoderLayer(norm_first=True, gelu) */
    ClefAttn self_attn, cross_attn;
    ClefNorm norm1, norm2, norm3;
    float *ff1_w, *ff1_b, *ff2_w, *ff2_b;
} ClefDecoder;

typedef struct {
    int hidden, width, routing_layers, layers, heads, feedforward;
    ClefNorm hidden_norm;
    float *memory_proj, *question_proj, *option_question_proj, *global_proj;
    float *option_context_proj, *option_lexical_proj;      /* [width, hidden] */
    float *type_embedding;                                  /* [3, width] */
    ClefRoute *route;
    ClefNorm option_summary_norm, field_norm, option_norm;
    ClefDecoder *dec;
    float *score1_w, *score1_b, *score2_w, *score2_b;       /* [width, 4 width], [1, width] */
    float prior_logit_scale, joint_logit_scale, residual_gate;
} ClefHead;

/* A tensor of the head as f32, `numel` elements, or NULL when it is missing or
 * the wrong size (the caller refuses the checkpoint). */
typedef float *(*ClefLoadFn)(void *ctx, const char *name, int64_t numel);

typedef struct { void *ctx; ClefLoadFn load; int missing; char first[160]; } ClefLoader;

static float *clef_take(ClefLoader *l, const char *name, int64_t numel)
{
    float *p = l->load(l->ctx, name, numel);
    if (!p && !l->missing++) snprintf(l->first, sizeof(l->first), "%s", name);
    return p;
}

static void clef_take_norm(ClefLoader *l, ClefNorm *n, const char *stem, int d)
{
    char name[160];
    snprintf(name, sizeof(name), "%s.weight", stem); n->w = clef_take(l, name, d);
    snprintf(name, sizeof(name), "%s.bias", stem);   n->b = clef_take(l, name, d);
}

static void clef_take_attn(ClefLoader *l, ClefAttn *a, const char *stem, int d)
{
    char name[160];
    snprintf(name, sizeof(name), "%s.in_proj_weight", stem);  a->in_w = clef_take(l, name, (int64_t)3 * d * d);
    snprintf(name, sizeof(name), "%s.in_proj_bias", stem);    a->in_b = clef_take(l, name, (int64_t)3 * d);
    snprintf(name, sizeof(name), "%s.out_proj.weight", stem); a->out_w = clef_take(l, name, (int64_t)d * d);
    snprintf(name, sizeof(name), "%s.out_proj.bias", stem);   a->out_b = clef_take(l, name, d);
}

/* Every tensor of JointSchemaHead's state dict, sized from joint_head_config.json.
 * Returns 1, or 0 with the first missing or misshapen tensor in `err`. */
static int clef_head_load(ClefHead *h, void *ctx, ClefLoadFn load, char *err, size_t cap)
{
    ClefLoader l = {ctx, load, 0, ""};
    const int H = h->hidden, W = h->width, F = h->feedforward;
    char stem[96];
    clef_take_norm(&l, &h->hidden_norm, "hidden_norm", H);
    h->memory_proj = clef_take(&l, "memory_projection.weight", (int64_t)W * H);
    h->question_proj = clef_take(&l, "question_projection.weight", (int64_t)W * H);
    h->option_question_proj = clef_take(&l, "option_question_projection.weight", (int64_t)W * H);
    h->global_proj = clef_take(&l, "global_projection.weight", (int64_t)W * H);
    h->option_context_proj = clef_take(&l, "option_context_projection.weight", (int64_t)W * H);
    h->option_lexical_proj = clef_take(&l, "option_lexical_projection.weight", (int64_t)W * H);
    h->type_embedding = clef_take(&l, "type_embedding.weight", (int64_t)3 * W);
    h->route = (ClefRoute *)calloc((size_t)h->routing_layers, sizeof(ClefRoute));
    h->dec = (ClefDecoder *)calloc((size_t)h->layers, sizeof(ClefDecoder));
    if (!h->route || !h->dec) { snprintf(err, cap, "out of memory"); return 0; }
    for (int i = 0; i < h->routing_layers; i++) {
        ClefRoute *r = &h->route[i];
        char name[160];
        snprintf(stem, sizeof(stem), "evidence_layers.%d.query_norm", i);        clef_take_norm(&l, &r->query_norm, stem, W);
        snprintf(stem, sizeof(stem), "evidence_layers.%d.memory_norm", i);       clef_take_norm(&l, &r->memory_norm, stem, W);
        snprintf(stem, sizeof(stem), "evidence_layers.%d.feedforward_norm", i);  clef_take_norm(&l, &r->ff_norm, stem, W);
        snprintf(stem, sizeof(stem), "evidence_layers.%d.attention", i);         clef_take_attn(&l, &r->attn, stem, W);
        snprintf(name, sizeof(name), "evidence_layers.%d.feedforward.0.weight", i); r->ff1_w = clef_take(&l, name, (int64_t)F * W);
        snprintf(name, sizeof(name), "evidence_layers.%d.feedforward.0.bias", i);   r->ff1_b = clef_take(&l, name, F);
        snprintf(name, sizeof(name), "evidence_layers.%d.feedforward.3.weight", i); r->ff2_w = clef_take(&l, name, (int64_t)W * F);
        snprintf(name, sizeof(name), "evidence_layers.%d.feedforward.3.bias", i);   r->ff2_b = clef_take(&l, name, W);
    }
    clef_take_norm(&l, &h->option_summary_norm, "option_summary_norm", W);
    for (int i = 0; i < h->layers; i++) {
        ClefDecoder *d = &h->dec[i];
        char name[160];
        snprintf(stem, sizeof(stem), "layers.%d.self_attn", i);      clef_take_attn(&l, &d->self_attn, stem, W);
        snprintf(stem, sizeof(stem), "layers.%d.multihead_attn", i); clef_take_attn(&l, &d->cross_attn, stem, W);
        snprintf(stem, sizeof(stem), "layers.%d.norm1", i);          clef_take_norm(&l, &d->norm1, stem, W);
        snprintf(stem, sizeof(stem), "layers.%d.norm2", i);          clef_take_norm(&l, &d->norm2, stem, W);
        snprintf(stem, sizeof(stem), "layers.%d.norm3", i);          clef_take_norm(&l, &d->norm3, stem, W);
        snprintf(name, sizeof(name), "layers.%d.linear1.weight", i); d->ff1_w = clef_take(&l, name, (int64_t)F * W);
        snprintf(name, sizeof(name), "layers.%d.linear1.bias", i);   d->ff1_b = clef_take(&l, name, F);
        snprintf(name, sizeof(name), "layers.%d.linear2.weight", i); d->ff2_w = clef_take(&l, name, (int64_t)W * F);
        snprintf(name, sizeof(name), "layers.%d.linear2.bias", i);   d->ff2_b = clef_take(&l, name, W);
    }
    clef_take_norm(&l, &h->field_norm, "field_norm", W);
    clef_take_norm(&l, &h->option_norm, "option_norm", W);
    h->score1_w = clef_take(&l, "residual_scorer.0.weight", (int64_t)W * 4 * W);
    h->score1_b = clef_take(&l, "residual_scorer.0.bias", W);
    h->score2_w = clef_take(&l, "residual_scorer.3.weight", W);
    h->score2_b = clef_take(&l, "residual_scorer.3.bias", 1);
    float *scalar;
    if ((scalar = clef_take(&l, "prior_logit_scale", 1))) { h->prior_logit_scale = *scalar; free(scalar); }
    if ((scalar = clef_take(&l, "joint_logit_scale", 1))) { h->joint_logit_scale = *scalar; free(scalar); }
    if ((scalar = clef_take(&l, "residual_gate", 1))) { h->residual_gate = *scalar; free(scalar); }
    if (l.missing) {
        snprintf(err, cap, "%d head tensor(s) missing or of the wrong size, the first %s", l.missing, l.first);
        return 0;
    }
    return 1;
}

/* ---- the pieces of the forward ---- */

static void clef_layernorm(float *out, const float *x, const ClefNorm *n, int rows, int d)
{
    #pragma omp parallel for schedule(static)
    for (int r = 0; r < rows; r++) {
        const float *v = x + (int64_t)r * d;
        float *o = out + (int64_t)r * d;
        double mean = 0, var = 0;
        for (int i = 0; i < d; i++) mean += v[i];
        mean /= d;
        for (int i = 0; i < d; i++) { double c = v[i] - mean; var += c * c; }
        var /= d;
        float inv = (float)(1.0 / sqrt(var + 1e-5));
        for (int i = 0; i < d; i++) o[i] = (float)((v[i] - mean) * inv) * n->w[i] + n->b[i];
    }
}

static void clef_add_bias(float *y, const float *b, int rows, int d)
{
    for (int r = 0; r < rows; r++) for (int i = 0; i < d; i++) y[(int64_t)r * d + i] += b[i];
}

/* nn.GELU() and activation="gelu": the exact erf form */
static float clef_gelu(float x) { return 0.5f * x * (1.0f + erff(x * 0.70710678118654752f)); }

/* y[rows, out] = x @ W^T + b */
static void clef_linear(float *y, const float *x, const float *w, const float *b, int rows, int in, int out)
{
    matmul(y, x, w, rows, in, out);
    if (b) clef_add_bias(y, b, rows, out);
}

/* nn.MultiheadAttention(batch_first) without a mask: out[nq, d] */
static int clef_attention(const ClefAttn *a, const float *q_in, int nq, const float *kv_in, int nk,
                          int d, int heads, float *out)
{
    float *Q = (float *)malloc((size_t)nq * d * sizeof(float));
    float *K = (float *)malloc((size_t)nk * d * sizeof(float));
    float *V = (float *)malloc((size_t)nk * d * sizeof(float));
    float *C = (float *)malloc((size_t)nq * d * sizeof(float));
    int hd = d / heads, ok = Q && K && V && C;
    if (ok) {
        clef_linear(Q, q_in, a->in_w, a->in_b, nq, d, d);
        clef_linear(K, kv_in, a->in_w + (int64_t)d * d, a->in_b + d, nk, d, d);
        clef_linear(V, kv_in, a->in_w + (int64_t)2 * d * d, a->in_b + 2 * d, nk, d, d);
        const float scale = 1.0f / sqrtf((float)hd);
        #pragma omp parallel
        {
            float *p = (float *)malloc((size_t)nk * sizeof(float));
            #pragma omp for schedule(dynamic, 1)
            for (int t = 0; t < nq * heads; t++) {
                int i = t / heads, h = t % heads;
                float *c = C + (int64_t)i * d + h * hd;
                if (!p) { for (int j = 0; j < hd; j++) c[j] = NAN; continue; }
                const float *qv = Q + (int64_t)i * d + h * hd;
                float mx = -INFINITY;
                for (int k = 0; k < nk; k++) {
                    p[k] = dot_f32_lanes(qv, K + (int64_t)k * d + h * hd, hd) * scale;
                    if (p[k] > mx) mx = p[k];
                }
                double sum = 0;
                for (int k = 0; k < nk; k++) { p[k] = expf(p[k] - mx); sum += p[k]; }
                float inv = (float)(1.0 / sum);
                for (int j = 0; j < hd; j++) c[j] = 0.f;
                for (int k = 0; k < nk; k++) {
                    float w = p[k] * inv;
                    const float *vv = V + (int64_t)k * d + h * hd;
                    for (int j = 0; j < hd; j++) c[j] += w * vv[j];
                }
            }
            free(p);
        }
        clef_linear(out, C, a->out_w, a->out_b, nq, d, d);
    }
    free(Q); free(K); free(V); free(C);
    return ok;
}

/* x += linear2(gelu(linear1(norm(x)))) */
static int clef_feedforward(float *x, const ClefNorm *norm, const float *w1, const float *b1,
                            const float *w2, const float *b2, int rows, int d, int f)
{
    float *n = (float *)malloc((size_t)rows * d * sizeof(float));
    float *u = (float *)malloc((size_t)rows * f * sizeof(float));
    float *y = (float *)malloc((size_t)rows * d * sizeof(float));
    int ok = n && u && y;
    if (ok) {
        clef_layernorm(n, x, norm, rows, d);
        clef_linear(u, n, w1, b1, rows, d, f);
        for (int64_t i = 0; i < (int64_t)rows * f; i++) u[i] = clef_gelu(u[i]);
        clef_linear(y, u, w2, b2, rows, f, d);
        for (int64_t i = 0; i < (int64_t)rows * d; i++) x[i] += y[i];
    }
    free(n); free(u); free(y);
    return ok;
}

static double clef_norm2(const float *v, int n)
{
    double s = 0;
    for (int i = 0; i < n; i++) s += (double)v[i] * v[i];
    return sqrt(s);
}

/* The LM head's row for a token id (the lexical option vectors read the output
 * embedding, not the input one), f32, `hidden` wide. Returns 0 on failure. */
typedef int (*ClefRowFn)(void *ctx, int id, float *out);

/* JointSchemaHead.forward for one record. `hidden` holds the final-normed
 * hidden state of every position, [n, H]; it is overwritten (hidden_norm runs
 * in place). `logits[q]` receives in->q[q].n values in the REFERENCE's option
 * order. Returns 1, or 0 with `err` set. */
static int clef_head_forward(const ClefHead *h, float *hidden, const ClefInput *in,
                             ClefRowFn lm_row, void *row_ctx, double **logits, char *err, size_t cap)
{
    const int H = h->hidden, W = h->width, F = h->feedforward, L = in->n, Q = in->n_q;
    int N = 0;
    for (int q = 0; q < Q; q++) N += in->q[q].n;
    float *memory = (float *)malloc((size_t)L * W * sizeof(float));
    float *qv = (float *)calloc((size_t)Q * H, sizeof(float));      /* question_vectors */
    float *ctxv = (float *)calloc((size_t)N * H, sizeof(float));    /* option context means */
    float *lex = (float *)calloc((size_t)N * H, sizeof(float));     /* lexical option means */
    float *row = (float *)malloc((size_t)H * sizeof(float));
    float *routed = (float *)malloc((size_t)N * W * sizeof(float));
    float *tmp = (float *)malloc((size_t)(N > Q ? N : Q) * W * sizeof(float));
    float *tmp2 = (float *)malloc((size_t)(N > Q ? N : Q) * W * sizeof(float));
    float *mnorm = (float *)malloc((size_t)L * W * sizeof(float));
    float *fields = (float *)malloc((size_t)Q * W * sizeof(float));
    float *base = (float *)malloc((size_t)Q * W * sizeof(float));
    float *summary = (float *)calloc((size_t)Q * W, sizeof(float));
    float *feat = (float *)malloc((size_t)4 * W * sizeof(float));
    float *hid = (float *)malloc((size_t)W * sizeof(float));
    int ok = memory && qv && ctxv && lex && row && routed && tmp && tmp2 && mnorm && fields &&
             base && summary && feat && hid;
    if (!ok) { snprintf(err, cap, "out of memory in the decision head"); goto done; }

    /* normalized_hidden = hidden_norm(hidden_states); memory = memory_projection(...) */
    clef_layernorm(hidden, hidden, &h->hidden_norm, L, H);
    matmul(memory, hidden, h->memory_proj, L, H, W);
    const float *global = hidden + (int64_t)(L - 1) * H;

    /* _mean_span for the questions and the options; the lexical vectors are the
     * mean of the LM head's rows at the option's tokens */
    for (int q = 0, o = 0; q < Q; q++) {
        const ClefQuestion *cq = &in->q[q];
        for (int t = cq->qs; t < cq->qe; t++)
            for (int i = 0; i < H; i++) qv[(int64_t)q * H + i] += hidden[(int64_t)t * H + i];
        for (int i = 0; i < H; i++) qv[(int64_t)q * H + i] /= (float)(cq->qe - cq->qs);
        for (int k = 0; k < cq->n; k++, o++) {
            float *c = ctxv + (int64_t)o * H, *x = lex + (int64_t)o * H;
            for (int t = cq->os[k]; t < cq->oe[k]; t++) {
                for (int i = 0; i < H; i++) c[i] += hidden[(int64_t)t * H + i];
                if (!lm_row(row_ctx, in->ids[t], row)) {
                    ok = 0; snprintf(err, cap, "cannot read the LM head's row %d", in->ids[t]); goto done;
                }
                for (int i = 0; i < H; i++) x[i] += row[i];
            }
            float count = (float)(cq->oe[k] - cq->os[k]);
            for (int i = 0; i < H; i++) { c[i] /= count; x[i] /= count; }
        }
    }

    /* option queries: context + lexical + the question's own vector */
    matmul(routed, ctxv, h->option_context_proj, N, H, W);
    matmul(tmp, lex, h->option_lexical_proj, N, H, W);
    for (int64_t i = 0; i < (int64_t)N * W; i++) routed[i] += tmp[i];
    matmul(base, qv, h->option_question_proj, Q, H, W);
    for (int q = 0, o = 0; q < Q; q++)
        for (int k = 0; k < in->q[q].n; k++, o++)
            for (int i = 0; i < W; i++) routed[(int64_t)o * W + i] += base[(int64_t)q * W + i];

    /* EvidenceRoutingLayer x routing_layers: the options read the whole sequence */
    for (int r = 0; r < h->routing_layers && ok; r++) {
        const ClefRoute *rl = &h->route[r];
        clef_layernorm(tmp, routed, &rl->query_norm, N, W);
        clef_layernorm(mnorm, memory, &rl->memory_norm, L, W);
        ok = clef_attention(&rl->attn, tmp, N, mnorm, L, W, h->heads, tmp2);
        for (int64_t i = 0; ok && i < (int64_t)N * W; i++) routed[i] += tmp2[i];
        ok = ok && clef_feedforward(routed, &rl->ff_norm, rl->ff1_w, rl->ff1_b, rl->ff2_w, rl->ff2_b, N, W, F);
    }
    if (!ok) { snprintf(err, cap, "out of memory in the decision head"); goto done; }

    /* fields: the question, a softmax-weighted summary of its options, the last
     * position, the question type */
    matmul(base, qv, h->question_proj, Q, H, W);
    for (int q = 0, o = 0; q < Q; q++) {
        const ClefQuestion *cq = &in->q[q];
        const float *field = base + (int64_t)q * W;
        double mx = -INFINITY, sum = 0;
        double *w = (double *)malloc((size_t)cq->n * sizeof(double));
        if (!w) { ok = 0; snprintf(err, cap, "out of memory in the decision head"); goto done; }
        for (int k = 0; k < cq->n; k++) {
            w[k] = dot_f32_lanes(routed + (int64_t)(o + k) * W, field, W) / sqrt((double)W);
            if (w[k] > mx) mx = w[k];
        }
        for (int k = 0; k < cq->n; k++) { w[k] = exp(w[k] - mx); sum += w[k]; }
        for (int k = 0; k < cq->n; k++) {
            float wk = (float)(w[k] / sum);
            for (int i = 0; i < W; i++) summary[(int64_t)q * W + i] += wk * routed[(int64_t)(o + k) * W + i];
        }
        free(w);
        o += cq->n;
    }
    clef_layernorm(fields, summary, &h->option_summary_norm, Q, W);
    matmul(hid, global, h->global_proj, 1, H, W);
    for (int q = 0; q < Q; q++)
        for (int i = 0; i < W; i++)
            fields[(int64_t)q * W + i] += base[(int64_t)q * W + i] + hid[i] +
                                          h->type_embedding[(int64_t)in->q[q].type * W + i];

    /* TransformerDecoderLayer x layers (norm_first): self-attention over the
     * fields, cross-attention into the (unnormalized) memory, feed-forward */
    for (int l = 0; l < h->layers && ok; l++) {
        const ClefDecoder *d = &h->dec[l];
        clef_layernorm(tmp, fields, &d->norm1, Q, W);
        ok = clef_attention(&d->self_attn, tmp, Q, tmp, Q, W, h->heads, tmp2);
        for (int64_t i = 0; ok && i < (int64_t)Q * W; i++) fields[i] += tmp2[i];
        if (ok) clef_layernorm(tmp, fields, &d->norm2, Q, W);
        ok = ok && clef_attention(&d->cross_attn, tmp, Q, memory, L, W, h->heads, tmp2);
        for (int64_t i = 0; ok && i < (int64_t)Q * W; i++) fields[i] += tmp2[i];
        ok = ok && clef_feedforward(fields, &d->norm3, d->ff1_w, d->ff1_b, d->ff2_w, d->ff2_b, Q, W, F);
    }
    if (!ok) { snprintf(err, cap, "out of memory in the decision head"); goto done; }
    clef_layernorm(fields, fields, &h->field_norm, Q, W);
    clef_layernorm(routed, routed, &h->option_norm, N, W);     /* options = option_norm(routed) */

    /* the score: prior (lexical vs question + last position) + gated joint
     * (scaled cosine + the residual scorer) */
    const double prior_scale = exp(fmin((double)h->prior_logit_scale, log(100.0)));
    const double joint_scale = exp(fmin((double)h->joint_logit_scale, log(100.0)));
    const double gate = 1.0 / (1.0 + exp(-(double)h->residual_gate));
    for (int q = 0, o = 0; q < Q; q++) {
        const ClefQuestion *cq = &in->q[q];
        const float *field = fields + (int64_t)q * W;
        for (int i = 0; i < H; i++) row[i] = qv[(int64_t)q * H + i] + global[i];
        double anchor_norm = fmax(clef_norm2(row, H), 1e-12);
        double field_norm = fmax(clef_norm2(field, W), 1e-8);
        for (int k = 0; k < cq->n; k++, o++) {
            const float *x = lex + (int64_t)o * H, *opt = routed + (int64_t)o * W;
            double lex_norm = fmax(clef_norm2(x, H), 1e-12), dot = 0;
            for (int i = 0; i < H; i++) dot += (double)x[i] * row[i];
            double prior = prior_scale * dot / (lex_norm * anchor_norm);
            double opt_norm = fmax(clef_norm2(opt, W), 1e-8), fo = 0;
            for (int i = 0; i < W; i++) fo += (double)field[i] * opt[i];
            double cosine = fo / (field_norm * opt_norm);
            for (int i = 0; i < W; i++) {
                feat[i] = field[i];
                feat[W + i] = opt[i];
                feat[2 * W + i] = field[i] * opt[i];
                feat[3 * W + i] = fabsf(field[i] - opt[i]);
            }
            clef_linear(hid, feat, h->score1_w, h->score1_b, 1, 4 * W, W);
            double residual = h->score2_b[0];
            for (int i = 0; i < W; i++) residual += (double)clef_gelu(hid[i]) * h->score2_w[i];
            logits[q][k] = prior + gate * (joint_scale * cosine + residual);
        }
    }
done:
    free(memory); free(qv); free(ctxv); free(lex); free(row); free(routed); free(tmp); free(tmp2);
    free(mnorm); free(fields); free(base); free(summary); free(feat); free(hid);
    return ok;
}

/* A question's answer from its logits (reference order): softmax, then both
 * back in the record's option order. */
static int clef_answer(const ClefQuestion *cq, const double *logits, DecideAnswer *a)
{
    a->n = cq->n;
    a->logits = (double *)calloc((size_t)cq->n, sizeof(double));
    a->probs = (double *)calloc((size_t)cq->n, sizeof(double));
    if (!a->logits || !a->probs) return 0;
    double mx = -INFINITY, sum = 0;
    for (int k = 0; k < cq->n; k++) if (logits[k] > mx) mx = logits[k];
    for (int k = 0; k < cq->n; k++) sum += exp(logits[k] - mx);
    for (int k = 0; k < cq->n; k++) {
        a->logits[cq->record_index[k]] = logits[k];
        a->probs[cq->record_index[k]] = exp(logits[k] - mx) / sum;
    }
    a->temperature = NAN;            /* the head's logits are the answer: no calibration */
    return 1;
}

#endif