@rybosome/tspice 0.0.3 → 0.0.8

package/backend-wasm/dist/domains/ek.js

@@ -0,0 +1,543 @@
+import { assertSpiceInt32, assertSpiceInt32NonNegative } from "#backend-contract";
+import { WASM_ERR_MAX_BYTES, WASM_MAX_ALLOC_BYTES, withAllocs, withMalloc } from "../codec/alloc.js";
+import { throwWasmSpiceError } from "../codec/errors.js";
+import { readFixedWidthCString, writeUtf8CString } from "../codec/strings.js";
+import { resolveKernelPath } from "../runtime/fs.js";
+const UTF8_ENCODER = new TextEncoder();
+const INT32_MAX = 2_147_483_647;
+// Keep parity with the Node backend's `kMaxEkArrayLen`.
+const kMaxEkArrayLen = 1_000_000;
+// Prevent pathological `vallen` from forcing enormous allocations.
+const kMaxEkVallenBytes = 1_000_000;
+const EK_ONLY = ["EK"];
+function utf8TruncateLen(encoded, maxBytes) {
+    if (maxBytes <= 0) {
+        return 0;
+    }
+    if (encoded.length <= maxBytes) {
+        return encoded.length;
+    }
+    // Truncate to a UTF-8 boundary so we don't split a multi-byte codepoint.
+    //
+    // We only need to inspect the last few bytes because UTF-8 sequences are
+    // at most 4 bytes long.
+    let len = maxBytes;
+    let start = len - 1;
+    // Walk backwards over continuation bytes (10xxxxxx).
+    while (start >= 0 && (encoded[start] & 0b1100_0000) === 0b1000_0000) {
+        start--;
+    }
+    if (start < 0) {
+        // The slice starts mid-codepoint (e.g. maxBytes < first codepoint length).
+        return 0;
+    }
+    const lead = encoded[start];
+    let seqLen;
+    if ((lead & 0b1000_0000) === 0) {
+        seqLen = 1;
+    }
+    else if ((lead & 0b1110_0000) === 0b1100_0000) {
+        seqLen = 2;
+    }
+    else if ((lead & 0b1111_0000) === 0b1110_0000) {
+        seqLen = 3;
+    }
+    else if ((lead & 0b1111_1000) === 0b1111_0000) {
+        seqLen = 4;
+    }
+    else {
+        // Shouldn't happen for TextEncoder output; treat as a single byte.
+        seqLen = 1;
+    }
+    // If the last codepoint would extend past our slice, drop it.
+    if (start + seqLen > len) {
+        len = start;
+    }
+    return len;
+}
+function writeFixedWidthStringArray(module, ptr, stride, values) {
+    const totalBytes = stride * values.length;
+    module.HEAPU8.fill(0, ptr, ptr + totalBytes);
+    const maxBytes = Math.max(0, stride - 1);
+    let offset = ptr;
+    for (const value of values) {
+        const encoded = UTF8_ENCODER.encode(value);
+        const copyLen = utf8TruncateLen(encoded, maxBytes);
+        if (copyLen > 0) {
+            module.HEAPU8.set(encoded.subarray(0, copyLen), offset);
+        }
+        module.HEAPU8[offset + copyLen] = 0;
+        offset += stride;
+    }
+}
+function sumEntszsChecked(entszs, nlflgs, context) {
+    if (entszs.length !== nlflgs.length) {
+        throw new RangeError(`${context}: expected entszs.length === nlflgs.length`);
+    }
+    let sum = 0;
+    for (let i = 0; i < entszs.length; i++) {
+        const isNull = nlflgs[i];
+        if (typeof isNull !== "boolean") {
+            throw new TypeError(`${context}: expected nlflgs[${i}] to be a boolean`);
+        }
+        // CSPICE semantics (keep parity with the C shim + Node addon):
+        // - NULL entries may have entszs[i] == 0 (and are allowed to be any value >= 0)
+        // - non-NULL entries must have entszs[i] >= 1
+        assertSpiceInt32(entszs[i], `${context}(entszs[${i}])`, { min: isNull ? 0 : 1 });
+        sum += entszs[i];
+        if (sum > INT32_MAX) {
+            throw new RangeError(`${context}: sum(entszs) overflow (max ${INT32_MAX})`);
+        }
+        if (sum > kMaxEkArrayLen) {
+            throw new RangeError(`${context}: sum(entszs) must be <= ${kMaxEkArrayLen}`);
+        }
+    }
+    return sum;
+}
+function readHeapI32(module, idx, context) {
+    const heap = module.HEAP32;
+    const v = heap[idx];
+    if (v === undefined) {
+        throw new RangeError(`${context}: out-of-bounds HEAP32 read (idx=${idx}, heapLen=${heap.length})`);
+    }
+    return v;
+}
+function callVoidHandle(module, fn, handle) {
+    withMalloc(module, WASM_ERR_MAX_BYTES, (errPtr) => {
+        const code = fn(handle, errPtr, WASM_ERR_MAX_BYTES);
+        if (code !== 0) {
+            throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+        }
+    });
+}
+/** Create an {@link EkApi} implementation backed by a WASM Emscripten module. */
+export function createEkApi(module, spiceHandles) {
+    const TABLE_NAME_MAX_BYTES = 256;
+    const api = {
+        ekopr: (path) => {
+            const resolved = resolveKernelPath(path);
+            const pathPtr = writeUtf8CString(module, resolved);
+            try {
+                const nativeHandle = withAllocs(module, [4, WASM_ERR_MAX_BYTES], (outHandlePtr, errPtr) => {
+                    module.HEAP32[outHandlePtr >> 2] = 0;
+                    const code = module._tspice_ekopr(pathPtr, outHandlePtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                    return readHeapI32(module, outHandlePtr >> 2, "ekopr(outHandlePtr)");
+                });
+                return spiceHandles.register("EK", nativeHandle);
+            }
+            finally {
+                module._free(pathPtr);
+            }
+        },
+        ekopw: (path) => {
+            const resolved = resolveKernelPath(path);
+            const pathPtr = writeUtf8CString(module, resolved);
+            try {
+                const nativeHandle = withAllocs(module, [4, WASM_ERR_MAX_BYTES], (outHandlePtr, errPtr) => {
+                    module.HEAP32[outHandlePtr >> 2] = 0;
+                    const code = module._tspice_ekopw(pathPtr, outHandlePtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                    return readHeapI32(module, outHandlePtr >> 2, "ekopw(outHandlePtr)");
+                });
+                return spiceHandles.register("EK", nativeHandle);
+            }
+            finally {
+                module._free(pathPtr);
+            }
+        },
+        ekopn: (path, ifname, ncomch) => {
+            assertSpiceInt32NonNegative(ncomch, "ekopn(ncomch)");
+            const resolved = resolveKernelPath(path);
+            // `ekopn_c` creates the output file via C stdio, so we must ensure the
+            // directory exists in the Emscripten FS.
+            const dir = resolved.split("/").slice(0, -1).join("/") || "/";
+            if (dir && dir !== "/") {
+                module.FS.mkdirTree(dir);
+            }
+            const pathPtr = writeUtf8CString(module, resolved);
+            const ifnamePtr = writeUtf8CString(module, ifname);
+            try {
+                const nativeHandle = withAllocs(module, [4, WASM_ERR_MAX_BYTES], (outHandlePtr, errPtr) => {
+                    module.HEAP32[outHandlePtr >> 2] = 0;
+                    const code = module._tspice_ekopn(pathPtr, ifnamePtr, ncomch, outHandlePtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                    return readHeapI32(module, outHandlePtr >> 2, "ekopn(outHandlePtr)");
+                });
+                return spiceHandles.register("EK", nativeHandle);
+            }
+            finally {
+                module._free(ifnamePtr);
+                module._free(pathPtr);
+            }
+        },
+        ekcls: (handle) => spiceHandles.close(handle, EK_ONLY, (entry) => callVoidHandle(module, module._tspice_ekcls, entry.nativeHandle), "ekcls"),
+        ekntab: () => withAllocs(module, [4, WASM_ERR_MAX_BYTES], (outNPtr, errPtr) => {
+            module.HEAP32[outNPtr >> 2] = 0;
+            const code = module._tspice_ekntab(outNPtr, errPtr, WASM_ERR_MAX_BYTES);
+            if (code !== 0) {
+                throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+            }
+            const n = readHeapI32(module, outNPtr >> 2, "ekntab(outNPtr)");
+            assertSpiceInt32NonNegative(n, "ekntab()");
+            return n;
+        }),
+        ektnam: (n) => {
+            assertSpiceInt32NonNegative(n, "ektnam(n)");
+            return withAllocs(module, [TABLE_NAME_MAX_BYTES, WASM_ERR_MAX_BYTES], (outNamePtr, errPtr) => {
+                module.HEAPU8[outNamePtr] = 0;
+                const code = module._tspice_ektnam(n, outNamePtr, TABLE_NAME_MAX_BYTES, errPtr, WASM_ERR_MAX_BYTES);
+                if (code !== 0) {
+                    throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                }
+                return readFixedWidthCString(module, outNamePtr, TABLE_NAME_MAX_BYTES);
+            });
+        },
+        eknseg: (handle) => {
+            const nativeHandle = spiceHandles.lookup(handle, EK_ONLY, "eknseg").nativeHandle;
+            return withAllocs(module, [4, WASM_ERR_MAX_BYTES], (outNsegPtr, errPtr) => {
+                module.HEAP32[outNsegPtr >> 2] = 0;
+                const code = module._tspice_eknseg(nativeHandle, outNsegPtr, errPtr, WASM_ERR_MAX_BYTES);
+                if (code !== 0) {
+                    throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                }
+                const nseg = readHeapI32(module, outNsegPtr >> 2, "eknseg(outNsegPtr)");
+                assertSpiceInt32NonNegative(nseg, "eknseg(handle)");
+                return nseg;
+            });
+        },
+        ekfind: (query) => {
+            const queryPtr = writeUtf8CString(module, query);
+            const outErrmsgMaxBytes = WASM_ERR_MAX_BYTES;
+            try {
+                return withAllocs(module, [4, 4, outErrmsgMaxBytes, WASM_ERR_MAX_BYTES], (outNmrowsPtr, outErrorPtr, outErrmsgPtr, errPtr) => {
+                    module.HEAP32[outNmrowsPtr >> 2] = 0;
+                    module.HEAP32[outErrorPtr >> 2] = 0;
+                    module.HEAPU8[outErrmsgPtr] = 0;
+                    const code = module._tspice_ekfind(queryPtr, outErrmsgMaxBytes, outNmrowsPtr, outErrorPtr, outErrmsgPtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                    const error = readHeapI32(module, outErrorPtr >> 2, "ekfind(outErrorPtr)") !== 0;
+                    if (error) {
+                        return { ok: false, errmsg: readFixedWidthCString(module, outErrmsgPtr, outErrmsgMaxBytes) };
+                    }
+                    const nmrows = readHeapI32(module, outNmrowsPtr >> 2, "ekfind(outNmrowsPtr)");
+                    return { ok: true, nmrows };
+                });
+            }
+            finally {
+                module._free(queryPtr);
+            }
+        },
+        ekgc: (selidx, row, elment) => {
+            assertSpiceInt32NonNegative(selidx, "ekgc(selidx)");
+            assertSpiceInt32NonNegative(row, "ekgc(row)");
+            assertSpiceInt32NonNegative(elment, "ekgc(elment)");
+            // Keep parity with backend-node's `kOutMaxBytes`: large enough to avoid truncating
+            // before CSPICE's own ~1024-char EK string limit (1024 + NUL).
+            const outMaxBytes = WASM_ERR_MAX_BYTES;
+            return withAllocs(module, [outMaxBytes, 4, 4, WASM_ERR_MAX_BYTES], (outCdataPtr, outNullPtr, outFoundPtr, errPtr) => {
+                module.HEAPU8[outCdataPtr] = 0;
+                module.HEAP32[outNullPtr >> 2] = 0;
+                module.HEAP32[outFoundPtr >> 2] = 0;
+                const code = module._tspice_ekgc(selidx, row, elment, outCdataPtr, outMaxBytes, outNullPtr, outFoundPtr, errPtr, WASM_ERR_MAX_BYTES);
+                if (code !== 0) {
+                    throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                }
+                const found = readHeapI32(module, outFoundPtr >> 2, "ekgc(outFoundPtr)") !== 0;
+                if (!found) {
+                    return { found: false };
+                }
+                const isNull = readHeapI32(module, outNullPtr >> 2, "ekgc(outNullPtr)") !== 0;
+                if (isNull) {
+                    return { found: true, isNull: true };
+                }
+                return {
+                    found: true,
+                    isNull: false,
+                    value: readFixedWidthCString(module, outCdataPtr, outMaxBytes),
+                };
+            });
+        },
+        ekgd: (selidx, row, elment) => {
+            assertSpiceInt32NonNegative(selidx, "ekgd(selidx)");
+            assertSpiceInt32NonNegative(row, "ekgd(row)");
+            assertSpiceInt32NonNegative(elment, "ekgd(elment)");
+            return withAllocs(module, [8, 4, 4, WASM_ERR_MAX_BYTES], (outDdataPtr, outNullPtr, outFoundPtr, errPtr) => {
+                module.HEAPF64[outDdataPtr >> 3] = 0;
+                module.HEAP32[outNullPtr >> 2] = 0;
+                module.HEAP32[outFoundPtr >> 2] = 0;
+                const code = module._tspice_ekgd(selidx, row, elment, outDdataPtr, outNullPtr, outFoundPtr, errPtr, WASM_ERR_MAX_BYTES);
+                if (code !== 0) {
+                    throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                }
+                const found = readHeapI32(module, outFoundPtr >> 2, "ekgd(outFoundPtr)") !== 0;
+                if (!found) {
+                    return { found: false };
+                }
+                const isNull = readHeapI32(module, outNullPtr >> 2, "ekgd(outNullPtr)") !== 0;
+                if (isNull) {
+                    return { found: true, isNull: true };
+                }
+                const value = module.HEAPF64[outDdataPtr >> 3];
+                return { found: true, isNull: false, value };
+            });
+        },
+        ekgi: (selidx, row, elment) => {
+            assertSpiceInt32NonNegative(selidx, "ekgi(selidx)");
+            assertSpiceInt32NonNegative(row, "ekgi(row)");
+            assertSpiceInt32NonNegative(elment, "ekgi(elment)");
+            return withAllocs(module, [4, 4, 4, WASM_ERR_MAX_BYTES], (outIdataPtr, outNullPtr, outFoundPtr, errPtr) => {
+                module.HEAP32[outIdataPtr >> 2] = 0;
+                module.HEAP32[outNullPtr >> 2] = 0;
+                module.HEAP32[outFoundPtr >> 2] = 0;
+                const code = module._tspice_ekgi(selidx, row, elment, outIdataPtr, outNullPtr, outFoundPtr, errPtr, WASM_ERR_MAX_BYTES);
+                if (code !== 0) {
+                    throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                }
+                const found = readHeapI32(module, outFoundPtr >> 2, "ekgi(outFoundPtr)") !== 0;
+                if (!found) {
+                    return { found: false };
+                }
+                const isNull = readHeapI32(module, outNullPtr >> 2, "ekgi(outNullPtr)") !== 0;
+                if (isNull) {
+                    return { found: true, isNull: true };
+                }
+                const value = readHeapI32(module, outIdataPtr >> 2, "ekgi(outIdataPtr)");
+                return { found: true, isNull: false, value };
+            });
+        },
+        ekifld: (handle, tabnam, nrows, cnames, decls) => {
+            assertSpiceInt32(nrows, "ekifld(nrows)", { min: 1 });
+            // Hard cap to defend against pathological `nrows` values that would otherwise trigger
+            // massive native allocations (e.g. rcptrs).
+            if (nrows > kMaxEkArrayLen) {
+                throw new RangeError(`ekifld(): expected nrows <= ${kMaxEkArrayLen}`);
+            }
+            if (cnames.length === 0) {
+                throw new RangeError("ekifld(cnames): expected cnames.length > 0");
+            }
+            if (decls.length !== cnames.length) {
+                throw new RangeError("ekifld(decls): expected decls.length === cnames.length");
+            }
+            const ncols = cnames.length;
+            let cnamln = 2;
+            for (const s of cnames) {
+                cnamln = Math.max(cnamln, UTF8_ENCODER.encode(s).length + 1);
+            }
+            let declen = 2;
+            for (const s of decls) {
+                declen = Math.max(declen, UTF8_ENCODER.encode(s).length + 1);
+            }
+            const nativeHandle = spiceHandles.lookup(handle, EK_ONLY, "ekifld").nativeHandle;
+            const tabnamPtr = writeUtf8CString(module, tabnam);
+            try {
+                return withAllocs(module, [ncols * cnamln, ncols * declen, 4, nrows * 4, WASM_ERR_MAX_BYTES], (cnamesPtr, declsPtr, outSegnoPtr, outRcptrsPtr, errPtr) => {
+                    writeFixedWidthStringArray(module, cnamesPtr, cnamln, cnames);
+                    writeFixedWidthStringArray(module, declsPtr, declen, decls);
+                    module.HEAP32[outSegnoPtr >> 2] = 0;
+                    const code = module._tspice_ekifld(nativeHandle, tabnamPtr, ncols, nrows, cnamln, cnamesPtr, declen, declsPtr, outSegnoPtr, outRcptrsPtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                    const segno = readHeapI32(module, outSegnoPtr >> 2, "ekifld(outSegnoPtr)");
+                    const rcptrsView = module.HEAP32.subarray(outRcptrsPtr >> 2, (outRcptrsPtr >> 2) + nrows);
+                    return { segno, rcptrs: Array.from(rcptrsView) };
+                });
+            }
+            finally {
+                module._free(tabnamPtr);
+            }
+        },
+        ekacli: (handle, segno, column, ivals, entszs, nlflgs, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekacli(segno)");
+            const nrows = rcptrs.length;
+            if (entszs.length !== nrows || nlflgs.length !== nrows) {
+                throw new RangeError("ekacli(): expected entszs/nlflgs/rcptrs to have the same length");
+            }
+            if (nrows === 0) {
+                throw new RangeError("ekacli(): expected rcptrs.length > 0");
+            }
+            if (nrows > kMaxEkArrayLen) {
+                throw new RangeError(`ekacli(): expected nrows <= ${kMaxEkArrayLen}`);
+            }
+            const required = sumEntszsChecked(entszs, nlflgs, "ekacli()");
+            if (ivals.length !== required) {
+                throw new RangeError("ekacli(): expected ivals.length === sum(entszs)");
+            }
+            for (let i = 0; i < ivals.length; i++) {
+                assertSpiceInt32(ivals[i], `ekacli(ivals[${i}])`);
+            }
+            for (let i = 0; i < rcptrs.length; i++) {
+                assertSpiceInt32(rcptrs[i], `ekacli(rcptrs[${i}])`);
+            }
+            const nativeHandle = spiceHandles.lookup(handle, EK_ONLY, "ekacli").nativeHandle;
+            const columnPtr = writeUtf8CString(module, column);
+            // `withAllocs()` rejects 0-byte allocations; when all rows are NULL,
+            // `sum(entszs) === 0` and the values buffer can be empty.
+            const ivalsBytes = Math.max(1, ivals.length) * 4;
+            try {
+                return withAllocs(module, [ivalsBytes, nrows * 4, nrows * 4, nrows * 4, WASM_ERR_MAX_BYTES], (ivalsPtr, entszsPtr, nlflgsPtr, rcptrsPtr, errPtr) => {
+                    module.HEAP32.set(Int32Array.from(ivals), ivalsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(entszs), entszsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(nlflgs.map((b) => (b ? 1 : 0))), nlflgsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(rcptrs), rcptrsPtr >> 2);
+                    const code = module._tspice_ekacli(nativeHandle, segno, columnPtr, nrows, ivalsPtr, ivals.length, entszsPtr, nlflgsPtr, rcptrsPtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                });
+            }
+            finally {
+                module._free(columnPtr);
+            }
+        },
+        ekacld: (handle, segno, column, dvals, entszs, nlflgs, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekacld(segno)");
+            const nrows = rcptrs.length;
+            if (entszs.length !== nrows || nlflgs.length !== nrows) {
+                throw new RangeError("ekacld(): expected entszs/nlflgs/rcptrs to have the same length");
+            }
+            if (nrows === 0) {
+                throw new RangeError("ekacld(): expected rcptrs.length > 0");
+            }
+            if (nrows > kMaxEkArrayLen) {
+                throw new RangeError(`ekacld(): expected nrows <= ${kMaxEkArrayLen}`);
+            }
+            const required = sumEntszsChecked(entszs, nlflgs, "ekacld()");
+            if (dvals.length !== required) {
+                throw new RangeError("ekacld(): expected dvals.length === sum(entszs)");
+            }
+            for (let i = 0; i < dvals.length; i++) {
+                if (!Number.isFinite(dvals[i])) {
+                    throw new TypeError(`ekacld(dvals[${i}]) must be a finite number`);
+                }
+            }
+            for (let i = 0; i < rcptrs.length; i++) {
+                assertSpiceInt32(rcptrs[i], `ekacld(rcptrs[${i}])`);
+            }
+            const nativeHandle = spiceHandles.lookup(handle, EK_ONLY, "ekacld").nativeHandle;
+            const columnPtr = writeUtf8CString(module, column);
+            // `withAllocs()` rejects 0-byte allocations; when all rows are NULL,
+            // `sum(entszs) === 0` and the values buffer can be empty.
+            const dvalsBytes = Math.max(1, dvals.length) * 8;
+            try {
+                return withAllocs(module, [dvalsBytes, nrows * 4, nrows * 4, nrows * 4, WASM_ERR_MAX_BYTES], (dvalsPtr, entszsPtr, nlflgsPtr, rcptrsPtr, errPtr) => {
+                    module.HEAPF64.set(Float64Array.from(dvals), dvalsPtr >> 3);
+                    module.HEAP32.set(Int32Array.from(entszs), entszsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(nlflgs.map((b) => (b ? 1 : 0))), nlflgsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(rcptrs), rcptrsPtr >> 2);
+                    const code = module._tspice_ekacld(nativeHandle, segno, columnPtr, nrows, dvalsPtr, dvals.length, entszsPtr, nlflgsPtr, rcptrsPtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                });
+            }
+            finally {
+                module._free(columnPtr);
+            }
+        },
+        ekaclc: (handle, segno, column, cvals, entszs, nlflgs, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekaclc(segno)");
+            const nrows = rcptrs.length;
+            if (entszs.length !== nrows || nlflgs.length !== nrows) {
+                throw new RangeError("ekaclc(): expected entszs/nlflgs/rcptrs to have the same length");
+            }
+            if (nrows === 0) {
+                throw new RangeError("ekaclc(): expected rcptrs.length > 0");
+            }
+            if (nrows > kMaxEkArrayLen) {
+                throw new RangeError(`ekaclc(): expected nrows <= ${kMaxEkArrayLen}`);
+            }
+            const required = sumEntszsChecked(entszs, nlflgs, "ekaclc()");
+            if (cvals.length !== required) {
+                throw new RangeError("ekaclc(): expected cvals.length === sum(entszs)");
+            }
+            const nvals = cvals.length;
+            let vallen = 1;
+            for (const s of cvals) {
+                const bytes = UTF8_ENCODER.encode(s).length + 1;
+                if (bytes > kMaxEkVallenBytes) {
+                    throw new RangeError(`ekaclc(): value byte length exceeds cap (${kMaxEkVallenBytes})`);
+                }
+                vallen = Math.max(vallen, bytes);
+            }
+            if (nvals > kMaxEkArrayLen) {
+                throw new RangeError(`ekaclc(): expected nvals <= ${kMaxEkArrayLen}`);
+            }
+            if (!Number.isSafeInteger(nvals * vallen)) {
+                throw new RangeError("ekaclc(): cvals buffer size overflow");
+            }
+            const cvalsMaxBytes = nvals * vallen;
+            if (cvalsMaxBytes > WASM_MAX_ALLOC_BYTES) {
+                throw new RangeError(`ekaclc(): cvals buffer too large (${cvalsMaxBytes} bytes)`);
+            }
+            const nativeHandle = spiceHandles.lookup(handle, EK_ONLY, "ekaclc").nativeHandle;
+            const columnPtr = writeUtf8CString(module, column);
+            // `withAllocs()` rejects 0-byte allocations; when all rows are NULL,
+            // `sum(entszs) === 0` and the values buffer can be empty.
+            const cvalsAllocBytes = Math.max(1, cvalsMaxBytes);
+            try {
+                return withAllocs(module, [cvalsAllocBytes, nrows * 4, nrows * 4, nrows * 4, WASM_ERR_MAX_BYTES], (cvalsPtr, entszsPtr, nlflgsPtr, rcptrsPtr, errPtr) => {
+                    writeFixedWidthStringArray(module, cvalsPtr, vallen, cvals);
+                    module.HEAP32.set(Int32Array.from(entszs), entszsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(nlflgs.map((b) => (b ? 1 : 0))), nlflgsPtr >> 2);
+                    module.HEAP32.set(Int32Array.from(rcptrs), rcptrsPtr >> 2);
+                    const code = module._tspice_ekaclc(nativeHandle, segno, columnPtr, nrows, nvals, vallen, cvalsMaxBytes, cvalsPtr, entszsPtr, nlflgsPtr, rcptrsPtr, errPtr, WASM_ERR_MAX_BYTES);
+                    if (code !== 0) {
+                        throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                    }
+                });
+            }
+            finally {
+                module._free(columnPtr);
+            }
+        },
+        ekffld: (handle, segno, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekffld(segno)");
+            const nrows = rcptrs.length;
+            if (nrows === 0) {
+                throw new RangeError("ekffld(rcptrs): expected rcptrs.length > 0");
+            }
+            if (nrows > kMaxEkArrayLen) {
+                throw new RangeError(`ekffld(): expected rcptrs.length <= ${kMaxEkArrayLen}`);
+            }
+            for (let i = 0; i < nrows; i++) {
+                assertSpiceInt32(rcptrs[i], `ekffld(rcptrs[${i}])`);
+            }
+            const nativeHandle = spiceHandles.lookup(handle, EK_ONLY, "ekffld").nativeHandle;
+            return withAllocs(module, [rcptrs.length * 4, WASM_ERR_MAX_BYTES], (rcptrsPtr, errPtr) => {
+                module.HEAP32.set(Int32Array.from(rcptrs), rcptrsPtr >> 2);
+                const code = module._tspice_ekffld(nativeHandle, segno, rcptrsPtr, errPtr, WASM_ERR_MAX_BYTES);
+                if (code !== 0) {
+                    throwWasmSpiceError(module, errPtr, WASM_ERR_MAX_BYTES, code);
+                }
+            });
+        },
+    };
+    Object.defineProperty(api, "__debugOpenHandleCount", {
+        value: () => {
+            const entries = spiceHandles.__entries?.();
+            if (!entries) {
+                return spiceHandles.size();
+            }
+            let count = 0;
+            for (const [, entry] of entries) {
+                if (entry.kind === "EK") {
+                    count++;
+                }
+            }
+            return count;
+        },
+        enumerable: false,
+    });
+    return api;
+}
+//# sourceMappingURL=ek.js.map

package/backend-wasm/dist/domains/ephemeris.d.ts

@@ -1,4 +1,7 @@
 import type { EphemerisApi } from "#backend-contract";
 import type { EmscriptenModule } from "../lowlevel/exports.js";
-export declare function createEphemerisApi(module: EmscriptenModule): EphemerisApi;
+import type { SpiceHandleRegistry } from "../runtime/spice-handles.js";
+import type { VirtualOutputRegistry } from "../runtime/virtual-outputs.js";
+/** Create an {@link EphemerisApi} implementation backed by a WASM Emscripten module. */
+export declare function createEphemerisApi(module: EmscriptenModule, handles: SpiceHandleRegistry, virtualOutputs: VirtualOutputRegistry): EphemerisApi;
 //# sourceMappingURL=ephemeris.d.ts.map