Function trace_cursor_decode

src/mcp/mcp.c:6163–6197

Decode + validate. Returns NULL on success, else a static teaching error. */

/* Decode + validate. Returns NULL on success, else a static teaching error. */
static const char *trace_cursor_decode(const char *token, const char *current_generation,
                                       uint64_t expected_qhash, trace_cursor_t *out) {
    memset(out, 0, sizeof(*out));
    if (!token || strncmp(token, "c1.", 3) != 0) {
        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
    }
    const char *p = token + 3;
    if (*p != 'o' && *p != 'i') {
        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
    }
    out->leg = *p;
    p += 2; /* leg + '.' */
    const char *gen_end = strchr(p, '.');
    if (!gen_end || (size_t)(gen_end - p) >= sizeof(out->generation)) {
        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
    }
    memcpy(out->generation, p, (size_t)(gen_end - p));
    out->generation[gen_end - p] = '\0';
    unsigned long long qh = 0;
    long long nid = 0;
    if (sscanf(gen_end + 1, "%16llx.%d.%lld", &qh, &out->hop, &nid) != 3) {
        return "invalid_cursor: unrecognized token — re-run the original query without 'cursor'";
    }
    out->qhash = qh;
    out->node_id = nid;
    if (out->qhash != expected_qhash) {
        return "cursor_params_mismatch: this cursor was issued for different arguments — "
               "pass the cursor back with ALL other arguments identical";
    }
    if (strcmp(out->generation, current_generation) != 0) {
        return "stale_cursor: the project was reindexed since this cursor was issued — "
               "re-run the original query without 'cursor' (node identities changed)";
    }
    return NULL;
}

/* Slice a canonically-ordered traversal at the watermark: index of the first
 * row strictly AFTER (hop, id). */