@rybosome/tspice 0.0.7 → 0.0.8

package/backend-contract/dist/domains/coords-vectors.d.ts

@@ -1,17 +1,29 @@
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ */
 import type { Mat3RowMajor, SpiceVector3 } from "../shared/types.js";
+/** Backend contract for basic coordinate transforms and vector/matrix math. */
 export interface CoordsVectorsApi {
+    /** SPICE `reclat_c`: rectangular -> latitudinal coordinates. */
     reclat(rect: SpiceVector3): {
         radius: number;
         lon: number;
         lat: number;
     };
+    /** SPICE `latrec_c`: latitudinal -> rectangular coordinates. */
     latrec(radius: number, lon: number, lat: number): SpiceVector3;
+    /** SPICE `recsph_c`: rectangular -> spherical coordinates. */
     recsph(rect: SpiceVector3): {
         radius: number;
         colat: number;
         lon: number;
     };
+    /** SPICE `sphrec_c`: spherical -> rectangular coordinates. */
     sphrec(radius: number, colat: number, lon: number): SpiceVector3;
+    /** SPICE `vnorm_c`: vector magnitude (Euclidean norm). */
     vnorm(v: SpiceVector3): number;
     /**
      * Compute the unit vector of `v`.
@@ -22,9 +34,47 @@ export interface CoordsVectorsApi {
      * This matches the NAIF CSPICE `vhat_c` definition.
      */
     vhat(v: SpiceVector3): SpiceVector3;
+    /** SPICE `vdot_c`: dot product of two vectors. */
     vdot(a: SpiceVector3, b: SpiceVector3): number;
+    /** SPICE `vcrss_c`: cross product of two vectors. */
     vcrss(a: SpiceVector3, b: SpiceVector3): SpiceVector3;
+    /** SPICE `vadd_c`: vector addition. */
+    vadd(a: SpiceVector3, b: SpiceVector3): SpiceVector3;
+    /** SPICE `vsub_c`: vector subtraction. */
+    vsub(a: SpiceVector3, b: SpiceVector3): SpiceVector3;
+    /** SPICE `vminus_c`: negate a vector. */
+    vminus(v: SpiceVector3): SpiceVector3;
+    /** SPICE `vscl_c`: multiply vector by scalar. */
+    vscl(s: number, v: SpiceVector3): SpiceVector3;
+    /** SPICE `mxm_c`: matrix-matrix multiplication. */
+    mxm(a: Mat3RowMajor, b: Mat3RowMajor): Mat3RowMajor;
+    /**
+     * Generate a rotation matrix representing a rotation about a coordinate axis.
+     *
+     * Axis is 1=x, 2=y, 3=z.
+     */
+    rotate(angle: number, axis: number): Mat3RowMajor;
+    /**
+     * Rotate a matrix about a coordinate axis.
+     *
+     * Axis is 1=x, 2=y, 3=z.
+     */
+    rotmat(m: Mat3RowMajor, angle: number, axis: number): Mat3RowMajor;
+    /**
+     * Convert an axis and angle to a rotation matrix.
+     */
+    axisar(axis: SpiceVector3, angle: number): Mat3RowMajor;
+    /** SPICE `georec_c`: geodetic lon/lat/alt -> rectangular coordinates. */
+    georec(lon: number, lat: number, alt: number, re: number, f: number): SpiceVector3;
+    /** SPICE `recgeo_c`: rectangular -> geodetic lon/lat/alt coordinates. */
+    recgeo(rect: SpiceVector3, re: number, f: number): {
+        lon: number;
+        lat: number;
+        alt: number;
+    };
+    /** SPICE `mxv_c`: multiply matrix by vector. */
     mxv(m: Mat3RowMajor, v: SpiceVector3): SpiceVector3;
+    /** SPICE `mtxv_c`: multiply transpose(matrix) by vector. */
     mtxv(m: Mat3RowMajor, v: SpiceVector3): SpiceVector3;
 }
 //# sourceMappingURL=coords-vectors.d.ts.map

package/backend-contract/dist/domains/dsk.d.ts

@@ -0,0 +1,49 @@
+import type { SpiceHandle, SpiceVector3 } from "../shared/types.js";
+import type { SpiceIntCell } from "./cells-windows.js";
+import type { DlaDescriptor } from "./file-io.js";
+/** Segment descriptor returned by `dskgd` (CSPICE: `SpiceDSKDescr`). */
+export type DskDescriptor = {
+    surfce: number;
+    center: number;
+    dclass: number;
+    dtype: number;
+    frmcde: number;
+    corsys: number;
+    /** Coordinate system parameters (CSPICE: `corpar[SPICE_DSK_NSYPAR]`). */
+    corpar: number[];
+    co1min: number;
+    co1max: number;
+    co2min: number;
+    co2max: number;
+    co3min: number;
+    co3max: number;
+    start: number;
+    stop: number;
+};
+/** Summary bookkeeping parameters for a type 2 DSK segment (CSPICE: `dskb02_c`). */
+export type DskType2Bookkeeping = {
+    nv: number;
+    np: number;
+    nvxtot: number;
+    /** Vertex bounds: `[[xmin,xmax],[ymin,ymax],[zmin,zmax]]` (CSPICE: `vtxbds[3][2]`). */
+    vtxbds: [[number, number], [number, number], [number, number]];
+    voxsiz: number;
+    voxori: SpiceVector3;
+    vgrext: SpiceVector3;
+    cgscal: number;
+    vtxnpl: number;
+    voxnpt: number;
+    voxnpl: number;
+};
+/** Backend contract for DSK (Digital Shape Kernel) segment queries. */
+export interface DskApi {
+    /** Return the set of body IDs for which the specified DSK has segments. */
+    dskobj(dsk: string, bodids: SpiceIntCell): void;
+    /** Return the set of surface IDs for which the specified DSK has segments. */
+    dsksrf(dsk: string, bodyid: number, srfids: SpiceIntCell): void;
+    /** Return the descriptor of a DSK segment. */
+    dskgd(handle: SpiceHandle, dladsc: DlaDescriptor): DskDescriptor;
+    /** Return the type 2 DSK segment bookkeeping parameters. */
+    dskb02(handle: SpiceHandle, dladsc: DlaDescriptor): DskType2Bookkeeping;
+}
+//# sourceMappingURL=dsk.d.ts.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dsk.js.map

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

@@ -0,0 +1,186 @@
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ */
+import type { SpiceHandle } from "../shared/types.js";
+/**
+ * Result of running an EK query via `ekfind`.
+ *
+ * Notes:
+ * - `ekfind` has a *non-standard* error reporting mechanism: query parse/semantic
+ *   failures are returned via an `error/errmsg` output pair rather than SPICE's
+ *   global error state.
+ * - Backend implementations should surface that query-specific failure via this
+ *   return type (no throw).
+ * - SPICE-signaled failures (e.g. no loaded EKs) should still throw.
+ */
+export type EkFindResult = {
+    ok: true;
+    /** Number of matching rows. */
+    nmrows: number;
+} | {
+    ok: false;
+    /** Query language parse/semantic error message returned by `ekfind_c`. */
+    errmsg: string;
+};
+/**
+ * Result of fetching an element from an EK query result set.
+ *
+ * This is a tri-state:
+ * - `{ found: false }`: the requested element doesn't exist (commonly `elment`
+ *   is out of range for the entry).
+ * - `{ found: true, isNull: true }`: the entry exists but is SQL NULL.
+ * - `{ found: true, isNull: false, value: T }`: a concrete value.
+ */
+export type EkGetResult<T> = {
+    found: false;
+} | {
+    found: true;
+    isNull: true;
+} | {
+    found: true;
+    isNull: false;
+    value: T;
+};
+/** Backend contract for EK (Events Kernel) file/query operations. */
+export interface EkApi {
+    /** Open an existing EK file for read (see `ekopr_c`). */
+    ekopr(path: string): SpiceHandle;
+    /** Open an existing EK file for write (see `ekopw_c`). */
+    ekopw(path: string): SpiceHandle;
+    /**
+     * Create and open a new EK file for write (see `ekopn_c`).
+     *
+     * `ncomch` is the number of comment characters to allocate for the EK.
+     */
+    ekopn(path: string, ifname: string, ncomch: number): SpiceHandle;
+    /**
+     * Close an EK file opened via `ekopr` / `ekopw` / `ekopn` (see `ekcls_c`).
+     *
+     * Notes:
+     * - EK handles are explicit resources and are not automatically closed by `unload()` / `kclear()`.
+     * - If `path` was backed by byte-staged temp bytes, close EK handles before calling
+     *   `unload()` / `kclear()` to allow best-effort temp file deletion (especially on Windows).
+     */
+    ekcls(handle: SpiceHandle): void;
+    /**
+     * Number of EK tables currently loaded (see `ekntab_c`).
+     *
+     * Postconditions:
+     * - Returns an integer count `n` with `0 <= n <= 2_147_483_647`.
+     * - Backends should validate this postcondition and throw if violated.
+     */
+    ekntab(): number;
+    /**
+     * Retrieve the EK table name by 0-based index (see `ektnam_c`).
+     *
+     * `n` must be in the range `0..ekntab()-1`.
+     */
+    ektnam(n: number): string;
+    /**
+     * Number of segments in an EK file opened via handle (see `eknseg_c`).
+     *
+     * Postconditions:
+     * - Returns an integer count `n` with `0 <= n <= 2_147_483_647`.
+     * - Backends should validate this postcondition and throw if violated.
+     */
+    eknseg(handle: SpiceHandle): number;
+    /**
+     * Execute an EK query (see `ekfind_c`).
+     *
+     * Notes:
+     * - EK query results live in CSPICE global state.
+     * - Beginning fast-write via `ekifld` can invalidate the active selection/result set.
+     *   Avoid interleaving `ekfind`/`ekg*` reads with fast-write; rerun `ekfind` after fast-write
+     *   if you need to read again.
+     */
+    ekfind(query: string): EkFindResult;
+    /**
+     * Fetch a character-valued element from the active query result set (see `ekgc_c`).
+     *
+     * Indices are 0-based per NAIF:
+     * - `selidx`: 0-based index of the selected item in the query's `SELECT` clause.
+     * - `row`: 0-based row index in the result set (`0..nmrows-1` from the last successful `ekfind`).
+     * - `elment`: 0-based element index within the cell entry (`0` for scalar entries).
+     */
+    ekgc(selidx: number, row: number, elment: number): EkGetResult<string>;
+    /**
+     * Fetch a double-valued element from the active query result set (see `ekgd_c`).
+     *
+     * Indices are 0-based per NAIF:
+     * - `selidx`: 0-based index of the selected item in the query's `SELECT` clause.
+     * - `row`: 0-based row index in the result set (`0..nmrows-1` from the last successful `ekfind`).
+     * - `elment`: 0-based element index within the cell entry (`0` for scalar entries).
+     */
+    ekgd(selidx: number, row: number, elment: number): EkGetResult<number>;
+    /**
+     * Fetch an integer-valued element from the active query result set (see `ekgi_c`).
+     *
+     * Indices are 0-based per NAIF:
+     * - `selidx`: 0-based index of the selected item in the query's `SELECT` clause.
+     * - `row`: 0-based row index in the result set (`0..nmrows-1` from the last successful `ekfind`).
+     * - `elment`: 0-based element index within the cell entry (`0` for scalar entries).
+     */
+    ekgi(selidx: number, row: number, elment: number): EkGetResult<number>;
+    /**
+     * Begin fast-write for a new EK segment (see `ekifld_c`).
+     *
+     * Returns `segno` (new segment number) and the `rcptrs` workspace array.
+     * `rcptrs` must be passed to the subsequent column-add calls and to `ekffld`.
+     *
+     * Notes:
+     * - Calling `ekifld` may invalidate the active EK query selection (from `ekfind`). If you need
+     *   to read query results after starting fast-write, rerun `ekfind`.
+     */
+    ekifld(handle: SpiceHandle, tabnam: string, nrows: number, cnames: readonly string[], decls: readonly string[]): {
+        segno: number;
+        rcptrs: number[];
+    };
+    /**
+     * Add an integer column's data to a fast-write segment (see `ekacli_c`).
+     *
+     * Packing:
+     * - `entszs`, `nlflgs`, and `rcptrs` are per-row arrays and must have the same length
+     *   `nrows` (the `nrows` passed to `ekifld`, i.e. `rcptrs.length`).
+     * - `ivals` is a packed array containing exactly `sum(entszs)` values.
+     *
+     * NULL rows (`nlflgs[i] === true`):
+     * - Variable-size columns: set `entszs[i] = 0` and do not include any values for that row.
+     * - Fixed-size columns (`SIZE = N`): include/pad `N` placeholder values for that row and set
+     *   `entszs[i] = N` so `ivals.length === sum(entszs)` remains true.
+     */
+    ekacli(handle: SpiceHandle, segno: number, column: string, ivals: readonly number[], entszs: readonly number[], nlflgs: readonly boolean[], rcptrs: readonly number[]): void;
+    /**
+     * Add a double-precision column's data to a fast-write segment (see `ekacld_c`).
+     *
+     * Packing:
+     * - `entszs`, `nlflgs`, and `rcptrs` are per-row arrays and must have the same length
+     *   `nrows` (the `nrows` passed to `ekifld`, i.e. `rcptrs.length`).
+     * - `dvals` is a packed array containing exactly `sum(entszs)` values.
+     *
+     * NULL rows (`nlflgs[i] === true`):
+     * - Variable-size columns: set `entszs[i] = 0` and do not include any values for that row.
+     * - Fixed-size columns (`SIZE = N`): include/pad `N` placeholder values for that row and set
+     *   `entszs[i] = N` so `dvals.length === sum(entszs)` remains true.
+     */
+    ekacld(handle: SpiceHandle, segno: number, column: string, dvals: readonly number[], entszs: readonly number[], nlflgs: readonly boolean[], rcptrs: readonly number[]): void;
+    /**
+     * Add a character column's data to a fast-write segment (see `ekaclc_c`).
+     *
+     * Packing:
+     * - `entszs`, `nlflgs`, and `rcptrs` are per-row arrays and must have the same length
+     *   `nrows` (the `nrows` passed to `ekifld`, i.e. `rcptrs.length`).
+     * - `cvals` is a packed array containing exactly `sum(entszs)` values.
+     *
+     * NULL rows (`nlflgs[i] === true`):
+     * - Variable-size columns: set `entszs[i] = 0` and do not include any values for that row.
+     * - Fixed-size columns (`SIZE = N`): include/pad `N` placeholder values for that row and set
+     *   `entszs[i] = N` so `cvals.length === sum(entszs)` remains true.
+     */
+    ekaclc(handle: SpiceHandle, segno: number, column: string, cvals: readonly string[], entszs: readonly number[], nlflgs: readonly boolean[], rcptrs: readonly number[]): void;
+    /** Complete a fast-write segment (see `ekffld_c`). */
+    ekffld(handle: SpiceHandle, segno: number, rcptrs: readonly number[]): void;
+}
+//# sourceMappingURL=ek.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ */
+export {};
+//# sourceMappingURL=ek.js.map

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

@@ -1,8 +1,146 @@
-import type { AbCorr, SpkezrResult, SpkposResult } from "../shared/types.js";
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ */
+import type { AbCorr, Found, SpiceHandle, SpiceStateVector, SpkezrResult, SpkposResult, VirtualOutput } from "../shared/types.js";
+import type { SpiceIntCell, SpiceWindow } from "./cells-windows.js";
+/**
+ * Packed SPK segment descriptor (DAF summary) as a 5-double array.
+ *
+ * This is the packed form returned by `spksfs` and accepted by `spkuds`.
+ */
+export type SpkPackedDescriptor = readonly [number, number, number, number, number];
+/** Unpacked SPK segment descriptor (see `spkuds_c`). */
+export type SpkUnpackedDescriptor = {
+    body: number;
+    center: number;
+    frame: number;
+    type: number;
+    first: number;
+    last: number;
+    baddr: number;
+    eaddr: number;
+};
+/** Backend contract for SPK/ephemeris computations (positions, states, segment inspection). */
 export interface EphemerisApi {
-    /** Compute state (6-vector) and light time via `spkezr`. */
+    /**
+     * Compute state relative to observer using loaded kernels (see `spkezr_c`).
+     *
+     * Note: `abcorr` is a known set of SPICE aberration correction strings, but we allow arbitrary
+     * strings for forward-compatibility.
+     */
     spkezr(target: string, et: number, ref: string, abcorr: AbCorr | string, observer: string): SpkezrResult;
-    /** Compute position (3-vector) and light time via `spkpos`. */
+    /**
+     * Compute position relative to observer using loaded kernels (see `spkpos_c`).
+     */
     spkpos(target: string, et: number, ref: string, abcorr: AbCorr | string, observer: string): SpkposResult;
+    /** Compute state (6-vector) and light time via `spkez` (numeric IDs). */
+    spkez(target: number, et: number, ref: string, abcorr: AbCorr | string, observer: number): SpkezrResult;
+    /** Compute position (3-vector) and light time via `spkezp` (numeric IDs). */
+    spkezp(target: number, et: number, ref: string, abcorr: AbCorr | string, observer: number): SpkposResult;
+    /** Compute geometric state (6-vector) and light time via `spkgeo` (numeric IDs). */
+    spkgeo(target: number, et: number, ref: string, observer: number): SpkezrResult;
+    /** Compute geometric position (3-vector) and light time via `spkgps` (numeric IDs). */
+    spkgps(target: number, et: number, ref: string, observer: number): SpkposResult;
+    /** Compute state (6-vector) of `target` relative to the solar system barycenter via `spkssb`. */
+    spkssb(target: number, et: number, ref: string): SpiceStateVector;
+    /**
+     * Compute the coverage window for an object in an SPK via `spkcov`.
+     *
+     * **Path semantics (backend-dependent):**
+     * - Node backend: `spk` is a host filesystem path.
+     * - WASM backend: `spk` is an Emscripten FS (virtual) path/id (typically the
+     *   `path` you used in `furnsh({ path, bytes })`).
+     *
+     * **Output window requirements:** `cover` must be a valid, initialized window
+     * handle created by the backend (e.g. `newWindow(maxIntervals)`) and must have
+     * sufficient capacity for the merged output.
+     *
+     * **Error safety note:** Like CSPICE `spkcov_c`, if this routine throws while
+     * updating `cover` (including due to insufficient capacity), the contents of
+     * `cover` may be left in a corrupted/undefined state. If an error is thrown,
+     * do **not** keep using `cover`; free it and create a fresh window.
+     *
+     * **Window semantics:** `cover` is updated in place. Like CSPICE `spkcov_c`,
+     * coverage is **merged** with any intervals already present in `cover`.
+     * Clear the window first (e.g. `scard(0, cover)`) if you want to avoid
+     * accumulation.
+     */
+    spkcov(spk: string, idcode: number, cover: SpiceWindow): void;
+    /**
+     * Find the set of objects present in an SPK via `spkobj`.
+     *
+     * **Path semantics (backend-dependent):**
+     * - Node backend: `spk` is a host filesystem path.
+     * - WASM backend: `spk` is an Emscripten FS (virtual) path/id (typically the
+     *   `path` you used in `furnsh({ path, bytes })`).
+     *
+     * **Output cell requirements:** `ids` must be a valid, initialized set cell
+     * handle created by the backend (e.g. `newIntCell(size)`) and must have
+     * sufficient capacity for the unioned output.
+     *
+     * **Error safety note:** Like CSPICE `spkobj_c`, if this routine throws while
+     * updating `ids` (including due to insufficient capacity), the contents of
+     * `ids` may be left in a corrupted/undefined state. If an error is thrown, do
+     * **not** keep using `ids`; free it and create a fresh cell.
+     *
+     * **Cell semantics:** `ids` is updated in place. Like CSPICE `spkobj_c`, the
+     * output is the **union** of the IDs already present in `ids` and the IDs
+     * found in `spk`.
+     * Clear the cell first (e.g. `scard(0, ids)`) if you want to
+     * avoid accumulation.
+     */
+    spkobj(spk: string, ids: SpiceIntCell): void;
+    /**
+     * Search loaded SPK files for the highest-priority segment applicable to `body` and `et`.
+     *
+     * Note: `handle` is the native SPICE DAF handle for the file containing the segment.
+     */
+    spksfs(body: number, et: number): Found<{
+        handle: number;
+        descr: SpkPackedDescriptor;
+        ident: string;
+    }>;
+    /** Pack an SPK segment descriptor via `spkpds`. */
+    spkpds(body: number, center: number, frame: string, type: number, first: number, last: number): SpkPackedDescriptor;
+    /** Unpack a packed SPK segment descriptor via `spkuds`. */
+    spkuds(descr: SpkPackedDescriptor): SpkUnpackedDescriptor;
+    /**
+     * Open a new SPK file for write (see `spkopn_c`).
+     *
+     * `file` interpretation is backend-dependent:
+     * - Node: OS filesystem path
+     * - WASM: virtual id under the backend's virtual filesystem (currently
+     *   normalized into `/kernels/...`).
+     *
+     *   In other words, for the WASM backend, `file: string` is **not** a raw
+     *   Emscripten absolute path. It is treated like other "kernel-ish" paths and
+     *   is normalized into `/kernels`.
+     *
+     *   Examples (WASM backend):
+     *   - `spkopn("out.bsp", ...)` writes to `/kernels/out.bsp`
+     *   - `spkopn("/kernels/out.bsp", ...)` refers to the same file
+     *   - `spkopn("/tmp/out.bsp", ...)` throws (OS paths/URLs are rejected)
+     *
+     * When `file` is a `VirtualOutput`, backends should allow reading bytes back
+     * via `readVirtualOutput()` after closing the file handle.
+     *
+     * Callers should retain the `VirtualOutput` they passed to `spkopn`/`spkopa`.
+     * It is the identifier used to read bytes back later.
+     */
+    spkopn(file: string | VirtualOutput, ifname: string, ncomch: number): SpiceHandle;
+    /** Open an existing SPK for append (see `spkopa_c`). Same `file` semantics as `spkopn`. */
+    spkopa(file: string | VirtualOutput): SpiceHandle;
+    /** Close an SPK file previously opened by `spkopn`/`spkopa` (see `spkcls_c`). */
+    spkcls(handle: SpiceHandle): void;
+    /**
+     * Write a type 8 SPK segment (see `spkw08_c`).
+     *
+     * `states` is a flat array with layout `[x,y,z, dx,dy,dz]` for each record.
+     * The number of records `n` is derived as `states.length / 6`.
+     */
+    spkw08(handle: SpiceHandle, body: number, center: number, frame: string, first: number, last: number, segid: string, degree: number, states: readonly number[] | Float64Array, epoch1: number, step: number): void;
 }
 //# sourceMappingURL=ephemeris.d.ts.map

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

@@ -0,0 +1,42 @@
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ *
+ * Error policy:
+ * - Backend methods throw for SPICE-signaled failures.
+ * - "Found-style" routines (e.g. `bodn2c`, `bodc2n`, `namfrm`, ...) must **not** throw when
+ *   SPICE reports "not found" via a `found` output flag; they return `{ found: false }`.
+ */
+/** Subset of CSPICE error/status utilities exposed by tspice backends. */
+export declare const GETMSG_WHICH_VALUES: readonly ["SHORT", "LONG", "EXPLAIN"];
+export type GetmsgWhich = (typeof GETMSG_WHICH_VALUES)[number];
+/** Type guard for {@link GetmsgWhich}. */
+export declare function isGetmsgWhich(which: unknown): which is GetmsgWhich;
+/**
+ * Runtime validation for `getmsg(which)`.
+ *
+ * Even though `which` is a narrow union type, callers may still pass arbitrary
+ * values at runtime (e.g. JS consumers, `as any`, etc.). Backends must reject
+ * invalid selectors rather than forwarding them to CSPICE.
+ */
+export declare function assertGetmsgWhich(which: unknown): asserts which is GetmsgWhich;
+/** Backend contract for SPICE error/status utilities (failed/reset/getmsg/etc). */
+export interface ErrorApi {
+    /** Return `true` if the CSPICE error status is currently set. */
+    failed(): boolean;
+    /** Reset/clear the CSPICE error status and messages. */
+    reset(): void;
+    /** Get a CSPICE error message component. */
+    getmsg(which: GetmsgWhich): string;
+    /** Set the long error message text used by `sigerr()`. */
+    setmsg(message: string): void;
+    /** Signal a CSPICE error with the provided short error code (e.g. `"SPICE(BADTIME)"`). */
+    sigerr(short: string): void;
+    /** Add `name` to the CSPICE traceback stack. */
+    chkin(name: string): void;
+    /** Remove `name` from the CSPICE traceback stack. */
+    chkout(name: string): void;
+}
+//# sourceMappingURL=error.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ *
+ * Error policy:
+ * - Backend methods throw for SPICE-signaled failures.
+ * - "Found-style" routines (e.g. `bodn2c`, `bodc2n`, `namfrm`, ...) must **not** throw when
+ *   SPICE reports "not found" via a `found` output flag; they return `{ found: false }`.
+ */
+/** Subset of CSPICE error/status utilities exposed by tspice backends. */
+export const GETMSG_WHICH_VALUES = ["SHORT", "LONG", "EXPLAIN"];
+/** Type guard for {@link GetmsgWhich}. */
+export function isGetmsgWhich(which) {
+    return (which === "SHORT" ||
+        which === "LONG" ||
+        which === "EXPLAIN");
+}
+/**
+ * Runtime validation for `getmsg(which)`.
+ *
+ * Even though `which` is a narrow union type, callers may still pass arbitrary
+ * values at runtime (e.g. JS consumers, `as any`, etc.). Backends must reject
+ * invalid selectors rather than forwarding them to CSPICE.
+ */
+export function assertGetmsgWhich(which) {
+    if (isGetmsgWhich(which))
+        return;
+    const allowed = GETMSG_WHICH_VALUES.map((v) => JSON.stringify(v)).join(" | ");
+    throw new TypeError(`getmsg(which) expected one of ${allowed} (got ${JSON.stringify(which)})`);
+}
+//# sourceMappingURL=error.js.map

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

@@ -0,0 +1,114 @@
+/**
+ * Contract conventions:
+ * - Inputs are assumed validated at the backend boundary; the contract itself is primarily type-level.
+ * - Methods throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ */
+import type { SpiceHandle, VirtualOutput } from "../shared/types.js";
+/**
+ * Plain-object representation of CSPICE `SpiceDLADescr`.
+ *
+ * These are the 8 integer components of a DLA descriptor.
+ *
+ * ## Portability
+ *
+ * Each field is an **int32** (32-bit signed integer). Backend implementations
+ * must reject (throw) non-integers and values outside the int32 range to
+ * prevent silent truncation across native/WASM boundaries.
+ *
+ * This matches tspice's project-wide assumption that `SpiceInt` is 32-bit
+ * (`sizeof(SpiceInt) == 4`) in all supported builds.
+ */
+export type DlaDescriptor = {
+    bwdptr: number;
+    fwdptr: number;
+    ibase: number;
+    isize: number;
+    dbase: number;
+    dsize: number;
+    cbase: number;
+    csize: number;
+};
+export type FoundDlaDescriptor = {
+    found: false;
+} | {
+    found: true;
+    descr: DlaDescriptor;
+};
+/** Backend contract for SPICE file I/O primitives (DAF/DAS/DLA + virtual outputs). */
+export interface FileIoApi {
+    /** Returns whether a file exists at `path`. */
+    exists(path: string): boolean;
+    /** Determine SPICE file architecture + type (see `getfat_c`). */
+    getfat(path: string): {
+        arch: string;
+        type: string;
+    };
+    /**
+     * Read back bytes for a previously-created virtual output file.
+     *
+     * Notes:
+     * - Virtual outputs are only guaranteed to be readable after their associated
+     *   writer handle has been closed (e.g. `spkcls(handle)` for SPK outputs).
+     * - Backends may reject reads for outputs they did not create via a writer
+     *   API. This is intentionally **not** a general filesystem read.
+     */
+    readVirtualOutput(output: VirtualOutput): Uint8Array;
+    /** Open a DAF file for read (see `dafopr_c`). */
+    dafopr(path: string): SpiceHandle;
+    /** Close a DAF file previously opened by `dafopr()`. */
+    dafcls(handle: SpiceHandle): void;
+    /** Begin a forward search for arrays in the given DAF file (see `dafbfs_c`). */
+    dafbfs(handle: SpiceHandle): void;
+    /**
+     * Find the next DAF array (see `daffna_c`).
+     *
+     * Backend implementations should select the current DAF via `dafcs_c(handle)`
+     * before calling `daffna_c` to support interleaving multiple DAF searches.
+     */
+    daffna(handle: SpiceHandle): boolean;
+    /** Open a DAS file for read (see `dasopr_c`). */
+    dasopr(path: string): SpiceHandle;
+    /**
+     * Close a DAS-backed file handle.
+     *
+     * In CSPICE, `dascls_c` closes both DAS and DLA handles, and `dlacls_c` is an
+     * alias. We mirror that behavior: `dascls` and `dlacls` are interchangeable
+     * and accept handles returned from either `dasopr()` (read) or `dlaopn()`
+     * (write).
+     */
+    dascls(handle: SpiceHandle): void;
+    /** Create and open a DLA file for write (see `dlaopn_c`). */
+    dlaopn(path: string, ftype: string, ifname: string, ncomch: number): SpiceHandle;
+    /**
+     * Begin a forward search for DLA segments (see `dlabfs_c`).
+     *
+     * DLA is DAS-backed: `handle` must be a DAS handle to a DLA file, opened via
+     * `dasopr()` (read) or `dlaopn()` (write).
+     */
+    dlabfs(handle: SpiceHandle): FoundDlaDescriptor;
+    /**
+     * Find the next DLA segment after `descr` (see `dlafns_c`).
+     *
+     * DLA is DAS-backed: `handle` must be a DAS handle to a DLA file, opened via
+     * `dasopr()` (read) or `dlaopn()` (write).
+     */
+    dlafns(handle: SpiceHandle, descr: DlaDescriptor): FoundDlaDescriptor;
+    /**
+     * Close a DAS-backed DLA handle.
+     *
+     * Provided for parity with CSPICE `dlacls_c`, but implemented as an alias of
+     * `dascls` (same handle compatibility).
+     */
+    dlacls(handle: SpiceHandle): void;
+    /** Create and open a DSK file for write (see `dskopn_c`). */
+    dskopn(path: string, ifname: string, ncomch: number): SpiceHandle;
+    /** Build the spatial index for a type 2 DSK segment (see `dskmi2_c`). */
+    dskmi2(nv: number, vrtces: readonly number[], np: number, plates: readonly number[], finscl: number, corscl: number, worksz: number, voxpsz: number, voxlsz: number, makvtl: boolean, spxisz: number): {
+        spaixd: number[];
+        spaixi: number[];
+    };
+    /** Write a type 2 segment to a DSK file opened by `dskopn` (see `dskw02_c`). */
+    dskw02(handle: SpiceHandle, center: number, surfid: number, dclass: number, frame: string, corsys: number, corpar: readonly number[], mncor1: number, mxcor1: number, mncor2: number, mxcor2: number, mncor3: number, mxcor3: number, first: number, last: number, nv: number, vrtces: readonly number[], np: number, plates: readonly number[], spaixd: readonly number[], spaixi: readonly number[]): void;
+}
+//# sourceMappingURL=file-io.d.ts.map