@rybosome/tspice 0.0.3 → 0.0.8

package/backend-node/dist/domains/dsk.js

@@ -0,0 +1,108 @@
+import { invariant } from "#core";
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+const DAS_BACKED = ["DAS", "DLA"];
+function assertDlaDescriptor(value, context) {
+    invariant(typeof value === "object" && value !== null, `${context}: expected an object`);
+    const obj = value;
+    for (const key of [
+        "bwdptr",
+        "fwdptr",
+        "ibase",
+        "isize",
+        "dbase",
+        "dsize",
+        "cbase",
+        "csize",
+    ]) {
+        const v = obj[key];
+        invariant(typeof v === "number" &&
+            Number.isInteger(v) &&
+            v >= I32_MIN &&
+            v <= I32_MAX, `${context}: expected ${key} to be a 32-bit signed integer`);
+    }
+}
+function assertI32(value, context) {
+    invariant(typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= I32_MIN &&
+        value <= I32_MAX, `${context}: expected a 32-bit signed integer`);
+}
+function assertFiniteNumber(value, context) {
+    invariant(typeof value === "number" && Number.isFinite(value), `${context}: expected a finite number`);
+}
+function normalizeDskDescriptor(value, context) {
+    invariant(typeof value === "object" && value !== null, `${context}: expected an object`);
+    const obj = value;
+    for (const k of ["surfce", "center", "dclass", "dtype", "frmcde", "corsys"]) {
+        assertI32(obj[k], `${context}.${k}`);
+    }
+    invariant(Array.isArray(obj.corpar), `${context}.corpar: expected an array`);
+    invariant(obj.corpar.length === 10, `${context}.corpar: expected length 10`);
+    for (let i = 0; i < obj.corpar.length; i++) {
+        assertFiniteNumber(obj.corpar[i], `${context}.corpar[${i}]`);
+    }
+    for (const k of [
+        "co1min",
+        "co1max",
+        "co2min",
+        "co2max",
+        "co3min",
+        "co3max",
+        "start",
+        "stop",
+    ]) {
+        assertFiniteNumber(obj[k], `${context}.${k}`);
+    }
+    return obj;
+}
+function normalizeDskType2Bookkeeping(value, context) {
+    invariant(typeof value === "object" && value !== null, `${context}: expected an object`);
+    const obj = value;
+    for (const k of ["nv", "np", "nvxtot", "cgscal", "vtxnpl", "voxnpt", "voxnpl"]) {
+        assertI32(obj[k], `${context}.${k}`);
+    }
+    invariant(Array.isArray(obj.vtxbds), `${context}.vtxbds: expected an array`);
+    invariant(obj.vtxbds.length === 3, `${context}.vtxbds: expected length 3`);
+    for (let axis = 0; axis < 3; axis++) {
+        const pair = obj.vtxbds[axis];
+        invariant(Array.isArray(pair), `${context}.vtxbds[${axis}]: expected an array`);
+        invariant(pair.length === 2, `${context}.vtxbds[${axis}]: expected length 2`);
+        assertFiniteNumber(pair[0], `${context}.vtxbds[${axis}][0]`);
+        assertFiniteNumber(pair[1], `${context}.vtxbds[${axis}][1]`);
+    }
+    assertFiniteNumber(obj.voxsiz, `${context}.voxsiz`);
+    invariant(Array.isArray(obj.voxori), `${context}.voxori: expected an array`);
+    invariant(obj.voxori.length === 3, `${context}.voxori: expected length 3`);
+    for (let i = 0; i < 3; i++) {
+        assertFiniteNumber(obj.voxori[i], `${context}.voxori[${i}]`);
+    }
+    invariant(Array.isArray(obj.vgrext), `${context}.vgrext: expected an array`);
+    invariant(obj.vgrext.length === 3, `${context}.vgrext: expected length 3`);
+    for (let i = 0; i < 3; i++) {
+        assertI32(obj.vgrext[i], `${context}.vgrext[${i}]`);
+    }
+    return obj;
+}
+/** Create a {@link DskApi} implementation backed by the native Node addon. */
+export function createDskApi(native, handles) {
+    return {
+        dskobj: (dsk, bodids) => {
+            native.dskobj(dsk, bodids);
+        },
+        dsksrf: (dsk, bodyid, srfids) => {
+            native.dsksrf(dsk, bodyid, srfids);
+        },
+        dskgd: (handle, dladsc) => {
+            assertDlaDescriptor(dladsc, "dskgd(dladsc)");
+            const entry = handles.lookup(handle, DAS_BACKED, "dskgd");
+            return normalizeDskDescriptor(native.dskgd(entry.nativeHandle, dladsc), "dskgd()");
+        },
+        dskb02: (handle, dladsc) => {
+            assertDlaDescriptor(dladsc, "dskb02(dladsc)");
+            const entry = handles.lookup(handle, DAS_BACKED, "dskb02");
+            return normalizeDskType2Bookkeeping(native.dskb02(entry.nativeHandle, dladsc), "dskb02()");
+        },
+    };
+}
+//# sourceMappingURL=dsk.js.map

package/backend-node/dist/domains/ek.d.ts

@@ -0,0 +1,10 @@
+import { type EkApi } from "#backend-contract";
+import type { NativeAddon } from "../runtime/addon.js";
+import type { KernelStager } from "../runtime/kernel-staging.js";
+import type { SpiceHandleRegistry } from "../runtime/spice-handles.js";
+type NativeEkDeps = Pick<NativeAddon, "ekopr" | "ekopw" | "ekopn" | "ekcls" | "ekntab" | "ektnam" | "eknseg" | "ekfind" | "ekgc" | "ekgd" | "ekgi" | "ekifld" | "ekacli" | "ekacld" | "ekaclc" | "ekffld">;
+type KernelStagerEkDeps = Pick<KernelStager, "resolvePath">;
+/** Create an {@link EkApi} implementation backed by the native Node addon. */
+export declare function createEkApi<N extends NativeEkDeps, S extends KernelStagerEkDeps | undefined>(native: N, handles: SpiceHandleRegistry, stager?: S): EkApi;
+export {};
+//# sourceMappingURL=ek.d.ts.map

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

@@ -0,0 +1,100 @@
+import { assertSpiceInt32, assertSpiceInt32NonNegative, } from "#backend-contract";
+import { invariant } from "#core";
+const I32_MAX = 2147483647;
+const EK_ONLY = ["EK"];
+/** Create an {@link EkApi} implementation backed by the native Node addon. */
+export function createEkApi(native, handles, stager) {
+    const registerEkHandle = (nativeHandle, context) => {
+        invariant(typeof nativeHandle === "number", `Expected native backend ${context} to return a number handle`);
+        assertSpiceInt32(nativeHandle, `native backend ${context} handle`);
+        return handles.register("EK", nativeHandle);
+    };
+    const resolvePath = (path) => {
+        if (!stager)
+            return path;
+        try {
+            return stager.resolvePath(path);
+        }
+        catch (error) {
+            // Best-effort path resolution for *virtual-ish* kernel IDs only. If this
+            // was an OS path (or some unexpected staging invariant), surface the error.
+            const isVirtualish = path.startsWith("kernels/") || path.startsWith("/kernels/");
+            if (!isVirtualish) {
+                throw error;
+            }
+            return path;
+        }
+    };
+    const api = {
+        ekopr: (path) => registerEkHandle(native.ekopr(resolvePath(path)), "ekopr(path)"),
+        ekopw: (path) => registerEkHandle(native.ekopw(resolvePath(path)), "ekopw(path)"),
+        ekopn: (path, ifname, ncomch) => {
+            assertSpiceInt32NonNegative(ncomch, "ekopn(ncomch)");
+            return registerEkHandle(native.ekopn(resolvePath(path), ifname, ncomch), "ekopn(path,ifname,ncomch)");
+        },
+        ekcls: (handle) => handles.close(handle, EK_ONLY, (e) => native.ekcls(e.nativeHandle), "ekcls"),
+        ekntab: () => {
+            const n = native.ekntab();
+            invariant(typeof n === "number" &&
+                Number.isInteger(n) &&
+                n >= 0 &&
+                n <= I32_MAX, "Expected native backend ekntab() to return a non-negative 32-bit signed integer");
+            return n;
+        },
+        ektnam: (n) => {
+            assertSpiceInt32NonNegative(n, "ektnam(n)");
+            const name = native.ektnam(n);
+            invariant(typeof name === "string", "Expected native backend ektnam(n) to return a string");
+            return name;
+        },
+        eknseg: (handle) => {
+            const nseg = native.eknseg(handles.lookup(handle, EK_ONLY, "eknseg").nativeHandle);
+            invariant(typeof nseg === "number" &&
+                Number.isInteger(nseg) &&
+                nseg >= 0 &&
+                nseg <= I32_MAX, "Expected native backend eknseg(handle) to return a non-negative 32-bit signed integer");
+            return nseg;
+        },
+        ekfind: (query) => native.ekfind(query),
+        ekgc: (selidx, row, elment) => {
+            assertSpiceInt32NonNegative(selidx, "ekgc(selidx)");
+            assertSpiceInt32NonNegative(row, "ekgc(row)");
+            assertSpiceInt32NonNegative(elment, "ekgc(elment)");
+            return native.ekgc(selidx, row, elment);
+        },
+        ekgd: (selidx, row, elment) => {
+            assertSpiceInt32NonNegative(selidx, "ekgd(selidx)");
+            assertSpiceInt32NonNegative(row, "ekgd(row)");
+            assertSpiceInt32NonNegative(elment, "ekgd(elment)");
+            return native.ekgd(selidx, row, elment);
+        },
+        ekgi: (selidx, row, elment) => {
+            assertSpiceInt32NonNegative(selidx, "ekgi(selidx)");
+            assertSpiceInt32NonNegative(row, "ekgi(row)");
+            assertSpiceInt32NonNegative(elment, "ekgi(elment)");
+            return native.ekgi(selidx, row, elment);
+        },
+        ekifld: (handle, tabnam, nrows, cnames, decls) => {
+            assertSpiceInt32(nrows, "ekifld(nrows)", { min: 1 });
+            return native.ekifld(handles.lookup(handle, EK_ONLY, "ekifld").nativeHandle, tabnam, nrows, cnames, decls);
+        },
+        ekacli: (handle, segno, column, ivals, entszs, nlflgs, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekacli(segno)");
+            native.ekacli(handles.lookup(handle, EK_ONLY, "ekacli").nativeHandle, segno, column, ivals, entszs, nlflgs, rcptrs);
+        },
+        ekacld: (handle, segno, column, dvals, entszs, nlflgs, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekacld(segno)");
+            native.ekacld(handles.lookup(handle, EK_ONLY, "ekacld").nativeHandle, segno, column, dvals, entszs, nlflgs, rcptrs);
+        },
+        ekaclc: (handle, segno, column, cvals, entszs, nlflgs, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekaclc(segno)");
+            native.ekaclc(handles.lookup(handle, EK_ONLY, "ekaclc").nativeHandle, segno, column, cvals, entszs, nlflgs, rcptrs);
+        },
+        ekffld: (handle, segno, rcptrs) => {
+            assertSpiceInt32NonNegative(segno, "ekffld(segno)");
+            native.ekffld(handles.lookup(handle, EK_ONLY, "ekffld").nativeHandle, segno, rcptrs);
+        },
+    };
+    return api;
+}
+//# sourceMappingURL=ek.js.map

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

@@ -1,4 +1,8 @@
 import type { EphemerisApi } from "#backend-contract";
 import type { NativeAddon } from "../runtime/addon.js";
-export declare function createEphemerisApi(native: NativeAddon): EphemerisApi;
+import type { KernelStager } from "../runtime/kernel-staging.js";
+import type { SpiceHandleRegistry } from "../runtime/spice-handles.js";
+import type { VirtualOutputStager } from "../runtime/virtual-output-staging.js";
+/** Create an {@link EphemerisApi} implementation backed by the native Node addon. */
+export declare function createEphemerisApi(native: NativeAddon, handles: SpiceHandleRegistry, stager: KernelStager, outputs: VirtualOutputStager): EphemerisApi;
 //# sourceMappingURL=ephemeris.d.ts.map

package/backend-node/dist/domains/ephemeris.js

@@ -1,5 +1,29 @@
 import { invariant } from "#core";
-export function createEphemerisApi(native) {
+const I32_MAX = 2147483647;
+function assertSpkPackedDescriptor(out, label) {
+    invariant(Array.isArray(out) && out.length === 5, `Expected ${label} to be a length-5 array`);
+    for (let i = 0; i < 5; i++) {
+        const v = out[i];
+        invariant(typeof v === "number" && Number.isFinite(v), `Expected ${label}[${i}] to be a finite number`);
+    }
+}
+function isVirtualOutput(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === "virtual-output" &&
+        typeof value.path === "string");
+}
+function resolveSpkPath(outputs, file, context) {
+    if (typeof file === "string") {
+        return file;
+    }
+    // Be defensive: callers can cast.
+    invariant(isVirtualOutput(file), `${context}: expected VirtualOutput {kind:'virtual-output', path:string}`);
+    return outputs.resolvePathForSpice(file);
+}
+/** Create an {@link EphemerisApi} implementation backed by the native Node addon. */
+export function createEphemerisApi(native, handles, stager, outputs) {
+    const virtualOutputByHandle = new Map();
     return {
         spkezr: (target, et, ref, abcorr, observer) => {
             const out = native.spkezr(target, et, ref, abcorr, observer);
@@ -19,6 +43,131 @@ export function createEphemerisApi(native) {
             const result = { pos, lt: out.lt };
             return result;
         },
+        spkez: (target, et, ref, abcorr, observer) => {
+            const out = native.spkez(target, et, ref, abcorr, observer);
+            invariant(out && typeof out === "object", "Expected spkez() to return an object");
+            invariant(Array.isArray(out.state) && out.state.length === 6, "Expected spkez().state to be a length-6 array");
+            invariant(typeof out.lt === "number", "Expected spkez().lt to be a number");
+            const state = out.state;
+            const result = { state, lt: out.lt };
+            return result;
+        },
+        spkezp: (target, et, ref, abcorr, observer) => {
+            const out = native.spkezp(target, et, ref, abcorr, observer);
+            invariant(out && typeof out === "object", "Expected spkezp() to return an object");
+            invariant(Array.isArray(out.pos) && out.pos.length === 3, "Expected spkezp().pos to be a length-3 array");
+            invariant(typeof out.lt === "number", "Expected spkezp().lt to be a number");
+            const pos = out.pos;
+            const result = { pos, lt: out.lt };
+            return result;
+        },
+        spkgeo: (target, et, ref, observer) => {
+            const out = native.spkgeo(target, et, ref, observer);
+            invariant(out && typeof out === "object", "Expected spkgeo() to return an object");
+            invariant(Array.isArray(out.state) && out.state.length === 6, "Expected spkgeo().state to be a length-6 array");
+            invariant(typeof out.lt === "number", "Expected spkgeo().lt to be a number");
+            const state = out.state;
+            const result = { state, lt: out.lt };
+            return result;
+        },
+        spkgps: (target, et, ref, observer) => {
+            const out = native.spkgps(target, et, ref, observer);
+            invariant(out && typeof out === "object", "Expected spkgps() to return an object");
+            invariant(Array.isArray(out.pos) && out.pos.length === 3, "Expected spkgps().pos to be a length-3 array");
+            invariant(typeof out.lt === "number", "Expected spkgps().lt to be a number");
+            const pos = out.pos;
+            const result = { pos, lt: out.lt };
+            return result;
+        },
+        spkssb: (target, et, ref) => {
+            const out = native.spkssb(target, et, ref);
+            invariant(Array.isArray(out) && out.length === 6, "Expected spkssb() to return a length-6 array");
+            return out;
+        },
+        spkcov: (spk, idcode, cover) => {
+            const resolved = stager.resolvePathForSpice(spk);
+            native.spkcov(resolved, idcode, cover);
+        },
+        spkobj: (spk, ids) => {
+            const resolved = stager.resolvePathForSpice(spk);
+            native.spkobj(resolved, ids);
+        },
+        spksfs: (body, et) => {
+            const out = native.spksfs(body, et);
+            invariant(out && typeof out === "object", "Expected spksfs() to return an object");
+            invariant(typeof out.found === "boolean", "Expected spksfs().found to be a boolean");
+            if (!out.found) {
+                return { found: false };
+            }
+            invariant(typeof out.handle === "number", "Expected spksfs().handle to be a number when found");
+            const descr = out.descr;
+            assertSpkPackedDescriptor(descr, "spksfs().descr");
+            invariant(typeof out.ident === "string", "Expected spksfs().ident to be a string when found");
+            return {
+                found: true,
+                handle: out.handle,
+                descr,
+                ident: out.ident,
+            };
+        },
+        spkpds: (body, center, frame, type, first, last) => {
+            const out = native.spkpds(body, center, frame, type, first, last);
+            assertSpkPackedDescriptor(out, "spkpds() output");
+            return out;
+        },
+        spkuds: (descr) => {
+            const out = native.spkuds(descr);
+            invariant(out && typeof out === "object", "Expected spkuds() to return an object");
+            const obj = out;
+            const keys = ["body", "center", "frame", "type", "first", "last", "baddr", "eaddr"];
+            for (const k of keys) {
+                invariant(typeof obj[k] === "number", `Expected spkuds().${k} to be a number`);
+            }
+            return out;
+        },
+        // --- SPK writers -------------------------------------------------------
+        spkopn: (file, ifname, ncomch) => {
+            const path = resolveSpkPath(outputs, file, "spkopn(file)");
+            const nativeHandle = native.spkopn(path, ifname, ncomch);
+            const handle = handles.register("SPK", nativeHandle);
+            if (typeof file !== "string") {
+                // `resolveSpkPath` already validated, but be defensive: callers can cast.
+                invariant(isVirtualOutput(file), "spkopn(file): expected VirtualOutput {kind:'virtual-output', path:string}");
+                const out = { kind: "virtual-output", path: file.path };
+                outputs.markOpen(out);
+                virtualOutputByHandle.set(handle, out);
+            }
+            return handle;
+        },
+        spkopa: (file) => {
+            const path = resolveSpkPath(outputs, file, "spkopa(file)");
+            const nativeHandle = native.spkopa(path);
+            const handle = handles.register("SPK", nativeHandle);
+            if (typeof file !== "string") {
+                invariant(isVirtualOutput(file), "spkopa(file): expected VirtualOutput {kind:'virtual-output', path:string}");
+                const out = { kind: "virtual-output", path: file.path };
+                outputs.markOpen(out);
+                virtualOutputByHandle.set(handle, out);
+            }
+            return handle;
+        },
+        spkcls: (handle) => {
+            const out = virtualOutputByHandle.get(handle);
+            handles.close(handle, ["SPK"], (e) => native.spkcls(e.nativeHandle), "spkcls");
+            if (out) {
+                outputs.markClosed(out);
+                virtualOutputByHandle.delete(handle);
+            }
+        },
+        spkw08: (handle, body, center, frame, first, last, segid, degree, states, epoch1, step) => {
+            invariant(Array.isArray(states) || states instanceof Float64Array, "spkw08(states): expected number[] or Float64Array");
+            invariant(states.length % 6 === 0, "spkw08(): expected states.length to be a multiple of 6");
+            invariant(states.length > 0, "spkw08(): expected at least one state record");
+            const n = states.length / 6;
+            invariant(Number.isSafeInteger(n) && n > 0 && n <= I32_MAX, `spkw08(): expected states.length/6 to be a 32-bit signed integer (got n=${n})`);
+            const nativeHandle = handles.lookup(handle, ["SPK"], "spkw08").nativeHandle;
+            native.spkw08(nativeHandle, body, center, frame, first, last, segid, degree, states, epoch1, step);
+        },
     };
 }
 //# sourceMappingURL=ephemeris.js.map

package/backend-node/dist/domains/error.d.ts

@@ -0,0 +1,5 @@
+import { type ErrorApi } from "#backend-contract";
+import type { NativeAddon } from "../runtime/addon.js";
+/** Create an {@link ErrorApi} implementation backed by the native Node addon. */
+export declare function createErrorApi(native: NativeAddon): ErrorApi;
+//# sourceMappingURL=error.d.ts.map

package/backend-node/dist/domains/error.js

@@ -0,0 +1,34 @@
+import { assertGetmsgWhich } from "#backend-contract";
+import { invariant } from "#core";
+/** Create an {@link ErrorApi} implementation backed by the native Node addon. */
+export function createErrorApi(native) {
+    return {
+        failed: () => {
+            const out = native.failed();
+            invariant(typeof out === "boolean", "Expected native backend failed() to return a boolean");
+            return out;
+        },
+        reset: () => {
+            native.reset();
+        },
+        getmsg: (which) => {
+            assertGetmsgWhich(which);
+            const out = native.getmsg(which);
+            invariant(typeof out === "string", "Expected native backend getmsg() to return a string");
+            return out;
+        },
+        setmsg: (message) => {
+            native.setmsg(message);
+        },
+        sigerr: (short) => {
+            native.sigerr(short);
+        },
+        chkin: (name) => {
+            native.chkin(name);
+        },
+        chkout: (name) => {
+            native.chkout(name);
+        },
+    };
+}
+//# sourceMappingURL=error.js.map

package/backend-node/dist/domains/file-io.d.ts

@@ -0,0 +1,7 @@
+import type { FileIoApi } from "#backend-contract";
+import type { NativeAddon } from "../runtime/addon.js";
+import type { VirtualOutputStager } from "../runtime/virtual-output-staging.js";
+import type { SpiceHandleRegistry } from "../runtime/spice-handles.js";
+/** Create a {@link FileIoApi} implementation backed by the native Node addon. */
+export declare function createFileIoApi(native: NativeAddon, handles: SpiceHandleRegistry, outputs: VirtualOutputStager): FileIoApi;
+//# sourceMappingURL=file-io.d.ts.map

package/backend-node/dist/domains/file-io.js

@@ -0,0 +1,105 @@
+import { invariant } from "#core";
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+const DAS_BACKED = ["DAS", "DLA"];
+function assertDlaDescriptor(value, context) {
+    invariant(typeof value === "object" && value !== null, `${context}: expected an object`);
+    const obj = value;
+    for (const key of [
+        "bwdptr",
+        "fwdptr",
+        "ibase",
+        "isize",
+        "dbase",
+        "dsize",
+        "cbase",
+        "csize",
+    ]) {
+        const v = obj[key];
+        invariant(typeof v === "number" &&
+            Number.isInteger(v) &&
+            v >= I32_MIN &&
+            v <= I32_MAX, `${context}: expected ${key} to be a 32-bit signed integer`);
+        const min = key === "bwdptr" || key === "fwdptr" ? -1 : 0;
+        invariant(v >= min, `${context}: expected ${key} to be >= ${min}`);
+    }
+}
+function normalizeFoundDlaDescriptor(value, context) {
+    invariant(typeof value === "object" && value !== null, `${context}: expected an object`);
+    const obj = value;
+    invariant(typeof obj.found === "boolean", `${context}: expected found to be a boolean`);
+    if (!obj.found) {
+        return { found: false };
+    }
+    assertDlaDescriptor(obj.descr, `${context}.descr`);
+    return { found: true, descr: obj.descr };
+}
+/** Create a {@link FileIoApi} implementation backed by the native Node addon. */
+export function createFileIoApi(native, handles, outputs) {
+    function closeDasBacked(handle, context) {
+        handles.close(handle, DAS_BACKED, (entry) => {
+            // In CSPICE, `dascls_c` closes both DAS and DLA handles, and `dlacls_c`
+            // is just an alias.
+            native.dascls(entry.nativeHandle);
+        }, context);
+    }
+    const api = {
+        exists: (path) => {
+            const exists = native.exists(path);
+            invariant(typeof exists === "boolean", "Expected native backend exists() to return a boolean");
+            return exists;
+        },
+        getfat: (path) => {
+            const result = native.getfat(path);
+            invariant(typeof result === "object" && result !== null, "Expected native backend getfat() to return an object");
+            const obj = result;
+            invariant(typeof obj.arch === "string", "Expected getfat().arch to be a string");
+            invariant(typeof obj.type === "string", "Expected getfat().type to be a string");
+            return { arch: obj.arch, type: obj.type };
+        },
+        readVirtualOutput: (output) => {
+            invariant(output && typeof output === "object", "readVirtualOutput(output): expected an object");
+            const obj = output;
+            invariant(obj.kind === "virtual-output", "readVirtualOutput(output): expected kind='virtual-output'");
+            invariant(typeof obj.path === "string", "readVirtualOutput(output): expected path to be a string");
+            return outputs.readVirtualOutput({ kind: "virtual-output", path: obj.path });
+        },
+        dafopr: (path) => handles.register("DAF", native.dafopr(path)),
+        dafcls: (handle) => handles.close(handle, ["DAF"], (e) => native.dafcls(e.nativeHandle), "dafcls"),
+        dafbfs: (handle) => native.dafbfs(handles.lookup(handle, ["DAF"], "dafbfs").nativeHandle),
+        daffna: (handle) => {
+            const found = native.daffna(handles.lookup(handle, ["DAF"], "daffna").nativeHandle);
+            invariant(typeof found === "boolean", "Expected native backend daffna() to return a boolean");
+            return found;
+        },
+        dasopr: (path) => handles.register("DAS", native.dasopr(path)),
+        dascls: (handle) => closeDasBacked(handle, "dascls"),
+        dlaopn: (path, ftype, ifname, ncomch) => handles.register("DLA", native.dlaopn(path, ftype, ifname, ncomch)),
+        dlabfs: (handle) => normalizeFoundDlaDescriptor(native.dlabfs(handles.lookup(handle, DAS_BACKED, "dlabfs").nativeHandle), "dlabfs()"),
+        dlafns: (handle, descr) => {
+            assertDlaDescriptor(descr, "dlafns(descr)");
+            return normalizeFoundDlaDescriptor(native.dlafns(handles.lookup(handle, DAS_BACKED, "dlafns").nativeHandle, descr), "dlafns()");
+        },
+        dlacls: (handle) => closeDasBacked(handle, "dlacls"),
+        dskopn: (path, ifname, ncomch) => 
+        // DSKs are DAS-backed; register as DAS so `dascls` can close it.
+        handles.register("DAS", native.dskopn(path, ifname, ncomch)),
+        dskmi2: (nv, vrtces, np, plates, finscl, corscl, worksz, voxpsz, voxlsz, makvtl, spxisz) => {
+            const result = native.dskmi2(nv, vrtces, np, plates, finscl, corscl, worksz, voxpsz, voxlsz, makvtl, spxisz);
+            invariant(typeof result === "object" && result !== null, "Expected native backend dskmi2() to return an object");
+            const obj = result;
+            invariant(Array.isArray(obj.spaixd), "Expected dskmi2().spaixd to be an array");
+            invariant(Array.isArray(obj.spaixi), "Expected dskmi2().spaixi to be an array");
+            invariant(obj.spaixd.every((v) => typeof v === "number"), "Expected dskmi2().spaixd to be a number[]");
+            invariant(obj.spaixi.every((v) => typeof v === "number"), "Expected dskmi2().spaixi to be a number[]");
+            return { spaixd: obj.spaixd, spaixi: obj.spaixi };
+        },
+        dskw02: (handle, center, surfid, dclass, frame, corsys, corpar, mncor1, mxcor1, mncor2, mxcor2, mncor3, mxcor3, first, last, nv, vrtces, np, plates, spaixd, spaixi) => native.dskw02(handles.lookup(handle, ["DAS"], "dskw02").nativeHandle, center, surfid, dclass, frame, corsys, corpar, mncor1, mxcor1, mncor2, mxcor2, mncor3, mxcor3, first, last, nv, vrtces, np, plates, spaixd, spaixi),
+    };
+    Object.defineProperty(api, "__debugOpenHandleCount", {
+        value: () => handles.size(),
+        enumerable: false,
+    });
+    return api;
+}
+//# sourceMappingURL=file-io.js.map

package/backend-node/dist/domains/frames.d.ts

@@ -1,4 +1,5 @@
 import type { FramesApi } from "#backend-contract";
 import type { NativeAddon } from "../runtime/addon.js";
+/** Create a {@link FramesApi} implementation backed by the native Node addon. */
 export declare function createFramesApi(native: NativeAddon): FramesApi;
 //# sourceMappingURL=frames.d.ts.map

package/backend-node/dist/domains/frames.js

@@ -1,4 +1,21 @@
+import { brandMat3RowMajor } from "#backend-contract";
 import { invariant } from "#core";
+const UINT32_MAX = 0xffff_ffff;
+// Opaque cell/window handles are represented as branded numbers in the backend
+// contract, but we still validate them at runtime to keep error behavior
+// consistent across backends (mirrors the WASM handle assertions).
+function assertOpaqueHandle(handle, context) {
+    if (typeof handle !== "number" || !Number.isFinite(handle) || !Number.isInteger(handle)) {
+        throw new TypeError(`${context}: expected handle to be an integer number (got ${handle})`);
+    }
+    if (handle <= 0) {
+        throw new RangeError(`${context}: expected handle to be > 0 (got ${handle})`);
+    }
+    if (!Number.isSafeInteger(handle) || handle > UINT32_MAX) {
+        throw new RangeError(`${context}: expected handle to be a non-zero uint32 (got ${handle})`);
+    }
+}
+/** Create a {@link FramesApi} implementation backed by the native Node addon. */
 export function createFramesApi(native) {
     return {
         namfrm: (name) => {
@@ -35,34 +52,69 @@ export function createFramesApi(native) {
             invariant(typeof out.frname === "string", "Expected cnmfrm().frname to be a string");
             return { found: true, frcode: out.frcode, frname: out.frname };
         },
+        frinfo: (frameId) => {
+            const out = native.frinfo(frameId);
+            if (!out.found) {
+                return { found: false };
+            }
+            invariant(typeof out.center === "number", "Expected frinfo().center to be a number");
+            invariant(typeof out.frameClass === "number", "Expected frinfo().frameClass to be a number");
+            invariant(typeof out.classId === "number", "Expected frinfo().classId to be a number");
+            return { found: true, center: out.center, frameClass: out.frameClass, classId: out.classId };
+        },
+        ccifrm: (frameClass, classId) => {
+            const out = native.ccifrm(frameClass, classId);
+            if (!out.found) {
+                return { found: false };
+            }
+            invariant(typeof out.frcode === "number", "Expected ccifrm().frcode to be a number");
+            invariant(typeof out.frname === "string", "Expected ccifrm().frname to be a string");
+            invariant(typeof out.center === "number", "Expected ccifrm().center to be a number");
+            return { found: true, frcode: out.frcode, frname: out.frname, center: out.center };
+        },
         ckgp: (inst, sclkdp, tol, ref) => {
             const out = native.ckgp(inst, sclkdp, tol, ref);
             if (!out.found) {
                 return { found: false };
             }
-            invariant(Array.isArray(out.cmat) && out.cmat.length === 9, "Expected ckgp().cmat to be a length-9 array");
+            const cmat = brandMat3RowMajor(out.cmat, { label: "ckgp().cmat" });
             invariant(typeof out.clkout === "number", "Expected ckgp().clkout to be a number");
-            return { found: true, cmat: out.cmat, clkout: out.clkout };
+            return { found: true, cmat, clkout: out.clkout };
         },
         ckgpav: (inst, sclkdp, tol, ref) => {
             const out = native.ckgpav(inst, sclkdp, tol, ref);
             if (!out.found) {
                 return { found: false };
             }
-            invariant(Array.isArray(out.cmat) && out.cmat.length === 9, "Expected ckgpav().cmat to be a length-9 array");
+            const cmat = brandMat3RowMajor(out.cmat, { label: "ckgpav().cmat" });
             invariant(Array.isArray(out.av) && out.av.length === 3, "Expected ckgpav().av to be a length-3 array");
             invariant(typeof out.clkout === "number", "Expected ckgpav().clkout to be a number");
             return {
                 found: true,
-                cmat: out.cmat,
+                cmat,
                 av: out.av,
                 clkout: out.clkout,
             };
         },
+        cklpf: (ck) => {
+            const handle = native.cklpf(ck);
+            invariant(typeof handle === "number" && Number.isInteger(handle), "Expected cklpf() to return an integer handle");
+            return handle;
+        },
+        ckupf: (handle) => {
+            native.ckupf(handle);
+        },
+        ckobj: (ck, ids) => {
+            assertOpaqueHandle(ids, "ckobj(ids)");
+            native.ckobj(ck, ids);
+        },
+        ckcov: (ck, idcode, needav, level, tol, timsys, cover) => {
+            assertOpaqueHandle(cover, "ckcov(cover)");
+            native.ckcov(ck, idcode, needav, level, tol, timsys, cover);
+        },
         pxform: (from, to, et) => {
             const m = native.pxform(from, to, et);
-            invariant(Array.isArray(m) && m.length === 9, "Expected pxform() to return a length-9 array");
-            return m;
+            return brandMat3RowMajor(m, { label: "pxform()" });
         },
         sxform: (from, to, et) => {
             const m = native.sxform(from, to, et);