leptris 1.9.201.0-arm-linux → 1.9.201.2-arm-linux

data/vendor-src/libleptris/src/leptris/dom/compact.h

@@ -0,0 +1,307 @@
+/* lib/src/dom/compact.h - Compressed Pointer Architecture
+ * Copyright (c) 2024, Ribose Inc.
+ *
+ * Based on pugixml's compact mode design.
+ * Enables 6x smaller element structures (32 bytes vs 192 bytes).
+ *
+ * Key innovations:
+ * - 1-byte pointers instead of 8-byte pointers (for local references)
+ * - 2-byte pointers for parent (which may be far)
+ * - Inline string storage (1-3 bytes vs 8 bytes)
+ * - Hash table fallback for large offsets
+ *
+ * This is the key to beating pugixml's performance!
+ */
+
+#ifndef LEPTRIS_DOM_COMPACT_H
+#define LEPTRIS_DOM_COMPACT_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stddef.h>
+
+/* ============================================================================
+ * Constants
+ * ============================================================================ */
+
+/* Alignment for compact pointers (4 bytes, not 8!) */
+#define LEPTRIS_COMPACT_ALIGNMENT 4
+#define LEPTRIS_COMPACT_ALIGNMENT_LOG2 2
+
+/* Special compact pointer values */
+#define LEPTRIS_COMPACT_PTR_NULL       0    /* NULL pointer */
+
+/* ============================================================================
+ * Core Compact Types
+ * ============================================================================ */
+
+/**
+ * Compact header (2 bytes)
+ *
+ * Stores page offset and node type flags.
+ * All structures in compact mode must start with this header.
+ */
+typedef struct leptris_compact_header {
+    uint8_t page_offset;   /* Offset from page_base in 4-byte units */
+    uint8_t flags;         /* Node type flags (LEPTRIS_NODE_ELEMENT, etc.) */
+} LeptrisCompactHeader;
+
+/* ============================================================================
+ * Overflow Hash Table
+ * ============================================================================ */
+
+/**
+ * Overflow hash table entry
+ *
+ * Stores pointer values that don't fit in compact representation.
+ */
+typedef struct leptris_compact_overflow_entry {
+    const void* key;              /* Pointer to compact field */
+    void* value;                  /* Actual pointer value */
+    struct leptris_document* doc;   /* Document that owns this entry */
+    struct leptris_compact_overflow_entry* next;
+} LeptrisCompactOverflowEntry;
+
+/**
+ * Overflow hash table
+ *
+ * Maps compact field pointers to actual pointer values.
+ */
+typedef struct leptris_compact_overflow_table {
+    LeptrisCompactOverflowEntry** buckets;
+    size_t bucket_count;
+    size_t entry_count;
+    /* Entry slabs (any-size robustness, TODO 195b): mutation-heavy
+     * documents create one overflow entry per out-of-range edge —
+     * malloc-per-entry dominated append time at scale. Entries are
+     * now carved from slab allocations; destroy frees whole slabs. */
+    void** slabs;
+    size_t slab_count;
+    size_t slab_capacity;
+    LeptrisCompactOverflowEntry* slab_next;  /* carve cursor */
+    size_t slab_remaining;
+} LeptrisCompactOverflowTable;
+
+/* ============================================================================
+ * Encoding/Decoding Functions
+ * ============================================================================ */
+
+/* TODO 121: int32 compact pointer encode/decode for tree edges.
+ *
+ * Used by element.h, text.h, comment.h, cdata.h, pi.h for parent/
+ * first/last/next-sibling offsets.  On macOS, ASLR can place pool-
+ * residential nodes > 2GB apart, overflowing int32_t.  The encode side
+ * detects overflow and registers the mapping in the global overflow
+ * table keyed on `field_addr` (the address of the int32_t field
+ * itself), returning INT32_MIN as a sentinel.  Decode recognises the
+ * sentinel and consults the table.
+ *
+ * The helpers are exposed because the call sites are inlined in
+ * headers; they can't reach file-static helpers in compact.c. */
+#include <stdint.h>
+#ifdef __cplusplus
+extern "C" {
+#endif
+int32_t leptris_compact_int32_encode(void* base, void* target,
+                                     const int32_t* field_addr);
+void*   leptris_compact_int32_decode(void* base, int32_t off,
+                                     const int32_t* field_addr);
+#ifdef __cplusplus
+}
+#endif
+
+/* int32 sentinel written when the delta overflows and lands in the
+ * overflow table (compact.c keeps the authoritative definition; the
+ * value is INT32_MIN). */
+#define LEPTRIS_INT32_OVERFLOW_SENTINEL_H ((int32_t)(-2147483647 - 1))
+
+/* Inline fast paths (lane 18): the shared encode/decode live in
+ * compact.c, so every tree-edge store or sibling/parent read paid an
+ * out-of-line call — two per node in the parse loop and one per edge
+ * in every mutation. The in-range case is a plain subtraction/add,
+ * inlined here; only NULL, the sentinel, and out-of-range deltas
+ * reach the shared functions (which keep the overflow-table and
+ * current-document registration semantics). Semantics are identical
+ * to the compact.c definitions — the asserts in test_compact guard
+ * the pairing. */
+static inline int32_t leptris_compact_int32_encode_inline(
+    void* base, void* target, const int32_t* field_addr) {
+    if (!target) return 0;
+    ptrdiff_t d = (char*)target - (char*)base;
+    if (d < INT32_MIN || d > INT32_MAX)
+        return leptris_compact_int32_encode(base, target, field_addr);
+    return (int32_t)d;
+}
+
+static inline void* leptris_compact_int32_decode_inline(
+    void* base, int32_t off, const int32_t* field_addr) {
+    if (off == 0) return NULL;
+    if (off == LEPTRIS_INT32_OVERFLOW_SENTINEL_H)
+        return leptris_compact_int32_decode(base, off, field_addr);
+    return (char*)base + off;
+}
+
+/* TODO 178: 1-byte and 2-byte compact pointer encoders.
+ *
+ * Same overflow-table mechanism as int32, but tighter encoding for
+ * nearby-pointer cases common in tree edges (text/comment/cdata/pi
+ * sibling chains, attribute lists). The byte offset between base and
+ * target is scaled by `1 << align_log2` before storage, so the
+ * representable range with N-byte signed storage becomes:
+ *
+ *   1-byte, align_log2=3: ±127 * 8  = ±1016 bytes (covers small pages)
+ *   2-byte, align_log2=3: ±32767 * 8 = ±262 KB   (covers any doc)
+ *
+ * NULL is encoded as 0 (the field's natural zero-init state, so
+ * calloc'd memory is correctly NULL). INT8_MIN / INT16_MIN are
+ * reserved as overflow sentinels: when encode returns one, the
+ * (field_addr -> target) mapping has been registered in the global
+ * overflow table; decode recognises the sentinel and looks it up.
+ *
+ * The base pointer is the address of the struct containing the field
+ * (e.g., for `text_node->next_sibling_cp`, base is `text_node`).
+ * field_addr is `&text_node->next_sibling_cp` — used as the hash key
+ * so distinct fields on the same struct don't collide. */
+#define LEPTRIS_COMPACT_PTR8_OVERFLOW  INT8_MIN
+#define LEPTRIS_COMPACT_PTR16_OVERFLOW INT16_MIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+int8_t  leptris_compact_ptr8_encode(const void* base, const void* target,
+                                    int align_log2,
+                                    const int8_t* field_addr);
+void*   leptris_compact_ptr8_decode(const void* base, int8_t off,
+                                    int align_log2,
+                                    const int8_t* field_addr);
+
+int16_t leptris_compact_ptr16_encode(const void* base, const void* target,
+                                     int align_log2,
+                                     const int16_t* field_addr);
+void*   leptris_compact_ptr16_decode(const void* base, int16_t off,
+                                     int align_log2,
+                                     const int16_t* field_addr);
+#ifdef __cplusplus
+}
+#endif
+
+/* ============================================================================
+ * Overflow Hash Table Functions
+ * ============================================================================ */
+
+/**
+ * Create overflow hash table
+ *
+ * @param bucket_count Number of buckets (must be power of 2)
+ * @return New table, or NULL on failure
+ */
+LeptrisCompactOverflowTable* leptris_compact_overflow_table_create(size_t bucket_count);
+
+/**
+ * Destroy overflow hash table
+ *
+ * @param table Table to destroy
+ */
+void leptris_compact_overflow_table_destroy(LeptrisCompactOverflowTable* table);
+
+/**
+ * Store pointer in overflow table
+ *
+ * @param table  Overflow table
+ * @param key    Pointer to compact field
+ * @param value  Actual pointer value
+ * @param doc    Document that owns this entry (required)
+ * @return 0 on success, -1 on failure
+ */
+int leptris_compact_overflow_set(LeptrisCompactOverflowTable* table,
+                                const void* key,
+                                void* value,
+                                struct leptris_document* doc);
+
+/**
+ * Cleanup all overflow entries for a specific document
+ *
+ * This removes all overflow table entries that were created for this document,
+ * preventing stale pointers when the document's memory is freed.
+ *
+ * @param doc  Document whose overflow entries should be removed
+ */
+void leptris_compact_cleanup_document(struct leptris_document* doc);
+
+/**
+ * Load pointer from overflow table
+ *
+ * @param table  Overflow table
+ * @param key    Pointer to compact field
+ * @return Stored pointer value, or NULL if not found
+ */
+void* leptris_compact_overflow_get(LeptrisCompactOverflowTable* table,
+                                  const void* key);
+
+/**
+ * Cleanup thread-local overflow table
+ *
+ * This function destroys the global thread-local overflow table.
+ */
+void leptris_compact_cleanup(void);
+
+/**
+ * Cleanup all overflow entries for a specific document
+ *
+ * This removes all overflow table entries that were created for this document,
+ * preventing stale pointers when the document's memory is freed.
+ * Must be called BEFORE the document's memory pool is destroyed.
+ *
+ * @param doc  Document whose overflow entries should be removed
+ */
+void leptris_compact_cleanup_document(struct leptris_document* doc);
+
+/**
+ * Increment overflow table reference count
+ *
+ * Call this when creating a new document that might use compact pointers.
+ * The overflow table will be destroyed when the reference count reaches 0.
+ */
+void leptris_compact_table_addref(void);
+
+/**
+ * Decrement overflow table reference count
+ *
+ * Call this when freeing a document. If the reference count reaches 0,
+ * the overflow table will be destroyed.
+ */
+void leptris_compact_table_release(void);
+
+/**
+ * Set current document for overflow tracking during encoding
+ *
+ * @param doc  Document to set as current (NULL to clear)
+ */
+void leptris_compact_set_current_document(struct leptris_document* doc);
+
+/* ============================================================================
+ * Compact Header Functions
+ * ============================================================================ */
+
+/**
+ * Get memory page from compact header
+ *
+ * @param header    Compact header
+ * @param page_base Base pointer for page offset calculation
+ * @return          Pointer to memory page
+ */
+void* leptris_compact_header_get_page(const LeptrisCompactHeader* header,
+                                     void* page_base);
+
+/**
+ * Initialize compact header
+ *
+ * @param header    Compact header to initialize
+ * @param page_base Base pointer for offset calculation
+ * @param flags     Node type flags
+ */
+void leptris_compact_header_init(LeptrisCompactHeader* header,
+                                void* page_base,
+                                uint8_t flags);
+
+#endif /* LEPTRIS_DOM_COMPACT_H */

data/vendor-src/libleptris/src/leptris/dom/diag.c

@@ -0,0 +1,58 @@
+/* dom/diag.c — unified error narration records (#1126). */
+#include "diag.h"
+#include "node.h"
+#include "element.h"
+#include "../leptris_internal.h"  /* leptris_strdup */
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+LeptrisDiag* leptris_diag_emit(LeptrisDiag** list, int* count, int* cap,
+                               LeptrisDiagKind kind, LeptrisNodeRef offender,
+                               const char* fmt, ...) {
+    if (!list || !count || !cap) return NULL;
+    if (*count == *cap) {
+        int nc = *cap ? *cap * 2 : 8;
+        LeptrisDiag* nl = (LeptrisDiag*)realloc(
+            *list, sizeof(LeptrisDiag) * (size_t)nc);
+        if (!nl) return NULL;
+        *list = nl;
+        *cap = nc;
+    }
+    LeptrisDiag* d = &(*list)[*count];
+    d->kind = kind;
+    d->offender_name = NULL;
+    d->line = 0;
+    d->col_start = 0;
+    d->col_end = 0;
+    if (offender) {
+        LeptrisSourcePosition pos;
+        leptris_node_source_position(offender, &pos);
+        d->line = pos.line;
+        d->col_start = pos.col_start;
+        d->col_end = pos.col_end;
+        /* capture the name NOW (#1194): the node belongs to the
+         * validated document, which the caller may free before the
+         * report is read — a stored ref dangles (musl unmaps the
+         * freed region and error_report segfaulted reading it). */
+        const char* nm = leptris_element_name((LeptrisElement)offender);
+        d->offender_name = (nm && *nm) ? leptris_strdup(nm) : NULL;
+    }
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(d->message, sizeof(d->message), fmt, ap);
+    va_end(ap);
+    (*count)++;
+    return d;
+}
+
+void leptris_diag_free(LeptrisDiag** list, int* count, int* cap) {
+    if (!list) return;
+    if (*list && count) {
+        for (int i = 0; i < *count; i++) free((*list)[i].offender_name);
+    }
+    free(*list);
+    *list = NULL;
+    if (count) *count = 0;
+    if (cap) *cap = 0;
+}

data/vendor-src/libleptris/src/leptris/dom/diag.h

@@ -0,0 +1,75 @@
+/* dom/diag.h — unified error narration records (#1126).
+ *
+ * One structured record per validation failure, shared by every
+ * validator (RNG today; XSD/Schematron follow). The record carries
+ * the KIND (which selects the Jing reporting convention: which
+ * column, which vocabulary family), the offending node, and the
+ * rendered message. The per-format verdict engines stay separate —
+ * their semantics differ — but narration goes through here so the
+ * vocabulary and position rules live once.
+ */
+#ifndef LEPTRIS_DOM_DIAG_H
+#define LEPTRIS_DOM_DIAG_H
+
+#include "../include/leptris.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    LEPTRIS_DIAG_INVALID = 0,
+    LEPTRIS_DIAG_NOT_ALLOWED_ANYWHERE,   /* name never valid in model */
+    LEPTRIS_DIAG_NOT_ALLOWED_HERE,       /* valid name, wrong position */
+    LEPTRIS_DIAG_NOT_ALLOWED_YET,        /* later; missing required first */
+    LEPTRIS_DIAG_INCOMPLETE,             /* content ends before required */
+    LEPTRIS_DIAG_MISSING_REQUIRED_ATTR,
+    LEPTRIS_DIAG_ATTR_NOT_ALLOWED,
+    LEPTRIS_DIAG_ATTR_VALUE_INVALID,
+    LEPTRIS_DIAG_CHAR_CONTENT_INVALID,   /* data/value/list mismatch */
+    LEPTRIS_DIAG_COUNT_
+} LeptrisDiagKind;
+
+typedef struct {
+    LeptrisDiagKind kind;
+    char* offender_name;          /* captured at emit time (strdup'd);
+                                   * NULL when the diag has no offender.
+                                   * #1207: a node ref dangles once the
+                                   * validated document is freed — musl
+                                   * unmaps the region and the report
+                                   * pass segfaulted reading it. */
+
+    int line;
+    int col_start;                /* Jing: element/attr errors */
+    int col_end;                  /* Jing: incomplete/content errors */
+    char message[256];
+} LeptrisDiag;
+
+/* Does this kind report at the element's END column (Jing's
+ * incomplete / character-content convention)? */
+static inline int leptris_diag_kind_uses_end_col(LeptrisDiagKind k) {
+    return k == LEPTRIS_DIAG_INCOMPLETE ||
+           k == LEPTRIS_DIAG_CHAR_CONTENT_INVALID;
+}
+
+/* Append one record. Position comes from the parser-recorded
+ * source offsets (#1124); the column is chosen by kind. The
+ * message is vsnprintf'd from fmt. Returns the appended record or
+ * NULL when allocation failed. */
+LeptrisDiag* leptris_diag_emit(LeptrisDiag** list, int* count, int* cap,
+                               LeptrisDiagKind kind, LeptrisNodeRef offender,
+                               const char* fmt, ...)
+#if defined(__GNUC__)
+    __attribute__((format(printf, 6, 7)))
+#endif
+    ;
+
+/* Release a record list (the messages are inline, so this is one
+ * free + reset). */
+void leptris_diag_free(LeptrisDiag** list, int* count, int* cap);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LEPTRIS_DOM_DIAG_H */

data/vendor-src/libleptris/src/leptris/dom/digest.c

@@ -0,0 +1,255 @@
+/* dom/digest.c — on-demand subtree structural digest (#869).
+ *
+ * Content-defined Merkle hash: no pointers or addresses
+ * participate, so the value is stable across processes. Equality
+ * implies subtree equivalence under the flag semantics (the
+ * comparator's soundness contract); inequality implies nothing.
+ * Zero cost when never called — nothing here runs on any parse,
+ * serialize, or eval path.
+ */
+
+#include "../include/leptris.h"
+#include "../leptris_internal.h"
+#include "element.h"
+#include "node.h"
+#include "text.h"
+#include "comment.h"
+#include "cdata.h"
+#include "pi.h"
+#include <stdlib.h>
+#include <string.h>
+
+#define DIGEST_FNV_OFFSET 1469598103934665603ULL
+#define DIGEST_FNV_PRIME  1099511628211ULL
+
+/* Length-prefixed byte mix: the length prefix keeps field
+ * boundaries unambiguous ("ab"+"c" never collides with "a"+"bc"). */
+static uint64_t digest_mix_bytes(uint64_t h, const char* s, size_t len) {
+    h ^= (uint64_t)len + 1;
+    h *= DIGEST_FNV_PRIME;
+    for (size_t i = 0; i < len; i++) {
+        h ^= (unsigned char)s[i];
+        h *= DIGEST_FNV_PRIME;
+    }
+    return h;
+}
+
+static uint64_t digest_mix_str(uint64_t h, const char* s) {
+    /* NULL and "" both mix as empty — an absent namespace and an
+     * empty namespace URI are the same no-namespace. */
+    return s ? digest_mix_bytes(h, s, strlen(s))
+             : digest_mix_bytes(h, "", 0);
+}
+
+static uint64_t digest_mix_u64(uint64_t h, uint64_t v) {
+    for (int i = 0; i < 8; i++) {
+        h ^= (unsigned char)(v >> (i * 8));
+        h *= DIGEST_FNV_PRIME;
+    }
+    return h;
+}
+
+static int digest_is_ws_only(const char* s, size_t len) {
+    for (size_t i = 0; i < len; i++) {
+        char c = s[i];
+        if (c != ' ' && c != '\t' && c != '\r' && c != '\n') return 0;
+    }
+    return 1;
+}
+
+typedef struct {
+    const char* uri;      /* resolved namespace URI ("" = none) */
+    const char* local;    /* local part (after the colon) */
+    const char* value;
+    size_t local_len;
+    size_t value_len;
+} DigestAttr;
+
+static int digest_attr_cmp(const void* a, const void* b) {
+    const DigestAttr* da = (const DigestAttr*)a;
+    const DigestAttr* db = (const DigestAttr*)b;
+    const char* ua = da->uri ? da->uri : "";
+    const char* ub = db->uri ? db->uri : "";
+    int c = strcmp(ua, ub);
+    if (c != 0) return c;
+    size_t ml = da->local_len < db->local_len ? da->local_len : db->local_len;
+    c = memcmp(da->local, db->local, ml);
+    if (c != 0) return c;
+    if (da->local_len < db->local_len) return -1;
+    if (da->local_len > db->local_len) return 1;
+    return 0;
+}
+
+static uint64_t digest_element(LeptrisElement e, LeptrisDigestFlags flags);
+
+static uint64_t digest_element(LeptrisElement e, LeptrisDigestFlags flags) {
+    uint64_t h = DIGEST_FNV_OFFSET;
+    h = digest_mix_bytes(h, "E", 1);
+    char* pfx = leptris_elem_prefix(e);
+    h = digest_mix_str(h, pfx);
+    h = digest_mix_str(h, leptris_element_get_namespace_uri(e));
+    const char* name = leptris_element_get_name(e);
+    h = digest_mix_str(h, name);
+
+    /* Namespace declarations ON this element (prefix->URI pairs,
+     * sorted like attrs so declaration order doesn't false-split;
+     * a changed or re-prefixed declaration changes the subtree —
+     * the x:root case resolved through the element URI, but an
+     * unused redeclaration only shows here). */
+    {
+        size_t ndecl = 0;
+        for (struct leptris_namespace* n2 = leptris_elem_namespaces(e);
+             n2; n2 = n2->next)
+            ndecl++;
+        if (ndecl > 0) {
+            struct leptris_namespace** order =
+                (struct leptris_namespace**)malloc(
+                    ndecl * sizeof(*order));
+            if (order) {
+                size_t k = 0;
+                for (struct leptris_namespace* n2 =
+                         leptris_elem_namespaces(e);
+                     n2; n2 = n2->next)
+                    order[k++] = n2;
+                for (size_t i = 0; i < ndecl; i++)
+                    for (size_t j = i + 1; j < ndecl; j++) {
+                        const char* pi = order[i]->prefix
+                                            ? order[i]->prefix : "";
+                        const char* pj = order[j]->prefix
+                                            ? order[j]->prefix : "";
+                        if (strcmp(pi, pj) > 0) {
+                            struct leptris_namespace* t = order[i];
+                            order[i] = order[j];
+                            order[j] = t;
+                        }
+                    }
+                h = digest_mix_u64(h, (uint64_t)ndecl);
+                for (size_t i = 0; i < ndecl; i++) {
+                    h = digest_mix_str(h, order[i]->prefix);
+                    h = digest_mix_str(h, order[i]->uri);
+                }
+                free(order);
+            }
+        }
+    }
+
+    /* Attributes: resolved (URI, local, value) triples, sorted,
+     * deduplicated first-wins (document order). */
+    uint8_t acount = leptris_element_attribute_count(e);
+    if (acount > 0) {
+        DigestAttr stack_attrs[32];
+        DigestAttr* attrs = stack_attrs;
+        DigestAttr* heap_attrs = NULL;
+        if (acount > 32) {
+            heap_attrs = (DigestAttr*)malloc(acount * sizeof(DigestAttr));
+            attrs = heap_attrs;
+        }
+        size_t n = 0;
+        if (attrs) {
+            for (struct leptris_attribute* a =
+                     leptris_element_get_first_attribute(e);
+                 a; a = leptris_attr_next(a)) {
+                const char* cname = attr_cname(a);
+                const char* colon = cname ? strchr(cname, ':') : NULL;
+                const char* local =
+                    colon ? colon + 1 : (cname ? cname : "");
+                size_t local_len =
+                    a->name_view.length -
+                    (colon ? (size_t)(colon - cname) + 1 : 0);
+                const char* uri = NULL;
+                if (colon) {
+                    uri = leptris_attribute_namespace_uri(a);
+                    if (!uri) continue;   /* undeclared prefix: skip */
+                }
+                /* First-wins dedup on the resolved key. */
+                int dup = 0;
+                for (size_t i = 0; i < n; i++) {
+                    const char* u2 = attrs[i].uri ? attrs[i].uri : "";
+                    const char* u1 = uri ? uri : "";
+                    if (strcmp(u1, u2) == 0 &&
+                        attrs[i].local_len == local_len &&
+                        memcmp(attrs[i].local, local, local_len) == 0) {
+                        dup = 1;
+                        break;
+                    }
+                }
+                if (dup) continue;
+                attrs[n].uri = uri;
+                attrs[n].local = local;
+                attrs[n].local_len = local_len;
+                attrs[n].value = leptris_attr_value_sv(a).data ? leptris_attr_value_sv(a).data : "";
+                attrs[n].value_len = leptris_attr_value_sv(a).length;
+                n++;
+            }
+            qsort(attrs, n, sizeof(DigestAttr), digest_attr_cmp);
+        }
+        h = digest_mix_u64(h, n);
+        for (size_t i = 0; i < n; i++) {
+            h = digest_mix_str(h, attrs[i].uri);
+            h = digest_mix_bytes(h, attrs[i].local, attrs[i].local_len);
+            h = digest_mix_bytes(h, attrs[i].value, attrs[i].value_len);
+        }
+        free(heap_attrs);
+    }
+
+    /* Children in document order, each hashed recursively (Merkle
+     * combine — a child's full digest feeds the parent). */
+    size_t n_children = 0;
+    for (LeptrisNode* c = leptris_node_first_child_internal((LeptrisNode*)e);
+         c; c = leptris_node_get_next_sibling(c)) {
+        if ((flags & LEPTRIS_DIGEST_DROP_WS_TEXT) &&
+            c->type == LEPTRIS_NODE_TYPE_TEXT) {
+            const char* t = leptris_text_get_content((LeptrisTextNode*)c);
+            if (digest_is_ws_only(t ? t : "", t ? strlen(t) : 0)) continue;
+        }
+        n_children++;
+    }
+    h = digest_mix_u64(h, n_children);
+    for (LeptrisNode* c = leptris_node_first_child_internal((LeptrisNode*)e);
+         c; c = leptris_node_get_next_sibling(c)) {
+        if ((flags & LEPTRIS_DIGEST_DROP_WS_TEXT) &&
+            c->type == LEPTRIS_NODE_TYPE_TEXT) {
+            const char* t = leptris_text_get_content((LeptrisTextNode*)c);
+            if (digest_is_ws_only(t ? t : "", t ? strlen(t) : 0)) continue;
+        }
+        h = digest_mix_u64(h, leptris_node_digest((LeptrisNodeRef)c, flags));
+    }
+    return h;
+}
+
+LEPTRIS_API uint64_t leptris_node_digest(LeptrisNodeRef node,
+                                         LeptrisDigestFlags flags) {
+    if (!node) return 0;
+    LeptrisNode* n = (LeptrisNode*)node;
+    switch (n->type) {
+        case LEPTRIS_NODE_TYPE_ELEMENT:
+            return digest_element((LeptrisElement)n, flags);
+        case LEPTRIS_NODE_TYPE_TEXT: {
+            uint64_t h = DIGEST_FNV_OFFSET;
+            h = digest_mix_bytes(h, "T", 1);
+            const char* t = leptris_text_get_content((LeptrisTextNode*)n);
+            return digest_mix_str(h, t);
+        }
+        case LEPTRIS_NODE_TYPE_CDATA: {
+            uint64_t h = DIGEST_FNV_OFFSET;
+            h = digest_mix_bytes(h, "C", 1);
+            const char* t = leptris_cdata_get_content((LeptrisCDATANode*)n);
+            return digest_mix_str(h, t);
+        }
+        case LEPTRIS_NODE_TYPE_COMMENT: {
+            uint64_t h = DIGEST_FNV_OFFSET;
+            h = digest_mix_bytes(h, "M", 1);
+            const char* t = leptris_comment_get_content((LeptrisCommentNode*)n);
+            return digest_mix_str(h, t);
+        }
+        case LEPTRIS_NODE_TYPE_PI: {
+            uint64_t h = DIGEST_FNV_OFFSET;
+            h = digest_mix_bytes(h, "P", 1);
+            LeptrisPINode* pi = (LeptrisPINode*)n;
+            h = digest_mix_str(h, leptris_pi_get_target(pi));
+            return digest_mix_str(h, leptris_pi_get_data(pi));
+        }
+        default:
+            return 0;
+    }
+}