kaabalah 6.16.0 → 6.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/README.md +19 -6
  2. package/dist/astrology/index.d.mts +3423 -148
  3. package/dist/astrology/index.d.ts +3423 -148
  4. package/dist/astrology/index.js +849 -59
  5. package/dist/astrology/index.mjs +4 -2
  6. package/dist/{chunk-MWLSSRHL.mjs → chunk-4BKDSA7L.mjs} +3 -4
  7. package/dist/chunk-4BKDSA7L.mjs.map +1 -0
  8. package/dist/chunk-4WVN4RMM.mjs +1139 -0
  9. package/dist/chunk-4WVN4RMM.mjs.map +1 -0
  10. package/dist/{chunk-J5Y325TG.mjs → chunk-4ZFY3GBP.mjs} +2210 -3
  11. package/dist/chunk-4ZFY3GBP.mjs.map +1 -0
  12. package/dist/{chunk-LQVHJ3VY.mjs → chunk-54QDLBID.mjs} +41 -41
  13. package/dist/{chunk-LQVHJ3VY.mjs.map → chunk-54QDLBID.mjs.map} +1 -1
  14. package/dist/{chunk-PBBF5DKC.js → chunk-6SBCBVTZ.js} +21 -21
  15. package/dist/{chunk-WP5MRAYG.mjs → chunk-COEM6U4V.mjs} +3 -4
  16. package/dist/chunk-COEM6U4V.mjs.map +1 -0
  17. package/dist/{chunk-3JMY4U4S.mjs → chunk-DBRPCQRR.mjs} +245 -211
  18. package/dist/chunk-DBRPCQRR.mjs.map +1 -0
  19. package/dist/{chunk-WRF3EORB.js → chunk-DCJYTCJZ.js} +16 -17
  20. package/dist/chunk-DCJYTCJZ.js.map +1 -0
  21. package/dist/{chunk-UO2RQQZO.mjs → chunk-DK2VS36Z.mjs} +2 -2
  22. package/dist/{chunk-HEZCZXQC.js → chunk-E353GPHE.js} +16 -16
  23. package/dist/{chunk-6LZOAU6E.js → chunk-GDJSVV46.js} +272 -241
  24. package/dist/chunk-GDJSVV46.js.map +1 -0
  25. package/dist/{chunk-Z3JZ5DZN.mjs → chunk-IZBM4CPN.mjs} +2 -2
  26. package/dist/chunk-J3WVI5Y3.mjs +16280 -0
  27. package/dist/chunk-J3WVI5Y3.mjs.map +1 -0
  28. package/dist/{chunk-7OWGGDRF.js → chunk-JFRVH3TD.js} +2288 -80
  29. package/dist/chunk-JFRVH3TD.js.map +1 -0
  30. package/dist/chunk-MZBY6G5S.js +1182 -0
  31. package/dist/chunk-MZBY6G5S.js.map +1 -0
  32. package/dist/{chunk-7JWBIAUF.mjs → chunk-NS5AXNEW.mjs} +3 -3
  33. package/dist/chunk-QU4RKOBD.js +16536 -0
  34. package/dist/chunk-QU4RKOBD.js.map +1 -0
  35. package/dist/{chunk-CMXTZKWW.js → chunk-UCNBHGIY.js} +157 -157
  36. package/dist/{chunk-CMXTZKWW.js.map → chunk-UCNBHGIY.js.map} +1 -1
  37. package/dist/{chunk-BKFHIKFY.js → chunk-XRSK74V5.js} +179 -180
  38. package/dist/chunk-XRSK74V5.js.map +1 -0
  39. package/dist/{chunk-2IC6H3FI.js → chunk-YVLKVB6W.js} +52 -52
  40. package/dist/cli.js +27609 -11656
  41. package/dist/cli.js.map +1 -1
  42. package/dist/core/index.js +56 -57
  43. package/dist/core/index.mjs +2 -3
  44. package/dist/core-B3_-9yli.d.mts +279 -0
  45. package/dist/core-cWIQtely.d.ts +279 -0
  46. package/dist/gematria/index.js +7 -8
  47. package/dist/gematria/index.mjs +2 -3
  48. package/dist/iching/index.d.mts +37 -37
  49. package/dist/iching/index.d.ts +37 -37
  50. package/dist/iching/index.js +46 -47
  51. package/dist/iching/index.mjs +3 -4
  52. package/dist/index.d.mts +139 -2
  53. package/dist/index.d.ts +139 -2
  54. package/dist/index.js +1422 -301
  55. package/dist/index.js.map +1 -1
  56. package/dist/index.mjs +190 -10
  57. package/dist/index.mjs.map +1 -1
  58. package/dist/numerology/index.d.mts +437 -252
  59. package/dist/numerology/index.d.ts +437 -252
  60. package/dist/numerology/index.js +108 -28
  61. package/dist/numerology/index.mjs +4 -4
  62. package/dist/schedule-types-DsR1_guG.d.mts +200 -0
  63. package/dist/schedule-types-DsR1_guG.d.ts +200 -0
  64. package/dist/semantic/index.d.mts +10 -9
  65. package/dist/semantic/index.d.ts +10 -9
  66. package/dist/semantic/index.js +41 -41
  67. package/dist/semantic/index.mjs +8 -8
  68. package/dist/swisseph.node-734BKSOZ.js +10 -0
  69. package/dist/swisseph.node-734BKSOZ.js.map +1 -0
  70. package/dist/swisseph.node-TDPYTBSS.mjs +8 -0
  71. package/dist/swisseph.node-TDPYTBSS.mjs.map +1 -0
  72. package/dist/tarot/index.js +30 -31
  73. package/dist/tarot/index.mjs +3 -4
  74. package/dist/visual/index.d.mts +1 -0
  75. package/dist/visual/index.d.ts +1 -0
  76. package/dist/visual/index.js +46 -47
  77. package/dist/visual/index.mjs +3 -4
  78. package/dist/wasm/build/swisseph.node-734BKSOZ.js +10 -0
  79. package/dist/wasm/build/swisseph.node-734BKSOZ.js.map +1 -0
  80. package/dist/wasm/build/swisseph.node-TDPYTBSS.mjs +8 -0
  81. package/dist/wasm/build/swisseph.node-TDPYTBSS.mjs.map +1 -0
  82. package/package.json +4 -2
  83. package/dist/chunk-3JMY4U4S.mjs.map +0 -1
  84. package/dist/chunk-3QN5V3DP.js +0 -4737
  85. package/dist/chunk-3QN5V3DP.js.map +0 -1
  86. package/dist/chunk-6LZOAU6E.js.map +0 -1
  87. package/dist/chunk-7OWGGDRF.js.map +0 -1
  88. package/dist/chunk-BKFHIKFY.js.map +0 -1
  89. package/dist/chunk-IT7GZ337.mjs +0 -4679
  90. package/dist/chunk-IT7GZ337.mjs.map +0 -1
  91. package/dist/chunk-J5Y325TG.mjs.map +0 -1
  92. package/dist/chunk-JY4QC6FR.js +0 -2214
  93. package/dist/chunk-JY4QC6FR.js.map +0 -1
  94. package/dist/chunk-MWLSSRHL.mjs.map +0 -1
  95. package/dist/chunk-RUE6NTVT.mjs +0 -2211
  96. package/dist/chunk-RUE6NTVT.mjs.map +0 -1
  97. package/dist/chunk-WP5MRAYG.mjs.map +0 -1
  98. package/dist/chunk-WRF3EORB.js.map +0 -1
  99. package/dist/swisseph.node-53QCJWTI.mjs +0 -3471
  100. package/dist/swisseph.node-53QCJWTI.mjs.map +0 -1
  101. package/dist/swisseph.node-CGBZTQ5N.js +0 -3473
  102. package/dist/swisseph.node-CGBZTQ5N.js.map +0 -1
  103. package/dist/swisseph.node-GPVFDOB6.wasm +0 -0
  104. package/dist/wasm/build/swisseph.node-53QCJWTI.mjs +0 -3471
  105. package/dist/wasm/build/swisseph.node-53QCJWTI.mjs.map +0 -1
  106. package/dist/wasm/build/swisseph.node-CGBZTQ5N.js +0 -3473
  107. package/dist/wasm/build/swisseph.node-CGBZTQ5N.js.map +0 -1
  108. package/dist/wasm/build/swisseph.node-GPVFDOB6.wasm +0 -0
  109. /package/dist/{chunk-PBBF5DKC.js.map → chunk-6SBCBVTZ.js.map} +0 -0
  110. /package/dist/{chunk-2IC6H3FI.js.map → chunk-DK2VS36Z.mjs.map} +0 -0
  111. /package/dist/{chunk-7JWBIAUF.mjs.map → chunk-E353GPHE.js.map} +0 -0
  112. /package/dist/{chunk-Z3JZ5DZN.mjs.map → chunk-IZBM4CPN.mjs.map} +0 -0
  113. /package/dist/{chunk-HEZCZXQC.js.map → chunk-NS5AXNEW.mjs.map} +0 -0
  114. /package/dist/{chunk-UO2RQQZO.mjs.map → chunk-YVLKVB6W.js.map} +0 -0
@@ -1,3 +1,37 @@
1
+ import { v as CivilDate, L as LifePathMethod, f as MasterPolicy, e as ShortMonthPolicy } from '../schedule-types-DsR1_guG.mjs';
2
+
3
+ /**
4
+ * Type definitions for Swiss Ephemeris WebAssembly module
5
+ */
6
+ interface SwissEphModule {
7
+ _malloc(size: number): number;
8
+ _free(ptr: number): void;
9
+ getValue(ptr: number, type: string): number;
10
+ setValue(ptr: number, value: number, type: string): void;
11
+ stringToUTF8(str: string, ptr: number, maxLength: number): void;
12
+ cwrap<T>(name: string, returnType: string | null, paramTypes: (string | null)[]): T;
13
+ UTF8ToString(ptr: number): string;
14
+ HEAP8: Int8Array;
15
+ /** Present only when the wasm build exports swe_version (the shipped build does not). */
16
+ _swe_version?(buf: number): number;
17
+ fill(value: number, start: number, end: number): void;
18
+ FS?: {
19
+ mkdir(path: string): void;
20
+ mount(fs: unknown, opts: {
21
+ root: string;
22
+ }, mountPoint: string): void;
23
+ readdir(path: string): string[];
24
+ analyzePath(path: string): {
25
+ exists: boolean;
26
+ };
27
+ createPreloadedFile(parent: string, name: string, url: string, canRead: boolean, canWrite: boolean): void;
28
+ writeFile(path: string, data: Uint8Array | string, opts?: unknown): void;
29
+ filesystems?: {
30
+ NODEFS?: unknown;
31
+ };
32
+ };
33
+ }
34
+
1
35
  /**
2
36
  * TypeScript wrapper for Swiss Ephemeris WebAssembly module
3
37
  */
@@ -71,6 +105,57 @@ interface PlanetPosition {
71
105
  latitudeSpeed?: number;
72
106
  distanceSpeed?: number;
73
107
  }
108
+ /**
109
+ * Which ephemeris backend Swiss Ephemeris reports having used for a calculation.
110
+ * Derived from the flag bits returned by `swe_calc_ut`:
111
+ * SEFLG_JPLEPH = 1, SEFLG_SWIEPH = 2, SEFLG_MOSEPH = 4.
112
+ */
113
+ type SwissEphemerisKind = "swiss" | "moshier" | "jpl";
114
+ /** Derive the ephemeris label from a flags word; null when no ephemeris bit is set. */
115
+ declare function ephemerisFromFlags(flags: number): SwissEphemerisKind | null;
116
+ type SwissEphErrorCode = "SWISSEPH_NOT_INITIALIZED" | "SWISSEPH_ASSET_NOT_FOUND" | "SWISSEPH_NODE_BUILTINS_UNAVAILABLE" | "SWISSEPH_EPHEMERIS_FILES_UNAVAILABLE" | "SWISSEPH_EPHEMERIS_FILE_UNAVAILABLE" | "SWISSEPH_DATE_OUT_OF_RANGE" | "SWISSEPH_EPHEMERIS_MISMATCH" | "SWISSEPH_CALCULATION_FAILED" | "SWISSEPH_HOUSES_UNAVAILABLE" | "SWISSEPH_STATE_MISUSE";
117
+ /** Typed error for every Swiss Ephemeris runtime failure; `code` is stable API. */
118
+ declare class SwissEphError extends Error {
119
+ readonly code: SwissEphErrorCode;
120
+ readonly details: Record<string, unknown>;
121
+ constructor(code: SwissEphErrorCode, message: string, details?: Record<string, unknown>);
122
+ }
123
+ /** Thrown in strict mode when the returned ephemeris differs from the requested one. */
124
+ declare class SwissEphEphemerisMismatchError extends SwissEphError {
125
+ readonly requestedEphemeris: SwissEphemerisKind;
126
+ readonly returnedEphemeris: SwissEphemerisKind | null;
127
+ readonly requestedFlags: number;
128
+ readonly returnedFlags: number;
129
+ readonly reason: "date_outside_installed_ephemeris_files" | "ephemeris_files_unavailable" | "unknown";
130
+ readonly warning: string | null;
131
+ constructor(info: {
132
+ requestedEphemeris: SwissEphemerisKind;
133
+ returnedEphemeris: SwissEphemerisKind | null;
134
+ requestedFlags: number;
135
+ returnedFlags: number;
136
+ reason: "date_outside_installed_ephemeris_files" | "ephemeris_files_unavailable" | "unknown";
137
+ warning: string | null;
138
+ julianDay: number;
139
+ missingFile: string | null;
140
+ });
141
+ }
142
+ /** A position plus the provenance Swiss Ephemeris reported for it. */
143
+ interface PlanetPositionDetailed {
144
+ position: PlanetPosition;
145
+ requestedFlags: number;
146
+ /** Raw flag word returned by swe_calc_ut (ret value). */
147
+ returnedFlags: number;
148
+ requestedEphemeris: SwissEphemerisKind;
149
+ ephemeris: SwissEphemerisKind | null;
150
+ /** True when the returned ephemeris differs from the requested one. */
151
+ substituted: boolean;
152
+ /** Non-fatal serr text from Swiss Ephemeris (for example a Moshier fallback notice), else null. */
153
+ warning: string | null;
154
+ }
155
+ interface CalculatePositionOptions {
156
+ /** Throw SwissEphEphemerisMismatchError instead of returning substituted output. */
157
+ strictEphemeris?: boolean;
158
+ }
74
159
  declare const normalizeAngle: (deg: number) => number;
75
160
 
76
161
  type RuntimeAssetSource = "explicit" | "env" | "candidate" | "bundled";
@@ -89,19 +174,128 @@ interface ResolveSwissEphRuntimeAssetsOptions {
89
174
  }
90
175
  declare function resolveSwissEphRuntimeAssets(options?: ResolveSwissEphRuntimeAssetsOptions): SwissEphRuntimeAssetPaths;
91
176
  /**
92
- * Initializes and returns the Swiss Ephemeris instance.
177
+ * Async variant that first loads Node built-ins, so it also works synchronously-unsafe
178
+ * environments (native ESM on Node < 20.16).
179
+ */
180
+ declare function resolveSwissEphRuntimeAssetsAsync(options?: ResolveSwissEphRuntimeAssetsOptions): Promise<SwissEphRuntimeAssetPaths>;
181
+ type SwissEphMountMode = "nodefs-mount" | "host-path" | "memfs-copy" | "browser-memfs";
182
+ interface SwissEphRuntimeRecord {
183
+ runtime: "node" | "browser";
184
+ moduleDirectory: string | null;
185
+ wasmPath: string;
186
+ wasmPathSource: RuntimeAssetSource;
187
+ ephePath: string;
188
+ ephePathSource: RuntimeAssetSource;
189
+ mountMode: SwissEphMountMode;
190
+ /** Path handed to swe_set_ephe_path inside the module's virtual file system. */
191
+ swissEphePath: string;
192
+ nodeGlue: "bundled" | "external-file" | "browser";
193
+ fs: SwissEphModule["FS"];
194
+ probe: {
195
+ ephemeris: SwissEphemerisKind | null;
196
+ returnedFlags: number;
197
+ warning: string | null;
198
+ };
199
+ }
200
+ interface SwissEphInfo {
201
+ initialized: boolean;
202
+ strictEphemeris: boolean;
203
+ runtime: "node" | "browser" | null;
204
+ moduleDirectory: string | null;
205
+ wasmPath: string | null;
206
+ wasmPathSource: RuntimeAssetSource | null;
207
+ /** Host (or URL) location the ephemeris files were loaded from. */
208
+ ephePath: string | null;
209
+ ephePathSource: RuntimeAssetSource | null;
210
+ /** How the files were made visible to Swiss Ephemeris. */
211
+ mountMode: SwissEphMountMode | null;
212
+ /** Path Swiss Ephemeris searches (inside the wasm virtual file system). */
213
+ swissEphePath: string | null;
214
+ /** How the Emscripten glue was loaded (native ESM loads the shipped CJS file by URL). */
215
+ nodeGlue: "bundled" | "external-file" | "browser" | null;
216
+ /** Swiss Ephemeris version string; null because the shipped wasm build does not export swe_version. */
217
+ swissEphemerisVersion: string | null;
218
+ /** Required ephemeris files and whether each is visible to Swiss Ephemeris. */
219
+ ephemerisFiles: {
220
+ required: string[];
221
+ found: string[];
222
+ missing: string[];
223
+ };
224
+ /** Documented coverage of the shipped files (Swiss file naming: *_18.se1 = 1800-2399 CE). */
225
+ shippedCoverage: {
226
+ fromYear: number;
227
+ toYearExclusive: number;
228
+ note: string;
229
+ };
230
+ /** Result of the init-time probe calculation (Sun at J2000, Swiss files requested). */
231
+ probe: SwissEphRuntimeRecord["probe"] | null;
232
+ }
233
+ /**
234
+ * Report what the engine actually resolved: asset paths and where they came from, how the
235
+ * ephemeris files are mounted, which files are visible, the Swiss version (if exposed),
236
+ * and the init-time probe. Safe to call before initialization (reports initialized: false).
237
+ */
238
+ declare function getSwissEphInfo(): SwissEphInfo;
239
+ /** Enable/disable process-wide strict mode (throw instead of returning substituted Moshier output). */
240
+ declare function setSwissEphStrictEphemeris(enabled: boolean): void;
241
+ interface GetSwissEphOptions {
242
+ ephePath?: string;
243
+ wasmPath?: string;
244
+ onRuntimeNotice?: (message: string) => void;
245
+ /**
246
+ * When true, any calculation for which Swiss Ephemeris silently substitutes another
247
+ * ephemeris (e.g. Moshier outside the installed .se1 range) throws a
248
+ * SwissEphEphemerisMismatchError. Applies to the shared instance, also when it is
249
+ * already initialized.
250
+ */
251
+ strictEphemeris?: boolean;
252
+ }
253
+ /**
254
+ * Initializes the shared Swiss Ephemeris instance (idempotent; concurrent first calls share
255
+ * one initialization).
93
256
  * In a browser environment, assets are loaded relative to the script.
94
- * In Node.js, assets are loaded from the package's 'dist' directory.
257
+ * In Node.js, assets are resolved next to the running module (`import.meta.url` in native
258
+ * ESM, `__dirname` in CJS), so default initialization works from a packed install.
95
259
  * @param options - Optional overrides for asset paths.
96
260
  * @param options.ephePath - Path to the directory containing ephemeris data files.
97
261
  * @param options.wasmPath - Path to the `swisseph.wasm` file.
98
262
  * @param options.onRuntimeNotice - Optional sink for path setup notices; defaults to stderr.
263
+ * @param options.strictEphemeris - Throw when Swiss Ephemeris substitutes Moshier output.
264
+ * @throws SwissEphError with a stable `code` (asset not found, ephemeris files unavailable, ...).
99
265
  */
100
- declare function getSwissEph(options?: {
101
- ephePath?: string;
102
- wasmPath?: string;
103
- onRuntimeNotice?: (message: string) => void;
104
- }): Promise<void>;
266
+ declare function getSwissEph(options?: GetSwissEphOptions): Promise<void>;
267
+ interface CalculatePlanetPositionDetailedOptions extends CalculatePositionOptions {
268
+ /** Swiss flags; defaults to SWISS_EPH | SPEED (the same as every other helper here). */
269
+ flags?: number;
270
+ }
271
+ /**
272
+ * Like calculateSinglePlanetPosition, but also reports provenance: the requested and
273
+ * returned Swiss flags and a derived `ephemeris` label ("swiss" | "moshier" | "jpl").
274
+ * `substituted` is true when Swiss Ephemeris returned a different ephemeris than requested
275
+ * (for example Moshier outside the installed .se1 range); with `strictEphemeris` that
276
+ * throws SwissEphEphemerisMismatchError instead.
277
+ */
278
+ declare function calculatePlanetPositionDetailed(date: Date, planet: Planet, options?: CalculatePlanetPositionDetailedOptions): PlanetPositionDetailed;
279
+ /**
280
+ * Run `fn` with Swiss global state (sidereal mode and/or topocentric observer) set, then
281
+ * restore the Swiss defaults (sidereal Fagan/Bradley = 0, topocentric 0/0/0) before
282
+ * returning, even if `fn` throws. The callback must be SYNCHRONOUS: because the state is
283
+ * process-wide, awaiting inside would let a concurrent caller observe it. A promise result
284
+ * and re-entrant use are rejected with SWISSEPH_STATE_MISUSE. Callers still opt in per call by
285
+ * adding CalcFlag.SIDEREAL / CalcFlag.TOPOCTR to the flags they pass.
286
+ */
287
+ declare function withSwissEphState<T>(state: {
288
+ sidereal?: {
289
+ mode: number;
290
+ t0?: number;
291
+ ayanT0?: number;
292
+ };
293
+ topocentric?: {
294
+ longitude: number;
295
+ latitude: number;
296
+ altitudeMeters?: number;
297
+ };
298
+ }, fn: () => T): T;
105
299
  /**
106
300
  * Clean up Swiss Ephemeris resources
107
301
  */
@@ -366,8 +560,86 @@ declare function getDetriment(planet: TraditionalPlanet): Sign[];
366
560
  /** Sign where the planet is in fall (opposite of its exaltation sign). */
367
561
  declare function getFall(planet: TraditionalPlanet): Sign;
368
562
  declare function getEssentialDignity(planet: TraditionalPlanet, sign: Sign): EssentialDignityResult;
563
+ /** Tradition names used by the extended dignity tables. */
564
+ declare const DIGNITY_TRADITION: {
565
+ readonly rulership: "traditional (Ptolemaic) domicile, exaltation, detriment and fall";
566
+ readonly triplicity: "Dorothean (day / night / participating rulers by element)";
567
+ readonly bounds: "Egyptian (Ptolemaic Tetrabiblos I.21 'Egyptian' terms)";
568
+ readonly face: "Chaldean decans (order Mars, Sun, Venus, Mercury, Moon, Saturn, Jupiter from 0 Aries)";
569
+ readonly intervalConvention: "half-open [start, end) in degrees of ecliptic longitude";
570
+ };
571
+ type TriplicityElement = "fire" | "earth" | "air" | "water";
572
+ type TriplicityRole = "day" | "night" | "participating";
573
+ declare const SIGN_ELEMENTS: Record<Sign, TriplicityElement>;
574
+ /** Dorothean triplicity rulers by element. */
575
+ declare const DOROTHEAN_TRIPLICITY_RULERS: Record<TriplicityElement, Record<TriplicityRole, TraditionalPlanet>>;
576
+ interface BoundSegment {
577
+ ruler: TraditionalPlanet;
578
+ /** Start degree within the sign, inclusive. */
579
+ start: number;
580
+ /** End degree within the sign, exclusive. */
581
+ end: number;
582
+ }
583
+ /** Egyptian bounds (terms) with half-open `[start, end)` degree intervals within each sign. */
584
+ declare const EGYPTIAN_BOUNDS: Record<Sign, BoundSegment[]>;
585
+ /** Egyptian bound ruler at an ecliptic longitude (half-open intervals). */
586
+ declare function getEgyptianBound(longitude: number): BoundSegment & {
587
+ sign: Sign;
588
+ };
589
+ /** Dorothean triplicity rulers for a sign. */
590
+ declare function getDorotheanTriplicity(sign: Sign): Record<TriplicityRole, TraditionalPlanet> & {
591
+ element: TriplicityElement;
592
+ };
593
+ /** Chaldean face (decan) ruler at an ecliptic longitude. */
594
+ declare function getFaceRuler(longitude: number): TraditionalPlanet;
595
+ type PositiveDignity = "domicile" | "exaltation" | "triplicity" | "participatingTriplicity" | "bound" | "face";
596
+ interface EssentialDignitiesDetail {
597
+ planet: TraditionalPlanet;
598
+ longitude: number;
599
+ sign: Sign;
600
+ degreeInSign: number;
601
+ /** Sect used to select the triplicity ruler; null when not supplied. */
602
+ sect: Sect | null;
603
+ domicile: boolean;
604
+ exaltation: boolean;
605
+ /** Planet is the Dorothean ruler matching `sect` (false when sect is null). */
606
+ triplicity: boolean;
607
+ /** Planet is the participating (third) Dorothean ruler. */
608
+ participatingTriplicity: boolean;
609
+ /** Planet's role among the three triplicity rulers of this element, if any (day/night/participating). */
610
+ triplicityRole: TriplicityRole | null;
611
+ bound: boolean;
612
+ face: boolean;
613
+ detriment: boolean;
614
+ fall: boolean;
615
+ /**
616
+ * True only when none of the positive dignities applies: domicile,
617
+ * exaltation, triplicity (any of day / night / participating ruler of the
618
+ * element, so the result does not depend on sect knowledge), bound or face.
619
+ * Detriment and fall do not affect it.
620
+ */
621
+ peregrine: boolean;
622
+ positiveDignities: PositiveDignity[];
623
+ rulers: {
624
+ domicile: TraditionalPlanet;
625
+ exaltation: TraditionalPlanet | null;
626
+ triplicity: Record<TriplicityRole, TraditionalPlanet> & {
627
+ element: TriplicityElement;
628
+ sectRuler: TraditionalPlanet | null;
629
+ };
630
+ bound: TraditionalPlanet;
631
+ face: TraditionalPlanet;
632
+ };
633
+ tradition: typeof DIGNITY_TRADITION;
634
+ }
635
+ /**
636
+ * Degree- and sect-aware essential dignities for a traditional planet at an
637
+ * ecliptic longitude. Extends (does not replace) `getEssentialDignity`, whose
638
+ * `peregrine` ignores triplicity, bounds and faces.
639
+ */
640
+ declare function getEssentialDignities(planet: TraditionalPlanet, longitude: number, sect?: Sect | null): EssentialDignitiesDetail;
369
641
 
370
- /** Lowercase chart planet keys. Not every planet has authored descriptions yet. */
642
+ /** Lowercase chart planet keys; authored coverage varies by factor kind. */
371
643
  type DescriptionPlanet = "sun" | "moon" | "mercury" | "venus" | "mars" | "jupiter" | "saturn" | "uranus" | "neptune" | "pluto";
372
644
  interface PlanetSignDescriptionEntry {
373
645
  readonly pt: string;
@@ -383,14 +655,27 @@ interface PlanetSignDescriptionEntry {
383
655
  }[];
384
656
  readonly reviewNotes: readonly string[];
385
657
  }
658
+ type DescriptionHouseNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
659
+ type PlanetHouseDescriptionEntry = PlanetSignDescriptionEntry;
660
+ type HouseDescriptionEntry = PlanetSignDescriptionEntry;
386
661
  interface AstrologyDescriptions {
387
662
  readonly planetSigns: Readonly<Partial<Record<DescriptionPlanet, Readonly<Partial<Record<Sign, PlanetSignDescriptionEntry>>>>>>;
663
+ readonly planetHouses: Readonly<Partial<Record<DescriptionPlanet, Readonly<Partial<Record<DescriptionHouseNumber, PlanetHouseDescriptionEntry>>>>>>;
664
+ readonly houses?: Readonly<Partial<Record<DescriptionHouseNumber, HouseDescriptionEntry>>>;
388
665
  }
389
666
  declare const ASTROLOGY_DESCRIPTIONS: AstrologyDescriptions;
390
667
  /** Return the immutable authored entry; inherited keys are never descriptions. */
391
668
  declare function getPlanetSignDescriptionEntry(planet: DescriptionPlanet, sign: Sign): PlanetSignDescriptionEntry | undefined;
392
669
  /** English by default; Portuguese for locale strings starting with `pt`. */
393
670
  declare function getPlanetSignDescription(planet: DescriptionPlanet, sign: Sign, language?: string): string | undefined;
671
+ /** Chart house numbers are one-based; missing placements have no profile fallback. */
672
+ declare function getPlanetHouseDescriptionEntry(planet: DescriptionPlanet, house: number): PlanetHouseDescriptionEntry | undefined;
673
+ /** English by default; Portuguese for locale strings starting with `pt`. */
674
+ declare function getPlanetHouseDescription(planet: DescriptionPlanet, house: number, language?: string): string | undefined;
675
+ /** Numbered house themes, independent of planet placements and angle identities. */
676
+ declare function getHouseDescriptionEntry(house: number): HouseDescriptionEntry | undefined;
677
+ /** English by default; Portuguese for locale strings starting with `pt`. */
678
+ declare function getHouseDescription(house: number, language?: string): string | undefined;
394
679
 
395
680
  /**
396
681
  * Decan (face) lookup — Chaldean rulers + Golden Dawn tarot correspondence.
@@ -444,11 +729,60 @@ interface MonthlyProfectionsResult {
444
729
  }
445
730
  declare function getAnnualProfection(natalChart: BirthChart, birthDate: Date, targetYear?: number): AnnualProfection;
446
731
  declare function getMonthlyProfections(natalChart: BirthChart, birthDate: Date, targetYear?: number): MonthlyProfectionsResult;
732
+ /** Hard cap on profection years per timeline call. */
733
+ declare const MAX_PROFECTION_TIMELINE_YEARS = 150;
734
+ interface ProfectionForAge {
735
+ age: number;
736
+ house: number;
737
+ sign: string;
738
+ ruler: TraditionalPlanet;
739
+ }
740
+ /**
741
+ * Whole-sign annual profection for an age: house = age mod 12 + 1 and the profected
742
+ * sign counted from the natal ASCENDANT sign (whole-sign houses by definition, so it
743
+ * is correct for any recorded house system). Agrees with `getAnnualProfection` for
744
+ * whole-sign charts.
745
+ */
746
+ declare function getProfectionForAge(natalChart: BirthChart, age: number): ProfectionForAge;
747
+ interface ProfectionTimelineEntry extends ProfectionForAge {
748
+ /** Birthday that starts this profection year (civil date; 29 Feb births use 1 Mar in non-leap years). */
749
+ start: CivilDate;
750
+ /** Next birthday: the half-open end of the year [start, endExclusive). */
751
+ endExclusive: CivilDate;
752
+ }
753
+ type ProfectionTimelineRange = {
754
+ fromAge: number;
755
+ toAge: number;
756
+ } | {
757
+ from: CivilDate | Date;
758
+ to: CivilDate | Date;
759
+ };
760
+ interface ProfectionTimelineResult {
761
+ entries: ProfectionTimelineEntry[];
762
+ birth: CivilDate;
763
+ method: {
764
+ houses: "whole-sign from the natal ascendant sign";
765
+ yearBoundary: "birthday to next birthday, half-open [start, endExclusive); 29 Feb births roll to 1 Mar in non-leap years";
766
+ selection: string;
767
+ };
768
+ }
769
+ /**
770
+ * One entry per annual profection year for a bounded age range or civil-date range
771
+ * (a year is included when [start, endExclusive) overlaps [from, to] of the date
772
+ * range). Dates are civil dates; `Date` inputs are read with local calendar getters.
773
+ */
774
+ declare function getAnnualProfectionTimeline(natalChart: BirthChart, birth: CivilDate | Date, range: ProfectionTimelineRange): ProfectionTimelineResult;
447
775
 
448
776
  /**
449
777
  * Firdaria — traditional planetary period system.
450
778
  * Pure math, no WASM dependency.
451
779
  */
780
+ type TimelineErrorCode = "INVALID_RANGE" | "RANGE_TOO_LARGE" | "UNBOUNDED_INPUT" | "INVALID_INPUT" | "UNAVAILABLE_INPUT";
781
+ /** Typed error of the bounded timeline functions (profections, firdaria, return passes). */
782
+ declare class TimelineError extends Error {
783
+ readonly code: TimelineErrorCode;
784
+ constructor(code: TimelineErrorCode, message: string);
785
+ }
452
786
  type FirdariaPlanet = "Sun" | "Moon" | "Mercury" | "Venus" | "Mars" | "Jupiter" | "Saturn" | "NorthNode" | "SouthNode";
453
787
  interface FirdariaSubPeriod {
454
788
  planet: FirdariaPlanet;
@@ -472,190 +806,3131 @@ interface FirdariaOptions {
472
806
  nodeSubPeriodStart?: "jupiter-saturn" | "sun-mars";
473
807
  }
474
808
  declare function getFirdaria(birthDate: Date, isDiurnal: boolean, targetDate?: Date, options?: FirdariaOptions): FirdariaResult;
475
-
476
- /** Names used by astrology calculations, including dignity, sect and lunar nodes. */
477
- declare const ASTROLOGY_LABELS: Readonly<Record<string, Readonly<{
478
- en: string;
479
- pt: string;
480
- }>>>;
481
- /**
482
- * Display a sign, planet, node, dignity, sect, aspect or decan card name in the requested language.
483
- * English is the default. Calculation identifiers remain unchanged. Unknown names pass through.
484
- */
485
- declare function getAstrologyLabel(label: string, language?: string): string;
486
-
487
- /**
488
- * Astrological calculations using Swiss Ephemeris
489
- */
490
-
491
- interface BirthChartOptions {
492
- /**
493
- * Local civil date-time for the chart moment.
494
- * Prefer `LocalDateTimeParts` when the source data comes from separate
495
- * date/time inputs so callers do not have to encode wall-clock parts into a
496
- * browser-local `Date`.
497
- */
498
- date: Date | LocalDateTimeParts;
499
- latitude: number;
500
- longitude: number;
501
- houseSystem?: HouseSystem;
502
- timeZoneSettings?: TimeZoneOptions;
809
+ /** Hard caps: at most 3 repeats of the 75-year sequence, and a window of at most 225 years. */
810
+ declare const MAX_FIRDARIA_CYCLES = 3;
811
+ declare const MAX_FIRDARIA_WINDOW_YEARS = 225;
812
+ /** Years of one full firdaria sequence. */
813
+ declare const FIRDARIA_CYCLE_YEARS = 75;
814
+ /** All major periods (with sub-periods) of `cycles` repeats of the 75-year sequence, from birth. */
815
+ declare function getFirdariaPeriods(birthDate: Date, isDiurnal: boolean, cycles?: number, options?: FirdariaOptions): FirdariaMajorPeriod[];
816
+ interface FirdariaTimelineOptions extends FirdariaOptions {
817
+ /** Window start (inclusive). Default: birth. */
818
+ from?: Date;
819
+ /** Window end (exclusive). Required: unbounded timelines are refused. */
820
+ to: Date;
821
+ /** Include the 7 sub-periods of each major (default true). */
822
+ includeSubPeriods?: boolean;
503
823
  }
504
- type ZodiacPosition = {
505
- sign: string;
506
- decimalDegrees: number;
507
- traditionalFormat: string;
508
- decimal: string;
509
- longitude: number;
510
- house: number;
511
- };
512
- type HydratedNode = ZodiacPosition & {
513
- id: VirtualNodes;
514
- name: string;
515
- };
516
- type HydratedPlanet = PlanetPosition & {
517
- id: Planet;
518
- name: string;
519
- zodiacPosition: ZodiacPosition;
520
- };
521
- type Sect = "diurnal" | "nocturnal";
522
- interface BirthChart {
523
- dateUtc: Date;
524
- planets: Record<string, HydratedPlanet>;
525
- nodes: Record<string, HydratedNode>;
526
- houses: {
527
- ascendant: ZodiacPosition;
528
- mc: ZodiacPosition;
529
- dc: ZodiacPosition;
530
- ic: ZodiacPosition;
531
- houses: ZodiacPosition[];
532
- ascmc?: {
533
- armc?: ZodiacPosition;
534
- vertex?: ZodiacPosition;
535
- equasc?: ZodiacPosition;
536
- coasc1?: ZodiacPosition;
537
- coasc2?: ZodiacPosition;
538
- polasc?: ZodiacPosition;
539
- };
824
+ interface FirdariaTimelineSub {
825
+ planet: FirdariaPlanet;
826
+ /** Clipped start (inclusive). */
827
+ start: Date;
828
+ /** Clipped end (exclusive). */
829
+ endExclusive: Date;
830
+ nominalStart: Date;
831
+ nominalEnd: Date;
832
+ clippedStart: boolean;
833
+ clippedEnd: boolean;
834
+ }
835
+ interface FirdariaTimelineEntry {
836
+ planet: FirdariaPlanet;
837
+ years: number;
838
+ /** 0-based repeat of the 75-year sequence. */
839
+ cycle: number;
840
+ start: Date;
841
+ endExclusive: Date;
842
+ nominalStart: Date;
843
+ nominalEnd: Date;
844
+ clippedStart: boolean;
845
+ clippedEnd: boolean;
846
+ subPeriods: FirdariaTimelineSub[];
847
+ }
848
+ interface FirdariaTimelineResult {
849
+ sect: "diurnal" | "nocturnal";
850
+ window: {
851
+ from: Date;
852
+ toExclusive: Date;
853
+ };
854
+ entries: FirdariaTimelineEntry[];
855
+ method: {
856
+ yearLengthDays: 365.25;
857
+ intervals: "half-open [start, endExclusive); consecutive periods share the boundary instant";
858
+ subPeriods: string;
859
+ sequence: string;
540
860
  };
541
- aspects: AspectEdge[];
542
- sect: Sect;
543
861
  }
544
862
  /**
545
- * Determines chart sect from the Sun's house position.
546
- * Houses 7-12 place the Sun above the horizon, matching the rule used by getBirthChart.
863
+ * Major and sub periods intersecting a bounded window, clipped to it (nominal ends are kept).
864
+ * Reuses the firdaria sequence, year length (365.25 d) and sub-period rules of `getFirdaria`.
547
865
  */
548
- declare function getSect(sunHouse: number): Sect;
866
+ declare function getFirdariaTimeline(birthDate: Date, isDiurnal: boolean, options: FirdariaTimelineOptions): FirdariaTimelineResult;
867
+
549
868
  /**
550
- * Calculate a birth chart using Swiss Ephemeris
869
+ * Ephemeris-agnostic, station-aware search for exact angular crossings.
551
870
  *
552
- * @param options Chart calculation options
553
- * @returns Birth chart data
871
+ * The solver finds every time `t` in a window at which an angular function
872
+ * `longitude(t)` equals a target angle, using the SIGNED angular difference
873
+ * normalised to (-180, 180]. It never minimises an orb: a "closest approach"
874
+ * is a different result kind and is never labelled exact.
875
+ *
876
+ * Three concepts are kept separate throughout:
877
+ * - display orb: a caller concern (not used by the solver),
878
+ * - root angular residual: `|signedAngle(longitude(t) - target)|` at the emitted instant,
879
+ * - time tolerance: width of the final bracket (seconds).
880
+ *
881
+ * Time values are Julian Days (UT) when the solver is used with an ephemeris,
882
+ * but any monotone day-valued coordinate works for pure/analytic functions.
883
+ *
884
+ * Coverage qualification: roots are found on a finite grid refined with
885
+ * velocity-zero stations (sign changes of the longitude speed between grid
886
+ * points). Two stations hidden entirely inside one grid step are not formally
887
+ * excluded; this is a station-aware numerical search, not a symbolic proof of
888
+ * completeness.
554
889
  */
555
- declare function getBirthChart(options: BirthChartOptions): Promise<BirthChart>;
556
- declare const SIGNS: readonly ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"];
890
+ declare function jdToDate(jd: number): Date;
891
+ declare function dateToJd(date: Date): number;
892
+ /** Signed angular difference normalised to (-180, 180]. */
893
+ declare function signedAngleDifference(value: number): number;
894
+ type RootDirection = "direct" | "retrograde" | "stationary";
895
+ interface AngularRootSearchOptions {
896
+ /** Longitude in degrees (any real value; wrapped internally) at time `t`. */
897
+ longitude: (t: number) => number;
898
+ /** Optional longitude speed in degrees/day. Defaults to a central difference of `longitude`. */
899
+ speed?: (t: number) => number;
900
+ /** Target angle in degrees. */
901
+ target: number;
902
+ /** Window start/end (Julian Days or any day-valued coordinate); both ends are inclusive. */
903
+ start: number;
904
+ end: number;
905
+ /** Coarse grid step in days. Default 1. */
906
+ stepDays?: number;
907
+ /** Final bracket width in seconds. Default 0.001. */
908
+ timeToleranceSeconds?: number;
909
+ /** Maximum accepted |residual| in degrees for an emitted root. Default 1e-6. */
910
+ residualToleranceDegrees?: number;
911
+ /** Also return stationary closest approaches that do not reach the target. Default false. */
912
+ includeClosestApproaches?: boolean;
913
+ /** Only keep closest approaches with separation <= this (degrees). Default: unlimited. */
914
+ maxClosestSeparationDegrees?: number;
915
+ }
916
+ interface AngularRoot {
917
+ kind: "exact";
918
+ /** Root instant as Julian Day (the solver's time coordinate). */
919
+ jd: number;
920
+ /** Root instant as a UTC Date (millisecond rounded; assumes `t` is a UT Julian Day). */
921
+ instant: Date;
922
+ /** |signed angular difference| at `jd`, degrees. */
923
+ residualDegrees: number;
924
+ /** Signed difference longitude - target at `jd`, degrees in (-180, 180]. */
925
+ signedResidualDegrees: number;
926
+ /** Width of the final bracket in seconds (0 when the root is a sampled/analytic point). */
927
+ bracketWidthSeconds: number;
928
+ /** Requested time tolerance in seconds. */
929
+ timeToleranceSeconds: number;
930
+ /** Function evaluations spent refining this root's bracket. */
931
+ iterations: number;
932
+ /** Motion at the root. `stationary` for tangencies at a velocity-zero station. */
933
+ direction: RootDirection;
934
+ /** Longitude speed at the root (deg/day). */
935
+ speedDegreesPerDay: number;
936
+ /** True when the root coincides with a velocity-zero station (tangent touch). */
937
+ tangent: boolean;
938
+ /** How the root was found. */
939
+ method: "bracket-bisection" | "sample" | "station-tangent";
940
+ /** True when the root is exactly at the window start or end. */
941
+ boundary: boolean;
942
+ }
943
+ interface AngularClosestApproach {
944
+ kind: "closest-approach";
945
+ jd: number;
946
+ instant: Date;
947
+ /** Minimum |signed difference| in degrees; > 0 and never an exact crossing. */
948
+ separationDegrees: number;
949
+ signedSeparationDegrees: number;
950
+ direction: "stationary";
951
+ }
952
+ interface RootSearchCoverage {
953
+ scope: "finite-grid";
954
+ stepDays: number;
955
+ gridPoints: number;
956
+ stationsFound: number;
957
+ /** Fixed wording: no symbolic all-pass completeness is claimed. */
958
+ note: string;
959
+ }
960
+ interface AngularRootSearchResult {
961
+ target: number;
962
+ start: number;
963
+ end: number;
964
+ roots: AngularRoot[];
965
+ closestApproaches: AngularClosestApproach[];
966
+ /** Bracketed crossings dropped because the residual check failed (should be empty). */
967
+ rejected: {
968
+ jd: number;
969
+ residualDegrees: number;
970
+ }[];
971
+ coverage: RootSearchCoverage;
972
+ residualToleranceDegrees: number;
973
+ }
974
+ declare const ROOT_SEARCH_COVERAGE_NOTE: string;
557
975
  /**
558
- * Convert decimal degrees to degrees and minutes format
559
- *
560
- * @param decimalDegrees Decimal degrees (e.g., 9.8)
561
- * @returns Formatted string (e.g., "9°48'")
976
+ * Find all exact crossings of `target` by `longitude(t)` inside [start, end].
977
+ * Pure: depends only on the supplied functions.
562
978
  */
563
- declare function formatDegreeMinutes(decimalDegrees: number): string;
979
+ declare function findAngularRoots(options: AngularRootSearchOptions): AngularRootSearchResult;
980
+
564
981
  /**
565
- * Convert decimal degrees to zodiac position (sign and degrees)
982
+ * Exact longitude crossings and planetary returns built on the shared
983
+ * station-aware root solver (see ./root-solver).
566
984
  *
567
- * @param longitude Longitude in decimal degrees (0-360)
568
- * @returns Formatted zodiac position with both decimal and traditional format
985
+ * All functions are synchronous and require the Swiss Ephemeris to be
986
+ * initialised (`await getSwissEph(...)`). Solved instants are UTC.
987
+ *
988
+ * Time coordinate: UT Julian Day, passed to the ephemeris exactly (the Julian Day is
989
+ * never rebuilt from a whole-second Date, so no sub-second information is lost).
569
990
  */
570
- declare function getZodiacPosition(longitude: number, houseCusps: number[]): ZodiacPosition;
571
- declare function findHouseOf(longitude: number, housePositions: number[]): number;
572
- interface TwoChartOptions {
573
- chartA: BirthChartOptions;
574
- chartB: BirthChartOptions;
575
- aspectSpecs?: AspectSpec[];
991
+
992
+ /** Largest scan step allowed for ephemeris-backed searches (days). */
993
+ declare const MAX_BODY_SCAN_STEP_DAYS = 2;
994
+ interface BodyLongitudeSample {
995
+ longitude: number;
996
+ speed: number;
576
997
  }
577
- type SynastryChartOptions = TwoChartOptions;
578
- type CompositeChartOptions = TwoChartOptions;
579
- interface SynastryChart {
580
- chartA: BirthChart;
581
- chartB: BirthChart;
582
- aspects: AspectEdge[];
998
+ /** Longitude (deg, [0,360)) and speed (deg/day) of `body` at an exact UT Julian Day. */
999
+ declare function sampleBodyAtJd(body: Planet, jd: number): BodyLongitudeSample;
1000
+ interface BodyLongitudeFunctions {
1001
+ longitude: (jd: number) => number;
1002
+ speed: (jd: number) => number;
583
1003
  }
584
- interface CompositeChart {
585
- chartA: BirthChart;
586
- chartB: BirthChart;
587
- compositePlanets: Record<string, {
588
- name: string;
589
- longitude: number;
590
- zodiacPosition: ZodiacPosition;
591
- }>;
592
- compositeHouses: ZodiacPosition[];
593
- aspects: AspectEdge[];
1004
+ /** Cached longitude/speed functions for one body (shared by every search over that body). */
1005
+ declare function createBodyLongitudeFunctions(body: Planet): BodyLongitudeFunctions;
1006
+ interface RootSolverMethodMetadata {
1007
+ solver: "signed-angle-bracketing+station-insertion+bisection";
1008
+ timeScale: "UT Julian Day";
1009
+ ephemeris: "Swiss Ephemeris (SWISS_EPH, SPEED)";
1010
+ subSecondEvaluation: "exact Julian Day evaluation (no sub-second truncation or extrapolation)";
594
1011
  }
595
- declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart>;
596
- declare function getCompositeChart(options: CompositeChartOptions): Promise<CompositeChart>;
597
- interface TransitChartOptions {
598
- natal: BirthChartOptions;
599
- transitDate: Date;
600
- transitLatitude?: number;
601
- transitLongitude?: number;
602
- transitTimeZoneSettings?: TimeZoneOptions;
603
- aspectSpecs?: AspectSpec[];
604
- maxOrb?: number;
605
- transitPlanets?: string[];
606
- natalPlanets?: string[];
607
- aspectFilter?: AspectName[];
1012
+ declare const ROOT_SOLVER_METHOD: RootSolverMethodMetadata;
1013
+ interface BodyCrossingOptions {
1014
+ body: Planet;
1015
+ /** Tropical target longitude in degrees. */
1016
+ targetLongitude: number;
1017
+ /** Window (inclusive). Dates are absolute UTC instants. */
1018
+ from: Date;
1019
+ to: Date;
1020
+ /** Scan step in days (default 1, capped at 2). */
1021
+ stepDays?: number;
1022
+ /** Final bracket width in seconds (default 0.001). */
1023
+ timeToleranceSeconds?: number;
1024
+ /** Max accepted residual in degrees (default 1e-6). */
1025
+ residualToleranceDegrees?: number;
1026
+ includeClosestApproaches?: boolean;
1027
+ maxClosestSeparationDegrees?: number;
608
1028
  }
609
- interface TransitPlanet extends HydratedPlanet {
610
- retrograde: boolean;
611
- natalHouse: number;
1029
+ interface BodyCrossing extends AngularRoot {
1030
+ /** 1-based index among the passes in the window. */
1031
+ passIndex: number;
1032
+ /** Total passes found in the window. */
1033
+ passCount: number;
612
1034
  }
613
- interface TransitChart {
614
- natalChart: BirthChart;
615
- transitDateUtc: Date;
616
- transitPlanets: Record<string, TransitPlanet>;
617
- aspects: TransitAspectEdge[];
1035
+ interface BodyCrossingResult {
1036
+ body: Planet;
1037
+ bodyName: string;
1038
+ targetLongitude: number;
1039
+ from: Date;
1040
+ to: Date;
1041
+ crossings: BodyCrossing[];
1042
+ closestApproaches: AngularClosestApproach[];
1043
+ rejected: {
1044
+ jd: number;
1045
+ residualDegrees: number;
1046
+ }[];
1047
+ coverage: RootSearchCoverage;
1048
+ residualToleranceDegrees: number;
1049
+ timeToleranceSeconds: number;
1050
+ method: RootSolverMethodMetadata;
618
1051
  }
619
- interface TransitRangeOptions extends Omit<TransitChartOptions, "transitDate"> {
1052
+ /** All exact passes of `body` over a tropical longitude in [from, to]. */
1053
+ declare function findBodyLongitudeCrossings(options: BodyCrossingOptions): BodyCrossingResult;
1054
+ /** Same as {@link findBodyLongitudeCrossings} with caller-supplied (cacheable) sampling functions. */
1055
+ declare function findBodyLongitudeCrossingsWith(fns: BodyLongitudeFunctions, options: BodyCrossingOptions): BodyCrossingResult;
1056
+ /** Minimal structural view of a natal chart (compatible with `BirthChart`). */
1057
+ interface NatalLongitudeSource {
1058
+ planets: Record<string, {
1059
+ longitude: number;
1060
+ }>;
1061
+ }
1062
+ interface PlanetaryReturnOptions {
1063
+ /** Body whose crossing is searched (natal position of the same body unless `natalBody` is set). */
1064
+ body: Planet;
1065
+ /** Natal longitude to return to. Takes precedence over `natalChart`. */
1066
+ natalLongitude?: number;
1067
+ /** Natal chart used to look up the natal longitude of `natalBody ?? body`. */
1068
+ natalChart?: NatalLongitudeSource;
1069
+ natalBody?: Planet;
1070
+ /** Angular offset from the natal longitude (0 = return, 180 = opposition). */
1071
+ offsetDegrees?: number;
620
1072
  from: Date;
621
1073
  to: Date;
622
1074
  stepDays?: number;
1075
+ timeToleranceSeconds?: number;
1076
+ residualToleranceDegrees?: number;
1077
+ includeClosestApproaches?: boolean;
1078
+ maxClosestSeparationDegrees?: number;
623
1079
  }
624
- interface AspectPerfection {
1080
+ interface PlanetaryReturnResult extends BodyCrossingResult {
1081
+ natalLongitude: number;
1082
+ offsetDegrees: number;
1083
+ /** "return" for offset 0, "opposition" for 180, otherwise "offset-aspect". */
1084
+ eventKind: "return" | "opposition" | "offset-aspect";
1085
+ }
1086
+ /** All passes of `body` over its (offset) natal longitude in the window. */
1087
+ declare function findPlanetaryReturns(options: PlanetaryReturnOptions): PlanetaryReturnResult;
1088
+ type ReturnWrapperOptions = Omit<PlanetaryReturnOptions, "body" | "offsetDegrees" | "natalBody">;
1089
+ /** Solar returns (Sun to natal Sun). Usually one pass per year. */
1090
+ declare function findSolarReturns(options: ReturnWrapperOptions): PlanetaryReturnResult;
1091
+ /** Lunar returns (Moon to natal Moon); default step 0.5 day. */
1092
+ declare function findLunarReturns(options: ReturnWrapperOptions): PlanetaryReturnResult;
1093
+ /** Jupiter returns; returns ALL passes (up to three, due to retrograde). */
1094
+ declare function findJupiterReturns(options: ReturnWrapperOptions): PlanetaryReturnResult;
1095
+ /** Saturn returns; returns ALL passes (up to three, due to retrograde). */
1096
+ declare function findSaturnReturns(options: ReturnWrapperOptions): PlanetaryReturnResult;
1097
+ /** Nodal returns (mean node by default; pass `node: "true"` for the true node). */
1098
+ declare function findNodalReturns(options: ReturnWrapperOptions & {
1099
+ node?: "mean" | "true";
1100
+ }): PlanetaryReturnResult;
1101
+ /** Uranus opposition to its natal longitude (half-cycle); returns all passes. */
1102
+ declare function findUranusOppositions(options: ReturnWrapperOptions): PlanetaryReturnResult;
1103
+
1104
+ /**
1105
+ * Exact transit-to-natal aspect events built on the shared root solver.
1106
+ *
1107
+ * Natal targets are fixed points (zero velocity). Only verified crossings are
1108
+ * reported as exact; local minima that never reach the aspect are optional,
1109
+ * separate "closest approach" records.
1110
+ */
1111
+
1112
+ /** Solver metadata attached to every exact transit perfection. */
1113
+ interface PerfectionSolverMetadata {
1114
+ /** Angular root residual in degrees (separate from the display orb). */
1115
+ residualDegrees: number;
1116
+ /** Final bracket width in seconds. */
1117
+ bracketWidthSeconds: number;
1118
+ /** Requested time tolerance in seconds. */
1119
+ timeToleranceSeconds: number;
1120
+ iterations: number;
1121
+ direction: RootDirection;
1122
+ tangent: boolean;
1123
+ /** Scan step actually used for the transiting body (days). */
1124
+ scanStepDays: number;
1125
+ /** Signed target longitude solved (natal longitude +/- aspect angle). */
1126
+ targetLongitude: number;
1127
+ coverage: RootSearchCoverage;
1128
+ method: RootSolverMethodMetadata;
1129
+ }
1130
+ interface TransitPerfectionEvent {
1131
+ kind: "exact";
625
1132
  transitPlanet: string;
626
1133
  natalPlanet: string;
627
1134
  aspect: AspectName;
1135
+ /** Verified root instant (UTC). */
628
1136
  exactDate: Date;
1137
+ exactJd: number;
1138
+ /** Equals the angular root residual (~0); not the display orb. */
629
1139
  exactOrb: number;
630
1140
  retrograde: boolean;
631
1141
  category: "slow" | "fast";
1142
+ solver: PerfectionSolverMetadata;
632
1143
  }
633
- interface TransitRangeResult {
634
- natalChart: BirthChart;
635
- from: Date;
636
- to: Date;
637
- perfections: AspectPerfection[];
1144
+ interface TransitClosestApproach {
1145
+ kind: "closest-approach";
1146
+ transitPlanet: string;
1147
+ natalPlanet: string;
1148
+ aspect: AspectName;
1149
+ /** Instant of minimum separation (UTC) - NOT an exact aspect. */
1150
+ date: Date;
1151
+ jd: number;
1152
+ /** Minimum angular separation from the exact aspect in degrees (> 0). */
1153
+ separationDegrees: number;
1154
+ /** Display orb of the aspect spec the separation was compared with. */
1155
+ displayOrb: number;
1156
+ category: "slow" | "fast";
638
1157
  }
639
- declare function getTransitChart(options: TransitChartOptions): Promise<TransitChart>;
640
- declare function getTransitRange(options: TransitRangeOptions): Promise<TransitRangeResult>;
641
- interface SolarReturnOptions {
642
- natal: BirthChartOptions;
643
- year: number;
1158
+ interface FindTransitPerfectionsOptions {
1159
+ /** Fixed natal targets (longitude in degrees). */
1160
+ natalPoints: Record<string, {
1161
+ longitude: number;
1162
+ }>;
1163
+ /** Lowercase transit body names to search; undefined = all bodies. */
1164
+ transitPlanets?: string[];
1165
+ fromUtc: Date;
1166
+ toUtc: Date;
1167
+ stepDays: number;
1168
+ aspectSpecs?: AspectSpec[];
1169
+ timeToleranceSeconds?: number;
1170
+ residualToleranceDegrees?: number;
1171
+ includeClosestApproaches?: boolean;
1172
+ }
1173
+ interface FindTransitPerfectionsResult {
1174
+ perfections: TransitPerfectionEvent[];
1175
+ closestApproaches: TransitClosestApproach[];
1176
+ }
1177
+ declare function findTransitPerfections(options: FindTransitPerfectionsOptions): FindTransitPerfectionsResult;
1178
+
1179
+ /**
1180
+ * Sect (diurnal / nocturnal) from the physical horizon.
1181
+ *
1182
+ * Sect is a property of the sky, not of the house system: a chart is diurnal
1183
+ * when the Sun is above the horizon at the birth place and nocturnal otherwise.
1184
+ * The legacy `getSect(sunHouse)` approximation (in `./index`) only matches this
1185
+ * when the quadrant house cusps coincide with the horizon (Placidus-like
1186
+ * systems); in whole-sign houses it can be wrong by up to a whole sign.
1187
+ */
1188
+
1189
+ /** Which Sun altitude decides the sect. */
1190
+ type SectAltitudeBasis =
1191
+ /** True (unrefracted) altitude of the Sun's centre of disc. Default. */
1192
+ "geometric"
1193
+ /** Altitude including standard atmospheric refraction (1013.25 mbar, 15 C). */
1194
+ | "apparent";
1195
+ interface SectOptions {
1196
+ /** Altitude basis; default `"geometric"`. */
1197
+ basis?: SectAltitudeBasis;
1198
+ /**
1199
+ * Sun altitude threshold in degrees (default 0, the mathematical horizon).
1200
+ * Sect is diurnal when altitude is strictly greater than the threshold.
1201
+ */
1202
+ horizonAltitude?: number;
1203
+ }
1204
+ interface SectResult {
1205
+ sect: Sect;
1206
+ /** True (geometric) altitude of the Sun's centre, degrees. */
1207
+ sunGeometricAltitude: number;
1208
+ /** Refraction-corrected altitude, degrees. */
1209
+ sunApparentAltitude: number;
1210
+ /** Altitude actually compared against the threshold. */
1211
+ altitudeUsed: number;
1212
+ method: {
1213
+ basis: SectAltitudeBasis;
1214
+ horizonAltitude: number;
1215
+ /** Exact-horizon convention. */
1216
+ exactHorizon: "nocturnal";
1217
+ description: string;
1218
+ };
1219
+ }
1220
+ /**
1221
+ * Exact-horizon convention: sect is `"diurnal"` only when the altitude is
1222
+ * strictly greater than the threshold; an altitude exactly equal to the
1223
+ * threshold (0 by default) is `"nocturnal"`. Callers wanting the opposite
1224
+ * convention can use `sunGeometricAltitude` from the result.
1225
+ */
1226
+ declare function getSectFromAltitude(altitude: number, horizonAltitude?: number): Sect;
1227
+ /**
1228
+ * Compute sect from the Sun's position at the birth place. Requires an
1229
+ * initialised Swiss Ephemeris (it calls swe_azalt with default pressure and
1230
+ * temperature for the apparent altitude).
1231
+ *
1232
+ * @param dateUtc instant of birth (UTC)
1233
+ * @param sun ecliptic longitude/latitude of the Sun (degrees)
1234
+ */
1235
+ declare function computeSect(dateUtc: Date, latitude: number, longitude: number, sun: {
1236
+ longitude: number;
1237
+ latitude?: number;
1238
+ distance?: number;
1239
+ }, options?: SectOptions): SectResult;
1240
+
1241
+ /**
1242
+ * Hellenistic lots of Fortune and Spirit (sect-reversed counterparts).
1243
+ * Pure arithmetic, no WASM dependency.
1244
+ *
1245
+ * Fortune: day ASC + Moon - Sun night ASC + Sun - Moon
1246
+ * Spirit : day ASC + Sun - Moon night ASC + Moon - Sun
1247
+ *
1248
+ * Hence Fortune + Spirit = 2 * ASC (mod 360) in either sect.
1249
+ */
1250
+ interface LotsResult {
1251
+ fortune: number;
1252
+ spirit: number;
1253
+ method: {
1254
+ sectUsed: "diurnal" | "nocturnal";
1255
+ fortune: string;
1256
+ spirit: string;
1257
+ };
1258
+ }
1259
+ declare function calcLotOfFortune(asc: number, sun: number, moon: number, diurnal: boolean): number;
1260
+ declare function calcLotOfSpirit(asc: number, sun: number, moon: number, diurnal: boolean): number;
1261
+ declare function computeLots(asc: number, sun: number, moon: number, sect: "diurnal" | "nocturnal"): LotsResult;
1262
+
1263
+ /**
1264
+ * Moon phase from ecliptic longitudes. Pure arithmetic, no WASM dependency.
1265
+ *
1266
+ * Phase names use the 8-phase convention with 45 degree sectors centred on the
1267
+ * principal phases, i.e. boundaries at 22.5, 67.5, ... degrees of elongation
1268
+ * (lower boundary inclusive, upper exclusive):
1269
+ * [337.5, 22.5) new, [22.5, 67.5) waxing crescent, [67.5, 112.5) first quarter,
1270
+ * [112.5, 157.5) waxing gibbous, [157.5, 202.5) full, [202.5, 247.5) waning gibbous,
1271
+ * [247.5, 292.5) last quarter, [292.5, 337.5) waning crescent.
1272
+ * Waxing: elongation in [0, 180); waning: [180, 360). Exactly 0 is "new"/waxing,
1273
+ * exactly 180 is "full"/waning.
1274
+ */
1275
+ type MoonPhaseName = "new" | "waxing_crescent" | "first_quarter" | "waxing_gibbous" | "full" | "waning_gibbous" | "last_quarter" | "waning_crescent";
1276
+ declare const MOON_PHASE_NAMES: readonly MoonPhaseName[];
1277
+ interface MoonPhaseResult {
1278
+ /** (Moon - Sun) ecliptic longitude, 0 <= x < 360. */
1279
+ elongation: number;
1280
+ phase: MoonPhaseName;
1281
+ /** Index 0..7 into the 8-phase cycle. */
1282
+ phaseIndex: number;
1283
+ waxing: boolean;
1284
+ /** Illuminated fraction of the lunar disc, 0..1. */
1285
+ illuminatedFraction: number;
1286
+ illumination: {
1287
+ method: "approximate" | "exact";
1288
+ description: string;
1289
+ };
1290
+ }
1291
+ declare function computeMoonPhase(sunLongitude: number, moonLongitude: number): MoonPhaseResult;
1292
+
1293
+ /**
1294
+ * Composite-chart geometry: midpoints, angles and house cusps.
1295
+ * Pure math, no WASM dependency.
1296
+ *
1297
+ * Conventions (all reported back in `CompositeMethod`):
1298
+ *
1299
+ * - Midpoint: shorter-arc midpoint of two ecliptic longitudes.
1300
+ * - Antipodal policy: two points exactly (within `antipodalEpsilon`, default
1301
+ * 0.001 degree) opposite each other have two equally valid midpoints. The
1302
+ * rule is deterministic and symmetric in its arguments: the ARITHMETIC mean
1303
+ * of the two normalised longitudes in [0, 360) is used (i.e. the midpoint of
1304
+ * the arc that does not cross 0 Aries). Such a pair is flagged in
1305
+ * `notices` (`type: "antipodal"`).
1306
+ * - Angles: composite ASC = midpoint(ASC_A, ASC_B). The composite MC is the
1307
+ * midpoint(MC_A, MC_B) or its opposite, whichever puts the MC 0-180 degrees
1308
+ * behind the composite ASC (as in every real chart), so ASC/MC stay
1309
+ * consistent with each other. DSC = ASC + 180, IC = MC + 180.
1310
+ * - Whole-sign houses: house 1 starts at 0 degrees of the composite ASC's sign
1311
+ * and each following house is 30 degrees further on.
1312
+ * - Quadrant / other systems: cusp i = midpoint of cusp i of both charts. Cusp
1313
+ * 1 is anchored to the composite ASC when both charts' cusp 1 equals their
1314
+ * ASC. Cusps are then walked in order; for each, if the shorter-arc midpoint
1315
+ * falls on the opposite side (forward gap from the previous cusp not within
1316
+ * (0, 180)), the opposite point is used and the house is listed in
1317
+ * `correctedCusps`. If the result still is not strictly increasing mod 360
1318
+ * (should not happen below polar latitudes) equal houses from the composite
1319
+ * ASC are used and `fallback` is set to "equal".
1320
+ */
1321
+ declare const DEFAULT_ANTIPODAL_EPSILON = 0.001;
1322
+ interface CompositeMidpoint {
1323
+ longitude: number;
1324
+ /** True when the two inputs are within epsilon of exact opposition. */
1325
+ antipodal: boolean;
1326
+ }
1327
+ /** Midpoint of two longitudes, symmetric, with the antipodal policy above. */
1328
+ declare function compositeMidpoint(a: number, b: number, epsilon?: number): CompositeMidpoint;
1329
+ /** True when the cusps run strictly forward through exactly one full turn. */
1330
+ declare function cuspsStrictlyIncreasing(cusps: number[]): boolean;
1331
+ type CompositeNotice = {
1332
+ type: "antipodal";
1333
+ point: string;
1334
+ longitudeA: number;
1335
+ longitudeB: number;
1336
+ } | {
1337
+ type: "mc_flipped";
1338
+ reason: string;
1339
+ } | {
1340
+ type: "cusp_corrected";
1341
+ house: number;
1342
+ } | {
1343
+ type: "equal_house_fallback";
1344
+ reason: string;
1345
+ } | {
1346
+ type: "mixed_house_systems";
1347
+ reason: string;
1348
+ };
1349
+ interface CompositeMethod {
1350
+ midpoint: "shorter arc";
1351
+ antipodalPolicy: string;
1352
+ antipodalEpsilon: number;
1353
+ houses: "whole-sign" | "midpoint-of-corresponding-cusps";
1354
+ fallback: "equal" | null;
1355
+ correctedCusps: number[];
1356
+ }
1357
+ interface CompositeAngles {
1358
+ ascendant: number;
1359
+ mc: number;
1360
+ descendant: number;
1361
+ ic: number;
1362
+ }
1363
+ declare function computeCompositeAngles(a: {
1364
+ ascendant: number;
1365
+ mc: number;
1366
+ }, b: {
1367
+ ascendant: number;
1368
+ mc: number;
1369
+ }, epsilon?: number): {
1370
+ angles: CompositeAngles;
1371
+ notices: CompositeNotice[];
1372
+ };
1373
+ interface CompositeCuspInput {
1374
+ cuspsA: number[];
1375
+ cuspsB: number[];
1376
+ ascA: number;
1377
+ ascB: number;
1378
+ /** Use whole-sign houses from the composite ASC (both charts whole-sign). */
1379
+ wholeSign: boolean;
1380
+ compositeAsc: number;
1381
+ epsilon?: number;
1382
+ }
1383
+ declare function computeCompositeCusps(input: CompositeCuspInput): {
1384
+ cusps: number[];
1385
+ method: Pick<CompositeMethod, "houses" | "fallback" | "correctedCusps">;
1386
+ notices: CompositeNotice[];
1387
+ };
1388
+ declare const ANTIPODAL_POLICY_TEXT = "points within epsilon of exact opposition use the arithmetic mean of the normalised longitudes (arc not crossing 0 Aries); flagged in notices";
1389
+
1390
+ /**
1391
+ * Thin ephemeris access for the Jyotish module: geocentric body positions
1392
+ * (ecliptic + equatorial), true obliquity and the tropical ascendant at an
1393
+ * explicit UT Julian day. Everything here is tropical; sidereal conversion is
1394
+ * in `lahiri.ts`.
1395
+ */
1396
+
1397
+ type JyotishEphemeris = "swiss" | "moshier";
1398
+ /** Bodies that carry nakshatras and dashas in both frames (nodes handled separately). */
1399
+ declare const JYOTISH_BODY_IDS: readonly ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn"];
1400
+ type JyotishBodyId = (typeof JYOTISH_BODY_IDS)[number];
1401
+ type NodeConvention = "mean" | "true";
1402
+ /**
1403
+ * Which Swiss ephemeris actually produced the numbers. Swiss Ephemeris silently falls back to
1404
+ * Moshier when the .se1 files are missing or the date is outside their range; this records it.
1405
+ */
1406
+ interface EphemerisUsage {
1407
+ requested: JyotishEphemeris;
1408
+ /** Distinct ephemerides actually used across every body evaluation of the chart. */
1409
+ used: SwissEphemerisKind[];
1410
+ /** True when any evaluation used a different ephemeris than requested. */
1411
+ substituted: boolean;
1412
+ /** Distinct non-fatal Swiss notices (for example the Moshier fallback text). */
1413
+ warnings: string[];
1414
+ }
1415
+ /** Options shared by the Jyotish calculators. */
1416
+ interface EphemerisCheckOptions {
1417
+ /** Throw `SwissEphEphemerisMismatchError` instead of returning substituted (e.g. Moshier) output. */
1418
+ strictEphemeris?: boolean;
1419
+ }
1420
+ /** Collects provenance across body evaluations; threaded through the calculators. */
1421
+ declare class EphemerisTracker {
1422
+ readonly requested: JyotishEphemeris;
1423
+ readonly strictEphemeris?: boolean | undefined;
1424
+ private readonly kinds;
1425
+ private readonly notes;
1426
+ private anySubstituted;
1427
+ constructor(requested: JyotishEphemeris, strictEphemeris?: boolean | undefined);
1428
+ /** Evaluate a body (ecliptic, equatorial or sidereal flags) and record its provenance. */
1429
+ calc(julianDayUt: number, planet: number, flags: number): PlanetPosition;
1430
+ usage(): EphemerisUsage;
1431
+ }
1432
+ /** Combine several usages (e.g. Dhruva + Lahiri) into one chart-level record. */
1433
+ declare function mergeEphemerisUsage(...usages: EphemerisUsage[]): EphemerisUsage;
1434
+ interface GeocentricBody {
1435
+ /** Apparent tropical ecliptic longitude of date (degrees). */
1436
+ longitude: number;
1437
+ /** Ecliptic latitude (degrees); retained for the equatorial transformation. */
1438
+ latitude: number;
1439
+ /** Apparent right ascension, true equator and equinox of date (Swiss `SEFLG_EQUATORIAL`). */
1440
+ rightAscension: number;
1441
+ declination: number;
1442
+ }
1443
+ interface GeocentricBodies {
1444
+ planets: Record<JyotishBodyId, GeocentricBody>;
1445
+ meanNode: GeocentricBody;
1446
+ trueNode: GeocentricBody;
1447
+ }
1448
+
1449
+ /**
1450
+ * Nakshatra sector arithmetic shared by the Dhruva (equatorial) and Lahiri
1451
+ * (ecliptic sidereal) frames. Pure functions, no ephemeris.
1452
+ */
1453
+ /** Width of one nakshatra: 360 / 27 degrees. */
1454
+ declare const NAKSHATRA_WIDTH_DEGREES: number;
1455
+ /** Width of one pada: a quarter nakshatra. */
1456
+ declare const PADA_WIDTH_DEGREES: number;
1457
+ /** Stable ids as used by the reference implementation (underscored). */
1458
+ declare const NAKSHATRA_IDS: readonly ["Ashwini", "Bharani", "Krittika", "Rohini", "Mrigashira", "Ardra", "Punarvasu", "Pushya", "Ashlesha", "Magha", "Purva_Phalguni", "Uttara_Phalguni", "Hasta", "Chitra", "Swati", "Vishakha", "Anuradha", "Jyeshtha", "Mula", "Purva_Ashadha", "Uttara_Ashadha", "Shravana", "Dhanishtha", "Shatabhisha", "Purva_Bhadrapada", "Uttara_Bhadrapada", "Revati"];
1459
+ type NakshatraId = (typeof NAKSHATRA_IDS)[number];
1460
+ /** Vimshottari lord sequence; nakshatra index i is ruled by `VIMSHOTTARI_LORDS[i % 9]`. */
1461
+ declare const VIMSHOTTARI_LORDS: readonly ["ketu", "venus", "sun", "moon", "mars", "rahu", "jupiter", "saturn", "mercury"];
1462
+ type VimshottariLord = (typeof VIMSHOTTARI_LORDS)[number];
1463
+ /** Vimshottari years per lord, aligned with {@link VIMSHOTTARI_LORDS} (sum 120). */
1464
+ declare const VIMSHOTTARI_YEARS: readonly number[];
1465
+ declare const TROPICAL_SIGNS: readonly ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"];
1466
+ type SignName = (typeof TROPICAL_SIGNS)[number];
1467
+ interface SignPlacement {
1468
+ /** 0 = Aries ... 11 = Pisces (of the frame the longitude is in). */
1469
+ signIndex: number;
1470
+ sign: SignName;
1471
+ /** Degrees within the sign, [0, 30). */
1472
+ degreeInSign: number;
1473
+ }
1474
+ declare function signPlacement(longitude: number): SignPlacement;
1475
+ interface NakshatraPlacement {
1476
+ /** Position measured from the frame's zero point, [0, 360). */
1477
+ nakPos: number;
1478
+ /** 0-based nakshatra index, 0..26. */
1479
+ nakshatraIndex: number;
1480
+ /** 1-based nakshatra number, 1..27. */
1481
+ nakshatraNumber: number;
1482
+ /** Underscored id, e.g. `Purva_Phalguni`. */
1483
+ nakshatraId: NakshatraId;
1484
+ /** Display name, e.g. `Purva Phalguni`. */
1485
+ nakshatra: string;
1486
+ /** Pada 1..4. */
1487
+ pada: number;
1488
+ /** Fraction of the nakshatra already elapsed, [0, 1). */
1489
+ elapsedFraction: number;
1490
+ /** Vimshottari lord of the nakshatra. */
1491
+ lord: VimshottariLord;
1492
+ }
1493
+ /**
1494
+ * Classify a position that is already measured from the zero point. Mirrors the
1495
+ * reference: `index = min(26, floor(pos / (40/3)))`, `pada = min(4, floor(4 *
1496
+ * fraction) + 1)` with `fraction = pos/(40/3) - index`.
1497
+ */
1498
+ declare function nakshatraFromPosition(nakPosition: number): NakshatraPlacement;
1499
+
1500
+ /**
1501
+ * Ernst Wilhelm / Kala "Dhruva" (System 1) equatorial nakshatras.
1502
+ *
1503
+ * Ports the user-supplied, confirmed reference implementation. The method:
1504
+ *
1505
+ * - Anchor: Galactic Center (Sgr A*) ICRS RA 266.40499 deg, Dec -28.93617 deg,
1506
+ * taken to the FK5 mean equator/equinox of date (Astropy-equivalent, see
1507
+ * `frames.ts`).
1508
+ * - `zeroRA = (GC_RA_of_date - (246 + 2/3)) mod 360`.
1509
+ * - `nakPos = (actual RA of date - zeroRA) mod 360`; 27 equal sectors of
1510
+ * 40/3 deg, 4 padas of 10/3 deg each.
1511
+ * - Bodies use their actual geocentric apparent right ascension from Swiss
1512
+ * (`SEFLG_EQUATORIAL`: true equator and equinox of date, i.e. nutation,
1513
+ * aberration and light-time included) with their actual ecliptic latitude.
1514
+ * The GC anchor is the mean FK5 of date (no nutation); this mixture is what the
1515
+ * reference does and is reproduced as-is (difference <= ~0.005 deg).
1516
+ * - Lagna: RA of the tropical ASC at ecliptic latitude 0 with true obliquity.
1517
+ * - Rahu is the latitude-0 node point (mean primary, true as a variant); Ketu is
1518
+ * the antipode of the corresponding Rahu.
1519
+ *
1520
+ * It is NOT ecliptic longitude minus Lahiri and NOT Swiss ayanamsa mode 36.
1521
+ * Tropical rasis and tropical houses are reported separately and unchanged.
1522
+ */
1523
+
1524
+ /** Explicit, named method constants. Never fitted to any fixture. */
1525
+ interface DhruvaConstants {
1526
+ /** Sgr A* ICRS right ascension, degrees. */
1527
+ gcIcrsRightAscension: number;
1528
+ /** Sgr A* ICRS declination, degrees. */
1529
+ gcIcrsDeclination: number;
1530
+ /** Degrees subtracted from the GC RA of date to get the RA origin (246 + 2/3). */
1531
+ anchorOffsetDegrees: number;
1532
+ /** Nakshatra width (40/3 deg). */
1533
+ sectorWidthDegrees: number;
1534
+ /** Default dasha year length for this method, days. */
1535
+ yearLengthDays: number;
1536
+ }
1537
+ declare const DHRUVA_CONSTANTS: Readonly<DhruvaConstants>;
1538
+ interface DhruvaOrigin {
1539
+ /** UT Julian day read on the UTC scale (as the reference does). */
1540
+ julianDayUt: number;
1541
+ /** GC right ascension, FK5 mean equator/equinox of date, degrees. */
1542
+ gcRightAscensionOfDate: number;
1543
+ gcDeclinationOfDate: number;
1544
+ /** `(gcRightAscensionOfDate - anchorOffsetDegrees) mod 360`. */
1545
+ zeroRightAscension: number;
1546
+ constants: DhruvaConstants;
1547
+ }
1548
+ /** Date-specific GC anchor and RA origin. */
1549
+ declare function getDhruvaOrigin(julianDayUt: number, constants?: DhruvaConstants): DhruvaOrigin;
1550
+ interface DhruvaPoint extends NakshatraPlacement {
1551
+ /** Actual right ascension used (degrees, [0, 360)). */
1552
+ rightAscension: number;
1553
+ declination: number;
1554
+ /** Tropical ecliptic longitude of date (unchanged by the nakshatra frame). */
1555
+ longitude: number;
1556
+ /** Ecliptic latitude (0 for lagna and nodes). */
1557
+ latitude: number;
1558
+ /** Tropical rasi (sign of the tropical longitude); independent of nakshatra frame. */
1559
+ tropical: SignPlacement;
1560
+ /** Set for derived points (Ketu). */
1561
+ derivedFrom?: string;
1562
+ }
1563
+ /** Nakshatra placement for an actual RA against an origin. Mirrors the reference `nakshatra_position`. */
1564
+ declare function dhruvaPlacementFromRightAscension(rightAscension: number, origin: Pick<DhruvaOrigin, "zeroRightAscension">): NakshatraPlacement & {
1565
+ rightAscension: number;
1566
+ };
1567
+ /** Build a Dhruva point from an already-computed geocentric body (actual latitude retained in its RA). */
1568
+ declare function dhruvaPointFromBody(body: GeocentricBody, origin: DhruvaOrigin): DhruvaPoint;
1569
+ /** Ketu as the antipode of a Rahu point: RA + 180, declination negated, longitude + 180. */
1570
+ declare function dhruvaKetuFromRahu(rahu: DhruvaPoint, origin: DhruvaOrigin, convention: NodeConvention): DhruvaPoint;
1571
+ /** Lagna point from a tropical ASC longitude and the true obliquity (ecliptic latitude 0). */
1572
+ declare function dhruvaLagnaFromAscendant(ascendantLongitude: number, trueObliquityDegrees: number, origin: DhruvaOrigin): DhruvaPoint;
1573
+ type DhruvaPointId = JyotishBodyId | "rahu" | "ketu" | "lagna";
1574
+ interface DhruvaChart {
1575
+ origin: DhruvaOrigin;
1576
+ nodeConvention: NodeConvention;
1577
+ /** Sun..Saturn, Rahu/Ketu (selected node convention) and, when timed, Moon and lagna. */
1578
+ points: Partial<Record<DhruvaPointId, DhruvaPoint>>;
1579
+ /** Both node conventions side by side. */
1580
+ nodeVariants: Record<NodeConvention, {
1581
+ rahu: DhruvaPoint;
1582
+ ketu: DhruvaPoint;
1583
+ }>;
1584
+ trueObliquity?: number;
1585
+ timed: boolean;
1586
+ ephemeris: JyotishEphemeris;
1587
+ /** Ephemeris that actually produced the numbers (detects a silent Moshier substitution). */
1588
+ ephemerisUsage: EphemerisUsage;
1589
+ }
1590
+ interface DhruvaChartInput extends EphemerisCheckOptions {
1591
+ /** UT instant. */
1592
+ date: Date;
1593
+ /** Overrides `date` with an explicit UT Julian day (sub-second precision). */
1594
+ julianDayUt?: number;
1595
+ latitude: number;
1596
+ longitude: number;
1597
+ /** Mean node is primary (default); true node is exposed as a variant either way. */
1598
+ node?: NodeConvention;
1599
+ /** `false` excludes Moon and lagna (untimed births). Default `true`. */
1600
+ timed?: boolean;
1601
+ /** Swiss files (default) or Moshier. Moshier exists to reproduce the reference fixtures. */
1602
+ ephemeris?: JyotishEphemeris;
1603
+ constants?: DhruvaConstants;
1604
+ }
1605
+ /** Compute the Dhruva chart through the Swiss ephemeris. */
1606
+ declare function calculateDhruvaChart(input: DhruvaChartInput): DhruvaChart;
1607
+
1608
+ /**
1609
+ * Conventional Lahiri (Chitrapaksha) sidereal comparison chart.
1610
+ *
1611
+ * Separate from the Dhruva equatorial method: here nakshatras and padas come
1612
+ * from the ECLIPTIC sidereal longitude, `longitude_sidereal / (40/3)`.
1613
+ *
1614
+ * Frames and houses:
1615
+ * - Planets are computed by Swiss in sidereal mode 1 (Lahiri) with
1616
+ * `SEFLG_SIDEREAL`, apparent, nutation included.
1617
+ * - The ayanamsa is read back from the same engine as
1618
+ * `tropical longitude - sidereal longitude` of the Sun at the same instant and
1619
+ * flags, i.e. the true (nutation-included) ayanamsa Swiss itself subtracts. The
1620
+ * sidereal ascendant is `tropical ASC - that ayanamsa`. This is exactly what
1621
+ * Swiss `swe_houses_ex(SEFLG_SIDEREAL)` does (it subtracts the same ayanamsa
1622
+ * from the tropical ASC computed from the true obliquity), so planets and
1623
+ * ascendant are in the same nutated frame. It is NOT the mean ayanamsa
1624
+ * (without nutation) subtracted from a nutated ASC, which would shift the
1625
+ * ascendant relative to the planets by up to ~0.005 deg.
1626
+ * - The Swiss sidereal mode is global mutable state; it is set, used and reset
1627
+ * synchronously inside `withSiderealMode`, so tropical calculations are never
1628
+ * affected.
1629
+ */
1630
+
1631
+ interface LahiriPoint extends NakshatraPlacement {
1632
+ /** Sidereal (Lahiri) ecliptic longitude, [0, 360). */
1633
+ longitude: number;
1634
+ /** Ecliptic latitude (0 for ascendant and nodes). */
1635
+ latitude: number;
1636
+ /** Tropical longitude of the same point. */
1637
+ tropicalLongitude: number;
1638
+ /** Sidereal rasi. */
1639
+ sidereal: SignPlacement;
1640
+ /** Whole-sign house 1..12 counted from the sidereal ascendant's sign (absent when untimed). */
1641
+ wholeSignHouse?: number;
1642
+ longitudeSpeed?: number;
1643
+ retrograde?: boolean;
1644
+ derivedFrom?: string;
1645
+ }
1646
+ type LahiriPointId = JyotishBodyId | "rahu" | "ketu" | "lagna";
1647
+ interface LahiriChart {
1648
+ /** Swiss sidereal mode id used (SE_SIDM_LAHIRI = 1). */
1649
+ siderealMode: number;
1650
+ /** True (nutation-included) ayanamsa in degrees at the instant. */
1651
+ ayanamsa: number;
1652
+ ayanamsaKind: "true-nutated, tropical minus sidereal of the same body and flags";
1653
+ nodeConvention: NodeConvention;
1654
+ timed: boolean;
1655
+ ephemeris: JyotishEphemeris;
1656
+ /** Ephemeris that actually produced the numbers (detects a silent Moshier substitution). */
1657
+ ephemerisUsage: EphemerisUsage;
1658
+ /** Sidereal ascendant (undefined if untimed). */
1659
+ ascendant?: LahiriPoint;
1660
+ points: Partial<Record<LahiriPointId, LahiriPoint>>;
1661
+ nodeVariants: Record<NodeConvention, {
1662
+ rahu: LahiriPoint;
1663
+ ketu: LahiriPoint;
1664
+ }>;
1665
+ /** Whole-sign houses: house number -> sidereal sign index of its sign (empty if untimed). */
1666
+ wholeSignHouses: Array<{
1667
+ house: number;
1668
+ signIndex: number;
1669
+ sign: string;
1670
+ }>;
1671
+ }
1672
+ interface LahiriChartInput extends EphemerisCheckOptions {
1673
+ date: Date;
1674
+ julianDayUt?: number;
1675
+ latitude: number;
1676
+ longitude: number;
1677
+ node?: NodeConvention;
1678
+ timed?: boolean;
1679
+ ephemeris?: JyotishEphemeris;
1680
+ }
1681
+ declare function wholeSignHouseOf(longitude: number, ascendantLongitude: number): number;
1682
+ interface RawSidereal {
1683
+ longitude: number;
1684
+ latitude: number;
1685
+ speed?: number;
1686
+ }
1687
+ /**
1688
+ * Sidereal ecliptic positions for several Swiss bodies, computed with the
1689
+ * Lahiri mode selected only for the duration of the (synchronous) call.
1690
+ */
1691
+ declare function calculateSiderealPositions(julianDayUt: number, bodies: readonly number[], ephemeris?: JyotishEphemeris, tracker?: EphemerisTracker): RawSidereal[];
1692
+ /** True ayanamsa (degrees) in the same flag frame as sidereal planets. */
1693
+ declare function calculateLahiriAyanamsa(julianDayUt: number, ephemeris?: JyotishEphemeris, tracker?: EphemerisTracker): number;
1694
+ declare function calculateLahiriChart(input: LahiriChartInput): LahiriChart;
1695
+
1696
+ /**
1697
+ * Jaimini chara karakas (7- and 8-karaka schemes).
1698
+ *
1699
+ * Ranking value = degree within sign, descending: the highest degree is the
1700
+ * Atmakaraka. The frame of the degree (tropical or sidereal) is an explicit
1701
+ * input and echoed in the result. The reference dataset ranked TROPICAL
1702
+ * degrees with Rahu excluded (7 scheme); the traditional practice is sidereal.
1703
+ *
1704
+ * 8-karaka scheme: Rahu joins with ranking value `30 - degreeInSign` (it moves
1705
+ * retrograde). Mean or true node is the caller's choice and is echoed.
1706
+ *
1707
+ * Ties: bodies whose ranking values differ by no more than
1708
+ * `tieToleranceDegrees` are tied; they are ordered by the fixed canonical order
1709
+ * Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu and flagged
1710
+ * `tied: true`, with each group listed in `tieGroups`, so callers can apply their
1711
+ * own tradition (e.g. compare minutes/seconds, then nakshatra).
1712
+ */
1713
+ type KarakaBody = "sun" | "moon" | "mars" | "mercury" | "jupiter" | "venus" | "saturn" | "rahu";
1714
+ type KarakaScheme = 7 | 8;
1715
+ declare const KARAKA_NAMES_7: readonly ["Atmakaraka", "Amatyakaraka", "Bhratrukaraka", "Matrukaraka", "Putrakaraka", "Gnatikaraka", "Darakaraka"];
1716
+ declare const KARAKA_NAMES_8: readonly ["Atmakaraka", "Amatyakaraka", "Bhratrukaraka", "Matrukaraka", "Pitrukaraka", "Putrakaraka", "Gnatikaraka", "Darakaraka"];
1717
+ declare const KARAKA_ABBREVIATIONS_7: readonly ["AK", "AmK", "BK", "MK", "PK", "GK", "DK"];
1718
+ declare const KARAKA_ABBREVIATIONS_8: readonly ["AK", "AmK", "BK", "MK", "PiK", "PK", "GK", "DK"];
1719
+ type KarakaDegreeFrame = "tropical" | "sidereal";
1720
+ interface KarakaInput {
1721
+ body: KarakaBody;
1722
+ /** Degrees within the sign in the chosen frame, [0, 30). */
1723
+ degreeInSign: number;
1724
+ }
1725
+ interface KarakaEntry {
1726
+ /** 1-based rank. */
1727
+ rank: number;
1728
+ karaka: string;
1729
+ abbreviation: string;
1730
+ body: KarakaBody;
1731
+ degreeInSign: number;
1732
+ /** Value actually ranked: `degreeInSign`, or `30 - degreeInSign` for Rahu in the 8 scheme. */
1733
+ rankingValue: number;
1734
+ tied: boolean;
1735
+ }
1736
+ interface KarakaOptions {
1737
+ scheme: KarakaScheme;
1738
+ /** Frame of the supplied degrees; echoed, not interpreted. */
1739
+ degreeFrame: KarakaDegreeFrame;
1740
+ /** Node used for Rahu in the 8 scheme; echoed, not interpreted. */
1741
+ node?: "mean" | "true";
1742
+ /** Default 1e-9 degrees. */
1743
+ tieToleranceDegrees?: number;
1744
+ }
1745
+ interface KarakaResult {
1746
+ scheme: KarakaScheme;
1747
+ degreeFrame: KarakaDegreeFrame;
1748
+ rahuConvention?: {
1749
+ node: "mean" | "true";
1750
+ rankingValue: "30 - degreeInSign";
1751
+ };
1752
+ tieToleranceDegrees: number;
1753
+ entries: KarakaEntry[];
1754
+ tieGroups: KarakaBody[][];
1755
+ }
1756
+ declare function calculateCharaKarakas(inputs: readonly KarakaInput[], options: KarakaOptions): KarakaResult;
1757
+
1758
+ /**
1759
+ * Vimshottari (120-year) and Yogini (36-year) maha + antar dashas.
1760
+ *
1761
+ * Pure arithmetic, no ephemeris. Conventions (all explicit, none fitted):
1762
+ *
1763
+ * - Birth balance: the Moon's nakshatra lord's maha began
1764
+ * `elapsedFraction * mahaYears * yearLengthDays` days BEFORE birth. That
1765
+ * pre-birth start is kept as the first maha's `start` (`startsBeforeBirth`).
1766
+ * - `yearLengthDays` is mandatory per call. Documented reference
1767
+ * configurations: {@link DASHA_YEAR_LENGTH_REFERENCES} (Dhruva timelines used
1768
+ * 365.2422; the saved Lahiri comparison used 365.25, a reference
1769
+ * configuration and not a claim about every Lahiri practitioner).
1770
+ * - Antar lengths are proportional: `mahaLength * antarLordYears / totalYears`,
1771
+ * starting from the maha lord and continuing in sequence order.
1772
+ * - Intervals are half-open `[start, end)`; a boundary instant belongs to the
1773
+ * period that STARTS there.
1774
+ * - By default antars that ended on or before birth are omitted from the first
1775
+ * maha (`includePreBirthAntars` keeps them); the surviving first antar may
1776
+ * start before birth.
1777
+ * - Yogini: lords Mangala(1) .. Sankata(8), start index
1778
+ * `(nakshatraNumber + 3 - 1) mod 8`, i.e. the common "(number + 3) mod 8"
1779
+ * rule. This convention is chosen and implemented; it was NOT matched to a
1780
+ * Kala Yogini export.
1781
+ * - Generation is bounded by `through` (default: one full cycle after birth)
1782
+ * and `maxMahaPeriods`.
1783
+ */
1784
+ type DashaSystem = "vimshottari" | "yogini";
1785
+ declare const YOGINI_LORDS: readonly ["mangala", "pingala", "dhanya", "bhramari", "bhadrika", "ulka", "siddha", "sankata"];
1786
+ declare const YOGINI_YEARS: readonly number[];
1787
+ /** Named year-length reference configurations. */
1788
+ declare const DASHA_YEAR_LENGTH_REFERENCES: Readonly<{
1789
+ /** Dhruva (System 1) timelines in the source session. */
1790
+ dhruva: 365.2422;
1791
+ /** The saved Lahiri comparison. A reference configuration, not a universal claim. */
1792
+ lahiriReference: 365.25;
1793
+ }>;
1794
+ declare function dateToJulianDay(date: Date): number;
1795
+ declare function julianDayToDate(jd: number): Date;
1796
+ interface DashaPeriod {
1797
+ level: "maha" | "antar";
1798
+ lord: string;
1799
+ /** Julian day (UT) of the inclusive start. */
1800
+ startJd: number;
1801
+ /** Julian day (UT) of the exclusive end. */
1802
+ endJd: number;
1803
+ start: Date;
1804
+ end: Date;
1805
+ /** True when the period began before the birth instant. */
1806
+ startsBeforeBirth: boolean;
1807
+ /** Nominal length in the schedule's years. */
1808
+ years: number;
1809
+ /** Antars (maha only). */
1810
+ antars?: DashaPeriod[];
1811
+ }
1812
+ interface DashaBalance {
1813
+ /** Lord of the birth maha. */
1814
+ lord: string;
1815
+ mahaYears: number;
1816
+ /** Fraction of the birth maha already elapsed at birth (the Moon's elapsed fraction). */
1817
+ elapsedFraction: number;
1818
+ remainingFraction: number;
1819
+ elapsedDays: number;
1820
+ remainingDays: number;
1821
+ /** Remaining time expressed in `yearLengthDays` years. */
1822
+ remainingYears: number;
1823
+ }
1824
+ interface DashaScheduleInput {
1825
+ system: DashaSystem;
1826
+ /** Birth instant. */
1827
+ birth: Date;
1828
+ /** Overrides `birth` with an explicit UT Julian day (sub-millisecond precision). */
1829
+ birthJulianDayUt?: number;
1830
+ /** 0-based nakshatra index of the Moon in the SELECTED frame (Dhruva or Lahiri). */
1831
+ moonNakshatraIndex: number;
1832
+ /** Moon's elapsed fraction in that nakshatra, [0, 1). */
1833
+ moonElapsedFraction: number;
1834
+ /** Mandatory length of a dasha year in days. */
1835
+ yearLengthDays: number;
1836
+ /** Exclusive end of generation. Default: birth + one full cycle (120 / 36 years). */
1837
+ through?: Date;
1838
+ /** Keep antars of the first maha that ended on/before birth. Default false. */
1839
+ includePreBirthAntars?: boolean;
1840
+ /** Hard cap on generated mahas. Default 200. */
1841
+ maxMahaPeriods?: number;
1842
+ }
1843
+ interface DashaSchedule {
1844
+ system: DashaSystem;
1845
+ yearLengthDays: number;
1846
+ totalYears: number;
1847
+ birthJd: number;
1848
+ moonNakshatra: {
1849
+ index: number;
1850
+ id: string;
1851
+ elapsedFraction: number;
1852
+ };
1853
+ balance: DashaBalance;
1854
+ mahas: DashaPeriod[];
1855
+ /** Exclusive generation horizon (JD UT). */
1856
+ throughJd: number;
1857
+ /** True if `maxMahaPeriods` stopped generation before the horizon. */
1858
+ truncated: boolean;
1859
+ intervalConvention: "half-open [start, end)";
1860
+ }
1861
+ declare function generateDashaSchedule(input: DashaScheduleInput): DashaSchedule;
1862
+ /** Convenience wrappers. */
1863
+ declare function generateVimshottariDasha(input: Omit<DashaScheduleInput, "system">): DashaSchedule;
1864
+ declare function generateYoginiDasha(input: Omit<DashaScheduleInput, "system">): DashaSchedule;
1865
+ interface ActiveDasha {
1866
+ maha: DashaPeriod;
1867
+ antar?: DashaPeriod;
1868
+ }
1869
+ /**
1870
+ * Active maha and antar at `asOf`, half-open `[start, end)`. Returns
1871
+ * `undefined` outside the generated range. Instants before birth that fall in
1872
+ * the first maha's pre-birth portion are returned as-is (inspect
1873
+ * `startsBeforeBirth`); callers wanting "life only" should check `asOf >= birth`.
1874
+ */
1875
+ declare function findActiveDasha(schedule: DashaSchedule, asOf: Date | number): ActiveDasha | undefined;
1876
+
1877
+ /**
1878
+ * Celestial-frame mathematics for the Dhruva (equatorial) nakshatra method.
1879
+ *
1880
+ * Pure, browser-safe, no ephemeris dependency. Ports exactly what Astropy
1881
+ * (checked against 8.0.2 / pyerfa 2.0.1.5) does for
1882
+ *
1883
+ * SkyCoord(ra, dec, frame=ICRS()).transform_to(FK5(equinox=Time(jd, format="jd", scale="utc")))
1884
+ *
1885
+ * which is NOT the IAU 1976 precession and includes no nutation, aberration
1886
+ * or proper motion:
1887
+ *
1888
+ * 1. ICRS -> FK5 J2000: the three-rotation frame-bias matrix of USNO
1889
+ * Circular 179 (eta0 = -19.9 mas, xi0 = 9.1 mas, da0 = -22.9 mas),
1890
+ * `Rx(-eta0) Ry(xi0) Rz(da0)`.
1891
+ * 2. FK5 J2000 -> FK5 of date: the bias-free IAU 2006 (Capitaine et al.)
1892
+ * precession matrix, `erfa.bp06(...)[1]` = Fukushima-Williams matrix of
1893
+ * date times the transpose of the Fukushima-Williams matrix at J2000.
1894
+ * Result is the MEAN equator and equinox of date.
1895
+ * 3. The epoch of date is the supplied Julian date read on the UTC scale and
1896
+ * converted UTC -> TAI -> TT (leap seconds, then +32.184 s).
1897
+ *
1898
+ * All angles are degrees unless a name says radians.
1899
+ */
1900
+ declare const JD_J2000 = 2451545;
1901
+ declare const JULIAN_CENTURY_DAYS = 36525;
1902
+ declare const TT_MINUS_TAI_SECONDS = 32.184;
1903
+ declare function normalizeDegrees(value: number): number;
1904
+ /** Signed smallest difference a - b in (-180, 180]. */
1905
+ declare function signedAngleBetween(a: number, b: number): number;
1906
+ /**
1907
+ * TAI - UTC in seconds for a UTC Julian date, reproducing ERFA `eraDat`:
1908
+ * 0 before 1960 (ERFA flags this as "dubious year" but returns 0), drifting
1909
+ * rubber-second offsets 1960-1971, integer leap seconds after, held at the last
1910
+ * tabulated value for later dates.
1911
+ */
1912
+ declare function taiMinusUtcSeconds(jdUtc: number): number;
1913
+ /** Julian date on the TT scale for a Julian date read on the UTC scale (Astropy `Time(jd, format="jd", scale="utc")`). */
1914
+ declare function utcJdToTtJd(jdUtc: number): number;
1915
+ type Matrix3 = [number, number, number, number, number, number, number, number, number];
1916
+ /**
1917
+ * Bias-free IAU 2006 precession matrix J2000 -> mean equator/equinox of date
1918
+ * (`erfa.bp06(jd1, jd2)[1]`), for a TT Julian date.
1919
+ */
1920
+ declare function precessionMatrixJ2000ToDate(jdTt: number): Matrix3;
1921
+ /** USNO Circular 179 ICRS -> FK5 J2000 frame-bias matrix, as in Astropy `_icrs_to_fk5_matrix`. */
1922
+ declare function icrsToFk5J2000Matrix(): Matrix3;
1923
+ interface EquatorialCoordinate {
1924
+ /** Right ascension, degrees in [0, 360). */
1925
+ rightAscension: number;
1926
+ /** Declination, degrees. */
1927
+ declination: number;
1928
+ }
1929
+ /**
1930
+ * ICRS -> FK5 mean equator and equinox of date. `jdUtc` is the Julian date read
1931
+ * on the UTC scale (the reference passes the UT Julian day; UT1-UTC < 0.9 s is
1932
+ * ignored exactly as the reference ignores it).
1933
+ */
1934
+ declare function icrsToFk5OfDate(rightAscensionIcrs: number, declinationIcrs: number, jdUtc: number): EquatorialCoordinate;
1935
+ /** Right ascension (degrees) of an ecliptic point on the ecliptic (beta = 0) of obliquity `obliquityDegrees`. */
1936
+ declare function ecliptic0ToRightAscension(longitude: number, obliquityDegrees: number): number;
1937
+ /** Declination (degrees) of an ecliptic point at beta = 0. */
1938
+ declare function ecliptic0ToDeclination(longitude: number, obliquityDegrees: number): number;
1939
+
1940
+ /**
1941
+ * Jyotish: Dhruva (equatorial) and Lahiri (ecliptic sidereal) nakshatras,
1942
+ * chara karakas, Vimshottari and Yogini dashas. Calculation data and method
1943
+ * metadata only; no interpretation text.
1944
+ */
1945
+
1946
+ /**
1947
+ * Method, provenance and validation statement. Contains no private data.
1948
+ */
1949
+ declare const JYOTISH_METHODS: Readonly<{
1950
+ version: "1.0.0";
1951
+ dhruva: {
1952
+ name: string;
1953
+ provenance: string;
1954
+ anchor: string;
1955
+ anchorFrame: string;
1956
+ equinoxTimeScale: string;
1957
+ origin: string;
1958
+ bodyFrame: string;
1959
+ lagna: string;
1960
+ nodes: string;
1961
+ sectors: string;
1962
+ notEquivalentTo: string[];
1963
+ defaultYearLengthDays: number;
1964
+ };
1965
+ lahiri: {
1966
+ name: string;
1967
+ frame: string;
1968
+ nakshatras: string;
1969
+ wholeSign: string;
1970
+ referenceYearLengthDays: 365.25;
1971
+ };
1972
+ karakas: "Degree-in-sign ranking, 7 or 8 scheme; Rahu ranks by 30 - degree in the 8 scheme.";
1973
+ dashas: {
1974
+ vimshottari: string;
1975
+ yogini: string;
1976
+ intervals: string;
1977
+ };
1978
+ validation: {
1979
+ layers: string[];
1980
+ residualStatement: string;
1981
+ };
1982
+ }>;
1983
+ type NakshatraFrame = "dhruva" | "lahiri";
1984
+ interface JyotishChartInput {
1985
+ /** UT instant of birth. */
1986
+ date: Date;
1987
+ latitude: number;
1988
+ longitude: number;
1989
+ /** Frame for nakshatras/dashas. Default "dhruva". */
1990
+ nakshatraFrame?: NakshatraFrame;
1991
+ /** Node convention for Rahu/Ketu and the 8-karaka scheme. Default "mean". */
1992
+ node?: NodeConvention;
1993
+ /** Dasha year length in days. Default 365.2422 (dhruva) or 365.25 (lahiri reference). */
1994
+ yearLengthDays?: number;
1995
+ /** 7 (default) or 8. */
1996
+ karakaScheme?: KarakaScheme;
1997
+ /** Frame of the karaka degrees. Default: tropical for dhruva, sidereal for lahiri. */
1998
+ karakaDegreeFrame?: KarakaDegreeFrame;
1999
+ /** Default true. Untimed: no Moon, lagna, karakas, or dashas. */
2000
+ timed?: boolean;
2001
+ ephemeris?: JyotishEphemeris;
2002
+ /**
2003
+ * Throw `SwissEphEphemerisMismatchError` if Swiss Ephemeris substitutes another ephemeris
2004
+ * (for example Moshier outside the installed .se1 range). Default false: the substitution is
2005
+ * then reported in `ephemerisUsage` instead of being silent.
2006
+ */
2007
+ strictEphemeris?: boolean;
2008
+ /** Exclusive end of dasha generation; default one full cycle. */
2009
+ through?: Date;
2010
+ }
2011
+ interface JyotishChart {
2012
+ method: typeof JYOTISH_METHODS;
2013
+ nakshatraFrame: NakshatraFrame;
2014
+ node: NodeConvention;
2015
+ /** Always computed: tropical rasis/longitudes live on each point (`tropical`). */
2016
+ dhruva: DhruvaChart;
2017
+ lahiri: LahiriChart;
2018
+ karakas?: KarakaResult;
2019
+ vimshottari?: DashaSchedule;
2020
+ yogini?: DashaSchedule;
2021
+ yearLengthDays: number;
2022
+ /** Ephemeris actually used by both frames combined (see `EphemerisUsage`). */
2023
+ ephemerisUsage: EphemerisUsage;
2024
+ }
2025
+ /** Top-level convenience: both frames are computed, dashas/karakas follow the selected one. */
2026
+ declare function getJyotishChart(input: JyotishChartInput): JyotishChart;
2027
+
2028
+ /**
2029
+ * Stable, language-independent point identifiers and an adapter over the legacy
2030
+ * spaced-key chart dictionaries (`chart.planets`, `chart.nodes`, `chart.houses`,
2031
+ * `chart.lots`). The legacy dictionaries are read, never modified.
2032
+ *
2033
+ * Pure data: no Swiss Ephemeris dependency (types only).
2034
+ */
2035
+
2036
+ type PointClass = "luminary" | "planet" | "node" | "angle" | "lot" | "point";
2037
+ type PointId = "sun" | "moon" | "mercury" | "venus" | "mars" | "jupiter" | "saturn" | "uranus" | "neptune" | "pluto" | "mean-node" | "true-node" | "south-node-mean" | "south-node-true" | "mean-lilith" | "true-lilith" | "chiron" | "asc" | "mc" | "dsc" | "ic" | "vertex" | "lot-fortune" | "lot-spirit";
2038
+ /** Where the legacy value lives on a `BirthChart`. */
2039
+ type LegacySource = "planets" | "houses" | "lots" | "derived";
2040
+ interface PointDefinition {
2041
+ id: PointId;
2042
+ kind: PointClass;
2043
+ /** Key in the legacy aspect/planet dictionaries (`"mean node"`, `"ascendant"`, ...). */
2044
+ legacyKey: string;
2045
+ legacySource: LegacySource;
2046
+ /** Longitude depends on the exact birth time (Moon degree, angles, vertex, lots). */
2047
+ timeDependent: boolean;
2048
+ /** Axis membership: the two ends of an axis are geometrically complementary. */
2049
+ axis?: {
2050
+ id: string;
2051
+ end: 0 | 1;
2052
+ };
2053
+ }
2054
+ declare const POINT_DEFINITIONS: Readonly<Record<PointId, PointDefinition>>;
2055
+ declare const POINT_IDS: readonly PointId[];
2056
+ declare const POINT_CLASSES: readonly PointClass[];
2057
+ declare function isPointId(value: unknown): value is PointId;
2058
+ /** Per-point provenance flags. `placeholder` and `rectified` are set by `quality.ts`. */
2059
+ interface ChartPointFlags {
2060
+ /** Computed from other points (south nodes, DSC, IC, lots) rather than read from the ephemeris. */
2061
+ derived: boolean;
2062
+ /** Longitude depends on the exact birth time. */
2063
+ timeDependent: boolean;
2064
+ /** Position computed at a placeholder instant (untimed chart, local noon). */
2065
+ placeholder?: boolean;
2066
+ /** Time-dependent value that comes from a rectified (estimated) birth time. */
2067
+ rectified?: boolean;
2068
+ }
2069
+ interface ChartPoint {
2070
+ id: PointId;
2071
+ kind: PointClass;
2072
+ longitude: number;
2073
+ latitude?: number;
2074
+ /** Degrees per day; `null` = explicitly unavailable (angles, lots, hand-built points). */
2075
+ speed: number | null;
2076
+ legacyKey: string;
2077
+ legacySource: LegacySource;
2078
+ flags: ChartPointFlags;
2079
+ }
2080
+ /** Minimum shape the policy-based aspect functions need. `ChartPoint` satisfies it. */
2081
+ interface ChartPointLike {
2082
+ id: PointId;
2083
+ kind: PointClass;
2084
+ longitude: number;
2085
+ speed?: number | null;
2086
+ }
2087
+ interface ChartPointsOptions {
2088
+ /** Keep only these IDs (applied before `exclude`). */
2089
+ include?: readonly PointId[];
2090
+ exclude?: readonly PointId[];
2091
+ classes?: readonly PointClass[];
2092
+ }
2093
+ declare function getPointDefinition(id: PointId): PointDefinition;
2094
+ /** Reverse lookup: legacy spaced key (case/underscore tolerant) -> stable ID, or `null`. */
2095
+ declare function pointIdFromLegacyKey(key: string): PointId | null;
2096
+ /** Forward lookup: stable ID -> legacy key. */
2097
+ declare function legacyKeyFromPointId(id: PointId): string;
2098
+ /**
2099
+ * Points from raw Swiss positions keyed by `Planet` enum (no chart needed; used for
2100
+ * untimed charts and one-ephemeris-call multi-house-system computations). Includes the
2101
+ * derived south nodes. Speeds come from `longitudeSpeed` (`null` when absent).
2102
+ */
2103
+ declare function chartPointsFromPlanetPositions(positions: Partial<Record<number, PlanetPosition>>, options?: ChartPointsOptions): ChartPoint[];
2104
+ /**
2105
+ * Map a legacy `BirthChart` to typed points. `chart.planets`, `chart.nodes`, `chart.houses`
2106
+ * and `chart.lots` are only read. South nodes are derived (longitude + 180, same speed);
2107
+ * DSC/IC come from `chart.houses.dc/ic`. Angles and lots have `speed: null`.
2108
+ */
2109
+ declare function getChartPoints(chart: BirthChart, options?: ChartPointsOptions): ChartPoint[];
2110
+ /**
2111
+ * Re-key points to the legacy dictionary shape accepted by `computeAspects` and friends
2112
+ * (`{ [legacyKey]: { longitude, longitudeSpeed? } }`).
2113
+ */
2114
+ declare function toLegacyPointRecord(points: readonly ChartPoint[]): Record<string, {
2115
+ longitude: number;
2116
+ longitudeSpeed?: number;
2117
+ }>;
2118
+
2119
+ /**
2120
+ * Orb policies resolved at aspect GENERATION time.
2121
+ *
2122
+ * Legacy `computeAspects` uses one orb per aspect (`AspectSpec.orb`) and a CLI `--max-orb`
2123
+ * can only filter edges that were already generated, so it can never recover a contact the
2124
+ * generation orb omitted (e.g. a 5.5 degree sextile with the default 5 degree sextile orb).
2125
+ * An `OrbPolicy` is consulted for every pair BEFORE an edge exists, with per-body-class
2126
+ * rules, so wider (or narrower) windows are honoured exactly.
2127
+ *
2128
+ * Pair resolution (documented and echoed in every result's `policy` metadata). The orb
2129
+ * limit for aspect A between points P and Q is the first rule that applies:
2130
+ * 1. `pointPairOrbs["idP|idQ"]` (IDs sorted alphabetically);
2131
+ * 2. `classPairOrbs["classP|classQ"]` (classes sorted alphabetically);
2132
+ * 3. the `classOrbs` entry of the FIRST class in `classPrecedence` that is the class of P
2133
+ * or Q and has an entry (so a pair of different classes resolves to the higher-priority
2134
+ * class, not to an average or maximum);
2135
+ * 4. the aspect's own base orb (`aspects[i].orb`).
2136
+ * With `combine: "min"` the result of 1-3 is additionally capped by the aspect's base orb.
2137
+ * This reproduces the reference rule "points/angles 3, else luminaries 8, else planets 6":
2138
+ * `PTOLEMAIC_PLUS_QUINCUNX.classPrecedence` lists angle/node/point/lot before luminary
2139
+ * before planet, so Sun-Mercury is 8, Mercury-Mars is 6 and anything involving an
2140
+ * angle/node/point/lot is 3 (a luminary paired with a point is therefore 3, not 8).
2141
+ *
2142
+ * Pure arithmetic, no WASM dependency.
2143
+ */
2144
+
2145
+ type AspectConfigErrorCode = "UNKNOWN_ASPECT_NAME" | "INVALID_ASPECT_ANGLE" | "ASPECT_ANGLE_MISMATCH" | "DUPLICATE_ASPECT" | "EMPTY_ASPECT_LIST" | "INVALID_ORB" | "UNKNOWN_POINT_CLASS" | "UNKNOWN_POINT_ID" | "INVALID_POINT" | "DUPLICATE_POINT_ID" | "INVALID_OPTION";
2146
+ declare class AspectConfigError extends Error {
2147
+ readonly code: AspectConfigErrorCode;
2148
+ readonly details?: Record<string, unknown>;
2149
+ constructor(code: AspectConfigErrorCode, message: string, details?: Record<string, unknown>);
2150
+ }
2151
+ declare const ASPECT_CANONICAL_ANGLES: Readonly<Record<AspectName, number>>;
2152
+ declare const KNOWN_ASPECT_NAMES: readonly AspectName[];
2153
+ /**
2154
+ * Throws `AspectConfigError` for unknown names, angles outside [0,180], an angle that
2155
+ * disagrees with the name's canonical angle, orbs that are not finite numbers in [0,180],
2156
+ * duplicates or an empty list. Does not mutate or normalise.
2157
+ */
2158
+ declare function validateAspectSpecs(specs: readonly AspectSpec[]): void;
2159
+ interface OrbPolicy {
2160
+ /** Stable identifier echoed in results. */
2161
+ id: string;
2162
+ /** Aspects to generate with their base orbs (the fallback when no class rule applies). */
2163
+ aspects: readonly AspectSpec[];
2164
+ /** Orb limit (degrees) per body class. */
2165
+ classOrbs?: Partial<Record<PointClass, number>>;
2166
+ /** Highest priority first. Default: angle, node, point, lot, luminary, planet. */
2167
+ classPrecedence?: readonly PointClass[];
2168
+ /** Overrides for a class pair, keyed `"classA|classB"` with classes sorted alphabetically. */
2169
+ classPairOrbs?: Record<string, number>;
2170
+ /** Overrides for a point pair, keyed `"idA|idB"` with IDs sorted alphabetically. */
2171
+ pointPairOrbs?: Record<string, number>;
2172
+ /**
2173
+ * `"class-replaces-aspect"` (default): a matching class/pair rule REPLACES the aspect base
2174
+ * orb. `"min"`: the class/pair limit is capped by the aspect base orb.
2175
+ */
2176
+ combine?: "class-replaces-aspect" | "min";
2177
+ }
2178
+ declare const DEFAULT_CLASS_PRECEDENCE: readonly PointClass[];
2179
+ type OrbRuleSource = "point-pair" | "class-pair" | "class" | "aspect";
2180
+ interface ResolvedOrb {
2181
+ limit: number;
2182
+ rule: OrbRuleSource;
2183
+ /** The class whose rule decided the limit (`rule: "class"`). */
2184
+ decidingClass?: PointClass;
2185
+ }
2186
+ /** Validate a policy (aspect specs, orbs, class names, point IDs). Throws `AspectConfigError`. */
2187
+ declare function validateOrbPolicy(policy: OrbPolicy): void;
2188
+ /** Build and validate a policy, filling defaults (`classPrecedence`, `combine`). */
2189
+ declare function defineOrbPolicy(policy: OrbPolicy): OrbPolicy;
2190
+ /**
2191
+ * Resolve the orb limit for `spec` between two points under `policy`
2192
+ * (precedence in the module header).
2193
+ */
2194
+ declare function resolveOrbLimit(policy: OrbPolicy, a: Pick<ChartPointLike, "id" | "kind">, b: Pick<ChartPointLike, "id" | "kind">, spec: AspectSpec): ResolvedOrb;
2195
+ /**
2196
+ * Named, OPT-IN profile (not a default): Ptolemaic aspects plus quincunx; luminaries 8,
2197
+ * planets 6, and 3 whenever either participant is an angle, node, point (Lilith, Chiron) or
2198
+ * lot. Mirrors the reference rule (points/angles 3 > luminaries 8 > planets 6).
2199
+ */
2200
+ declare const PTOLEMAIC_PLUS_QUINCUNX: Readonly<OrbPolicy>;
2201
+ declare const ORB_POLICY_PROFILES: Readonly<Record<string, Readonly<OrbPolicy>>>;
2202
+ type AspectMotion = "applying" | "separating" | "exact" | null;
2203
+ type MotionUnavailableReason = "speed-unknown" | "zero-relative-speed";
2204
+ interface AspectMotionResult {
2205
+ motion: AspectMotion;
2206
+ /** d(orb)/dt in degrees per day (positive = widening); `null` when unavailable. */
2207
+ orbRate: number | null;
2208
+ reason?: MotionUnavailableReason;
2209
+ }
2210
+ /** Orb at or below this (degrees) is reported as `"exact"`. */
2211
+ declare const DEFAULT_EXACT_TOLERANCE_DEGREES = 0.000001;
2212
+ /**
2213
+ * Instantaneous applying/separating convention (analytic derivative, not a projected
2214
+ * future orb): with d = signed longitude difference B - A wrapped to (-180, 180],
2215
+ * separation s = |d|, orb = |s - angle|:
2216
+ * d(orb)/dt = sign(s - angle) * sign(d) * (speedB - speedA).
2217
+ * Negative -> `"applying"`, positive -> `"separating"`. `"exact"` when orb <= tolerance.
2218
+ * `null` when either speed is unknown (`null`/`undefined`/non-finite), or when the relative
2219
+ * speed is exactly zero away from exactness (`reason` says which). Speeds are degrees/day
2220
+ * (retrograde negative); wrap across 0 degrees is handled by the signed difference.
2221
+ */
2222
+ declare function getAspectMotion(lonA: number, speedA: number | null | undefined, lonB: number, speedB: number | null | undefined, aspectAngle: number, exactToleranceDegrees?: number): AspectMotionResult;
2223
+ interface PolicyAspectEdge {
2224
+ /** Stable IDs; for two-set calls `a` belongs to the first set, `b` to the second. */
2225
+ a: PointId;
2226
+ b: PointId;
2227
+ aKind: PointClass;
2228
+ bKind: PointClass;
2229
+ longitudeA: number;
2230
+ longitudeB: number;
2231
+ aspect: AspectName;
2232
+ aspectAngle: number;
2233
+ /** Exact angular separation in [0, 180]. */
2234
+ separation: number;
2235
+ /** |separation - aspectAngle|. */
2236
+ orb: number;
2237
+ /** The generation-time orb limit that admitted this contact. */
2238
+ orbLimit: number;
2239
+ orbRule: OrbRuleSource;
2240
+ decidingClass?: PointClass;
2241
+ motion: AspectMotion;
2242
+ /** d(orb)/dt, degrees/day; `null` when unavailable. */
2243
+ orbRate: number | null;
2244
+ motionUnavailableReason?: MotionUnavailableReason;
2245
+ /** Equivalence key: opposite ends of one axis (ASC/DSC, MC/IC, node/south node) share it. */
2246
+ axisKey: string;
2247
+ }
2248
+ interface ComputePolicyAspectsOptions {
2249
+ include?: readonly PointId[];
2250
+ exclude?: readonly PointId[];
2251
+ /**
2252
+ * Additional POST-filter (like the CLI `--max-orb`): can only narrow the policy's limits.
2253
+ */
2254
+ maxOrb?: number;
2255
+ exactToleranceDegrees?: number;
2256
+ /** Same-set pairs on one axis (ASC-DSC, node-south node) are trivial; skipped unless true. */
2257
+ includeSameAxisPairs?: boolean;
2258
+ /**
2259
+ * Two-set calls only: ignore the second set's speeds (treat them as 0). Use for
2260
+ * transit-to-natal so natal targets stay fixed, and motion is then available even for
2261
+ * natal angles.
2262
+ */
2263
+ fixedTargets?: boolean;
2264
+ }
2265
+ interface AspectCounts {
2266
+ /** Edges as generated; ASC and DSC (etc.) count separately. */
2267
+ raw: number;
2268
+ /** One per axis-equivalence group. */
2269
+ grouped: number;
2270
+ byAspect: Partial<Record<AspectName, {
2271
+ raw: number;
2272
+ grouped: number;
2273
+ }>>;
2274
+ }
2275
+ interface AxisAspectGroup {
2276
+ key: string;
2277
+ /** Tightest-orb member. */
2278
+ representative: PolicyAspectEdge;
2279
+ members: PolicyAspectEdge[];
2280
+ }
2281
+ interface OrbPolicyMetadata {
2282
+ policyId: string;
2283
+ aspects: Array<{
2284
+ name: AspectName;
2285
+ angle: number;
2286
+ baseOrb: number;
2287
+ }>;
2288
+ classOrbs: Partial<Record<PointClass, number>>;
2289
+ classPrecedence: PointClass[];
2290
+ combine: "class-replaces-aspect" | "min";
2291
+ pairResolution: string;
2292
+ generation: "orb limits resolved per pair before an edge is created";
2293
+ motionConvention: string;
2294
+ axisEquivalence: string;
2295
+ }
2296
+ interface PolicyAspectResult {
2297
+ edges: PolicyAspectEdge[];
2298
+ counts: AspectCounts;
2299
+ axisGroups: AxisAspectGroup[];
2300
+ policy: OrbPolicyMetadata;
2301
+ }
2302
+ declare function describeOrbPolicy(policy: OrbPolicy): OrbPolicyMetadata;
2303
+ /** Tight-first ordering: orb, then IDs, then aspect angle (deterministic). */
2304
+ declare function sortTightContacts(edges: readonly PolicyAspectEdge[], options?: {
2305
+ maxOrb?: number;
2306
+ limit?: number;
2307
+ }): PolicyAspectEdge[];
2308
+ /** Group edges that are the same observation seen from opposite ends of an axis. */
2309
+ declare function groupAspectsByAxis(edges: readonly PolicyAspectEdge[]): AxisAspectGroup[];
2310
+ /** Raw and axis-grouped counts, overall and per aspect (grouped uses each group's representative). */
2311
+ declare function countAspects(edges: readonly PolicyAspectEdge[]): AspectCounts;
2312
+ /**
2313
+ * Aspects among one set of points under an orb policy (orb limits resolved at generation).
2314
+ * Throws `AspectConfigError` for invalid policies, options or points. Edges are sorted tight-first.
2315
+ */
2316
+ declare function computeAspectsWithPolicy(points: readonly ChartPointLike[], policy: OrbPolicy, options?: ComputePolicyAspectsOptions): PolicyAspectResult;
2317
+ /**
2318
+ * Two-set (synastry / transit-to-natal) variant: `a` ids come from `setA`, `b` ids from `setB`.
2319
+ * With `fixedTargets: true` set B is treated as stationary (natal targets), so motion is
2320
+ * available even for set-B angles.
2321
+ */
2322
+ declare function computeAspectsBetweenSetsWithPolicy(setA: readonly ChartPointLike[], setB: readonly ChartPointLike[], policy: OrbPolicy, options?: ComputePolicyAspectsOptions): PolicyAspectResult;
2323
+ /** Transit-to-natal: `computeAspectsBetweenSetsWithPolicy` with `fixedTargets` defaulting to true. */
2324
+ declare function computeTransitAspectsWithPolicy(transitPoints: readonly ChartPointLike[], natalPoints: readonly ChartPointLike[], policy: OrbPolicy, options?: ComputePolicyAspectsOptions): PolicyAspectResult;
2325
+
2326
+ /**
2327
+ * Quality-aware chart input: recorded / rectified / untimed / partial.
2328
+ *
2329
+ * - recorded : full chart from a documented birth time.
2330
+ * - rectified: full chart, but every time-dependent value (Moon degree, angles, vertex,
2331
+ * lots) is flagged `rectified: true`; analysis selectors can drop rectified angles.
2332
+ * - untimed : positions at LOCAL NOON, every point flagged `placeholder: true`. The
2333
+ * normalized analysis set omits the Moon degree, angles, houses, lots, sect and
2334
+ * time-dependent techniques, each with a structured `unavailable` reason. The
2335
+ * whole-day Moon sign range (local 00:00 to the next local 00:00) and any other
2336
+ * body changing sign that day are reported instead.
2337
+ * - partial : no full date; no chart is invented, only structured unavailability.
2338
+ *
2339
+ * Time and place assumptions are returned as `TimeProvenance`. Wall-clock input reuses
2340
+ * `LocalDateTimeParts` / `TimeZoneOptions` from `./swisseph` (no second representation).
2341
+ *
2342
+ * `getBirthChart` lives in `./index`, which re-exports this module, so it is loaded lazily
2343
+ * (or injected through `computeChart`) to avoid an import cycle at evaluation time.
2344
+ */
2345
+
2346
+ type InputQuality = "recorded" | "rectified" | "untimed" | "partial";
2347
+ type PlaceRole = "birthplace" | "residence" | "event" | "unknown";
2348
+ interface PartialDateParts {
2349
+ year?: number;
2350
+ month?: number;
2351
+ day?: number;
2352
+ }
2353
+ declare const ZODIAC_SIGN_KEYS: readonly ["aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"];
2354
+ type ZodiacSignKey = (typeof ZODIAC_SIGN_KEYS)[number];
2355
+ type InputQualityErrorCode = "INVALID_QUALITY" | "INCOMPLETE_DATE" | "MISSING_TIME" | "MISSING_LOCATION" | "INVALID_DATE";
2356
+ declare class InputQualityError extends Error {
2357
+ readonly code: InputQualityErrorCode;
2358
+ constructor(code: InputQualityErrorCode, message: string);
2359
+ }
2360
+ type ChartUnavailableReason = "birth-time-unknown" | "date-incomplete" | "excluded-by-selector";
2361
+ interface UnavailableItem {
2362
+ item: "chart" | "moon-degree" | "angles" | "houses" | "lots" | "sect" | "time-dependent-techniques" | "rectified-angles";
2363
+ reason: ChartUnavailableReason;
2364
+ message: string;
2365
+ pointIds?: PointId[];
2366
+ /** For `time-dependent-techniques`: the techniques that cannot be run. */
2367
+ techniques?: string[];
2368
+ }
2369
+ interface SignIngress {
2370
+ fromSign: ZodiacSignKey;
2371
+ toSign: ZodiacSignKey;
2372
+ atUtc: Date;
2373
+ }
2374
+ interface MoonDayRange {
2375
+ /** One sign, or two in order when the Moon changes sign during the day. */
2376
+ signs: ZodiacSignKey[];
2377
+ changesSign: boolean;
2378
+ /** First ingress during the interval, when the sign changes. */
2379
+ ingress?: SignIngress;
2380
+ startUtc: Date;
2381
+ endUtc: Date;
2382
+ /** Interval is local 00:00 of the date to local 00:00 of the next date (zone rules applied). */
2383
+ interval: "local-midnight-to-local-midnight";
2384
+ degreesExcluded: true;
2385
+ }
2386
+ interface BodySignChange {
2387
+ id: PointId;
2388
+ signs: ZodiacSignKey[];
2389
+ ingresses: SignIngress[];
2390
+ }
2391
+ type TimeBasis = "iana-zone" | "utc-offset" | "auto-from-coordinates" | "utc-instant" | "local-mean-time" | "unknown-place";
2392
+ interface TimeProvenance {
2393
+ basis: TimeBasis;
2394
+ /** IANA zone when known (explicit, resolver, or tz-lookup); undefined for offsets, UTC, LMT. */
2395
+ ianaZone?: string;
2396
+ /** Resolved offset of the reference instant, minutes east of UTC (fractional for LMT); null if unknown. */
2397
+ utcOffsetMinutes: number | null;
2398
+ /** DST in effect at the reference instant; null when it cannot be determined. */
2399
+ dst: boolean | null;
2400
+ /** The input was already a UTC instant (`treatAsUTC`). */
2401
+ alreadyUtc: boolean;
2402
+ /** Longitude-based local mean time was chosen instead of a zone's civil time. */
2403
+ localMeanTime: boolean;
2404
+ /** Reference instant: the given time (timed) or local noon (untimed). `null` for partial dates. */
2405
+ referenceInstantUtc: Date | null;
2406
+ placeRole: PlaceRole;
2407
+ /** Latitude/longitude were supplied. */
2408
+ placeKnown: boolean;
2409
+ notes: string[];
2410
+ }
2411
+ interface AnalysisSelection {
2412
+ include?: readonly PointId[];
2413
+ exclude?: readonly PointId[];
2414
+ classes?: readonly PointClass[];
2415
+ /** Drop angles (ASC/MC/DSC/IC/Vertex) that came from a rectified time. */
2416
+ excludeRectifiedAngles?: boolean;
2417
+ }
2418
+ interface QualifiedChartInput {
2419
+ quality: InputQuality;
2420
+ date: Date | LocalDateTimeParts | PartialDateParts;
2421
+ latitude?: number;
2422
+ longitude?: number;
2423
+ houseSystem?: HouseSystem;
2424
+ timeZoneSettings?: TimeZoneOptions;
2425
+ /**
2426
+ * Read the wall-clock parts as local mean time of `longitude` (4 minutes per degree east
2427
+ * of Greenwich), for pre-standard-time records. Overrides `timeZoneSettings`.
2428
+ */
2429
+ localMeanTime?: boolean;
2430
+ placeRole?: PlaceRole;
2431
+ analysis?: AnalysisSelection;
2432
+ /** Injected chart function (defaults to `getBirthChart` from `./index`, loaded lazily). */
2433
+ computeChart?: (options: BirthChartOptions) => Promise<ComputedBirthChart>;
2434
+ }
2435
+ interface QualifiedChart {
2436
+ quality: InputQuality;
2437
+ /** `complete`: everything computed; `limited`: untimed; `unavailable`: partial. */
2438
+ status: "complete" | "limited" | "unavailable";
2439
+ /** Full chart for recorded/rectified; always `null` for untimed and partial. */
2440
+ chart: ComputedBirthChart | null;
2441
+ /** Every computed point with provenance flags (placeholder / rectified). */
2442
+ points: ChartPoint[];
2443
+ /** Normalized point set to feed analysis (untimed: no Moon, angles, lots; selectors applied). */
2444
+ analysisPoints: ChartPoint[];
2445
+ unavailable: UnavailableItem[];
2446
+ /** Untimed only. */
2447
+ moonDayRange?: MoonDayRange;
2448
+ /** Untimed only: other bodies that change sign during the local day. */
2449
+ signChanges?: BodySignChange[];
2450
+ provenance: TimeProvenance;
2451
+ }
2452
+ /**
2453
+ * Describe how the reference instant was obtained: IANA zone and resolved DST offset,
2454
+ * already-UTC input, historical local-mean-time choice, birthplace vs residence, unknown place.
2455
+ * `reference` is the full local date-time to resolve (use noon for untimed charts).
2456
+ */
2457
+ declare function resolveTimeProvenance(input: QualifiedChartInput, reference: LocalDateTimeParts | null): Promise<TimeProvenance>;
2458
+ /** Moon sign(s) between two instants plus the first ingress (Moon never stations, so at most one per day). */
2459
+ declare function getMoonSignRange(startUtc: Date, endUtc: Date): MoonDayRange;
2460
+ /** Bodies other than the Moon that change sign between two instants (south nodes mirror their north node). */
2461
+ declare function getSignChangesBetween(startUtc: Date, endUtc: Date): BodySignChange[];
2462
+ /** Apply include/exclude/classes and the rectified-angle selector to a point list. */
2463
+ declare function selectAnalysisPoints(points: readonly ChartPoint[], selection?: AnalysisSelection): ChartPoint[];
2464
+ /**
2465
+ * Quality-aware chart. Opt-in; does not change `getBirthChart`.
2466
+ * Throws `InputQualityError` for an unknown quality, an incomplete date where a full date is
2467
+ * required, a missing time (recorded/rectified given `LocalDateTimeParts` without `hour`) or
2468
+ * missing coordinates (recorded/rectified).
2469
+ */
2470
+ declare function getQualifiedChart(input: QualifiedChartInput): Promise<QualifiedChart>;
2471
+
2472
+ /**
2473
+ * Several house systems from ONE ephemeris calculation.
2474
+ *
2475
+ * Planetary positions, sect and the Lots of Fortune/Spirit do not depend on the house
2476
+ * system (sect comes from the Sun's altitude at the place; Fortune/Spirit use the Ascendant,
2477
+ * which Swiss returns identically for every system), so they are computed once. Only the
2478
+ * cusps, the descendant/IC and each point's house placement are produced per system.
2479
+ */
2480
+
2481
+ interface HousesForSystemsDateInput {
2482
+ /** Local civil time (interpreted via `timeZoneSettings`) or a UTC instant with `treatAsUTC`. */
2483
+ date: Date | LocalDateTimeParts;
2484
+ latitude: number;
2485
+ longitude: number;
2486
+ timeZoneSettings?: TimeZoneOptions;
2487
+ }
2488
+ interface HousesForSystemsJulianInput {
2489
+ julianDayUt: number;
2490
+ latitude: number;
2491
+ longitude: number;
2492
+ }
2493
+ type HousesForSystemsInput = HousesForSystemsDateInput | HousesForSystemsJulianInput;
2494
+ interface SystemHouses {
2495
+ system: HouseSystem;
2496
+ /** 12 cusp longitudes, house 1 first, normalised to [0, 360). */
2497
+ cusps: number[];
2498
+ ascendant: number;
2499
+ mc: number;
2500
+ descendant: number;
2501
+ ic: number;
2502
+ vertex?: number;
2503
+ /** House number (1-12) of each point under THIS system (planets, nodes, Lilith, Chiron, lots). */
2504
+ placements: Partial<Record<PointId, number>>;
2505
+ }
2506
+ interface HouseSystemFailure {
2507
+ system: HouseSystem;
2508
+ message: string;
2509
+ }
2510
+ interface HousesForSystemsResult {
2511
+ julianDayUt: number;
2512
+ dateUtc: Date;
2513
+ latitude: number;
2514
+ longitude: number;
2515
+ /** Positions computed once (shared by every system). */
2516
+ points: ChartPoint[];
2517
+ /** House-system independent. */
2518
+ sect: SectResult;
2519
+ lots: LotsResult;
2520
+ systems: Partial<Record<HouseSystem, SystemHouses>>;
2521
+ /** Systems Swiss could not compute (for example Placidus/Koch at polar latitudes). */
2522
+ failures: HouseSystemFailure[];
2523
+ method: {
2524
+ ephemerisCalculations: "planets and sect computed once; houses computed once per system";
2525
+ flags: number;
2526
+ };
2527
+ }
2528
+ /**
2529
+ * Compute `systems` (deduplicated, order preserved) for one moment and place.
2530
+ * Throws if `systems` is empty. A system Swiss cannot compute is reported in `failures`
2531
+ * instead of aborting the others.
2532
+ */
2533
+ declare function getHousesForSystems(input: HousesForSystemsInput, systems: readonly HouseSystem[]): Promise<HousesForSystemsResult>;
2534
+
2535
+ /**
2536
+ * Both-direction house overlays and aspect-point extraction for derived charts.
2537
+ *
2538
+ * Pure math (no ephemeris access).
2539
+ *
2540
+ * Overlay convention: the house of a longitude is `findHouseOf(longitude, cusps)`,
2541
+ * i.e. the house whose cusp interval [cusp_i, cusp_i+1) contains it; a point on
2542
+ * a cusp belongs to the house that starts there. A chart without a complete set
2543
+ * of 12 cusps (untimed/partial) cannot receive overlays: that direction is
2544
+ * reported with `available: false` and a reason, never guessed.
2545
+ */
2546
+
2547
+ /** Structural view of a chart for overlays: bodies plus (optional) house cusps. */
2548
+ interface OverlayChartLike {
2549
+ planets: Record<string, {
2550
+ longitude: number;
2551
+ }>;
2552
+ houses?: {
2553
+ ascendant?: {
2554
+ longitude: number;
2555
+ };
2556
+ mc?: {
2557
+ longitude: number;
2558
+ };
2559
+ dc?: {
2560
+ longitude: number;
2561
+ };
2562
+ ic?: {
2563
+ longitude: number;
2564
+ };
2565
+ houses?: {
2566
+ longitude: number;
2567
+ }[];
2568
+ } | null;
2569
+ houseSystem?: HouseSystem;
2570
+ }
2571
+ interface HouseOverlayPlacement {
2572
+ point: string;
2573
+ longitude: number;
2574
+ /** House (1-12) of the receiving chart. */
2575
+ house: number;
2576
+ }
2577
+ interface HouseOverlayDirection {
2578
+ /** Chart whose points are placed. */
2579
+ from: "A" | "B";
2580
+ /** Chart whose houses receive them. */
2581
+ into: "A" | "B";
2582
+ available: boolean;
2583
+ /** Present when `available` is false. */
2584
+ reason?: string;
2585
+ /** Cusps of the receiving chart that were used. */
2586
+ cusps?: number[];
2587
+ houseSystem?: HouseSystem | null;
2588
+ houseSystemSource?: "chart" | "option" | "unknown";
2589
+ placements: HouseOverlayPlacement[];
2590
+ }
2591
+ interface HouseOverlays {
2592
+ aInB: HouseOverlayDirection;
2593
+ bInA: HouseOverlayDirection;
2594
+ method: {
2595
+ rule: string;
2596
+ points: string;
2597
+ angles: boolean;
2598
+ };
2599
+ }
2600
+ interface HouseOverlayOptions {
2601
+ /** Point keys to place (default: every key of `planets`, then angles if `includeAngles`). */
2602
+ points?: string[];
2603
+ /** Also place ascendant/mc/descendant/ic of the sending chart (default true). */
2604
+ includeAngles?: boolean;
2605
+ /** Used only when the chart does not record `houseSystem`. */
2606
+ houseSystemA?: HouseSystem;
2607
+ houseSystemB?: HouseSystem;
2608
+ }
2609
+ /**
2610
+ * House overlays in both directions: A's points in B's houses and B's points in A's houses.
2611
+ * The house system of each receiving chart is noted (`BirthChart.houseSystem`, else the option, else null).
2612
+ */
2613
+ declare function getHouseOverlays(chartA: OverlayChartLike, chartB: OverlayChartLike, options?: HouseOverlayOptions): HouseOverlays;
2614
+ /**
2615
+ * Aspect-ready point record (`{ longitude, longitudeSpeed? }`) of any chart-like
2616
+ * source: a `BirthChart` (natal, Davison, progressed, solar return), a composite
2617
+ * result, or a bare `planets` record. Angles `ascendant` and `mc` (plus
2618
+ * `descendant`, `ic` with `includeAllAngles`) are included. The result is accepted by
2619
+ * `computeAspects`, `computeSynastryAspects` and `computeTransitAspects`.
2620
+ */
2621
+ declare function derivedChartAspectPoints(source: BirthChart | CompositeChart | CompositeChartSummary | {
2622
+ planets: Record<string, {
2623
+ longitude: number;
2624
+ longitudeSpeed?: number;
2625
+ }>;
2626
+ }, options?: {
2627
+ includeAngles?: boolean;
2628
+ includeAllAngles?: boolean;
2629
+ }): Record<string, TransitAspectPoint>;
2630
+
2631
+ /**
2632
+ * Davison relationship chart: a REAL chart cast for the midpoint in TIME and
2633
+ * the midpoint in PLACE of two births.
2634
+ *
2635
+ * Davison and the midpoint composite (`getCompositeChart`) are DIFFERENT
2636
+ * methods: the composite averages the two charts' longitudes point by point and
2637
+ * has no time or place of its own; the Davison chart is an actual sky at an
2638
+ * actual instant, so planets stay physically consistent (e.g. Mercury within
2639
+ * 28 degrees of the Sun) and the two can differ by many degrees.
2640
+ *
2641
+ * Conventions (echoed in `method`):
2642
+ * - Time: arithmetic mean of the two UTC Julian Days (= the exact UTC instant
2643
+ * midpoint). The chart is cast at that JD without millisecond truncation.
2644
+ * - Place, default `"arithmetic-shorter-arc"` (the family reference): latitude =
2645
+ * arithmetic mean of the two latitudes; longitude = midpoint along the SHORTER
2646
+ * longitude arc (a + shortestDelta(b - a) / 2). Result normalised to (-180, 180].
2647
+ * Antimeridian: 179 E and 179 W give 180, not 0. Longitudes exactly 180 degrees
2648
+ * apart have two equally short arcs: the result is then symmetric in A/B (the
2649
+ * arithmetic mean of the two longitudes normalised to [-180, 180)) and a notice
2650
+ * is added.
2651
+ * - Place, `"great-circle"`: the normalised mean of the two unit vectors on the
2652
+ * sphere (true surface midpoint). Antipodal places have no unique midpoint: the
2653
+ * arithmetic convention is used instead and a notice is added.
2654
+ */
2655
+
2656
+ type GeographicMidpointConvention = "arithmetic-shorter-arc" | "great-circle";
2657
+ interface DavisonPersonInput {
2658
+ /** Absolute UTC instant of the birth. */
2659
+ dateUtc: Date;
2660
+ latitude: number;
2661
+ longitude: number;
2662
+ }
2663
+ interface DavisonOptions {
2664
+ a: DavisonPersonInput;
2665
+ b: DavisonPersonInput;
2666
+ houseSystem?: HouseSystem;
2667
+ /** Default "arithmetic-shorter-arc". */
2668
+ geographicMidpoint?: GeographicMidpointConvention;
2669
+ }
2670
+ type DavisonNotice = {
2671
+ type: "antipodal_longitudes";
2672
+ reason: string;
2673
+ } | {
2674
+ type: "antipodal_places";
2675
+ reason: string;
2676
+ };
2677
+ interface DavisonMethod {
2678
+ name: "davison";
2679
+ time: "arithmetic mean of the two UTC Julian Days (exact UTC instant midpoint)";
2680
+ geographicMidpoint: GeographicMidpointConvention;
2681
+ geographicMidpointRule: string;
2682
+ antimeridian: string;
2683
+ longitudeRange: "(-180, 180]";
2684
+ houseSystem: HouseSystem;
2685
+ distinctFromComposite: string;
2686
+ referenceConvention: string;
2687
+ }
2688
+ interface DavisonResult {
2689
+ chart: ComputedBirthChart;
2690
+ midpointJd: number;
2691
+ /** Midpoint instant rounded to the millisecond (`midpointJd` is exact). */
2692
+ midpointDateUtc: Date;
2693
+ location: {
2694
+ latitude: number;
2695
+ longitude: number;
2696
+ };
2697
+ inputs: {
2698
+ a: DavisonPersonInput;
2699
+ b: DavisonPersonInput;
2700
+ };
2701
+ notices: DavisonNotice[];
2702
+ method: DavisonMethod;
2703
+ }
2704
+ interface GeographicMidpoint {
2705
+ latitude: number;
2706
+ longitude: number;
2707
+ notices: DavisonNotice[];
2708
+ }
2709
+ /** Geographic midpoint of two places under the named convention (see module doc). */
2710
+ declare function geographicMidpoint(a: {
2711
+ latitude: number;
2712
+ longitude: number;
2713
+ }, b: {
2714
+ latitude: number;
2715
+ longitude: number;
2716
+ }, convention?: GeographicMidpointConvention): GeographicMidpoint;
2717
+ /** Davison chart from two UTC instants and places. */
2718
+ declare function getDavisonChart(options: DavisonOptions): DavisonResult;
2719
+ /** Davison chart from the same options as `getBirthChart` (local date-times are resolved to UTC first). */
2720
+ declare function getDavisonChartFromOptions(a: BirthChartOptions, b: BirthChartOptions, options?: {
2721
+ houseSystem?: HouseSystem;
2722
+ geographicMidpoint?: GeographicMidpointConvention;
2723
+ }): Promise<DavisonResult>;
2724
+
2725
+ /**
2726
+ * Secondary progressions, solar-arc directions and a chart-at-Julian-Day builder.
2727
+ *
2728
+ * Synchronous; require an initialised Swiss Ephemeris. All instants are UTC; the
2729
+ * time coordinate is the UT Julian Day, passed to the ephemeris WITHOUT
2730
+ * millisecond loss (unlike `getJulianDay(date)`).
2731
+ *
2732
+ * Conventions (every one is echoed in the result `method`):
2733
+ *
2734
+ * - Secondary progression ("a day for a year"): progressed JD = natal JD + age,
2735
+ * age = (target JD - natal JD) / year length, in "years". The year length is
2736
+ * explicit: `"julian"` 365.25 d (default, the family reference),
2737
+ * `"tropical"` 365.2422 d, a number of days, or `"solar-return"` (actual
2738
+ * years: completed solar returns + the fraction through the current
2739
+ * return-to-return interval).
2740
+ * - Progressed angles are NOT a single convention. All of these are returned:
2741
+ * `quotidian` (houses/angles computed at the progressed JD for the natal
2742
+ * place; the family reference convention; the progressed chart's `houses`),
2743
+ * `solar-arc` (natal angles + the true solar arc) and `naibod` (natal RAMC +
2744
+ * 0.985647 deg per year of age; MC/ASC derived with the natal-date true
2745
+ * obliquity and the natal latitude, angles only, no cusps).
2746
+ * - Solar arc (true): arc = progressed Sun - natal Sun, forward-normalised to
2747
+ * [0, 360), added to every target. Targets are explicit (`targetSet`). A
2748
+ * Naibod mean arc (0.985647 deg/yr x age) is an option.
2749
+ *
2750
+ * Passing derived charts to aspect functions: `result.points` (and
2751
+ * `derivedChartAspectPoints` for any chart) is a `Record<string, {longitude,
2752
+ * longitudeSpeed?}>`, accepted directly by `computeAspects`,
2753
+ * `computeSynastryAspects(natalPoints, progressed.points)` and
2754
+ * `computeTransitAspects`.
2755
+ */
2756
+
2757
+ declare const JULIAN_YEAR_DAYS = 365.25;
2758
+ declare const TROPICAL_YEAR_DAYS = 365.2422;
2759
+ /** Naibod rate: 59'08.33" of arc per year (mean solar motion), in degrees. */
2760
+ declare const NAIBOD_RATE_DEGREES_PER_YEAR: number;
2761
+ /** Hard cap on the age (years) accepted by the progression functions. */
2762
+ declare const MAX_PROGRESSION_AGE_YEARS = 200;
2763
+ type DerivedChartErrorCode = "INVALID_INPUT" | "TARGET_BEFORE_BIRTH" | "AGE_LIMIT_EXCEEDED" | "SOLAR_RETURN_NOT_FOUND" | "ANGLE_UNAVAILABLE";
2764
+ /** Typed error of the derived-chart functions (Davison, progressions). */
2765
+ declare class DerivedChartError extends Error {
2766
+ readonly code: DerivedChartErrorCode;
2767
+ constructor(code: DerivedChartErrorCode, message: string);
2768
+ }
2769
+ interface ChartAtJulianDayOptions {
2770
+ /** UT Julian Day (full sub-second precision is kept). */
2771
+ julianDayUt: number;
2772
+ latitude: number;
2773
+ longitude: number;
2774
+ houseSystem?: HouseSystem;
2775
+ /** Opt-in recorded substitute when the house system is unavailable at this latitude (see `BirthChartOptions`). */
2776
+ houseSystemFallback?: HouseSystemFallback;
2777
+ }
2778
+ /**
2779
+ * Full chart (same shape and fields as `getBirthChart`) cast for an exact UT Julian
2780
+ * Day and place, with no time-zone handling and no millisecond truncation. At a
2781
+ * whole-second instant it equals `getBirthChart({ date, timeZoneSettings: { treatAsUTC: true } })`.
2782
+ * `dateUtc` is the Julian Day rounded to the millisecond.
2783
+ */
2784
+ declare function getChartAtJulianDay(options: ChartAtJulianDayOptions): ComputedBirthChart;
2785
+ type YearLengthSpec = number | "julian" | "tropical" | "solar-return";
2786
+ interface ProgressionTimeKey {
2787
+ /** What the progressed JD is: natal JD + `ageYears` (one ephemeris day per year of life). */
2788
+ rule: "progressed JD = natal JD + age in years (a day for a year)";
2789
+ yearLength: {
2790
+ spec: string;
2791
+ days: number | null;
2792
+ };
2793
+ natalJd: number;
2794
+ targetJd: number;
2795
+ ageYears: number;
2796
+ progressedJd: number;
2797
+ }
2798
+ interface ProgressionOptions {
2799
+ /** Natal chart (from `getBirthChart`); only its planets, angles, house system and `dateUtc` are used. */
2800
+ natalChart: BirthChart;
2801
+ /** Natal place: a `BirthChart` does not store it, and quotidian/Naibod angles need it. */
2802
+ natalLatitude: number;
2803
+ natalLongitude: number;
2804
+ /** Absolute UTC instant the progression is computed for. */
2805
+ target: Date;
2806
+ /** Year-length convention of the time key (default "julian" = 365.25 days, the reference). */
2807
+ yearLength?: YearLengthSpec;
2808
+ /** House system of the quotidian progressed chart (default: the natal chart's recorded system, else Placidus). */
2809
+ houseSystem?: HouseSystem;
2810
+ }
2811
+ interface ProgressedAngles {
2812
+ convention: ProgressedAngleConvention;
2813
+ ascendant: number;
2814
+ mc: number;
2815
+ descendant: number;
2816
+ ic: number;
2817
+ /** 12 cusps when the convention provides them (quotidian, solar-arc); undefined for naibod. */
2818
+ cusps?: number[];
2819
+ }
2820
+ type ProgressedAngleConvention = "quotidian" | "solar-arc" | "naibod";
2821
+ declare const PROGRESSED_ANGLE_CONVENTIONS: ProgressedAngleConvention[];
2822
+ /** Ecliptic MC and ASC from the right ascension of the MC (ARMC), obliquity and latitude (degrees). */
2823
+ declare function anglesFromArmc(armc: number, obliquity: number, latitude: number): {
2824
+ mc: number;
2825
+ ascendant: number;
2826
+ };
2827
+ interface ProgressionMethodBase {
2828
+ timeKey: ProgressionTimeKey;
2829
+ ephemeris: "Swiss Ephemeris (SWISS_EPH, SPEED), UT Julian Day without millisecond truncation";
2830
+ }
2831
+ interface SecondaryProgressionOptions extends ProgressionOptions {
2832
+ /** Which progressed-angle conventions to compute (default: all three). */
2833
+ angleConventions?: ProgressedAngleConvention[];
2834
+ }
2835
+ interface SecondaryProgressionMethod extends ProgressionMethodBase {
2836
+ technique: "secondary progression";
2837
+ /** The convention behind `chart.houses` (always quotidian). */
2838
+ chartHousesConvention: "quotidian";
2839
+ angleConventions: ProgressedAngleConvention[];
2840
+ angleConventionNotes: Record<ProgressedAngleConvention, string>;
2841
+ /** Progressed longitude speeds are degrees per EPHEMERIS day (i.e. per progressed year of life). */
2842
+ speedUnits: "degrees per ephemeris day";
2843
+ targetSet: "all bodies of the progressed chart + angles";
2844
+ }
2845
+ interface SecondaryProgressionResult {
2846
+ /** Progressed planets at `progressedJd`; houses/angles follow the quotidian convention. */
2847
+ chart: ComputedBirthChart;
2848
+ /** Progressed bodies + angles (quotidian) ready for the aspect functions. */
2849
+ points: Record<string, TransitAspectPoint>;
2850
+ /** Angles under each requested convention. */
2851
+ angles: Partial<Record<ProgressedAngleConvention, ProgressedAngles>>;
2852
+ /** Progressed Sun minus natal Sun, forward-normalised to [0, 360). */
2853
+ solarArcDegrees: number;
2854
+ natalSunLongitude: number;
2855
+ progressedJd: number;
2856
+ ageYears: number;
2857
+ method: SecondaryProgressionMethod;
2858
+ }
2859
+ /** Secondary progressions ("a day for a year") with a declared time key and angle conventions. */
2860
+ declare function getSecondaryProgressions(options: SecondaryProgressionOptions): SecondaryProgressionResult;
2861
+ interface SolarArcOptions extends ProgressionOptions {
2862
+ /** "true" = progressed Sun - natal Sun (default); "naibod" = 0.985647 deg x age. */
2863
+ arcKind?: "true" | "naibod";
2864
+ /**
2865
+ * Natal points to direct, by key: planet keys as in `chart.planets` plus
2866
+ * `ascendant`, `mc`, `descendant`, `ic`. Default: every planet/body plus the four angles.
2867
+ */
2868
+ targets?: string[];
2869
+ }
2870
+ interface DirectedPoint {
2871
+ name: string;
2872
+ natalLongitude: number;
2873
+ longitude: number;
2874
+ zodiacPosition: ZodiacPosition;
2875
+ }
2876
+ interface SolarArcMethod extends ProgressionMethodBase {
2877
+ technique: "solar arc directions";
2878
+ arcKind: "true" | "naibod";
2879
+ arcRule: string;
2880
+ /** The exact target keys that were directed. */
2881
+ targetSet: string[];
2882
+ houses: "natal cusps advanced by the same arc";
2883
+ }
2884
+ interface SolarArcResult {
2885
+ arcDegrees: number;
2886
+ directed: Record<string, DirectedPoint>;
2887
+ directedCusps: number[];
2888
+ /** Directed points ready for the aspect functions. */
2889
+ points: Record<string, TransitAspectPoint>;
2890
+ progressedSunLongitude: number | null;
2891
+ method: SolarArcMethod;
2892
+ }
2893
+ /** Solar-arc directions: one arc added uniformly to an explicit set of natal points. */
2894
+ declare function getSolarArcDirections(options: SolarArcOptions): SolarArcResult;
2895
+
2896
+ /**
2897
+ * Bounded return-pass timelines: thin wrappers over `./returns` that run several
2898
+ * return/opposition searches for one natal chart and merge every pass into one
2899
+ * chronologically sorted list, each pass carrying its solver metadata.
2900
+ *
2901
+ * Bounded by hard caps (window length, number of kinds, number of passes);
2902
+ * violations throw `TimelineError` (typed `code`). Annual profection and firdaria
2903
+ * timelines live next to their logic: `getAnnualProfectionTimeline`
2904
+ * (./profections) and `getFirdariaTimeline` (./firdaria).
2905
+ *
2906
+ * Synchronous; require an initialised Swiss Ephemeris.
2907
+ */
2908
+
2909
+ declare const MAX_RETURN_TIMELINE_YEARS = 150;
2910
+ declare const MAX_RETURN_TIMELINE_PASSES = 2000;
2911
+ type ReturnPassKind = "saturn-return" | "jupiter-return" | "uranus-opposition" | "mean-nodal-return" | "true-nodal-return" | "solar-return";
2912
+ declare const DEFAULT_RETURN_PASS_KINDS: ReturnPassKind[];
2913
+ interface ReturnTimelineOptions {
2914
+ /** Natal chart (or any `{ planets: { [key]: { longitude } } }` source). */
2915
+ natalChart: NatalLongitudeSource;
2916
+ /** Window (inclusive), absolute UTC instants. */
2917
+ from: Date;
2918
+ to: Date;
2919
+ /** Kinds to search (default: Saturn, Jupiter, Uranus opposition, mean and true nodal returns). */
2920
+ kinds?: ReturnPassKind[];
2921
+ stepDays?: number;
2922
+ timeToleranceSeconds?: number;
2923
+ residualToleranceDegrees?: number;
2924
+ /**
2925
+ * The natal instant is itself a trivial zero-offset "pass" when the window includes it.
2926
+ * When the natal source has a `dateUtc` (a `BirthChart`), passes within 12 hours of it are
2927
+ * dropped and counted in `excludedNatalInstantPasses` unless this is set to false.
2928
+ */
2929
+ excludeNatalInstant?: boolean;
2930
+ }
2931
+ interface ReturnPassEntry {
2932
+ kind: ReturnPassKind;
2933
+ body: string;
2934
+ eventKind: "return" | "opposition" | "offset-aspect";
2935
+ /** 1-based pass index within this kind and window, and the number of passes of that kind. */
2936
+ passIndex: number;
2937
+ passCount: number;
2938
+ instant: Date;
2939
+ jd: number;
2940
+ natalLongitude: number;
2941
+ targetLongitude: number;
2942
+ residualDegrees: number;
2943
+ direction: RootDirection;
2944
+ speedDegreesPerDay: number;
2945
+ tangent: boolean;
2946
+ solver: {
2947
+ bracketWidthSeconds: number;
2948
+ timeToleranceSeconds: number;
2949
+ iterations: number;
2950
+ method: RootSolverMethodMetadata;
2951
+ };
2952
+ }
2953
+ interface ReturnTimelineResult {
2954
+ window: {
2955
+ from: Date;
2956
+ to: Date;
2957
+ };
2958
+ /** Passes of all kinds, sorted by `jd` (ties by kind order). */
2959
+ entries: ReturnPassEntry[];
2960
+ /** Number of trivial passes at the natal instant that were dropped (see `excludeNatalInstant`). */
2961
+ excludedNatalInstantPasses: number;
2962
+ /** Per-kind search metadata (coverage, tolerances, unrecovered roots). */
2963
+ searches: Record<string, {
2964
+ coverage: RootSearchCoverage;
2965
+ residualToleranceDegrees: number;
2966
+ timeToleranceSeconds: number;
2967
+ rejectedCount: number;
2968
+ }>;
2969
+ method: {
2970
+ solver: RootSolverMethodMetadata;
2971
+ note: string;
2972
+ };
2973
+ }
2974
+ /** Every return/opposition pass of the requested kinds between two dates, merged and sorted. */
2975
+ declare function getReturnPassTimeline(options: ReturnTimelineOptions): ReturnTimelineResult;
2976
+
2977
+ /**
2978
+ * Bulk / collection computation: structured manifests of people, events and pair selections.
2979
+ *
2980
+ * Guarantees
2981
+ * - Each person's natal chart is computed exactly ONCE (or never, for a precomputed chart),
2982
+ * no matter how many of the N(N-1)/2 pairs it takes part in.
2983
+ * - User IDs are preserved verbatim; the library never invents or rewrites them. Manifests
2984
+ * are name-free by design (an ID is the only identifier).
2985
+ * - Output order is deterministic: people and events in manifest order, pairs ordered by
2986
+ * manifest index (i < j), whatever order tasks actually finish in.
2987
+ * - One person's failure becomes `{ ok: false, error }` for that person; pairs that involve
2988
+ * a failed person are reported as unavailable with the reason, never dropped silently.
2989
+ * - Hard caps and typed `CollectionError`s reject duplicate IDs, unknown pair IDs,
2990
+ * self-pairs and oversized manifests before any chart is computed.
2991
+ *
2992
+ * Concurrency, honestly: Swiss Ephemeris runs as SYNCHRONOUS WebAssembly calls on the JS
2993
+ * thread. `concurrency` bounds how many async tasks are in flight and how far results may
2994
+ * run ahead of the consumer (backpressure); it does not make the ephemeris parallel. The
2995
+ * scheduler yields to the event loop on a small time budget so progress callbacks, timers
2996
+ * and abort signals stay responsive. The default pair computation is pure tropical
2997
+ * longitude geometry and this module owns no mutable engine state, so sidereal/Jyotish
2998
+ * frames cannot leak between items (callers that inject a Jyotish-aware `computeChart`
2999
+ * must keep Swiss state changes inside synchronous `withSwissEphState`-style scopes).
3000
+ *
3001
+ * Library-only: it accepts a standard `AbortSignal` and does not import CLI code.
3002
+ */
3003
+
3004
+ declare const COLLECTION_METHOD_VERSION = "kaabalah-collection/1";
3005
+ interface CollectionLimits {
3006
+ maxPeople: number;
3007
+ maxEvents: number;
3008
+ maxPairs: number;
3009
+ maxConcurrency: number;
3010
+ }
3011
+ /** Hard caps; `options.limits` may only lower them. 500 people allow every pair (124,750). */
3012
+ declare const COLLECTION_HARD_LIMITS: Readonly<CollectionLimits>;
3013
+ declare const DEFAULT_COLLECTION_CONCURRENCY = 4;
3014
+ type CollectionErrorCode = "INVALID_MANIFEST" | "DUPLICATE_ID" | "UNKNOWN_PAIR_ID" | "SELF_PAIR" | "MANIFEST_TOO_LARGE" | "INVALID_OPTION" | "ABORTED";
3015
+ /** Typed error for manifest/option problems and cancellation. `code` is stable API. */
3016
+ declare class CollectionError extends Error {
3017
+ readonly code: CollectionErrorCode;
3018
+ readonly details: Record<string, unknown>;
3019
+ constructor(code: CollectionErrorCode, message: string, details?: Record<string, unknown>);
3020
+ }
3021
+ /** AbortError-style error (`name === "AbortError"`, `code === "ABORTED"`) raised on cancellation. */
3022
+ declare class CollectionAbortError extends CollectionError {
3023
+ constructor(reason?: unknown);
3024
+ }
3025
+ /** How trustworthy/complete the birth time is. Untimed and partial people omit Moon and angles from pair aspects. */
3026
+ type CollectionInputQuality = "recorded" | "rectified" | "untimed" | "partial";
3027
+ interface CollectionPersonInput {
3028
+ /** Caller-owned identifier, preserved verbatim. Must be unique among people. */
3029
+ id: string;
3030
+ /** Chart input; the chart is computed once. Exactly one of `chart` / `precomputed`. */
3031
+ chart?: BirthChartOptions;
3032
+ /** An already computed chart (no computation happens). */
3033
+ precomputed?: BirthChart;
3034
+ /** Default "recorded". Untimed/partial: Moon and angles excluded from pair aspects and flagged. */
3035
+ quality?: CollectionInputQuality;
3036
+ }
3037
+ interface CollectionEventInput {
3038
+ id: string;
3039
+ date: Date | LocalDateTimeParts;
3040
+ /** Default 0. */
3041
+ latitude?: number;
3042
+ /** Default 0. */
3043
+ longitude?: number;
3044
+ /** Default `{ treatAsUTC: true }`. */
3045
+ timeZoneSettings?: TimeZoneOptions;
3046
+ }
3047
+ type PairSelection = {
3048
+ mode: "all";
3049
+ } | {
3050
+ mode: "pairs";
3051
+ pairs: ReadonlyArray<readonly [string, string]>;
3052
+ }
3053
+ /** All pairs among people whose quality is "recorded" or "rectified" (a supplied time). */
3054
+ | {
3055
+ mode: "timed-only";
3056
+ };
3057
+ interface CollectionManifest {
3058
+ people: readonly CollectionPersonInput[];
3059
+ events?: readonly CollectionEventInput[];
3060
+ /** Default `{ mode: "all" }`. */
3061
+ pairs?: PairSelection;
3062
+ }
3063
+ /** A person's chart prepared for pair computation. */
3064
+ interface PreparedPerson {
3065
+ id: string;
3066
+ /** Manifest index. */
3067
+ index: number;
3068
+ quality: CollectionInputQuality;
3069
+ /** True when Moon degree and angles are trustworthy (recorded / rectified). */
3070
+ timed: boolean;
3071
+ chart: BirthChart;
3072
+ }
3073
+ interface PairComputation {
3074
+ aspects: AspectEdge[];
3075
+ /** True when points were withheld or the result is otherwise incomplete. */
3076
+ partial?: boolean;
3077
+ excludedPoints?: {
3078
+ a: string[];
3079
+ b: string[];
3080
+ };
3081
+ /** Method metadata supplied by an injected computation; copied to the pair record. */
3082
+ metadata?: Record<string, unknown>;
3083
+ }
3084
+ interface PairComputeContext {
3085
+ aspectSpecs?: AspectSpec[];
3086
+ signal?: AbortSignal;
3087
+ }
3088
+ type ChartComputer = (input: BirthChartOptions, context: {
3089
+ id: string;
3090
+ kind: "person" | "event";
3091
+ }) => Promise<BirthChart>;
3092
+ type PairComputer = (a: PreparedPerson, b: PreparedPerson, context: PairComputeContext) => PairComputation | Promise<PairComputation>;
3093
+ interface CollectionProgress {
3094
+ phase: "people" | "events" | "pairs";
3095
+ /** Items finished in this phase, counted in deterministic emission order (1..total). */
3096
+ completed: number;
3097
+ total: number;
3098
+ /** Person/event id, or `${idA}~${idB}` for pairs (see `ids`). */
3099
+ id: string;
3100
+ ids?: [string, string];
3101
+ }
3102
+ interface CollectionOptions {
3103
+ /** Async tasks in flight and ahead-of-consumer window. Default 4, max 64. */
3104
+ concurrency?: number;
3105
+ signal?: AbortSignal;
3106
+ onProgress?: (progress: CollectionProgress) => void;
3107
+ /** Embed full charts in person/event records. Default false (lightweight records). */
3108
+ includeCharts?: boolean;
3109
+ aspectSpecs?: AspectSpec[];
3110
+ /** Replace the chart function (default `getBirthChart`). */
3111
+ computeChart?: ChartComputer;
3112
+ /** Replace the pair function (default tropical synastry aspects over eligible points). */
3113
+ computePair?: PairComputer;
3114
+ /** Lower the hard caps. */
3115
+ limits?: Partial<CollectionLimits>;
3116
+ /** Event-loop yield budget in milliseconds (default 8). `0` yields after every item. */
3117
+ yieldBudgetMs?: number;
3118
+ }
3119
+ interface ItemError {
3120
+ code: string;
3121
+ message: string;
3122
+ }
3123
+ interface PersonRecordOk {
3124
+ type: "person";
3125
+ id: string;
3126
+ index: number;
3127
+ ok: true;
3128
+ quality: CollectionInputQuality;
3129
+ timed: boolean;
3130
+ /** Eligible point longitudes (degrees). Untimed/partial: Moon excluded. */
3131
+ points: Record<string, number>;
3132
+ /** Ascendant / MC longitudes; absent when untimed or partial. */
3133
+ angles?: {
3134
+ ascendant: number;
3135
+ mc: number;
3136
+ };
3137
+ /** Points withheld because the time is not trustworthy. */
3138
+ excludedPoints: string[];
3139
+ chart?: BirthChart;
3140
+ }
3141
+ interface PersonRecordFailed {
3142
+ type: "person";
3143
+ id: string;
3144
+ index: number;
3145
+ ok: false;
3146
+ quality: CollectionInputQuality;
3147
+ error: ItemError;
3148
+ }
3149
+ type PersonRecord = PersonRecordOk | PersonRecordFailed;
3150
+ interface EventRecordOk {
3151
+ type: "event";
3152
+ id: string;
3153
+ index: number;
3154
+ ok: true;
3155
+ points: Record<string, number>;
3156
+ chart?: BirthChart;
3157
+ }
3158
+ interface EventRecordFailed {
3159
+ type: "event";
3160
+ id: string;
3161
+ index: number;
3162
+ ok: false;
3163
+ error: ItemError;
3164
+ }
3165
+ type EventRecord = EventRecordOk | EventRecordFailed;
3166
+ interface PairRecordOk {
3167
+ type: "pair";
3168
+ idA: string;
3169
+ idB: string;
3170
+ indexA: number;
3171
+ indexB: number;
3172
+ ok: true;
3173
+ partial: boolean;
3174
+ excludedPoints: {
3175
+ a: string[];
3176
+ b: string[];
3177
+ };
3178
+ aspectCount: number;
3179
+ aspects: AspectEdge[];
3180
+ metadata?: Record<string, unknown>;
3181
+ }
3182
+ interface PairRecordUnavailable {
3183
+ type: "pair";
3184
+ idA: string;
3185
+ idB: string;
3186
+ indexA: number;
3187
+ indexB: number;
3188
+ ok: false;
3189
+ error: ItemError;
3190
+ /** Ids of the people whose charts are unavailable. */
3191
+ unavailablePeople: string[];
3192
+ }
3193
+ type PairRecord = PairRecordOk | PairRecordUnavailable;
3194
+ interface CollectionSummary {
3195
+ type: "summary";
3196
+ method: {
3197
+ id: string;
3198
+ pairComputation: "default-tropical-synastry" | "custom";
3199
+ chartComputation: "getBirthChart" | "custom";
3200
+ aspectSpecs: "default" | "custom";
3201
+ ordering: string;
3202
+ executionModel: string;
3203
+ };
3204
+ selection: {
3205
+ mode: PairSelection["mode"];
3206
+ pairCount: number;
3207
+ };
3208
+ people: {
3209
+ total: number;
3210
+ ok: number;
3211
+ failed: number;
3212
+ };
3213
+ events: {
3214
+ total: number;
3215
+ ok: number;
3216
+ failed: number;
3217
+ };
3218
+ pairs: {
3219
+ total: number;
3220
+ ok: number;
3221
+ unavailable: number;
3222
+ partial: number;
3223
+ aspects: number;
3224
+ };
3225
+ /** People left out of pair selection by the selection mode itself (for example untimed in "timed-only"). */
3226
+ skippedPeople: {
3227
+ id: string;
3228
+ reason: string;
3229
+ }[];
3230
+ options: {
3231
+ concurrency: number;
3232
+ includeCharts: boolean;
3233
+ };
3234
+ }
3235
+ type CollectionRecord = PersonRecord | EventRecord | PairRecord | CollectionSummary;
3236
+ interface CollectionResult {
3237
+ method: typeof COLLECTION_METHOD_VERSION;
3238
+ people: PersonRecord[];
3239
+ events: EventRecord[];
3240
+ pairs: PairRecord[];
3241
+ summary: CollectionSummary;
3242
+ }
3243
+ /**
3244
+ * Pair-eligible points of a person: all chart planets plus ascendant and MC. Untimed and
3245
+ * partial people lose the Moon (noon placeholder) and both angles; withheld keys are listed.
3246
+ */
3247
+ declare function getEligiblePairPoints(person: PreparedPerson): {
3248
+ points: Record<string, {
3249
+ longitude: number;
3250
+ }>;
3251
+ excluded: string[];
3252
+ };
3253
+ /** Default pair function: inter-chart aspects over the eligible points (tropical longitudes, no shared state). */
3254
+ declare const defaultPairComputer: PairComputer;
3255
+ /**
3256
+ * Stream a collection as deterministic records: all people, then all events, then all
3257
+ * pairs, then one summary. Validation errors throw synchronously from this call; abort
3258
+ * rejects the iterator with `CollectionAbortError`. Pull-based: nothing runs ahead of the
3259
+ * consumer by more than `concurrency` items (backpressure), so it suits NDJSON streaming.
3260
+ */
3261
+ declare function iterateCollection(manifest: CollectionManifest, options?: CollectionOptions): AsyncGenerator<CollectionRecord, void, void>;
3262
+ /** Aggregate variant (the default): runs `iterateCollection` to completion and groups the records. */
3263
+ declare function computeCollection(manifest: CollectionManifest, options?: CollectionOptions): Promise<CollectionResult>;
3264
+
3265
+ /**
3266
+ * Deterministic cache keys for chart-level calculations, plus a small bounded LRU memo.
3267
+ *
3268
+ * A key is the canonical JSON (sorted keys, normalised numbers) of EVERY input that can
3269
+ * change a result: the complete chart input, civil-time semantics, timezone and resolved
3270
+ * offset, coordinates, input quality, house system(s), point selection, orb policy,
3271
+ * method/frame, node convention, year length, GC constants, ephemeris identity, package
3272
+ * version and any extra configuration. A person's ID is never a key by itself; it is not
3273
+ * even an accepted component. A required component that is `undefined` throws a typed
3274
+ * `CacheKeyError`; `null` is an explicit "not applicable" (for example no GC constants in
3275
+ * a tropical calculation).
3276
+ *
3277
+ * Pure and browser-safe: no ephemeris access, no shared mutable state other than the memo
3278
+ * instance you create.
3279
+ */
3280
+
3281
+ declare const CACHE_KEY_VERSION = 1;
3282
+ type CacheKeyErrorCode = "MISSING_COMPONENT" | "INVALID_COMPONENT" | "INVALID_CACHE_OPTION";
3283
+ /** Typed error raised by the cache-key builder and memo. `code` is stable API. */
3284
+ declare class CacheKeyError extends Error {
3285
+ readonly code: CacheKeyErrorCode;
3286
+ readonly component: string | null;
3287
+ constructor(code: CacheKeyErrorCode, message: string, component?: string | null);
3288
+ }
3289
+ /** Normalise a finite number: -0 becomes 0 and float noise beyond 15 significant digits is dropped. */
3290
+ declare function normalizeKeyNumber(value: number): number;
3291
+ /** Stable JSON: object keys sorted recursively, numbers normalised, Dates tagged. No whitespace. */
3292
+ declare function canonicalJson(value: unknown): string;
3293
+ type CacheInputQuality = "recorded" | "rectified" | "untimed" | "partial";
3294
+ type CivilTimeSemantics = "utc-instant" | "civil-iana" | "civil-fixed-offset" | "local-mean-time";
3295
+ type CacheKeyChartDate = {
3296
+ kind: "utc";
3297
+ iso: string;
3298
+ } | {
3299
+ kind: "local";
3300
+ year: number;
3301
+ month: number;
3302
+ day: number;
3303
+ hour: number;
3304
+ minute: number;
3305
+ second: number;
3306
+ };
3307
+ interface CacheEphemerisIdentity {
3308
+ /** "swiss" | "moshier" | "jpl" (as reported by Swiss Ephemeris) or "none" for ephemeris-free math. */
3309
+ kind: string;
3310
+ /** Swiss Ephemeris version when known, else null. */
3311
+ swissEphemerisVersion: string | null;
3312
+ /** Free-form data-set identity (for example the file set); null when not tracked. */
3313
+ dataSet: string | null;
3314
+ }
3315
+ interface ChartCacheKeyComponents {
3316
+ /** Normalised date (see `normalizeChartDate`). */
3317
+ date: CacheKeyChartDate;
3318
+ timeSemantics: CivilTimeSemantics;
3319
+ /** IANA zone used, or null when an explicit offset / UTC was used. */
3320
+ timeZone: string | null;
3321
+ /** Offset in minutes (east positive) that was actually applied; null only for `utc-instant`. */
3322
+ resolvedUtcOffsetMinutes: number | null;
3323
+ latitude: number;
3324
+ longitude: number;
3325
+ quality: CacheInputQuality;
3326
+ /** House system codes ("P", "W", ...); treated as a set. Empty array = houses not computed. */
3327
+ houseSystems: readonly string[];
3328
+ /** Point selection (chart point keys); treated as a set. */
3329
+ points: readonly string[];
3330
+ /** Orb policy object or identifier; use `null` only for "no aspects computed". */
3331
+ orbPolicy: unknown;
3332
+ /** Zodiac / nakshatra frame: "tropical" | "lahiri" | "dhruva" | other identifier. */
3333
+ frame: string;
3334
+ nodeConvention: "mean" | "true" | null;
3335
+ yearLengthDays: number | null;
3336
+ /** Dhruva GC constants (or null when not applicable). */
3337
+ gcConstants: unknown;
3338
+ ephemeris: CacheEphemerisIdentity;
3339
+ /** Defaults to this package's version; override only to key by a different producer. */
3340
+ packageVersion?: string;
3341
+ /** Any other configuration that can change the result. */
3342
+ extra?: Record<string, unknown>;
3343
+ }
3344
+ /** Names of the components `buildChartCacheKey` requires (explicit `null` is allowed where documented). */
3345
+ declare const CHART_CACHE_KEY_REQUIRED_COMPONENTS: readonly string[];
3346
+ declare const PACKAGE_VERSION: string;
3347
+ /**
3348
+ * Normalise a `BirthChartOptions.date` to its canonical key form. A `Date` is read with local
3349
+ * getters (the same convention `getBirthChart` uses), so the key matches the calculation.
3350
+ */
3351
+ declare function normalizeChartDate(date: Date | LocalDateTimeParts): CacheKeyChartDate;
3352
+ /** Canonical form of an already-UTC instant. */
3353
+ declare function normalizeUtcInstant(instant: Date | string): CacheKeyChartDate;
3354
+ /**
3355
+ * Offset (minutes, east positive) between local wall-clock parts and the UTC instant they
3356
+ * resolved to, for example `resolveUtcOffsetMinutes(localParts, chart.dateUtc)`.
3357
+ */
3358
+ declare function resolveUtcOffsetMinutes(local: LocalDateTimeParts, dateUtc: Date): number;
3359
+ /** Ephemeris identity read from the running engine (pass `getSwissEphInfo()`); `kind` falls back to "unknown". */
3360
+ declare function ephemerisIdentityFromInfo(info: {
3361
+ probe: {
3362
+ ephemeris: string | null;
3363
+ } | null;
3364
+ swissEphemerisVersion: string | null;
3365
+ ephemerisFiles: {
3366
+ found: string[];
3367
+ };
3368
+ }): CacheEphemerisIdentity;
3369
+ /**
3370
+ * Build the cache key for a chart-level result. Throws `CacheKeyError("MISSING_COMPONENT")`
3371
+ * when any required component is `undefined`.
3372
+ */
3373
+ declare function buildChartCacheKey(components: ChartCacheKeyComponents): string;
3374
+ interface BoundedMemoOptions {
3375
+ /** Maximum number of entries (>= 1). Least recently used entries are evicted first. */
3376
+ maxEntries: number;
3377
+ }
3378
+ interface BoundedMemoStats {
3379
+ size: number;
3380
+ maxEntries: number;
3381
+ hits: number;
3382
+ misses: number;
3383
+ evictions: number;
3384
+ }
3385
+ interface BoundedMemo<T> {
3386
+ get(key: string): T | undefined;
3387
+ has(key: string): boolean;
3388
+ set(key: string, value: T): void;
3389
+ /** Return the cached value or compute, store and return it. Concurrent calls share one computation; failures are not cached. */
3390
+ getOrCompute(key: string, compute: () => T | Promise<T>): T | Promise<T>;
3391
+ delete(key: string): boolean;
3392
+ clear(): void;
3393
+ readonly size: number;
3394
+ stats(): BoundedMemoStats;
3395
+ }
3396
+ /**
3397
+ * Small LRU memo keyed by strings from `buildChartCacheKey`. Because keys embed the full
3398
+ * configuration, two incompatible configurations can never share an entry.
3399
+ */
3400
+ declare function createBoundedMemo<T>(options: BoundedMemoOptions): BoundedMemo<T>;
3401
+
3402
+ /**
3403
+ * Capability discovery: a versioned, JSON-serialisable description of what this build of
3404
+ * kaabalah can compute, with the limits it enforces. Lets callers (and agents) check support
3405
+ * instead of inspecting bundles or catching failures.
3406
+ *
3407
+ * `getCapabilities()` never throws and never initialises the engine; ephemeris coverage is
3408
+ * taken from `getSwissEphInfo()` when the engine is initialised and otherwise reported as the
3409
+ * static shipped range, flagged `source: "static"`.
3410
+ *
3411
+ * `assertEphemerisReady()` turns a missing runtime or missing data into an actionable
3412
+ * `SwissEphError` (existing codes; no competing error hierarchy).
3413
+ */
3414
+
3415
+ declare const CAPABILITIES_SCHEMA_VERSION = 1;
3416
+ declare const KAABALAH_MODULES: readonly ["core", "numerology", "astrology", "gematria", "tarot", "iching", "ifa", "semantic", "visual"];
3417
+ declare const INPUT_QUALITY_KINDS: readonly [{
3418
+ readonly id: "recorded";
3419
+ readonly timed: true;
3420
+ readonly description: "Birth time recorded by a source; angles, houses and Moon degree are used.";
3421
+ }, {
3422
+ readonly id: "rectified";
3423
+ readonly timed: true;
3424
+ readonly description: "Birth time derived by rectification; angles are marked and may be excluded by analysis selectors.";
3425
+ }, {
3426
+ readonly id: "untimed";
3427
+ readonly timed: false;
3428
+ readonly description: "Birth time unknown; noon positions are placeholders; Moon degree, angles, houses and lots are withheld.";
3429
+ }, {
3430
+ readonly id: "partial";
3431
+ readonly timed: false;
3432
+ readonly description: "Date or time only partly known; treated like untimed for time-dependent points.";
3433
+ }];
3434
+ interface CapabilityPoint {
3435
+ /** Key used in `BirthChart.planets` (lower-cased display name). */
3436
+ key: string;
3437
+ name: string;
3438
+ swissId: number | null;
3439
+ }
3440
+ interface Capabilities {
3441
+ schemaVersion: number;
3442
+ kind: "kaabalah-capabilities";
3443
+ packageVersion: string;
3444
+ modules: string[];
3445
+ astrology: {
3446
+ houseSystems: {
3447
+ id: string;
3448
+ name: string;
3449
+ }[];
3450
+ /** Points available from the ephemeris (chart planets/nodes/asteroids) plus derived chart angles. */
3451
+ points: CapabilityPoint[];
3452
+ derivedPoints: string[];
3453
+ virtualPoints: string[];
3454
+ aspects: {
3455
+ name: string;
3456
+ angle: number;
3457
+ defaultOrb: number;
3458
+ }[];
3459
+ zodiacFrames: {
3460
+ id: "tropical" | "lahiri" | "dhruva";
3461
+ kind: "zodiac" | "nakshatra";
3462
+ description: string;
3463
+ }[];
3464
+ nodeConventions: ("mean" | "true")[];
3465
+ defaults: {
3466
+ houseSystem: string;
3467
+ nodeConvention: "mean" | "true";
3468
+ nakshatraFrame: "dhruva" | "lahiri";
3469
+ yearLengthDays: {
3470
+ dhruva: number;
3471
+ lahiri: number;
3472
+ };
3473
+ };
3474
+ gcConstants: {
3475
+ dhruva: Record<string, number>;
3476
+ };
3477
+ methods: {
3478
+ jyotish: string;
3479
+ collection: string;
3480
+ cacheKey: number;
3481
+ };
3482
+ inputQualities: {
3483
+ id: string;
3484
+ timed: boolean;
3485
+ description: string;
3486
+ }[];
3487
+ ephemeris: {
3488
+ initialized: boolean;
3489
+ /** "runtime" when read from the initialised engine, "static" when only the shipped range is known. */
3490
+ coverageSource: "runtime" | "static";
3491
+ coverage: {
3492
+ fromYear: number;
3493
+ toYearExclusive: number;
3494
+ note: string;
3495
+ };
3496
+ requiredFiles: string[];
3497
+ missingFiles: string[];
3498
+ swissEphemerisVersion: string | null;
3499
+ strictEphemeris: boolean;
3500
+ substitutionNote: string;
3501
+ };
3502
+ };
3503
+ numerology: {
3504
+ methodVersion: string;
3505
+ layers: string[];
3506
+ lifePathMethods: LifePathMethod[];
3507
+ masterPolicies: MasterPolicy[];
3508
+ shortMonthPolicies: ShortMonthPolicy[];
3509
+ };
3510
+ limits: {
3511
+ collection: {
3512
+ maxPeople: number;
3513
+ maxEvents: number;
3514
+ maxPairs: number;
3515
+ maxConcurrency: number;
3516
+ };
3517
+ numerology: {
3518
+ maxScheduleYear: number;
3519
+ maxTimelineRangeDays: number;
3520
+ maxTimelineIntervals: number;
3521
+ maxCandidateDates: number;
3522
+ };
3523
+ };
3524
+ errors: {
3525
+ swissEph: string[];
3526
+ collection: string[];
3527
+ cacheKey: string[];
3528
+ };
3529
+ }
3530
+ /** Describe what this build supports. Pure and cheap; the result is a fresh JSON-serialisable object. */
3531
+ declare function getCapabilities(): Capabilities;
3532
+ interface EphemerisReadinessOptions {
3533
+ /** Require coverage of this civil year (Swiss files cover [fromYear, toYearExclusive)). */
3534
+ year?: number;
3535
+ }
3536
+ /**
3537
+ * Throw an actionable `SwissEphError` unless the engine is initialised, the required
3538
+ * ephemeris files are visible and (optionally) the requested year is covered.
3539
+ */
3540
+ declare function assertEphemerisReady(options?: EphemerisReadinessOptions): void;
3541
+
3542
+ /** Names used by astrology calculations, including dignity, sect and lunar nodes. */
3543
+ declare const ASTROLOGY_LABELS: Readonly<Record<string, Readonly<{
3544
+ en: string;
3545
+ pt: string;
3546
+ }>>>;
3547
+ /**
3548
+ * Display a sign, planet, node, dignity, sect, aspect or decan card name in the requested language.
3549
+ * English is the default. Calculation identifiers remain unchanged. Unknown names pass through.
3550
+ */
3551
+ declare function getAstrologyLabel(label: string, language?: string): string;
3552
+
3553
+ /**
3554
+ * Astrological calculations using Swiss Ephemeris
3555
+ */
3556
+
3557
+ interface BirthChartOptions {
3558
+ /**
3559
+ * Local civil date-time for the chart moment.
3560
+ * Prefer `LocalDateTimeParts` when the source data comes from separate
3561
+ * date/time inputs so callers do not have to encode wall-clock parts into a
3562
+ * browser-local `Date`.
3563
+ */
3564
+ date: Date | LocalDateTimeParts;
3565
+ latitude: number;
3566
+ longitude: number;
3567
+ houseSystem?: HouseSystem;
3568
+ /**
3569
+ * OPT-IN substitute used only when the requested house system cannot be computed at this
3570
+ * latitude (Placidus and Koch are undefined beyond the polar circle, |latitude| >= ~66.56).
3571
+ * Default: off, and `getBirthChart` then throws a `SwissEphError` with code
3572
+ * `SWISSEPH_HOUSES_UNAVAILABLE`. When a substitution happens it is never silent:
3573
+ * `BirthChart.houseSystem` is the system actually used and
3574
+ * `BirthChart.houseSystemSubstitution` records the request, the reason and a notice.
3575
+ */
3576
+ houseSystemFallback?: HouseSystemFallback;
3577
+ timeZoneSettings?: TimeZoneOptions;
3578
+ }
3579
+ /** Latitude-independent house systems accepted as an explicit fallback. */
3580
+ type HouseSystemFallback = "whole-sign" | "equal" | "porphyry";
3581
+ /** Recorded on a chart when `houseSystemFallback` replaced the requested house system. */
3582
+ interface HouseSystemSubstitution {
3583
+ requested: HouseSystem;
3584
+ used: HouseSystem;
3585
+ latitude: number;
3586
+ reason: string;
3587
+ notice: string;
3588
+ }
3589
+ /**
3590
+ * Decide the fallback for a failed house computation. Returns undefined when no fallback is
3591
+ * configured or the error is not a "house system unavailable" error (the caller rethrows).
3592
+ */
3593
+ declare function planHouseSystemFallback(requested: HouseSystem, fallback: HouseSystemFallback | undefined, latitude: number, error: unknown): HouseSystemSubstitution | undefined;
3594
+ type ZodiacPosition = {
3595
+ sign: string;
3596
+ decimalDegrees: number;
3597
+ traditionalFormat: string;
3598
+ decimal: string;
3599
+ longitude: number;
3600
+ house: number;
3601
+ };
3602
+ type HydratedNode = ZodiacPosition & {
3603
+ id: VirtualNodes;
3604
+ name: string;
3605
+ };
3606
+ type HydratedPlanet = PlanetPosition & {
3607
+ id: Planet;
3608
+ name: string;
3609
+ zodiacPosition: ZodiacPosition;
3610
+ };
3611
+ type Sect = "diurnal" | "nocturnal";
3612
+ interface BirthChart {
3613
+ dateUtc: Date;
3614
+ /** House system the cusps were computed with (set by `getBirthChart`; optional for hand-built fixtures). */
3615
+ houseSystem?: HouseSystem;
3616
+ /** Present only when `houseSystemFallback` replaced the requested system (never a silent substitution). */
3617
+ houseSystemSubstitution?: HouseSystemSubstitution;
3618
+ planets: Record<string, HydratedPlanet>;
3619
+ nodes: Record<string, HydratedNode>;
3620
+ houses: {
3621
+ ascendant: ZodiacPosition;
3622
+ mc: ZodiacPosition;
3623
+ dc: ZodiacPosition;
3624
+ ic: ZodiacPosition;
3625
+ houses: ZodiacPosition[];
3626
+ ascmc?: {
3627
+ armc?: ZodiacPosition;
3628
+ vertex?: ZodiacPosition;
3629
+ equasc?: ZodiacPosition;
3630
+ coasc1?: ZodiacPosition;
3631
+ coasc2?: ZodiacPosition;
3632
+ polasc?: ZodiacPosition;
3633
+ };
3634
+ };
3635
+ aspects: AspectEdge[];
3636
+ /** Diurnal/nocturnal from the Sun's geometric altitude (independent of house system). */
3637
+ sect: Sect;
3638
+ /** Sun altitudes and the exact-horizon convention behind `sect` (always set by `getBirthChart`; optional so hand-built fixtures still type-check). */
3639
+ sectDetails?: SectResult;
3640
+ /** Lots of Fortune and Spirit (sect-reversed counterparts) with formulas used. */
3641
+ lots?: LotsResult & {
3642
+ fortunePosition: ZodiacPosition;
3643
+ spiritPosition: ZodiacPosition;
3644
+ };
3645
+ /** Sun-Moon elongation, phase name and illumination (labelled approximate). */
3646
+ moonPhase?: MoonPhaseResult;
3647
+ }
3648
+ /** Chart as returned by `getBirthChart`: the additive fields are always present. */
3649
+ type ComputedBirthChart = BirthChart & Required<Pick<BirthChart, "sectDetails" | "lots" | "moonPhase">>;
3650
+ /**
3651
+ * Determines chart sect from the Sun's house position.
3652
+ * Houses 7-12 place the Sun above the horizon.
3653
+ *
3654
+ * @deprecated House-based approximation: it is only right when the house
3655
+ * cusps follow the horizon (Placidus-like systems) and is wrong for
3656
+ * whole-sign and equal houses near sunrise/sunset. `getBirthChart` no longer
3657
+ * uses it; use `computeSect` / `getSectFromAltitude` (physical horizon).
3658
+ */
3659
+ declare function getSect(sunHouse: number): Sect;
3660
+ /**
3661
+ * Calculate a birth chart using Swiss Ephemeris
3662
+ *
3663
+ * @param options Chart calculation options
3664
+ * @returns Birth chart data
3665
+ */
3666
+ declare function getBirthChart(options: BirthChartOptions): Promise<ComputedBirthChart>;
3667
+ declare const SIGNS: readonly ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"];
3668
+ /**
3669
+ * Convert decimal degrees to degrees and minutes format
3670
+ *
3671
+ * @param decimalDegrees Decimal degrees (e.g., 9.8)
3672
+ * @returns Formatted string (e.g., "9°48'")
3673
+ */
3674
+ declare function formatDegreeMinutes(decimalDegrees: number): string;
3675
+ /**
3676
+ * Convert decimal degrees to zodiac position (sign and degrees)
3677
+ *
3678
+ * @param longitude Longitude in decimal degrees (0-360)
3679
+ * @returns Formatted zodiac position with both decimal and traditional format
3680
+ */
3681
+ declare function getZodiacPosition(longitude: number, houseCusps: number[]): ZodiacPosition;
3682
+ declare function findHouseOf(longitude: number, housePositions: number[]): number;
3683
+ interface TwoChartOptions {
3684
+ chartA: BirthChartOptions;
3685
+ chartB: BirthChartOptions;
3686
+ aspectSpecs?: AspectSpec[];
3687
+ /** Omit the embedded full charts from the result (see `SynastryChartSummary`). Default false. */
3688
+ omitCharts?: boolean;
3689
+ }
3690
+ type SynastryChartOptions = TwoChartOptions;
3691
+ type CompositeChartOptions = TwoChartOptions;
3692
+ /** Options for the already-computed-chart variants (`getSynastryFromCharts`, `getCompositeFromCharts`). */
3693
+ interface TwoChartFromChartsOptions {
3694
+ aspectSpecs?: AspectSpec[];
3695
+ /** Omit the embedded full charts from the result; the result then carries `charts` references only. */
3696
+ omitCharts?: boolean;
3697
+ /** Caller ids echoed into the lightweight `charts` references. */
3698
+ ids?: {
3699
+ a?: string;
3700
+ b?: string;
3701
+ };
3702
+ /**
3703
+ * House system of chart A / B. Only used when the chart does not record its own
3704
+ * (`BirthChart.houseSystem`); the chart's recorded value always wins.
3705
+ */
3706
+ houseSystemA?: HouseSystem;
3707
+ houseSystemB?: HouseSystem;
3708
+ }
3709
+ /** Metadata-only reference to a chart used in a two-chart result. */
3710
+ interface ChartReference {
3711
+ id?: string;
3712
+ dateUtc: Date;
3713
+ houseSystem?: HouseSystem;
3714
+ }
3715
+ interface SynastryChart {
3716
+ chartA: BirthChart;
3717
+ chartB: BirthChart;
3718
+ aspects: AspectEdge[];
3719
+ }
3720
+ /** Synastry result without the embedded charts (`omitCharts: true`). */
3721
+ interface SynastryChartSummary {
3722
+ charts: {
3723
+ a: ChartReference;
3724
+ b: ChartReference;
3725
+ };
3726
+ aspects: AspectEdge[];
3727
+ }
3728
+ interface CompositeChart {
3729
+ chartA: BirthChart;
3730
+ chartB: BirthChart;
3731
+ compositePlanets: Record<string, {
3732
+ name: string;
3733
+ longitude: number;
3734
+ zodiacPosition: ZodiacPosition;
3735
+ }>;
3736
+ compositeHouses: ZodiacPosition[];
3737
+ /** Composite ASC / MC / DSC / IC midpoint angles (see `./composite` conventions). */
3738
+ compositeAngles: Record<keyof CompositeAngles, ZodiacPosition>;
3739
+ /** Conventions used for midpoints, houses and the antipodal policy. */
3740
+ compositeMethod: CompositeMethod;
3741
+ /** Antipodal pairs, MC/cusp corrections and fallbacks encountered. */
3742
+ notices: CompositeNotice[];
3743
+ /** Aspects among `compositePlanets` only (the final point set). */
3744
+ aspects: AspectEdge[];
3745
+ /** House system of each input chart and where it came from. */
3746
+ houseSystems: {
3747
+ a: {
3748
+ system: HouseSystem;
3749
+ source: "chart" | "option" | "assumed-default";
3750
+ };
3751
+ b: {
3752
+ system: HouseSystem;
3753
+ source: "chart" | "option" | "assumed-default";
3754
+ };
3755
+ };
3756
+ }
3757
+ /** Composite result without the embedded charts (`omitCharts: true`). */
3758
+ type CompositeChartSummary = Omit<CompositeChart, "chartA" | "chartB"> & {
3759
+ charts: {
3760
+ a: ChartReference;
3761
+ b: ChartReference;
3762
+ };
3763
+ };
3764
+ declare function getSynastryFromCharts(chartA: BirthChart, chartB: BirthChart, options: TwoChartFromChartsOptions & {
3765
+ omitCharts: true;
3766
+ }): SynastryChartSummary;
3767
+ declare function getSynastryFromCharts(chartA: BirthChart, chartB: BirthChart, options?: TwoChartFromChartsOptions & {
3768
+ omitCharts?: false;
3769
+ }): SynastryChart;
3770
+ declare function getSynastryFromCharts(chartA: BirthChart, chartB: BirthChart, options?: TwoChartFromChartsOptions): SynastryChart | SynastryChartSummary;
3771
+ declare function getSynastryChart(options: SynastryChartOptions & {
3772
+ omitCharts: true;
3773
+ }): Promise<SynastryChartSummary>;
3774
+ declare function getSynastryChart(options: SynastryChartOptions & {
3775
+ omitCharts?: false;
3776
+ }): Promise<SynastryChart>;
3777
+ declare function getSynastryChart(options: SynastryChartOptions): Promise<SynastryChart | SynastryChartSummary>;
3778
+ declare function getCompositeFromCharts(chartA: BirthChart, chartB: BirthChart, options: TwoChartFromChartsOptions & {
3779
+ omitCharts: true;
3780
+ }): CompositeChartSummary;
3781
+ declare function getCompositeFromCharts(chartA: BirthChart, chartB: BirthChart, options?: TwoChartFromChartsOptions & {
3782
+ omitCharts?: false;
3783
+ }): CompositeChart;
3784
+ declare function getCompositeFromCharts(chartA: BirthChart, chartB: BirthChart, options?: TwoChartFromChartsOptions): CompositeChart | CompositeChartSummary;
3785
+ declare function getCompositeChart(options: CompositeChartOptions & {
3786
+ omitCharts: true;
3787
+ }): Promise<CompositeChartSummary>;
3788
+ declare function getCompositeChart(options: CompositeChartOptions & {
3789
+ omitCharts?: false;
3790
+ }): Promise<CompositeChart>;
3791
+ declare function getCompositeChart(options: CompositeChartOptions): Promise<CompositeChart | CompositeChartSummary>;
3792
+ interface TransitChartOptions {
3793
+ natal: BirthChartOptions;
3794
+ transitDate: Date;
3795
+ transitLatitude?: number;
3796
+ transitLongitude?: number;
3797
+ transitTimeZoneSettings?: TimeZoneOptions;
3798
+ aspectSpecs?: AspectSpec[];
3799
+ maxOrb?: number;
3800
+ transitPlanets?: string[];
3801
+ natalPlanets?: string[];
3802
+ aspectFilter?: AspectName[];
3803
+ }
3804
+ interface TransitPlanet extends HydratedPlanet {
3805
+ retrograde: boolean;
3806
+ natalHouse: number;
3807
+ }
3808
+ interface TransitChart {
3809
+ natalChart: BirthChart;
3810
+ transitDateUtc: Date;
3811
+ transitPlanets: Record<string, TransitPlanet>;
3812
+ aspects: TransitAspectEdge[];
3813
+ }
3814
+ interface TransitRangeOptions extends Omit<TransitChartOptions, "transitDate"> {
3815
+ /**
3816
+ * Window start. Two forms, both resolved to an absolute UTC instant (`TransitRangeResult.fromUtc`)
3817
+ * through `transitTimeZoneSettings` at the transit location (default: auto time zone from lat/lon):
3818
+ *
3819
+ * - `LocalDateTimeParts` (recommended): the wall-clock date/time at the transit location.
3820
+ * Independent of the host machine's time zone.
3821
+ * - `Date` (legacy, behaviour unchanged): read with the HOST-local getters
3822
+ * (`getFullYear()`, `getHours()`, ...) and reinterpreted as wall-clock time in the transit
3823
+ * location's zone, so the result depends on the host time zone. Pass
3824
+ * `transitTimeZoneSettings: { treatAsUTC: true }` to use the Date's own UTC instant instead.
3825
+ */
3826
+ from: Date | LocalDateTimeParts;
3827
+ /** Window end (inclusive); same two forms and semantics as `from`. */
3828
+ to: Date | LocalDateTimeParts;
3829
+ stepDays?: number;
3830
+ /** Final bracket width for each exact event, in seconds (default 0.001). */
3831
+ timeToleranceSeconds?: number;
3832
+ /** Max accepted angular residual of an exact event, in degrees (default 1e-6). */
3833
+ residualToleranceDegrees?: number;
3834
+ /** Also report stationary near-misses that never reach exactness (default false). */
3835
+ includeClosestApproaches?: boolean;
3836
+ }
3837
+ /**
3838
+ * A verified exact crossing of a transit aspect. `exactDate` is the UTC instant
3839
+ * of the root; `exactOrb` equals the angular residual (~0), not the display orb.
3840
+ */
3841
+ interface AspectPerfection {
3842
+ transitPlanet: string;
3843
+ natalPlanet: string;
3844
+ aspect: AspectName;
3845
+ exactDate: Date;
3846
+ exactOrb: number;
3847
+ retrograde: boolean;
3848
+ category: "slow" | "fast";
3849
+ kind?: "exact";
3850
+ exactJd?: number;
3851
+ solver?: PerfectionSolverMetadata;
3852
+ }
3853
+ interface TransitRangeResult {
3854
+ natalChart: BirthChart;
3855
+ /** The `from` Date as passed; for `LocalDateTimeParts` input it is the resolved UTC instant (= `fromUtc`). */
3856
+ from: Date;
3857
+ /** The `to` Date as passed; for `LocalDateTimeParts` input it is the resolved UTC instant (= `toUtc`). */
3858
+ to: Date;
3859
+ /** `from`/`to` resolved to absolute UTC instants (via the transit location's time zone settings). */
3860
+ fromUtc?: Date;
3861
+ toUtc?: Date;
3862
+ perfections: AspectPerfection[];
3863
+ /** Present only when `includeClosestApproaches` was requested. Never exact. */
3864
+ closestApproaches?: TransitClosestApproach[];
3865
+ }
3866
+ /**
3867
+ * Options for transits to an already-computed natal chart. A `BirthChart` does not
3868
+ * store its geographic location, so the transit location is explicit.
3869
+ */
3870
+ interface TransitFromChartOptions extends Omit<TransitChartOptions, "natal" | "transitLatitude" | "transitLongitude"> {
3871
+ transitLatitude: number;
3872
+ transitLongitude: number;
3873
+ /** House system for the transit chart; defaults to the natal chart's recorded system. */
3874
+ houseSystem?: HouseSystem;
3875
+ }
3876
+ declare function getTransitChart(options: TransitChartOptions): Promise<TransitChart>;
3877
+ /**
3878
+ * Transits over an already-computed natal chart (no natal recomputation). The
3879
+ * natal chart can be a natal `BirthChart` or any derived chart exposing the same
3880
+ * `planets` / `houses` shape. `getTransitChart` delegates here.
3881
+ */
3882
+ declare function getTransitChartFromChart(natalChart: BirthChart, options: TransitFromChartOptions): Promise<TransitChart>;
3883
+ declare function getTransitRange(options: TransitRangeOptions): Promise<TransitRangeResult>;
3884
+ interface SolarReturnOptions {
3885
+ natal: BirthChartOptions;
3886
+ /**
3887
+ * Which return: the calendar year of the natal LOCAL civil birthday. The solved return is the one
3888
+ * whose instant is nearest the UTC instant of that anniversary (the natal local civil date and
3889
+ * clock time moved to `year`, expressed with the natal zone's UTC offset). Consequently the
3890
+ * returned UTC instant can fall on Dec 31 of `year - 1` or Jan 1 of `year + 1` for births near
3891
+ * a year boundary or in extreme UTC offsets, but it is never the return of a neighbouring year.
3892
+ * For Feb 29 births in non-leap years the anniversary is Mar 1.
3893
+ */
3894
+ year: number;
644
3895
  solarReturnLatitude?: number;
645
3896
  solarReturnLongitude?: number;
646
3897
  solarReturnHouseSystem?: HouseSystem;
3898
+ /** Opt-in recorded house-system substitute for the return chart (defaults to `natal.houseSystemFallback`). */
3899
+ solarReturnHouseSystemFallback?: HouseSystemFallback;
3900
+ /** Final bracket width of the solved return instant, in seconds (default 0.001). */
3901
+ returnPrecisionSeconds?: number;
3902
+ /** Max accepted angular residual of the return, in degrees (default 1e-6). */
3903
+ residualToleranceDegrees?: number;
647
3904
  }
648
3905
  interface SolarReturnChart {
649
3906
  natalChart: BirthChart;
3907
+ /** Cast at the solved root's exact Julian Day (no sub-second truncation), so its Sun equals the natal Sun to ~1e-9 degrees. */
650
3908
  solarReturnChart: BirthChart;
3909
+ /** Verified UTC instant at which the Sun reaches its natal longitude. */
651
3910
  exactReturnDate: Date;
652
3911
  natalSunLongitude: number;
653
3912
  year: number;
3913
+ /** Julian Day (UT) of the solved return. */
3914
+ exactReturnJd?: number;
3915
+ /** Angular residual (degrees) of the Sun against the natal longitude at `exactReturnDate`'s solved root. */
3916
+ residualDegrees?: number;
3917
+ /** Final bracket width and tolerance, iterations, direction and coverage of the root search. */
3918
+ solver?: {
3919
+ bracketWidthSeconds: number;
3920
+ timeToleranceSeconds: number;
3921
+ iterations: number;
3922
+ direction: RootDirection;
3923
+ coverage: RootSearchCoverage;
3924
+ method: RootSolverMethodMetadata;
3925
+ };
654
3926
  }
655
3927
  /**
656
- * Calculate a Solar Return chart — the moment the transiting Sun returns
657
- * to its natal longitude in the given year.
3928
+ * Calculate a Solar Return chart: the moment the transiting Sun returns to its natal longitude
3929
+ * in the given `year` (see {@link SolarReturnOptions.year} for the exact convention).
3930
+ *
3931
+ * The search is centred on the natal birth instant moved to `year` (anchored on the natal UTC
3932
+ * instant, not on a UTC-noon calendar date), widened and retried if no crossing is bracketed.
658
3933
  */
659
3934
  declare function getSolarReturnChart(options: SolarReturnOptions): Promise<SolarReturnChart>;
660
3935
 
661
- export { ASTROCARTOGRAPHY_DEFAULT_PLANETS, ASTROLOGY_DESCRIPTIONS, ASTROLOGY_LABELS, type AngleType, type AnnualProfection, type AspectEdge, type AspectName, type AspectPerfection, type AspectSpec, type AstrocartographyHorizonLine, type AstrocartographyHorizonPoint, type AstrocartographyLineProximity, type AstrocartographyMap, type AstrocartographyMapOptions, type AstrocartographyMeridianLine, type AstrocartographyParan, type AstrocartographyQueryOptions, type AstrocartographyQueryResult, type AstrologyDescriptions, type AzaltResult, type BirthChart, type BirthChartOptions, CalcFlag, type CompositeChart, type CompositeChartOptions, DEFAULT_ASPECT_SPECS, DOMICILE_RULERS, type DecanResult, type DescriptionPlanet, type DodecatemoriaResult, EXALTATIONS, type EssentialDignityResult, type FirdariaMajorPeriod, type FirdariaOptions, type FirdariaPlanet, type FirdariaResult, type FirdariaSubPeriod, HouseSystem, type HydratedNode, type HydratedPlanet, type LocalDateTimeParts, type MonthlyProfection, type MonthlyProfectionsResult, PLANET_AND_NODE_NAMES, Planet, type PlanetEquatorial, type PlanetSignDescriptionEntry, type ResolveSwissEphRuntimeAssetsOptions, RiseTransitFlag, SIGNS, SLOW_PLANETS, type Sect, type Sign, type SolarReturnChart, type SolarReturnOptions, type SwissEphRuntimeAssetPaths, type SynastryChart, type SynastryChartOptions, type TraditionalPlanet, type TransitAspectEdge, type TransitAspectPoint, type TransitChart, type TransitChartOptions, type TransitPlanet, type TransitRangeOptions, type TransitRangeResult, type TwoChartOptions, VirtualNodes, type ZodiacPosition, closeSwissEph, computeAspects, computeAstrocartographyMap, computeEquatorialPositions, computeGMST, computeHorizonLongitude, computeICLongitude, computeMCLongitude, computeMidpoints, computeSynastryAspects, computeTransitAspects, findHouseOf, findParansAtLatitude, formatDegreeMinutes, geographicAngularDifference, getAnnualProfection, getAspectMatch, getAstrologyLabel, getBirthChart, getCompositeChart, getDecan, getDetriment, getDodecatemoria, getDomicileRuler, getEssentialDignity, getExaltation, getFall, getFirdaria, getMonthlyProfections, getOppositeSign, getPlanetSignDescription, getPlanetSignDescriptionEntry, getSect, getSolarReturnChart, getSwissEph, getSynastryChart, getTransitChart, getTransitRange, getZodiacPosition, normalizeAngle, queryAstrocartographyLocation, resolveSwissEphRuntimeAssets, shorterArcMidpoint };
3936
+ export { ANTIPODAL_POLICY_TEXT, ASPECT_CANONICAL_ANGLES, ASTROCARTOGRAPHY_DEFAULT_PLANETS, ASTROLOGY_DESCRIPTIONS, ASTROLOGY_LABELS, type ActiveDasha, type AnalysisSelection, type AngleType, type AngularClosestApproach, type AngularRoot, type AngularRootSearchOptions, type AngularRootSearchResult, type AnnualProfection, AspectConfigError, type AspectConfigErrorCode, type AspectCounts, type AspectEdge, type AspectMotion, type AspectMotionResult, type AspectName, type AspectPerfection, type AspectSpec, type AstrocartographyHorizonLine, type AstrocartographyHorizonPoint, type AstrocartographyLineProximity, type AstrocartographyMap, type AstrocartographyMapOptions, type AstrocartographyMeridianLine, type AstrocartographyParan, type AstrocartographyQueryOptions, type AstrocartographyQueryResult, type AstrologyDescriptions, type AxisAspectGroup, type AzaltResult, type BirthChart, type BirthChartOptions, type BodyCrossing, type BodyCrossingOptions, type BodyCrossingResult, type BodyLongitudeFunctions, type BodyLongitudeSample, type BodySignChange, type BoundSegment, type BoundedMemo, type BoundedMemoOptions, type BoundedMemoStats, CACHE_KEY_VERSION, CAPABILITIES_SCHEMA_VERSION, CHART_CACHE_KEY_REQUIRED_COMPONENTS, COLLECTION_HARD_LIMITS, COLLECTION_METHOD_VERSION, type CacheEphemerisIdentity, type CacheInputQuality, type CacheKeyChartDate, CacheKeyError, type CacheKeyErrorCode, CalcFlag, type Capabilities, type CapabilityPoint, type ChartAtJulianDayOptions, type ChartCacheKeyComponents, type ChartComputer, type ChartPoint, type ChartPointFlags, type ChartPointLike, type ChartPointsOptions, type ChartReference, type ChartUnavailableReason, type CivilTimeSemantics, CollectionAbortError, CollectionError, type CollectionErrorCode, type CollectionEventInput, type CollectionInputQuality, type CollectionLimits, type CollectionManifest, type CollectionOptions, type CollectionPersonInput, type CollectionProgress, type CollectionRecord, type CollectionResult, type CollectionSummary, type CompositeAngles, type CompositeChart, type CompositeChartOptions, type CompositeChartSummary, type CompositeCuspInput, type CompositeMethod, type CompositeMidpoint, type CompositeNotice, type ComputePolicyAspectsOptions, type ComputedBirthChart, DASHA_YEAR_LENGTH_REFERENCES, DEFAULT_ANTIPODAL_EPSILON, DEFAULT_ASPECT_SPECS, DEFAULT_CLASS_PRECEDENCE, DEFAULT_COLLECTION_CONCURRENCY, DEFAULT_EXACT_TOLERANCE_DEGREES, DEFAULT_RETURN_PASS_KINDS, DHRUVA_CONSTANTS, DIGNITY_TRADITION, DOMICILE_RULERS, DOROTHEAN_TRIPLICITY_RULERS, type DashaBalance, type DashaPeriod, type DashaSchedule, type DashaScheduleInput, type DashaSystem, type DavisonMethod, type DavisonNotice, type DavisonOptions, type DavisonPersonInput, type DavisonResult, type DecanResult, DerivedChartError, type DerivedChartErrorCode, type DescriptionHouseNumber, type DescriptionPlanet, type DhruvaChart, type DhruvaChartInput, type DhruvaConstants, type DhruvaOrigin, type DhruvaPoint, type DhruvaPointId, type DirectedPoint, type DodecatemoriaResult, EGYPTIAN_BOUNDS, EXALTATIONS, type EphemerisCheckOptions, type EphemerisReadinessOptions, EphemerisTracker, type EphemerisUsage, type EquatorialCoordinate, type EssentialDignitiesDetail, type EssentialDignityResult, type EventRecord, type EventRecordFailed, type EventRecordOk, FIRDARIA_CYCLE_YEARS, type FindTransitPerfectionsOptions, type FindTransitPerfectionsResult, type FirdariaMajorPeriod, type FirdariaOptions, type FirdariaPlanet, type FirdariaResult, type FirdariaSubPeriod, type FirdariaTimelineEntry, type FirdariaTimelineOptions, type FirdariaTimelineResult, type FirdariaTimelineSub, type GeocentricBodies, type GeocentricBody, type GeographicMidpoint, type GeographicMidpointConvention, type GetSwissEphOptions, type HouseDescriptionEntry, type HouseOverlayDirection, type HouseOverlayOptions, type HouseOverlayPlacement, type HouseOverlays, HouseSystem, type HouseSystemFailure, type HouseSystemFallback, type HouseSystemSubstitution, type HousesForSystemsDateInput, type HousesForSystemsInput, type HousesForSystemsJulianInput, type HousesForSystemsResult, type HydratedNode, type HydratedPlanet, INPUT_QUALITY_KINDS, type InputQuality, InputQualityError, type InputQualityErrorCode, type ItemError, JD_J2000, JULIAN_CENTURY_DAYS, JULIAN_YEAR_DAYS, JYOTISH_BODY_IDS, JYOTISH_METHODS, type JyotishBodyId, type JyotishChart, type JyotishChartInput, type JyotishEphemeris, KAABALAH_MODULES, KARAKA_ABBREVIATIONS_7, KARAKA_ABBREVIATIONS_8, KARAKA_NAMES_7, KARAKA_NAMES_8, KNOWN_ASPECT_NAMES, type KarakaBody, type KarakaDegreeFrame, type KarakaEntry, type KarakaInput, type KarakaOptions, type KarakaResult, type KarakaScheme, type LahiriChart, type LahiriChartInput, type LahiriPoint, type LahiriPointId, type LegacySource, type LocalDateTimeParts, type LotsResult, MAX_BODY_SCAN_STEP_DAYS, MAX_FIRDARIA_CYCLES, MAX_FIRDARIA_WINDOW_YEARS, MAX_PROFECTION_TIMELINE_YEARS, MAX_PROGRESSION_AGE_YEARS, MAX_RETURN_TIMELINE_PASSES, MAX_RETURN_TIMELINE_YEARS, MOON_PHASE_NAMES, type MonthlyProfection, type MonthlyProfectionsResult, type MoonDayRange, type MoonPhaseName, type MoonPhaseResult, type MotionUnavailableReason, NAIBOD_RATE_DEGREES_PER_YEAR, NAKSHATRA_IDS, NAKSHATRA_WIDTH_DEGREES, type NakshatraFrame, type NakshatraId, type NakshatraPlacement, type NatalLongitudeSource, type NodeConvention, ORB_POLICY_PROFILES, type OrbPolicy, type OrbPolicyMetadata, type OrbRuleSource, type OverlayChartLike, PACKAGE_VERSION, PADA_WIDTH_DEGREES, PLANET_AND_NODE_NAMES, POINT_CLASSES, POINT_DEFINITIONS, POINT_IDS, PROGRESSED_ANGLE_CONVENTIONS, PTOLEMAIC_PLUS_QUINCUNX, type PairComputation, type PairComputeContext, type PairComputer, type PairRecord, type PairRecordOk, type PairRecordUnavailable, type PairSelection, type PartialDateParts, type PerfectionSolverMetadata, type PersonRecord, type PersonRecordFailed, type PersonRecordOk, type PlaceRole, Planet, type PlanetEquatorial, type PlanetHouseDescriptionEntry, type PlanetPositionDetailed, type PlanetSignDescriptionEntry, type PlanetaryReturnOptions, type PlanetaryReturnResult, type PointClass, type PointDefinition, type PointId, type PolicyAspectEdge, type PolicyAspectResult, type PositiveDignity, type PreparedPerson, type ProfectionForAge, type ProfectionTimelineEntry, type ProfectionTimelineRange, type ProfectionTimelineResult, type ProgressedAngleConvention, type ProgressedAngles, type ProgressionMethodBase, type ProgressionOptions, type ProgressionTimeKey, type QualifiedChart, type QualifiedChartInput, ROOT_SEARCH_COVERAGE_NOTE, ROOT_SOLVER_METHOD, type ResolveSwissEphRuntimeAssetsOptions, type ResolvedOrb, type ReturnPassEntry, type ReturnPassKind, type ReturnTimelineOptions, type ReturnTimelineResult, RiseTransitFlag, type RootDirection, type RootSearchCoverage, type RootSolverMethodMetadata, SIGNS, SIGN_ELEMENTS, SLOW_PLANETS, type SecondaryProgressionMethod, type SecondaryProgressionOptions, type SecondaryProgressionResult, type Sect, type SectAltitudeBasis, type SectOptions, type SectResult, type Sign, type SignIngress, type SignName, type SignPlacement, type SolarArcMethod, type SolarArcOptions, type SolarArcResult, type SolarReturnChart, type SolarReturnOptions, SwissEphEphemerisMismatchError, SwissEphError, type SwissEphErrorCode, type SwissEphInfo, type SwissEphRuntimeAssetPaths, type SwissEphemerisKind, type SynastryChart, type SynastryChartOptions, type SynastryChartSummary, type SystemHouses, TROPICAL_SIGNS, TROPICAL_YEAR_DAYS, TT_MINUS_TAI_SECONDS, type TimeBasis, type TimeProvenance, TimelineError, type TimelineErrorCode, type TraditionalPlanet, type TransitAspectEdge, type TransitAspectPoint, type TransitChart, type TransitChartOptions, type TransitClosestApproach, type TransitFromChartOptions, type TransitPerfectionEvent, type TransitPlanet, type TransitRangeOptions, type TransitRangeResult, type TriplicityElement, type TriplicityRole, type TwoChartFromChartsOptions, type TwoChartOptions, type UnavailableItem, VIMSHOTTARI_LORDS, VIMSHOTTARI_YEARS, type VimshottariLord, VirtualNodes, YOGINI_LORDS, YOGINI_YEARS, type YearLengthSpec, ZODIAC_SIGN_KEYS, type ZodiacPosition, type ZodiacSignKey, anglesFromArmc, assertEphemerisReady, buildChartCacheKey, calcLotOfFortune, calcLotOfSpirit, calculateCharaKarakas, calculateDhruvaChart, calculateLahiriAyanamsa, calculateLahiriChart, calculatePlanetPositionDetailed, calculateSiderealPositions, canonicalJson, chartPointsFromPlanetPositions, closeSwissEph, compositeMidpoint, computeAspects, computeAspectsBetweenSetsWithPolicy, computeAspectsWithPolicy, computeAstrocartographyMap, computeCollection, computeCompositeAngles, computeCompositeCusps, computeEquatorialPositions, computeGMST, computeHorizonLongitude, computeICLongitude, computeLots, computeMCLongitude, computeMidpoints, computeMoonPhase, computeSect, computeSynastryAspects, computeTransitAspects, computeTransitAspectsWithPolicy, countAspects, createBodyLongitudeFunctions, createBoundedMemo, cuspsStrictlyIncreasing, dateToJd, dateToJulianDay, defaultPairComputer, defineOrbPolicy, derivedChartAspectPoints, describeOrbPolicy, dhruvaKetuFromRahu, dhruvaLagnaFromAscendant, dhruvaPlacementFromRightAscension, dhruvaPointFromBody, ecliptic0ToDeclination, ecliptic0ToRightAscension, ephemerisFromFlags, ephemerisIdentityFromInfo, findActiveDasha, findAngularRoots, findBodyLongitudeCrossings, findBodyLongitudeCrossingsWith, findHouseOf, findJupiterReturns, findLunarReturns, findNodalReturns, findParansAtLatitude, findPlanetaryReturns, findSaturnReturns, findSolarReturns, findTransitPerfections, findUranusOppositions, formatDegreeMinutes, generateDashaSchedule, generateVimshottariDasha, generateYoginiDasha, geographicAngularDifference, geographicMidpoint, getAnnualProfection, getAnnualProfectionTimeline, getAspectMatch, getAspectMotion, getAstrologyLabel, getBirthChart, getCapabilities, getChartAtJulianDay, getChartPoints, getCompositeChart, getCompositeFromCharts, getDavisonChart, getDavisonChartFromOptions, getDecan, getDetriment, getDhruvaOrigin, getDodecatemoria, getDomicileRuler, getDorotheanTriplicity, getEgyptianBound, getEligiblePairPoints, getEssentialDignities, getEssentialDignity, getExaltation, getFaceRuler, getFall, getFirdaria, getFirdariaPeriods, getFirdariaTimeline, getHouseDescription, getHouseDescriptionEntry, getHouseOverlays, getHousesForSystems, getJyotishChart, getMonthlyProfections, getMoonSignRange, getOppositeSign, getPlanetHouseDescription, getPlanetHouseDescriptionEntry, getPlanetSignDescription, getPlanetSignDescriptionEntry, getPointDefinition, getProfectionForAge, getQualifiedChart, getReturnPassTimeline, getSecondaryProgressions, getSect, getSectFromAltitude, getSignChangesBetween, getSolarArcDirections, getSolarReturnChart, getSwissEph, getSwissEphInfo, getSynastryChart, getSynastryFromCharts, getTransitChart, getTransitChartFromChart, getTransitRange, getZodiacPosition, groupAspectsByAxis, icrsToFk5J2000Matrix, icrsToFk5OfDate, isPointId, iterateCollection, jdToDate, julianDayToDate, legacyKeyFromPointId, mergeEphemerisUsage, nakshatraFromPosition, normalizeAngle, normalizeChartDate, normalizeDegrees, normalizeKeyNumber, normalizeUtcInstant, planHouseSystemFallback, pointIdFromLegacyKey, precessionMatrixJ2000ToDate, queryAstrocartographyLocation, resolveOrbLimit, resolveSwissEphRuntimeAssets, resolveSwissEphRuntimeAssetsAsync, resolveTimeProvenance, resolveUtcOffsetMinutes, sampleBodyAtJd, selectAnalysisPoints, setSwissEphStrictEphemeris, shorterArcMidpoint, signPlacement, signedAngleBetween, signedAngleDifference, sortTightContacts, taiMinusUtcSeconds, toLegacyPointRecord, utcJdToTtJd, validateAspectSpecs, validateOrbPolicy, wholeSignHouseOf, withSwissEphState };