Internal module guide. This module is now part of @astrology/western; use the public package README for application setup.

engine module

Western coordinator: profile and rulebook resolution, upstream binding, technique planning and the result envelope. Public imports use the package root. See the package specification and task W-11.

Run pnpm --filter @astrology/western build, check, and test after building Compose and the Western packages. Importing the package constructs nothing; the host registers features explicitly, so a natal-only consumer never loads an unregistered technique or provider adapter.

Construction

import { createWesternEngine } from './application/engine/index.js';

const engine = createWesternEngine({
  profiles: profileCatalog,
  rulebooks: rulebookRegistry,
  upstream: { composer },
  features: { natal },
});

Every feature must be registered under its own technique name, and its identity must name the same technique. Registration is the only place a technique implementation enters the engine.

Capabilities

capabilities(profile) (see capability) resolves the profile and rulebook, binds Composer once and assesses every registered feature. A feature is supported only when all of these hold:

• the profile elects its exact version and variant (unsupported-variant otherwise);
• the admitted rulebook declares the same technique revision and the feature’s bundle hash (rulebook-mismatch otherwise);
• every required upstream gate is open (missing-capability, with the owning task).

A technique whose required dependency is unregistered or unsupported is reported unsupported with dependency-unavailable, so a later technique exposes its prerequisite’s missing gate.

Chart request

chart({ profile, instant, houseObserver?, positionObserver?, techniques, requests?, allowPartial? })

1. Resolves one profile and one rulebook and asserts they are compatible.
2. Plans the requested techniques after their required prerequisites; optional dependencies run when requested or when supported.
3. Composes one snapshot — positions only when no runnable technique needs houses, which also drops the house observer requirement.
4. Evaluates shared geometry once, and only when a runnable technique asks for contacts (aspects); the contacts arrive in WesternFeatureContext.aspects.
5. Evaluates features in dependency order, collecting each value and its RuleMatch[].
6. Returns { value, rules, provenance, missing, complete }.

Without allowPartial, an unavailable or failing technique fails the whole request with its original code. With allowPartial, the response lists the omitted technique, its reason and blocked dependents, and complete is false.

Provenance

provenance (see provenance) carries the profile reference, rulebook identity (including its hash), engine version, Composer and snapshot references, probe ids, derived-point origins and collected evidence. The engine never substitutes a snapshot or provider identity.

Supplied-chart and search operations

compose({ profile, instant, houseObserver?, positionObserver?, houses? }) acquires one profile-pinned snapshot; houses: false permits positions-only acquisition. It resolves the same profile/rulebook admission as other engine calls.

operation({ profile, technique, request, snapshot?, prerequisiteRequests?, allowPartial? }) routes pair, mapped-chart and search requests without composing an unused chart. snapshot supplies the reference for natal, harmonic or direction operations; pair and search techniques carry their references in their own typed request. Required prerequisites are planned in dependency order and receive only their declared dependencies. Optional available dependencies are planned as in chart.

const reference = await engine.compose({
  profile: profileRef, instant: birthInstant, houseObserver: birthObserver,
});
const progression = await engine.operation({
  profile: profileRef,
  technique: 'progressions',
  request: { reference, targetInstant },
});

Synastry requests supply { source, target, completeness }; composites supply { a, b }. Transit requests explicitly select snapshot or window mode. Returns supply the reference, anchor, location policy and bounded probe budget. The feature’s pure probeRequest preflights the search; the engine opens one C-04 session from that declaration. Snapshot transit mode opens no session. Only features declaring requirements.composer receive Composer for mapped/event chart acquisition. A closed optional probe gate leaves snapshot mode usable; transit capabilities expose the available modes.

Feature outputs contribute source chart identities, original evidence, probe IDs, derived origins and factor omissions to the envelope. Optional-factor gaps mark complete: false without discarding successfully transformed points. Progression v1 always reports the undefined progressed ascendant. Return ambiguity/no-event are explicit search outcomes; exhausted searches are incomplete.

Synastry, composite, transit, return, progression, direction and harmonic operations correspond to the chart families in the vocabulary.

The operation integration fixtures exercise all eight families using real Composer, geometry and probe sessions with analytic astronomy.

Not implemented here

Technique formulas, rule tables and their validators, profile/rulebook admission, astronomy and geometry evaluation, and numerical search belong to their owning packages. The host registers all eight families when their resources are supplied. Production Binder configuration, astronomical time resolution, timezone lookup, interpretation and rendering remain host concerns.