@soulcraft/cor 3.0.0-rc.1

package/dist/utils/NativeUnifiedCache.d.ts

@@ -0,0 +1,87 @@
+/**
+ * NativeUnifiedCacheWrapper — Native Rust eviction engine with JS data storage
+ *
+ * The Rust NativeUnifiedCache manages eviction metadata (key, type, size, cost,
+ * access counts) but does NOT store actual JS data. This wrapper:
+ * - Keeps a Map<string, any> for actual cached data
+ * - Delegates eviction decisions to the native engine
+ * - Implements request coalescing in JS (same as brainy's UnifiedCache)
+ * - Drop-in replacement for brainy's UnifiedCache
+ */
+import type { UnifiedCacheConfig } from '@soulcraft/brainy/internals';
+import type { CacheProvider } from '../providerContracts.js';
+/**
+ * Implements {@link CacheProvider} so a compile error fires the moment this
+ * wrapper drops or drifts a member brainy calls on the installed global cache
+ * (`getSync` / `set` / `delete` / `deleteByPrefix` / `clear`).
+ */
+export declare class NativeUnifiedCacheWrapper implements CacheProvider {
+    private data;
+    private native;
+    private loadingPromises;
+    private readonly maxSize;
+    private readonly config;
+    private readonly memoryInfo;
+    private readonly allocationStrategy;
+    private memoryPressureCheckTimer;
+    private lastMemoryWarning;
+    constructor(config?: UnifiedCacheConfig);
+    get(key: string, loadFn?: () => Promise<any>): Promise<any>;
+    getSync(key: string): any | undefined;
+    set(key: string, data: any, type: 'vectors' | 'metadata' | 'embedding' | 'other', size: number, rebuildCost?: number): void;
+    delete(key: string): boolean;
+    deleteByPrefix(prefix: string): number;
+    clear(type?: 'vectors' | 'metadata' | 'embedding' | 'other'): void;
+    evictForSize(bytesNeeded: number): boolean;
+    private startFairnessMonitor;
+    private checkFairness;
+    private startMemoryPressureMonitor;
+    private checkMemoryPressure;
+    getStats(): {
+        totalSize: number;
+        maxSize: number;
+        utilization: number;
+        itemCount: number;
+        typeSizes: Record<string, number>;
+        typeCounts: Record<string, number>;
+        typeAccessCounts: Record<string, number>;
+        totalAccessCount: number;
+        hitRate: number;
+        memory: {
+            available: number;
+            source: "cgroup-v2" | "cgroup-v1" | "system" | "fallback";
+            isContainer: boolean;
+            systemTotal: number;
+            allocationRatio: number;
+            environment: "unknown" | "production" | "development" | "container";
+        };
+    };
+    getMemoryInfo(): {
+        memoryInfo: {
+            available: number;
+            source: "cgroup-v2" | "cgroup-v1" | "system" | "fallback";
+            isContainer: boolean;
+            systemTotal: number;
+            free: number;
+            warnings: string[];
+        };
+        allocationStrategy: {
+            cacheSize: number;
+            ratio: number;
+            minSize: number;
+            maxSize: number | null;
+            environment: "production" | "development" | "container" | "unknown";
+            modelMemory: number;
+            modelPrecision: "q8" | "fp32";
+            availableForCache: number;
+            reasoning: string;
+        };
+        currentPressure: {
+            pressure: "none" | "moderate" | "high" | "critical";
+            warnings: string[];
+        };
+    };
+    saveAccessPatterns(): Promise<any>;
+    loadAccessPatterns(patterns: any): Promise<void>;
+}
+//# sourceMappingURL=NativeUnifiedCache.d.ts.map

package/dist/utils/NativeUnifiedCache.js

@@ -0,0 +1,273 @@
+/**
+ * NativeUnifiedCacheWrapper — Native Rust eviction engine with JS data storage
+ *
+ * The Rust NativeUnifiedCache manages eviction metadata (key, type, size, cost,
+ * access counts) but does NOT store actual JS data. This wrapper:
+ * - Keeps a Map<string, any> for actual cached data
+ * - Delegates eviction decisions to the native engine
+ * - Implements request coalescing in JS (same as brainy's UnifiedCache)
+ * - Drop-in replacement for brainy's UnifiedCache
+ */
+import { loadNativeModule } from '../native/index.js';
+import { prodLog } from '@soulcraft/brainy/internals';
+import { getRecommendedCacheConfig, formatBytes, checkMemoryPressure, } from '@soulcraft/brainy/internals';
+// Cache type enum matching Rust (0-3)
+const CACHE_TYPE_MAP = {
+    vectors: 0,
+    metadata: 1,
+    embedding: 2,
+    other: 3,
+};
+/**
+ * Implements {@link CacheProvider} so a compile error fires the moment this
+ * wrapper drops or drifts a member brainy calls on the installed global cache
+ * (`getSync` / `set` / `delete` / `deleteByPrefix` / `clear`).
+ */
+export class NativeUnifiedCacheWrapper {
+    data = new Map();
+    native;
+    loadingPromises = new Map();
+    maxSize;
+    config;
+    memoryInfo;
+    allocationStrategy;
+    memoryPressureCheckTimer = null;
+    lastMemoryWarning = 0;
+    constructor(config = {}) {
+        const recommendation = getRecommendedCacheConfig({
+            manualSize: config.maxSize,
+            minSize: config.minSize,
+            developmentMode: config.developmentMode,
+        });
+        this.memoryInfo = recommendation.memoryInfo;
+        this.allocationStrategy = recommendation.allocation;
+        this.maxSize = recommendation.allocation.cacheSize;
+        prodLog.info(`NativeUnifiedCache initialized: ${formatBytes(this.maxSize)} ` +
+            `(${this.allocationStrategy.environment} mode, ` +
+            `${(this.allocationStrategy.ratio * 100).toFixed(0)}% of ${formatBytes(this.allocationStrategy.availableForCache)} ` +
+            `after ${formatBytes(this.allocationStrategy.modelMemory)} ${this.allocationStrategy.modelPrecision.toUpperCase()} model)`);
+        for (const warning of recommendation.warnings) {
+            prodLog.warn(`NativeUnifiedCache: ${warning}`);
+        }
+        this.config = {
+            enableRequestCoalescing: true,
+            enableFairnessCheck: true,
+            fairnessCheckInterval: 30000,
+            persistPatterns: true,
+            enableMemoryMonitoring: true,
+            memoryCheckInterval: 30000,
+            ...config,
+        };
+        const bindings = loadNativeModule();
+        this.native = new bindings.NativeUnifiedCache(this.maxSize);
+        if (this.config.enableFairnessCheck) {
+            this.startFairnessMonitor();
+        }
+        if (this.config.enableMemoryMonitoring) {
+            this.startMemoryPressureMonitor();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Core API
+    // ---------------------------------------------------------------------------
+    async get(key, loadFn) {
+        // Check JS data map
+        const cached = this.data.get(key);
+        if (cached !== undefined) {
+            this.native.recordAccess(key);
+            return cached;
+        }
+        if (!loadFn)
+            return undefined;
+        // Request coalescing
+        if (this.config.enableRequestCoalescing && this.loadingPromises.has(key)) {
+            return this.loadingPromises.get(key);
+        }
+        const loadPromise = loadFn();
+        if (this.config.enableRequestCoalescing) {
+            this.loadingPromises.set(key, loadPromise);
+        }
+        try {
+            const result = await loadPromise;
+            return result;
+        }
+        finally {
+            if (this.config.enableRequestCoalescing) {
+                this.loadingPromises.delete(key);
+            }
+        }
+    }
+    getSync(key) {
+        const cached = this.data.get(key);
+        if (cached !== undefined) {
+            this.native.recordAccess(key);
+            return cached;
+        }
+        return undefined;
+    }
+    set(key, data, type, size, rebuildCost = 1) {
+        const cacheType = CACHE_TYPE_MAP[type] ?? 3;
+        // Remove existing entry if present
+        if (this.data.has(key)) {
+            this.native.remove(key);
+        }
+        // Insert into native (may trigger eviction)
+        const evictionResult = this.native.insert(key, cacheType, size, rebuildCost);
+        // Remove evicted keys from JS data
+        for (const evictedKey of evictionResult.evictedKeys) {
+            this.data.delete(evictedKey);
+        }
+        // Store actual data in JS
+        this.data.set(key, data);
+    }
+    delete(key) {
+        const existed = this.data.has(key);
+        if (existed) {
+            this.native.remove(key);
+            this.data.delete(key);
+        }
+        return existed;
+    }
+    deleteByPrefix(prefix) {
+        const removedKeys = this.native.removeByPrefix(prefix);
+        for (const key of removedKeys) {
+            this.data.delete(key);
+        }
+        return removedKeys.length;
+    }
+    clear(type) {
+        if (!type) {
+            const clearedKeys = this.native.clear();
+            for (const key of clearedKeys) {
+                this.data.delete(key);
+            }
+            // Also clear any remaining data entries
+            this.data.clear();
+        }
+        else {
+            const cacheType = CACHE_TYPE_MAP[type] ?? 3;
+            const clearedKeys = this.native.clear(cacheType);
+            for (const key of clearedKeys) {
+                this.data.delete(key);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Eviction
+    // ---------------------------------------------------------------------------
+    evictForSize(bytesNeeded) {
+        const result = this.native.evictForSize(bytesNeeded);
+        for (const key of result.evictedKeys) {
+            this.data.delete(key);
+        }
+        return result.bytesFreed >= bytesNeeded;
+    }
+    // ---------------------------------------------------------------------------
+    // Fairness
+    // ---------------------------------------------------------------------------
+    startFairnessMonitor() {
+        const timer = setInterval(() => {
+            this.checkFairness();
+        }, this.config.fairnessCheckInterval);
+        if (timer.unref)
+            timer.unref();
+    }
+    checkFairness() {
+        const result = this.native.checkFairness();
+        for (const key of result.evictedKeys) {
+            this.data.delete(key);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Memory pressure
+    // ---------------------------------------------------------------------------
+    startMemoryPressureMonitor() {
+        const checkInterval = this.config.memoryCheckInterval || 30000;
+        this.memoryPressureCheckTimer = setInterval(() => {
+            this.checkMemoryPressure();
+        }, checkInterval);
+        if (this.memoryPressureCheckTimer.unref) {
+            this.memoryPressureCheckTimer.unref();
+        }
+    }
+    checkMemoryPressure() {
+        const stats = this.native.getStats();
+        const pressure = checkMemoryPressure(stats.totalSize, this.memoryInfo);
+        const now = Date.now();
+        const fiveMinutes = 5 * 60 * 1000;
+        if (pressure.warnings.length > 0 && now - this.lastMemoryWarning > fiveMinutes) {
+            for (const warning of pressure.warnings) {
+                prodLog.warn(`NativeUnifiedCache: ${warning}`);
+            }
+            this.lastMemoryWarning = now;
+        }
+        if (pressure.pressure === 'critical') {
+            const targetSize = Math.floor(this.maxSize * 0.7);
+            const bytesToFree = stats.totalSize - targetSize;
+            if (bytesToFree > 0) {
+                prodLog.warn(`NativeUnifiedCache: Critical memory pressure - forcing eviction of ${formatBytes(bytesToFree)}`);
+                this.evictForSize(bytesToFree);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Statistics
+    // ---------------------------------------------------------------------------
+    getStats() {
+        const nativeStats = this.native.getStats();
+        const typeNames = ['vectors', 'metadata', 'embedding', 'other'];
+        const typeSizes = {};
+        const typeCounts = {};
+        const typeAccessCounts = {};
+        for (let i = 0; i < typeNames.length; i++) {
+            typeSizes[typeNames[i]] = nativeStats.typeSizes[i] || 0;
+            typeCounts[typeNames[i]] = nativeStats.typeCounts[i] || 0;
+            typeAccessCounts[typeNames[i]] = nativeStats.typeAccessCounts[i] || 0;
+        }
+        const hitRate = nativeStats.totalAccessCount > 0
+            ? nativeStats.itemCount / nativeStats.totalAccessCount
+            : 0;
+        return {
+            totalSize: nativeStats.totalSize,
+            maxSize: nativeStats.maxSize,
+            utilization: nativeStats.maxSize > 0 ? nativeStats.totalSize / nativeStats.maxSize : 0,
+            itemCount: nativeStats.itemCount,
+            typeSizes,
+            typeCounts,
+            typeAccessCounts,
+            totalAccessCount: nativeStats.totalAccessCount,
+            hitRate,
+            memory: {
+                available: this.memoryInfo.available,
+                source: this.memoryInfo.source,
+                isContainer: this.memoryInfo.isContainer,
+                systemTotal: this.memoryInfo.systemTotal,
+                allocationRatio: this.allocationStrategy.ratio,
+                environment: this.allocationStrategy.environment,
+            },
+        };
+    }
+    getMemoryInfo() {
+        const stats = this.native.getStats();
+        return {
+            memoryInfo: { ...this.memoryInfo },
+            allocationStrategy: { ...this.allocationStrategy },
+            currentPressure: checkMemoryPressure(stats.totalSize, this.memoryInfo),
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Access pattern persistence
+    // ---------------------------------------------------------------------------
+    async saveAccessPatterns() {
+        if (!this.config.persistPatterns)
+            return;
+        const json = this.native.saveAccessPatterns();
+        return JSON.parse(json);
+    }
+    async loadAccessPatterns(patterns) {
+        if (!patterns)
+            return;
+        this.native.loadAccessPatterns(JSON.stringify(patterns));
+    }
+}
+//# sourceMappingURL=NativeUnifiedCache.js.map

package/dist/utils/binaryIdMapperFactory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module utils/binaryIdMapperFactory
+ * @description Single canonical constructor for cor's native mmap
+ * `BinaryIdMapper`. Derives the `_id_mapper/*` paths from a
+ * filesystem-backed storage adapter and opens (or creates / truncates)
+ * the paired `uuid_to_int.mkv` + `int_to_uuid.bin` files.
+ *
+ * Both the metadata index (the canonical UUID ↔ entity-int allocator
+ * since #72 Phase C) and the legacy `entityIdMapper` provider go through
+ * here so there is exactly one place that knows the file layout, the
+ * default sizes, and the paired-write / half-present invariant.
+ *
+ * The mapper is mmap-backed and demand-paged: a 32 GB default file is
+ * SPARSE on disk (only touched pages occupy blocks), so a fresh small
+ * brain pays only for what it uses. This is the constant-RAM,
+ * billion-scale store that replaces the resident JSON id-maps (#72).
+ */
+import type { NativeBinaryIdMapperInstance } from '../native/types.js';
+/** Default storage key for the extendible-hash UUID → int file. */
+export declare const DEFAULT_UUID_TO_INT_KEY = "_id_mapper/uuid_to_int.mkv";
+/** Default storage key for the direct-indexed int → UUID file. */
+export declare const DEFAULT_INT_TO_UUID_KEY = "_id_mapper/int_to_uuid.bin";
+/** Minimal storage surface this factory needs. */
+export interface StorageWithBlobPath {
+    getBinaryBlobPath?: (key: string) => string | null;
+}
+/** Options controlling file layout, sizing, and id width. */
+export interface BinaryIdMapperFactoryOptions {
+    uuidToIntKey?: string;
+    intToUuidKey?: string;
+    intToUuidSize?: bigint;
+    uuidToIntSize?: bigint;
+    bucketCapacity?: number;
+    maxGlobalDepth?: number;
+    idSpace?: 'u32' | 'u64';
+}
+/** What {@link openOrCreateBinaryIdMapper} resolves the mapper with. */
+export interface BinaryIdMapperHandle {
+    mapper: NativeBinaryIdMapperInstance;
+    uuidToIntPath: string;
+    intToUuidPath: string;
+    /** The mapper's actual on-disk IdSpace (authoritative over requested). */
+    idSpace: 'u32' | 'u64';
+    /** Whether the files were freshly created (vs opened existing). */
+    created: boolean;
+}
+/**
+ * Open (or create / truncate) the native `BinaryIdMapper` for a brain.
+ *
+ * @param storage - Filesystem-backed storage exposing `getBinaryBlobPath`.
+ * @param opts - File layout, sizing, id width, and the `forceCreate`
+ *   rebuild flag.
+ * @returns The native mapper handle plus its resolved paths + IdSpace.
+ * @throws If storage has no `getBinaryBlobPath`, if a path resolves null,
+ *   if the native `NativeBinaryIdMapper` binding is missing, or if the
+ *   two files are in a half-present (crash-torn) state.
+ */
+export declare function openOrCreateBinaryIdMapper(storage: StorageWithBlobPath, opts?: BinaryIdMapperFactoryOptions): BinaryIdMapperHandle;
+//# sourceMappingURL=binaryIdMapperFactory.d.ts.map

package/dist/utils/binaryIdMapperFactory.js

@@ -0,0 +1,94 @@
+/**
+ * @module utils/binaryIdMapperFactory
+ * @description Single canonical constructor for cor's native mmap
+ * `BinaryIdMapper`. Derives the `_id_mapper/*` paths from a
+ * filesystem-backed storage adapter and opens (or creates / truncates)
+ * the paired `uuid_to_int.mkv` + `int_to_uuid.bin` files.
+ *
+ * Both the metadata index (the canonical UUID ↔ entity-int allocator
+ * since #72 Phase C) and the legacy `entityIdMapper` provider go through
+ * here so there is exactly one place that knows the file layout, the
+ * default sizes, and the paired-write / half-present invariant.
+ *
+ * The mapper is mmap-backed and demand-paged: a 32 GB default file is
+ * SPARSE on disk (only touched pages occupy blocks), so a fresh small
+ * brain pays only for what it uses. This is the constant-RAM,
+ * billion-scale store that replaces the resident JSON id-maps (#72).
+ */
+import { existsSync } from 'node:fs';
+import { loadNativeModule } from '../native/index.js';
+/** Default storage key for the extendible-hash UUID → int file. */
+export const DEFAULT_UUID_TO_INT_KEY = '_id_mapper/uuid_to_int.mkv';
+/** Default storage key for the direct-indexed int → UUID file. */
+export const DEFAULT_INT_TO_UUID_KEY = '_id_mapper/int_to_uuid.bin';
+/** 32 GB default sparse-file size for each mapper file. */
+const DEFAULT_FILE_SIZE = BigInt(32) * BigInt(1024) ** BigInt(3);
+/**
+ * Open (or create / truncate) the native `BinaryIdMapper` for a brain.
+ *
+ * @param storage - Filesystem-backed storage exposing `getBinaryBlobPath`.
+ * @param opts - File layout, sizing, id width, and the `forceCreate`
+ *   rebuild flag.
+ * @returns The native mapper handle plus its resolved paths + IdSpace.
+ * @throws If storage has no `getBinaryBlobPath`, if a path resolves null,
+ *   if the native `NativeBinaryIdMapper` binding is missing, or if the
+ *   two files are in a half-present (crash-torn) state.
+ */
+export function openOrCreateBinaryIdMapper(storage, opts = {}) {
+    if (!storage.getBinaryBlobPath) {
+        throw new Error('openOrCreateBinaryIdMapper requires a storage adapter that exposes ' +
+            'getBinaryBlobPath() (filesystem-backed).');
+    }
+    const uuidToIntKey = opts.uuidToIntKey ?? DEFAULT_UUID_TO_INT_KEY;
+    const intToUuidKey = opts.intToUuidKey ?? DEFAULT_INT_TO_UUID_KEY;
+    const uuidToIntPath = storage.getBinaryBlobPath(uuidToIntKey);
+    const intToUuidPath = storage.getBinaryBlobPath(intToUuidKey);
+    if (!uuidToIntPath || !intToUuidPath) {
+        throw new Error(`openOrCreateBinaryIdMapper: getBinaryBlobPath returned null for ` +
+            `${uuidToIntKey} or ${intToUuidKey}`);
+    }
+    const bindings = loadNativeModule();
+    const NativeBinaryIdMapper = bindings.NativeBinaryIdMapper;
+    if (!NativeBinaryIdMapper) {
+        throw new Error('NativeBinaryIdMapper binding missing from cor native module — ' +
+            'this build of cor is older than the BinaryIdMapper feature');
+    }
+    const config = {
+        uuidToIntPath,
+        intToUuidPath,
+        intToUuidSize: opts.intToUuidSize ?? DEFAULT_FILE_SIZE,
+        uuidToIntSize: opts.uuidToIntSize ?? DEFAULT_FILE_SIZE,
+        bucketCapacity: opts.bucketCapacity ?? 16,
+        maxGlobalDepth: opts.maxGlobalDepth ?? 28,
+        idSpace: opts.idSpace ?? 'u64',
+    };
+    // Both files must exist together (paired write semantics). A
+    // half-present state is crash corruption surfaced as an error,
+    // never silently recreated.
+    let mapper;
+    let created;
+    const uuidFileExists = existsSync(uuidToIntPath);
+    const intFileExists = existsSync(intToUuidPath);
+    if (uuidFileExists && intFileExists) {
+        mapper = NativeBinaryIdMapper.openExisting(config);
+        created = false;
+    }
+    else if (!uuidFileExists && !intFileExists) {
+        mapper = NativeBinaryIdMapper.create(config);
+        created = true;
+    }
+    else {
+        throw new Error(`openOrCreateBinaryIdMapper: half-present file pair — ` +
+            `${uuidToIntKey} ${uuidFileExists ? 'exists' : 'missing'}, ` +
+            `${intToUuidKey} ${intFileExists ? 'exists' : 'missing'}. ` +
+            `Refusing to silently recreate; investigate manually.`);
+    }
+    return {
+        mapper,
+        uuidToIntPath,
+        intToUuidPath,
+        idSpace: mapper.idSpace(),
+        created,
+    };
+}
+//# sourceMappingURL=binaryIdMapperFactory.js.map

package/dist/utils/collation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module utils/collation
+ * @description Deterministic string ordering for cor's TypeScript fallback paths,
+ * byte-for-byte identical to `@soulcraft/brainy`'s `compareCodePoints` and to the
+ * native (Rust) column-store / aggregation engine.
+ *
+ * Strings are compared by **UTF-8 byte order**, which equals Unicode code-point order
+ * and Rust's `str::cmp` (`as_bytes().cmp()`). This is deterministic across
+ * environments (unlike `localeCompare`, whose default-locale ordering varies by
+ * OS / Node / ICU build) and consistent with the native engine, so sorted query
+ * results are identical with or without the native plugin.
+ *
+ * Cor keeps a local copy (rather than importing brainy's) so it never depends on
+ * a brainy internal export and is guaranteed available against any supported brainy
+ * version. The implementation must stay in lockstep with brainy `src/utils/collation.ts`.
+ * See `docs/ADR-001`.
+ */
+/**
+ * @description Compare two strings by UTF-8 byte order (== Unicode code-point order
+ * == Rust `str::cmp`). Use instead of `String.localeCompare` and the `<`/`>`
+ * operators (which compare UTF-16 code units and diverge for supplementary-plane
+ * characters) wherever ordering must match the native engine or be deterministic.
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns Negative if `a < b`, positive if `a > b`, `0` if equal — by UTF-8 byte order.
+ * @example
+ * ['b', 'A', 'a'].sort(compareCodePoints) // ['A', 'a', 'b']  (A=65, a=97, b=98)
+ */
+export declare function compareCodePoints(a: string, b: string): number;
+//# sourceMappingURL=collation.d.ts.map

package/dist/utils/collation.js

@@ -0,0 +1,40 @@
+/**
+ * @module utils/collation
+ * @description Deterministic string ordering for cor's TypeScript fallback paths,
+ * byte-for-byte identical to `@soulcraft/brainy`'s `compareCodePoints` and to the
+ * native (Rust) column-store / aggregation engine.
+ *
+ * Strings are compared by **UTF-8 byte order**, which equals Unicode code-point order
+ * and Rust's `str::cmp` (`as_bytes().cmp()`). This is deterministic across
+ * environments (unlike `localeCompare`, whose default-locale ordering varies by
+ * OS / Node / ICU build) and consistent with the native engine, so sorted query
+ * results are identical with or without the native plugin.
+ *
+ * Cor keeps a local copy (rather than importing brainy's) so it never depends on
+ * a brainy internal export and is guaranteed available against any supported brainy
+ * version. The implementation must stay in lockstep with brainy `src/utils/collation.ts`.
+ * See `docs/ADR-001`.
+ */
+const utf8 = new TextEncoder();
+/**
+ * @description Compare two strings by UTF-8 byte order (== Unicode code-point order
+ * == Rust `str::cmp`). Use instead of `String.localeCompare` and the `<`/`>`
+ * operators (which compare UTF-16 code units and diverge for supplementary-plane
+ * characters) wherever ordering must match the native engine or be deterministic.
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns Negative if `a < b`, positive if `a > b`, `0` if equal — by UTF-8 byte order.
+ * @example
+ * ['b', 'A', 'a'].sort(compareCodePoints) // ['A', 'a', 'b']  (A=65, a=97, b=98)
+ */
+export function compareCodePoints(a, b) {
+    const ea = utf8.encode(a);
+    const eb = utf8.encode(b);
+    const len = ea.length < eb.length ? ea.length : eb.length;
+    for (let i = 0; i < len; i++) {
+        if (ea[i] !== eb[i])
+            return ea[i] - eb[i];
+    }
+    return ea.length - eb.length;
+}
+//# sourceMappingURL=collation.js.map