caelus 0.17.0 → 0.18.0

package/README.md

@@ -5,7 +5,7 @@ ephemeris files. 1:1 port of the Python reference, checked by golden fixtures.
 
 ## Verification chain
 
-1. Python engine checked against Swiss Ephemeris 2.10 across 1900–2099:
+1. Python engine checked against Swiss Ephemeris 2.10 across 1850–2150:
    every planet ≤ 1″ (Sun–Saturn), Moon ≤ 2.5″, Chiron ≤ 1″, mean node ≤ 1″,
    true node ≤ 1′ vs SE's built-in ephemeris (≤ 1″ vs JPL DE431)
    (vs full DE431 files, 1850–2149), angles and Placidus cusps ≤ 3.2″ — all
@@ -100,4 +100,4 @@ test/golden.test.ts  conformance suite vs Python fixtures
 - caelus — this package
 - [caelus-birth](https://www.npmjs.com/package/caelus-birth) — local birth time + place → UT (charts take UT; use this)
 - [caelus-wheel](https://www.npmjs.com/package/caelus-wheel) — React SVG chart wheel
-- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, twenty-seven chart tools over stdio
+- [caelus-mcp](https://www.npmjs.com/package/caelus-mcp) — MCP server, twenty-nine chart tools over stdio

package/accuracy.json

@@ -1,11 +1,11 @@
 {
-  "basis": "Swiss Ephemeris 2.10, 1900-2099, apparent geocentric ecliptic longitude (true equinox of date)",
-  "range": "1900-2099",
+  "basis": "Swiss Ephemeris 2.10, 1850-2150, apparent geocentric ecliptic longitude (true equinox of date)",
+  "range": "1850-2150",
   "unit": "arcsec",
   "bodies": [
     {
       "name": "Sun",
-      "max": "0.4",
+      "max": "0.5",
       "rms": "0.2",
       "note": ""
     },
@@ -23,7 +23,7 @@
     },
     {
       "name": "Mercury",
-      "max": "0.5",
+      "max": "0.6",
       "rms": "0.2",
       "note": ""
     },
@@ -47,7 +47,7 @@
     },
     {
       "name": "Saturn",
-      "max": "0.8",
+      "max": "1.0",
       "rms": "0.4",
       "note": ""
     },
@@ -65,9 +65,9 @@
     },
     {
       "name": "Pluto",
-      "max": "2.5",
+      "max": "3.4",
       "rms": "1.0",
-      "note": "series valid 1885-2099"
+      "note": "JPL Horizons barycenter Chebyshev pack (1700-2212, fit residual 4.1e-6 AU ≈ 0.03″); supersedes the Meeus ch.37 series. Bound is vs SE's own Moshier Pluto"
     },
     {
       "name": "Chiron",
@@ -101,7 +101,7 @@
     },
     {
       "name": "Mean Lilith",
-      "max": "1.3",
+      "max": "1.6",
       "rms": "0.5",
       "note": "mean lunar apogee on the inclined orbit; latitude ≤0.1″"
     },
@@ -113,13 +113,13 @@
     },
     {
       "name": "RA / Dec",
-      "max": "2.1",
+      "max": "2.6",
       "rms": "—",
       "note": "rotation is exact; bound tracks each body's ecliptic accuracy (Moon worst)"
     },
     {
       "name": "Topocentric Moon",
-      "max": "2.5",
+      "max": "2.7",
       "rms": "—",
       "note": "parallax model adds ≤0.1″ over the geocentric bound"
     },
@@ -161,7 +161,7 @@
     },
     {
       "name": "True Lilith (osc. apogee)",
-      "max": "187",
+      "max": "214",
       "rms": "—",
       "note": "hypersensitive to the lunar theory (~1/e amplification); SE's own Moshier-vs-DE difference dominates. 'True Lilith' values disagree across software at this scale"
     },
@@ -221,7 +221,7 @@
     },
     {
       "label": "Pluto / Chiron",
-      "bound": "≤ 2.5″ / ≤ 1″"
+      "bound": "≤ 3.4″ / ≤ 1″"
     },
     {
       "label": "Angles & Placidus cusps",
@@ -233,7 +233,7 @@
     },
     {
       "label": "Mean Lilith",
-      "bound": "≤ 1.3″"
+      "bound": "≤ 1.6″"
     },
     {
       "label": "8 new house systems",
@@ -268,12 +268,12 @@
       "bound": "types exact; max ≤ 9 s"
     }
   ],
-  "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode)",
+  "v03_harness": "python/validate_swiss.py regenerates every figure above the line against pyswisseph 2.10 (Moshier mode), sampled over 1850-2150; validate_horizons.py cross-checks the edges (banded 1800/2200) against JPL directly",
   "true_node_vs_builtin": "1′",
   "counts": {
     "house_systems": 12,
     "sidereal_ayanamsas": 7,
-    "mcp_tools": 27,
+    "mcp_tools": 29,
     "default_bodies": 13
   }
 }

package/dist/src/anchored.d.ts

@@ -0,0 +1,49 @@
+/**
+ * astroengine anchored charts -- realize a {@link Realm} + anchors into a chart.
+ *
+ * This is where the provenance layer meets the two generators. Given what a
+ * chart *is* and how its time/place are anchored, {@link realize} routes:
+ * when an instant can be resolved it runs the ephemeris (`chartAt`); when it
+ * cannot but constraints are supplied it runs the compiler's symbolic synthesis
+ * (`compileForm`); otherwise it reports that nothing could be computed and why.
+ * The realm rides along as framing for the interpretation layer.
+ */
+import { Engine, Chart, ChartOptions } from "./chart.js";
+import { CompiledForm, Constraint } from "./compiler.js";
+import { Realm, TemporalAnchor, SpatialAnchor, AnchorRegistry, ResolvedTime, ResolvedPlace } from "./provenance.js";
+/** A chart described by its realm and anchors, not a bare (instant, place). */
+export interface AnchoredChart {
+    realm: Realm;
+    when: TemporalAnchor;
+    where?: SpatialAnchor;
+    /** Constraints for the compiler path -- a chart with no instant
+     *  (archetypal / conceptual / symbolic). */
+    constraints?: Constraint[];
+}
+/** The outcome of {@link realize}: how (or whether) a chart was produced. */
+export interface RealizedChart {
+    realm: Realm;
+    /** `ephemeris` (an instant resolved), `compiler` (synthesized from
+     *  constraints), or `none` (neither was possible). */
+    via: "ephemeris" | "compiler" | "none";
+    time: ResolvedTime;
+    place: ResolvedPlace;
+    /** The computed chart, when an instant was available. */
+    chart: Chart | null;
+    /** The synthesized form, when the compiler path ran. */
+    form: CompiledForm | null;
+    note: string;
+}
+/**
+ * Realize an {@link AnchoredChart}: resolve its anchors and run the appropriate
+ * generator. A resolvable instant always wins (the realm is then just framing);
+ * failing that, constraints synthesize a form; failing both, nothing computes.
+ *
+ * @param engine The engine for the ephemeris path.
+ * @param anchored The realm + temporal/spatial anchors (+ optional constraints).
+ * @param registry Lookups for relative/narrative/named anchors.
+ * @param opts Chart options (house system, zodiac) for the ephemeris path.
+ * @returns A {@link RealizedChart}; `chart`/`form` are null on the paths that
+ *   did not run.
+ */
+export declare function realize(engine: Engine, anchored: AnchoredChart, registry?: AnchorRegistry, opts?: ChartOptions): RealizedChart;

package/dist/src/anchored.js

@@ -0,0 +1,40 @@
+import { compileForm } from "./compiler.js";
+import { resolveTime, resolvePlace, isTimeAnchored, } from "./provenance.js";
+/**
+ * Realize an {@link AnchoredChart}: resolve its anchors and run the appropriate
+ * generator. A resolvable instant always wins (the realm is then just framing);
+ * failing that, constraints synthesize a form; failing both, nothing computes.
+ *
+ * @param engine The engine for the ephemeris path.
+ * @param anchored The realm + temporal/spatial anchors (+ optional constraints).
+ * @param registry Lookups for relative/narrative/named anchors.
+ * @param opts Chart options (house system, zodiac) for the ephemeris path.
+ * @returns A {@link RealizedChart}; `chart`/`form` are null on the paths that
+ *   did not run.
+ */
+export function realize(engine, anchored, registry = {}, opts = {}) {
+    const time = resolveTime(anchored.when, registry);
+    const place = resolvePlace(anchored.where ?? { kind: "none", reason: "intentionally_unset" }, registry);
+    const base = { realm: anchored.realm, time, place };
+    if (time.jd !== null) {
+        const chart = engine.chartAt(time.jd, place.place?.lat ?? 0, place.place?.lonEast ?? 0, opts);
+        return {
+            ...base, via: "ephemeris", chart, form: null,
+            note: `ephemeris (${time.certainty}) `
+                + (place.place ? `at ${place.note ?? "given coordinates"}` : "no place; houses nominal at 0,0"),
+        };
+    }
+    if (anchored.constraints?.length) {
+        const form = compileForm(anchored.constraints);
+        return {
+            ...base, via: "compiler", chart: null, form,
+            note: `compiler synthesis (${form.impossible ? "impossible form" : `residual ${form.residual.toFixed(2)}`})`,
+        };
+    }
+    return {
+        ...base, via: "none", chart: null, form: null,
+        note: isTimeAnchored(anchored.realm)
+            ? `time-anchored realm but no instant resolved (${time.note ?? "no time"}); supply a resolvable anchor or constraints`
+            : `${anchored.realm} realm has no instant; supply constraints to synthesize a form`,
+    };
+}

package/dist/src/astrocartography.js

@@ -24,10 +24,15 @@ export function planetLines(ra, dec, gastDeg, latMin = -85.0, latMax = 85.0, lat
     const asc = [];
     const dsc = [];
     const n = Math.floor((latMax - latMin) / latStep + 1e-9); // never exceed latMax
+    // Skip the degenerate near-tangent point where |x| -> 1 (h0 -> 0 or 180): the
+    // body grazes the horizon at the meridian, acos' is singular there, and
+    // cross-platform libm rounding would swing the longitude by ~mas. Trimming it
+    // costs <0.003 deg of line length and makes the track deterministic.
+    const EDGE = 1.0 - 1e-9;
     for (let i = 0; i <= n; i++) {
         const phi = latMin + i * latStep;
         const x = -Math.tan(phi * DEG) * td;
-        if (x >= -1.0 && x <= 1.0) {
+        if (x >= -EDGE && x <= EDGE) {
             const h0 = Math.acos(x) / DEG; // hour-angle half-width, degrees
             asc.push([mapLon(ra - h0 - gastDeg), phi]); // eastern horizon
             dsc.push([mapLon(ra + h0 - gastDeg), phi]); // western horizon

package/dist/src/brief.d.ts

@@ -0,0 +1,90 @@
+/**
+ * astroengine interpretation brief -- a chart as compact, citable LLM input,
+ * and an audit that the model cited real facts.
+ *
+ * This is the "novel and accurate" seam. An LLM writes fluent, original prose
+ * (novel); to keep it honest (accurate) it is given only the validated fact
+ * atoms, each tagged with a stable id, and asked to cite the id(s) every
+ * statement rests on. {@link auditCitations} then checks those citations
+ * resolve -- a claim that cites an id not in the brief invented its provenance
+ * and is flagged. The chart math was never the model's to hallucinate.
+ *
+ * Pairs with the MCP app, where the host model is already the interpreter:
+ * feed it {@link Brief.prompt} instead of raw positions it would guess at.
+ */
+import type { FactKind, InterpretationContext } from "./interpretation.js";
+import type { Reading } from "./interpret.js";
+import type { Zodiac } from "./chart.js";
+import type { Realm, Certainty } from "./provenance.js";
+/** Default instruction header prepended to {@link Brief.prompt}. */
+export declare const BRIEF_INSTRUCTIONS: string;
+/** A one-line framing for the realm and certainty, or `""` when neither needs it. */
+export declare function realmFraming(realm?: Realm, certainty?: Certainty): string;
+export interface BriefOptions {
+    /** Keep only the top-N facts by salience. Default: all. */
+    limit?: number;
+    /** Restrict to certain atom kinds. */
+    kinds?: FactKind[];
+    /** Drop facts below this salience. */
+    minSalience?: number;
+    /** Fold a resolved {@link Reading}'s entries in as suggested readings. */
+    reading?: Reading;
+    /** Prepend {@link BRIEF_INSTRUCTIONS}. Default `true`. */
+    header?: boolean;
+}
+/** A salience-ranked fact in a {@link Brief}. */
+export interface BriefFact {
+    id: string;
+    kind: FactKind;
+    text: string;
+    salience: number;
+}
+/** A chart rendered as citable LLM input. */
+export interface Brief {
+    jdUt: number;
+    zodiac: Zodiac;
+    /** The facts offered, ranked by salience. */
+    facts: BriefFact[];
+    /** A prompt-ready, id-tagged rendering of {@link Brief.facts}. */
+    prompt: string;
+}
+/**
+ * Render an {@link InterpretationContext} as a compact, id-tagged {@link Brief}
+ * for an LLM to interpret and cite.
+ *
+ * @param ctx A projection from {@link interpretationContext}.
+ * @param opts Capping, kind filter, an optional {@link Reading} to fold in, and
+ *   whether to prepend {@link BRIEF_INSTRUCTIONS}.
+ * @returns The {@link Brief}: a ranked `facts` list and a ready `prompt`.
+ */
+export declare function chartBrief(ctx: InterpretationContext, opts?: BriefOptions): Brief;
+/** A model-produced statement and the fact ids it claims to rest on. */
+export interface Claim {
+    text: string;
+    cites: string[];
+}
+/** The result of {@link auditCitations}. */
+export interface CitationAudit {
+    /** True when every cited id resolves to a fact in the context. */
+    ok: boolean;
+    /** Total claims examined. */
+    claims: number;
+    /** Claims that cited at least one fact. */
+    cited: number;
+    /** Claims with no citation. */
+    uncited: number;
+    /** Distinct cited ids that resolve to a real atom. */
+    valid: string[];
+    /** Distinct cited ids with no matching atom -- invented provenance. */
+    unknown: string[];
+}
+/**
+ * Check that a model's claims cite only facts that exist in the context -- the
+ * accuracy half of "novel and accurate". A claim citing an id not in `ctx`
+ * fabricated its provenance, so `ok` is false and the id lands in `unknown`.
+ *
+ * @param claims The model's statements with their cited ids.
+ * @param ctx The {@link InterpretationContext} the brief was built from.
+ * @returns A {@link CitationAudit}.
+ */
+export declare function auditCitations(claims: Claim[], ctx: InterpretationContext): CitationAudit;

package/dist/src/brief.js

@@ -0,0 +1,85 @@
+/** Default instruction header prepended to {@link Brief.prompt}. */
+export const BRIEF_INSTRUCTIONS = "Natal chart facts follow, each with a stable id in [brackets]. Interpret them "
+    + "in your own words; after each statement, cite the id(s) it rests on as [id]. "
+    + "Do not introduce astrological facts that are not listed here.";
+/** How to frame an interpretation given what the chart is. */
+const REALM_FRAMING = {
+    observed: "", reported: "",
+    planned: "This is a planned future moment; frame statements as potentials, not settled facts.",
+    forecast: "This is a forecast moment; frame statements as tendencies, not certainties.",
+    fictional: "This is a fictional subject; interpret the symbolism, not a real person's life.",
+    mythic: "This is a mythic subject; read it as a symbol or story, not a biography.",
+    counterfactual: "This is a hypothetical variant of a real event; keep it conditional.",
+    archetypal: "This is an archetype, not a person; interpret the configuration's meaning itself.",
+    conceptual: "This is a concept or organization, not a person; interpret it as such.",
+};
+/** A one-line framing for the realm and certainty, or `""` when neither needs it. */
+export function realmFraming(realm, certainty) {
+    const parts = [];
+    if (realm && REALM_FRAMING[realm])
+        parts.push(REALM_FRAMING[realm]);
+    if (certainty && certainty !== "exact") {
+        parts.push(`The time is ${certainty}, so the Moon, the angles, and the houses are uncertain`
+            + " -- lean on the slower planets and sign-level statements.");
+    }
+    return parts.join(" ");
+}
+/**
+ * Render an {@link InterpretationContext} as a compact, id-tagged {@link Brief}
+ * for an LLM to interpret and cite.
+ *
+ * @param ctx A projection from {@link interpretationContext}.
+ * @param opts Capping, kind filter, an optional {@link Reading} to fold in, and
+ *   whether to prepend {@link BRIEF_INSTRUCTIONS}.
+ * @returns The {@link Brief}: a ranked `facts` list and a ready `prompt`.
+ */
+export function chartBrief(ctx, opts = {}) {
+    let atoms = ctx.atoms;
+    if (opts.kinds)
+        atoms = atoms.filter((a) => opts.kinds.includes(a.kind));
+    if (opts.minSalience !== undefined)
+        atoms = atoms.filter((a) => a.salience >= opts.minSalience);
+    if (opts.limit !== undefined)
+        atoms = atoms.slice(0, opts.limit);
+    const facts = atoms.map((a) => ({
+        id: a.id, kind: a.kind, text: a.text, salience: a.salience,
+    }));
+    const lines = facts.map((f) => `[${f.id}] ${f.text}`);
+    const framing = realmFraming(ctx.realm, ctx.certainty);
+    let prompt = (opts.header === false ? "" : `${BRIEF_INSTRUCTIONS}\n\n`)
+        + (framing ? `${framing}\n\n` : "")
+        + lines.join("\n");
+    if (opts.reading && opts.reading.entries.length) {
+        prompt += "\n\nSuggested readings (cite the same fact ids):\n"
+            + opts.reading.entries
+                .map((e) => `${e.atomIds.map((id) => `[${id}]`).join("")} ${e.text}`)
+                .join("\n");
+    }
+    return { jdUt: ctx.jdUt, zodiac: ctx.zodiac, facts, prompt };
+}
+/**
+ * Check that a model's claims cite only facts that exist in the context -- the
+ * accuracy half of "novel and accurate". A claim citing an id not in `ctx`
+ * fabricated its provenance, so `ok` is false and the id lands in `unknown`.
+ *
+ * @param claims The model's statements with their cited ids.
+ * @param ctx The {@link InterpretationContext} the brief was built from.
+ * @returns A {@link CitationAudit}.
+ */
+export function auditCitations(claims, ctx) {
+    const ids = new Set(ctx.atoms.map((a) => a.id));
+    const valid = new Set();
+    const unknown = new Set();
+    let cited = 0;
+    for (const c of claims) {
+        if (c.cites.length)
+            cited++;
+        for (const id of c.cites)
+            (ids.has(id) ? valid : unknown).add(id);
+    }
+    return {
+        ok: unknown.size === 0,
+        claims: claims.length, cited, uncited: claims.length - cited,
+        valid: [...valid], unknown: [...unknown],
+    };
+}

package/dist/src/chart.d.ts

@@ -1,5 +1,6 @@
 /** astroengine chart -- public API: natal charts, aspects, retrogrades. */
 import { EngineData, AYANAMSA_J2000 } from "./core.js";
+import type { AspectPhase } from "./electional.js";
 export declare const BODIES: readonly ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "chiron", "mean_node", "true_node"];
 export type Body = (typeof BODIES)[number];
 /** Computable on request (not in the default chart set). */
@@ -130,6 +131,10 @@ export interface Aspect {
     aspect: string;
     /** Orb from exact, in degrees. */
     orb: number;
+    /** Applying, separating, or exact -- from the two bodies' longitude speeds. */
+    phase: AspectPhase;
+    /** Closeness in `[0, 1]`: `1` exact, `0` at the orb limit. */
+    strength: number;
 }
 /** A full natal chart, as returned by {@link Engine.chart} and
  *  {@link Engine.chartAt}. Longitudes are degrees in the chart's `zodiac`. */

package/dist/src/chart.js

@@ -200,7 +200,10 @@ export class Engine {
                 : moonApparentSeries(this.data, jde);
             return [lon, lat, km / KM_PER_AU];
         }
-        if (body === "pluto")
+        // Pluto: a wide-range Chebyshev pack when one is loaded (same heliocentric
+        // pipeline as Chiron, via the generic packed-body path below), else the
+        // Meeus ch.37 series (valid 1885-2099, accuracy degrades outside).
+        if (body === "pluto" && !this.data.chebPacks?.pluto)
             return plutoApparent(this.data, jde);
         if (body === "chiron") {
             if (!this.chironCheb)
@@ -346,7 +349,7 @@ export class Engine {
         let l;
         let b;
         let r;
-        if (body === "pluto") {
+        if (body === "pluto" && !this.data.chebPacks?.pluto) {
             [l, b, r] = plutoHeliocentric(this.data, jde);
             [l, b] = precessEcliptic(l, b, J2000, jde);
         }
@@ -628,11 +631,24 @@ export function findAspects(bodies, orbs = DEFAULT_ORBS) {
         for (let j = i + 1; j < names.length; j++) {
             const a = names[i];
             const b = names[j];
-            const sep = Math.abs(mod(bodies[a].lon - bodies[b].lon + 180, 360) - 180);
+            const e = mod(bodies[a].lon - bodies[b].lon + 180, 360) - 180; // signed gap
+            const sep = Math.abs(e);
             for (const [asp, angle] of Object.entries(ASPECTS)) {
                 const orb = Math.abs(sep - angle);
                 if (orb <= orbs[asp]) {
-                    out.push({ a, b, aspect: asp, orb: Math.round(orb * 100) / 100 });
+                    const orbRounded = Math.round(orb * 100) / 100;
+                    // Applying/separating from the closing of the signed orb (matches
+                    // electional.aspectPhase); strength from the same rounded orb so a
+                    // consumer can reproduce it from .orb and the orb policy.
+                    const signedOrb = sep - angle;
+                    const dAbsOrbDt = (signedOrb >= 0 ? 1 : -1) * (e >= 0 ? 1 : -1)
+                        * (bodies[a].speed - bodies[b].speed);
+                    const phase = Math.abs(signedOrb) < 1e-9
+                        ? "exact" : dAbsOrbDt < 0 ? "applying" : "separating";
+                    out.push({
+                        a, b, aspect: asp, orb: orbRounded,
+                        phase, strength: Math.max(0, 1 - orbRounded / orbs[asp]),
+                    });
                 }
             }
         }

package/dist/src/counterfactual.d.ts

@@ -0,0 +1,82 @@
+/**
+ * astroengine counterfactual -- a real chart, perturbed, and what changed.
+ *
+ * The `counterfactual` realm: take a resolved chart and ask "what if". Shift the
+ * instant ("born an hour later") or the place -- a real ephemeris recompute --
+ * or splice a body to a new longitude ("Mars in the next sign") -- a geometry
+ * what-if that keeps everything else and recomputes the aspects it touches.
+ * {@link chartDiff} reports the difference so the change is legible, not buried
+ * in two full charts.
+ */
+import { Engine, Chart, ChartOptions, Aspect } from "./chart.js";
+import { AnchorRegistry } from "./provenance.js";
+import { AnchoredChart, RealizedChart } from "./anchored.js";
+/** A perturbation of a resolved chart. */
+export interface CounterfactualEdit {
+    /** Shift the resolved instant by a duration (e.g. `"1h"`, `"-30m"`, `"P1D"`). */
+    shiftTime?: string;
+    /** Recompute at a different place. */
+    place?: {
+        lat: number;
+        lonEast: number;
+        altM?: number;
+    };
+    /** Move bodies to given ecliptic longitudes (degrees), keeping everything else
+     *  -- a geometry what-if. The moved body's house and the touched aspects are
+     *  recomputed; the angles and other bodies are untouched. */
+    setLongitudes?: Record<string, number>;
+}
+/** A body whose sign or house changed between two charts. */
+export interface BodyChange {
+    body: string;
+    /** Signed degrees the body moved (`b` minus `a`). */
+    dLon: number;
+    signFrom: string;
+    signTo: string;
+    houseFrom: number;
+    houseTo: number;
+}
+/** An angle whose sign changed. */
+export interface AngleChange {
+    angle: string;
+    from: string;
+    to: string;
+}
+/** What differs between two charts. */
+export interface ChartDiff {
+    /** Bodies whose sign or house changed. */
+    bodies: BodyChange[];
+    /** Aspects present in the variant but not the original. */
+    aspectsGained: Aspect[];
+    /** Aspects present in the original but not the variant. */
+    aspectsLost: Aspect[];
+    /** Angles whose sign changed. */
+    angles: AngleChange[];
+}
+/** Diff two charts: body sign/house shifts, aspects gained/lost, angle sign
+ *  changes. Bodies and angles that did not change sign/house are omitted. */
+export declare function chartDiff(a: Chart, b: Chart): ChartDiff;
+/** A counterfactual: a base chart and a perturbed variant, with the diff. */
+export interface Counterfactual {
+    edit: CounterfactualEdit;
+    /** The realized base (its `chart` is the original). */
+    original: RealizedChart;
+    /** The perturbed chart, or null when the base had no chart to perturb. */
+    variant: Chart | null;
+    diff: ChartDiff | null;
+    note: string;
+}
+/**
+ * Realize an {@link AnchoredChart}, then apply a {@link CounterfactualEdit} and
+ * diff the result -- "a real event, perturbed." A time/place edit recomputes the
+ * ephemeris; a `setLongitudes` edit splices the geometry.
+ *
+ * @param engine The engine.
+ * @param base The base chart to perturb (realized via {@link realize}).
+ * @param edit The perturbation.
+ * @param registry Anchor lookups for the base.
+ * @param opts Chart options (house system, zodiac).
+ * @returns A {@link Counterfactual}; `variant`/`diff` are null when the base
+ *   produced no chart (e.g. a constraints-only form).
+ */
+export declare function counterfactual(engine: Engine, base: AnchoredChart, edit: CounterfactualEdit, registry?: AnchorRegistry, opts?: ChartOptions): Counterfactual;

package/dist/src/counterfactual.js

@@ -0,0 +1,105 @@
+/**
+ * astroengine counterfactual -- a real chart, perturbed, and what changed.
+ *
+ * The `counterfactual` realm: take a resolved chart and ask "what if". Shift the
+ * instant ("born an hour later") or the place -- a real ephemeris recompute --
+ * or splice a body to a new longitude ("Mars in the next sign") -- a geometry
+ * what-if that keeps everything else and recomputes the aspects it touches.
+ * {@link chartDiff} reports the difference so the change is legible, not buried
+ * in two full charts.
+ */
+import { SIGNS, findAspects, DEFAULT_ORBS, } from "./chart.js";
+import { houseOf } from "./electional.js";
+import { mod } from "./core.js";
+import { parseOffset } from "./provenance.js";
+import { realize } from "./anchored.js";
+const signOf = (lon) => SIGNS[Math.floor(mod(lon, 360) / 30)];
+const aspectKey = (x) => `${[x.a, x.b].sort().join("~")}:${x.aspect}`;
+/** Diff two charts: body sign/house shifts, aspects gained/lost, angle sign
+ *  changes. Bodies and angles that did not change sign/house are omitted. */
+export function chartDiff(a, b) {
+    const bodies = [];
+    for (const [name, pa] of Object.entries(a.bodies)) {
+        const pb = b.bodies[name];
+        if (!pa || !pb || (pa.sign === pb.sign && pa.house === pb.house))
+            continue;
+        bodies.push({
+            body: name, dLon: mod(pb.lon - pa.lon + 180, 360) - 180,
+            signFrom: pa.sign, signTo: pb.sign, houseFrom: pa.house, houseTo: pb.house,
+        });
+    }
+    const aset = new Set(a.aspects.map(aspectKey));
+    const bset = new Set(b.aspects.map(aspectKey));
+    const angles = [];
+    for (const ang of ["asc", "mc", "vertex", "eastPoint"]) {
+        const from = signOf(a.angles[ang]);
+        const to = signOf(b.angles[ang]);
+        if (from !== to)
+            angles.push({ angle: ang, from, to });
+    }
+    return {
+        bodies,
+        aspectsGained: b.aspects.filter((x) => !aset.has(aspectKey(x))),
+        aspectsLost: a.aspects.filter((x) => !bset.has(aspectKey(x))),
+        angles,
+    };
+}
+/** Splice bodies to new longitudes, recomputing their sign/house and the
+ *  aspects (the angles and untouched bodies stay as they were). */
+function spliceLongitudes(chart, overrides) {
+    const bodies = { ...chart.bodies };
+    for (const [name, lon] of Object.entries(overrides)) {
+        const cur = bodies[name];
+        if (!cur)
+            continue;
+        const L = mod(lon, 360);
+        bodies[name] = {
+            ...cur, lon: L, sign: SIGNS[Math.floor(L / 30)], signDeg: L % 30,
+            house: houseOf(L, chart.cusps),
+        };
+    }
+    return {
+        ...chart, bodies: bodies,
+        aspects: findAspects(bodies, DEFAULT_ORBS),
+    };
+}
+/**
+ * Realize an {@link AnchoredChart}, then apply a {@link CounterfactualEdit} and
+ * diff the result -- "a real event, perturbed." A time/place edit recomputes the
+ * ephemeris; a `setLongitudes` edit splices the geometry.
+ *
+ * @param engine The engine.
+ * @param base The base chart to perturb (realized via {@link realize}).
+ * @param edit The perturbation.
+ * @param registry Anchor lookups for the base.
+ * @param opts Chart options (house system, zodiac).
+ * @returns A {@link Counterfactual}; `variant`/`diff` are null when the base
+ *   produced no chart (e.g. a constraints-only form).
+ */
+export function counterfactual(engine, base, edit, registry = {}, opts = {}) {
+    const original = realize(engine, base, registry, opts);
+    if (!original.chart) {
+        return { edit, original, variant: null, diff: null, note: `nothing to perturb (${original.note})` };
+    }
+    const shiftsTimeOrPlace = edit.shiftTime !== undefined || edit.place !== undefined;
+    let variant = original.chart;
+    if (shiftsTimeOrPlace) {
+        const off = edit.shiftTime !== undefined ? parseOffset(edit.shiftTime) : 0;
+        if (Number.isNaN(off))
+            throw new Error(`unparseable shiftTime ${edit.shiftTime}`);
+        const lat = edit.place?.lat ?? original.place.place?.lat ?? 0;
+        const lon = edit.place?.lonEast ?? original.place.place?.lonEast ?? 0;
+        variant = engine.chartAt(original.time.jd + off, lat, lon, opts);
+    }
+    if (edit.setLongitudes)
+        variant = spliceLongitudes(variant, edit.setLongitudes);
+    const bits = [
+        edit.shiftTime !== undefined ? `time ${edit.shiftTime}` : null,
+        edit.place ? "place" : null,
+        edit.setLongitudes ? `moved ${Object.keys(edit.setLongitudes).join(", ")}` : null,
+    ].filter(Boolean);
+    return {
+        edit, original, variant, diff: chartDiff(original.chart, variant),
+        note: bits.length ? `perturbed: ${bits.join("; ")}` : "no edit applied",
+    };
+}