@rybosome/tspice 0.0.7 → 0.0.8

package/backend-contract/dist/domains/file-io.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=file-io.js.map

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

@@ -1,19 +1,47 @@
+/**
+ * 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 { Found, Mat3RowMajor, SpiceMatrix6x6, SpiceVector3 } from "../shared/types.js";
+import type { SpiceIntCell, SpiceWindow } from "./cells-windows.js";
+/** Coverage detail level returned by {@link FramesApi.ckcov}. */
+export type CkCoverageLevel = "SEGMENT" | "INTERVAL";
+/** Time system used for coverage windows returned by {@link FramesApi.ckcov}. */
+export type CkCoverageTimeSystem = "SCLK" | "TDB";
+/** Backend contract for frame/name lookups, CK access, and frame transformations. */
 export interface FramesApi {
+    /** SPICE `namfrm_c`: look up a frame code by frame name. */
     namfrm(name: string): Found<{
         code: number;
     }>;
+    /** SPICE `frmnam_c`: look up a frame name by frame code. */
     frmnam(code: number): Found<{
         name: string;
     }>;
+    /** SPICE `cidfrm_c`: look up frame information for a center body ID. */
     cidfrm(center: number): Found<{
         frcode: number;
         frname: string;
     }>;
+    /** SPICE `cnmfrm_c`: look up frame information for a center body name. */
     cnmfrm(centerName: string): Found<{
         frcode: number;
         frname: string;
     }>;
+    /** SPICE `frinfo_c`: get center + frame class info for a frame ID. */
+    frinfo(frameId: number): Found<{
+        center: number;
+        frameClass: number;
+        classId: number;
+    }>;
+    /** SPICE `ccifrm_c`: map frame class + class ID to a frame code/name/center triple. */
+    ccifrm(frameClass: number, classId: number): Found<{
+        frcode: number;
+        frname: string;
+        center: number;
+    }>;
     /** Get pointing (attitude) for a CK instrument at a given encoded spacecraft clock time. */
     ckgp(inst: number, sclkdp: number, tol: number, ref: string): Found<{
         cmat: Mat3RowMajor;
@@ -25,6 +53,18 @@ export interface FramesApi {
         av: SpiceVector3;
         clkout: number;
     }>;
+    /**
+     * Load a CK file for access by pointing routines (`cklpf_c`).
+     *
+     * Returns a CK file handle suitable for {@link FramesApi.ckupf}.
+     */
+    cklpf(ck: string): number;
+    /** Unload a CK file previously loaded by {@link FramesApi.cklpf} (`ckupf_c`). */
+    ckupf(handle: number): void;
+    /** Return the set of instrument/object IDs for which the specified CK has segments (`ckobj_c`). */
+    ckobj(ck: string, ids: SpiceIntCell): void;
+    /** Return coverage for an instrument/object in a CK file (`ckcov_c`). */
+    ckcov(ck: string, idcode: number, needav: boolean, level: CkCoverageLevel, tol: number, timsys: CkCoverageTimeSystem, cover: SpiceWindow): void;
     /** Compute a 3x3 frame transformation matrix (row-major). */
     pxform(from: string, to: string, et: number): Mat3RowMajor;
     /** Compute a 6x6 state transformation matrix (row-major). */

package/backend-contract/dist/domains/geometry-gf.d.ts

@@ -0,0 +1,44 @@
+/**
+ * GF (Geometry Finder) event finding.
+ *
+ * Tranche 1 scope:
+ * - "Plumbing" utilities (`gfsstp/gfstep`, `gfstol`, `gfrefn`, `gfrepi/gfrepf`).
+ * - A couple high-level, callback-free searches: `gfsep` and `gfdist`.
+ *
+ * Notes:
+ * - The CSPICE GF subsystem has some **global mutable state** (e.g. `gfsstp`,
+ *   `gfstol`). Callers should treat these as process-global knobs.
+ * - Confinement/result windows use Group 2 `SpiceWindow` opaque handles.
+ */
+import type { AbCorr } from "../shared/types.js";
+import type { SpiceWindow } from "./cells-windows.js";
+/** Relation operators accepted by many high-level GF searches. */
+export type GfRelate = ">" | "<" | "=" | "ABSMAX" | "ABSMIN" | "LOCMAX" | "LOCMIN";
+/** Backend contract for Geometry Finder (GF) event-finding routines. */
+export interface GeometryGfApi {
+    /** Set the constant step size used by {@link GeometryGfApi.gfstep} (`gfsstp_c`). */
+    gfsstp(step: number): void;
+    /** Return the constant step size set by {@link GeometryGfApi.gfsstp} (`gfstep_c`). */
+    gfstep(time: number): number;
+    /** Override the GF convergence tolerance (`gfstol_c`). */
+    gfstol(value: number): void;
+    /** Default refinement estimator used by the GF subsystem (`gfrefn_c`). */
+    gfrefn(t1: number, t2: number, s1: boolean, s2: boolean): number;
+    /** Initialize the default console progress reporter (`gfrepi_c`). */
+    gfrepi(window: SpiceWindow, begmss: string, endmss: string): void;
+    /** Finalize the default console progress reporter (`gfrepf_c`). */
+    gfrepf(): void;
+    /**
+     * Angular separation search (`gfsep_c`).
+     *
+     * `refval` and `adjust` are in **radians**.
+     */
+    gfsep(targ1: string, shape1: string, frame1: string, targ2: string, shape2: string, frame2: string, abcorr: AbCorr | string, obsrvr: string, relate: GfRelate | string, refval: number, adjust: number, step: number, nintvls: number, cnfine: SpiceWindow, result: SpiceWindow): void;
+    /**
+     * Observer-target distance search (`gfdist_c`).
+     *
+     * `refval` and `adjust` are in **km**.
+     */
+    gfdist(target: string, abcorr: AbCorr | string, obsrvr: string, relate: GfRelate | string, refval: number, adjust: number, step: number, nintvls: number, cnfine: SpiceWindow, result: SpiceWindow): void;
+}
+//# sourceMappingURL=geometry-gf.d.ts.map

package/backend-contract/dist/domains/geometry-gf.js

@@ -0,0 +1,14 @@
+/**
+ * GF (Geometry Finder) event finding.
+ *
+ * Tranche 1 scope:
+ * - "Plumbing" utilities (`gfsstp/gfstep`, `gfstol`, `gfrefn`, `gfrepi/gfrepf`).
+ * - A couple high-level, callback-free searches: `gfsep` and `gfdist`.
+ *
+ * Notes:
+ * - The CSPICE GF subsystem has some **global mutable state** (e.g. `gfsstp`,
+ *   `gfstol`). Callers should treat these as process-global knobs.
+ * - Confinement/result windows use Group 2 `SpiceWindow` opaque handles.
+ */
+export {};
+//# sourceMappingURL=geometry-gf.js.map

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

@@ -1,4 +1,11 @@
-import type { AbCorr, Found, IluminResult, SubPointResult, SpiceVector3 } 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, IllumfResult, IllumgResult, IluminResult, Pl2nvcResult, SpicePlane, SubPointResult, SpiceVector3 } from "../shared/types.js";
+/** Backend contract for common SPICE geometry computations (subpoints, intercepts, illumination, etc). */
 export interface GeometryApi {
     /** Compute the sub-observer point on a target body's surface. */
     subpnt(method: string, target: string, et: number, fixref: string, abcorr: AbCorr | string, observer: string): SubPointResult;
@@ -8,7 +15,20 @@ export interface GeometryApi {
     sincpt(method: string, target: string, et: number, fixref: string, abcorr: AbCorr | string, observer: string, dref: string, dvec: SpiceVector3): Found<SubPointResult>;
     /** Compute illumination angles at a surface point. */
     ilumin(method: string, target: string, et: number, fixref: string, abcorr: AbCorr | string, observer: string, spoint: SpiceVector3): IluminResult;
+    /**
+     * Compute illumination angles at a surface point, with a caller-specified
+     * illumination source body.
+     */
+    illumg(method: string, target: string, ilusrc: string, et: number, fixref: string, abcorr: AbCorr | string, observer: string, spoint: SpiceVector3): IllumgResult;
+    /**
+     * Compute illumination angles + visibility/lighting flags at a surface point.
+     */
+    illumf(method: string, target: string, ilusrc: string, et: number, fixref: string, abcorr: AbCorr | string, observer: string, spoint: SpiceVector3): IllumfResult;
     /** Determine the occultation condition code for one target vs another. */
     occult(targ1: string, shape1: string, frame1: string, targ2: string, shape2: string, frame2: string, abcorr: AbCorr | string, observer: string, et: number): number;
+    /** Convert a normal vector + constant to a plane. */
+    nvc2pl(normal: SpiceVector3, konst: number): SpicePlane;
+    /** Convert a plane to a unit normal vector + constant. */
+    pl2nvc(plane: SpicePlane): Pl2nvcResult;
 }
 //# sourceMappingURL=geometry.d.ts.map

package/backend-contract/dist/domains/ids-names-normalize.d.ts

@@ -0,0 +1,3 @@
+/** Normalize a body-constant item name for `bodfnd` / `bodvar` lookups. */
+export declare function normalizeBodItem(item: string): string;
+//# sourceMappingURL=ids-names-normalize.d.ts.map

package/backend-contract/dist/domains/ids-names-normalize.js

@@ -0,0 +1,74 @@
+/**
+ * Normalize a body-constant item name for `bodfnd` / `bodvar` lookups.
+ *
+ * Body-constant item names are treated as case-insensitive by CSPICE, but CSPICE's
+ * casing behavior is ASCII-based. We intentionally avoid `String.prototype.toUpperCase()`
+ * here because it applies Unicode case mappings (e.g. `"ß" -> "SS"`), which can
+ * change lookup keys in surprising ways.
+ *
+ * We intentionally trim **ASCII whitespace only** (space/tab/newline/etc.) to match
+ * CSPICE behavior and keep native + WASM backends consistent.
+ */
+const MAX_BOD_ITEM_CHARS = 1024;
+/** Normalize a body-constant item name for `bodfnd` / `bodvar` lookups. */
+export function normalizeBodItem(item) {
+    // Defensive guardrail: kernel pool item names are expected to be short.
+    // If a pathological string makes it here (e.g. a multi-megabyte user input),
+    // uppercasing it can cause large allocations and unnecessary CPU work.
+    //
+    // This limit is intentionally *far* above any realistic item name.
+    if (item.length > MAX_BOD_ITEM_CHARS) {
+        throw new RangeError(`Kernel pool item name is too long: ${item.length} characters (max ${MAX_BOD_ITEM_CHARS})`);
+    }
+    return toAsciiUppercase(trimAsciiWhitespace(item));
+}
+function isAsciiWhitespace(code) {
+    // Keep this consistent with the native backend implementation.
+    return (code === 32 /* ' ' */ ||
+        code === 9 /* '\t' */ ||
+        code === 10 /* '\n' */ ||
+        code === 13 /* '\\r' */ ||
+        code === 12 /* '\f' */ ||
+        code === 11 /* '\\v' */);
+}
+function trimAsciiWhitespace(s) {
+    let start = 0;
+    while (start < s.length && isAsciiWhitespace(s.charCodeAt(start))) {
+        start++;
+    }
+    let end = s.length;
+    while (end > start && isAsciiWhitespace(s.charCodeAt(end - 1))) {
+        end--;
+    }
+    if (start === 0 && end === s.length) {
+        return s;
+    }
+    return s.slice(start, end);
+}
+function toAsciiUppercase(s) {
+    // JS `toUpperCase()` applies Unicode case mappings (e.g. "ß" -> "SS").
+    // For kernel pool item names, we only want to uppercase ASCII a-z.
+    //
+    // Performance: avoid allocating a new string if no changes are needed.
+    //
+    // Implementation note: we do a single pass over the string and only start
+    // constructing an output string after seeing the first lowercase ASCII letter.
+    let out;
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        const isAsciiLower = code >= 97 /* 'a' */ && code <= 122 /* 'z' */;
+        if (out === undefined) {
+            if (!isAsciiLower)
+                continue;
+            // We found at least one lowercase ASCII letter; build the output string.
+            //
+            // Note: `normalizeBodItem()` enforces a max input length, so a simple
+            // per-code-unit loop is safe and keeps allocation behavior predictable.
+            out = s.slice(0, i) + String.fromCharCode(code - 32);
+            continue;
+        }
+        out += String.fromCharCode(isAsciiLower ? code - 32 : code);
+    }
+    return out ?? s;
+}
+//# sourceMappingURL=ids-names-normalize.js.map

package/backend-contract/dist/domains/ids-names.d.ts

@@ -1,10 +1,47 @@
+/**
+ * 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 { Found } from "../shared/types.js";
+/** Backend contract for NAIF ID/name and body-constant lookups. */
 export interface IdsNamesApi {
+    /** SPICE `bodn2c_c`: look up a NAIF body ID code by name. */
     bodn2c(name: string): Found<{
         code: number;
     }>;
+    /** SPICE `bodc2n_c`: look up a body name by NAIF ID code. */
     bodc2n(code: number): Found<{
         name: string;
     }>;
+    /** Map a NAIF body ID code to a name (or decimal string if unknown). */
+    bodc2s(code: number): string;
+    /** Map a body name or numeric string to a NAIF body ID code. */
+    bods2c(name: string): Found<{
+        code: number;
+    }>;
+    /** Define a body name/code mapping (side effect). */
+    boddef(name: string, code: number): void;
+    /**
+     * Return true if a body constant exists in the kernel pool.
+     *
+     * Normalization:
+     * - `item` is normalized as `normalizeBodItem(item)` (trim ASCII whitespace + ASCII-only uppercase)
+     *   before lookup.
+     */
+    bodfnd(body: number, item: string): boolean;
+    /**
+     * Return values of a body constant from the kernel pool.
+     *
+     * Normalization:
+     * - `item` is normalized as `normalizeBodItem(item)` (trim ASCII whitespace + ASCII-only uppercase)
+     *   before lookup.
+     *
+     * Missing-item semantics:
+     * - If `item` is not found for `body` (or is non-numeric), returns `[]`.
+     * - Call `bodfnd(body, item)` if you need a strict presence check.
+     */
+    bodvar(body: number, item: string): number[];
 }
 //# sourceMappingURL=ids-names.d.ts.map

package/backend-contract/dist/domains/kernel-pool.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Kernel pool API contract.
+ *
+ * Contract conventions:
+ * - Backends MUST validate inputs as described below and throw on invalid arguments or SPICE errors.
+ * - Lookups that may legitimately miss return `Found<T>` (`{ found: false }`) instead of throwing.
+ *
+ * Terminology used in validation semantics:
+ * - "not empty or whitespace-only" means `value.trim().length > 0`.
+ * - "finite integer" means `Number.isFinite(value) && Number.isInteger(value)`.
+ *
+ * Empty arrays:
+ * - `pdpool`/`pipool`/`pcpool` accept `values: []` and set the variable to an empty list (size 0).
+ * - `swpool` accepts `names: []` and watches nothing (but still arms the agent so the next
+ *   `cvpool(agent)` returns `true`).
+ */
+import type { Found } from "../shared/types.js";
+export type KernelPoolVarType = "C" | "N";
+/** Backend contract for reading/writing kernel pool variables. */
+export interface KernelPoolApi {
+    /**
+     * Get numeric (double) kernel pool values.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     * - `start` must be a finite integer >= 0 (0-based).
+     * - `room` must be a finite integer > 0.
+     */
+    gdpool(name: string, start: number, room: number): Found<{
+        values: number[];
+    }>;
+    /**
+     * Get numeric (integer) kernel pool values.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     * - `start` must be a finite integer >= 0 (0-based).
+     * - `room` must be a finite integer > 0.
+     */
+    gipool(name: string, start: number, room: number): Found<{
+        values: number[];
+    }>;
+    /**
+     * Get character kernel pool values.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     * - `start` must be a finite integer >= 0 (0-based).
+     * - `room` must be a finite integer > 0.
+     */
+    gcpool(name: string, start: number, room: number): Found<{
+        values: string[];
+    }>;
+    /**
+     * Get the names of kernel pool variables matching a template.
+     *
+     * Wildcards:
+     * - `*` matches any substring
+     * - `%` matches any single character
+     *
+     * Validation semantics:
+     * - `template` must not be empty or whitespace-only.
+     * - `start` must be a finite integer >= 0 (0-based).
+     * - `room` must be a finite integer > 0.
+     */
+    gnpool(template: string, start: number, room: number): Found<{
+        values: string[];
+    }>;
+    /**
+     * Get kernel pool variable type (`C` or `N`) and size.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     */
+    dtpool(name: string): Found<{
+        n: number;
+        type: KernelPoolVarType;
+    }>;
+    /**
+     * Put numeric (double) values into the kernel pool.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     * - `values` may be empty (sets an empty value list).
+     * - Each value must be finite (no `NaN` / `±Infinity`).
+     */
+    pdpool(name: string, values: readonly number[]): void;
+    /**
+     * Put numeric (integer) values into the kernel pool.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     * - `values` may be empty (sets an empty value list).
+     * - Each value must be a safe integer in the signed 32-bit range
+     *   [-2147483648, 2147483647].
+     */
+    pipool(name: string, values: readonly number[]): void;
+    /**
+     * Put character values into the kernel pool.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     * - `values` may be empty (sets an empty value list).
+     */
+    pcpool(name: string, values: readonly string[]): void;
+    /**
+     * Set up a kernel pool "watch" for `agent`.
+     *
+     * After calling `swpool`, the next `cvpool(agent)` call will return `true`.
+     *
+     * Validation semantics:
+     * - `agent` must not be empty or whitespace-only.
+     * - `names` may be empty (watch nothing).
+     */
+    swpool(agent: string, names: readonly string[]): void;
+    /**
+     * Check whether watched variables for `agent` have been updated since the last call.
+     *
+     * Validation semantics:
+     * - `agent` must not be empty or whitespace-only.
+     */
+    cvpool(agent: string): boolean;
+    /**
+     * Check existence of a *numeric* kernel pool variable.
+     *
+     * NOTE: This does not detect character-valued variables; use `dtpool` if you need a
+     * general existence/type check.
+     *
+     * Validation semantics:
+     * - `name` must not be empty or whitespace-only.
+     */
+    expool(name: string): boolean;
+}
+//# sourceMappingURL=kernel-pool.d.ts.map

package/backend-contract/dist/domains/kernel-pool.js

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

package/backend-contract/dist/domains/kernels-utils.d.ts

@@ -0,0 +1,44 @@
+import type { Found, KernelData, KernelKind } from "../shared/types.js";
+import type { KernelKindInput } from "./kernels.js";
+/** Normalize a `ktotal/kdata` kind input into a canonical, non-empty kernel kind list. */
+export declare function normalizeKindInput(kind: KernelKindInput | undefined): readonly KernelKind[];
+/**
+ * Returns a representable native kind-query string (e.g. `"SPK CK"`) or null.
+ *
+ * This is used by backends to decide whether they can forward a kind filter to
+ * their underlying CSPICE implementation, or whether they must fall back to
+ * querying `ALL` and filtering in JS.
+ *
+ * NOTE: `kinds` is expected to be normalized (via {@link normalizeKindInput}).
+ * If non-normalized input slips through (e.g. empty arrays or `ALL` mixed with
+ * other tokens), this function is defensive and returns null.
+ */
+export declare function nativeKindQueryOrNull(kinds: readonly KernelKind[]): string | null;
+/**
+ * Return whether a kernel matches the requested kind filter.
+ *
+ * Requested kind tokens are treated as trim + case-insensitive. Empty tokens are ignored.
+ *
+ * NOTE: Unlike {@link normalizeKindInput}, this helper is intentionally lenient:
+ * unknown requested tokens are treated as non-matching (and do not throw).
+ * Unknown/unsupported `kernel.filtyp` values never match (unless `requested` includes `ALL`).
+ *
+ * TEXT-kernel subtypes (LSK/FK/IK/SCLK): SPICE reports these as `filtyp: "TEXT"`.
+ * When callers request a subtype, we infer it from the `kernel.file` identifier's
+ * filename extension (best-effort). If the identifier is virtual or extension-less,
+ * subtype matching may fall back to "TEXT".
+ */
+export declare function matchesKernelKind(requestedRaw: ReadonlySet<string>, kernel: Pick<KernelData, "file" | "filtyp">): boolean;
+/**
+ * JS implementation of CSPICE `kxtrct`.
+ *
+ * Notes on return values:
+ * - `substr` is right-trimmed (`trimEnd()`).
+ * - `wordsq` has the extracted words removed, but otherwise preserves whitespace
+ *   from the original input (so it may start with blanks).
+ */
+export declare function kxtrctJs(keywd: string, terms: readonly string[], wordsq: string): Found<{
+    wordsq: string;
+    substr: string;
+}>;
+//# sourceMappingURL=kernels-utils.d.ts.map