Western module specifications

The current package structure defines the workspace boundaries. The modules below share their owning domain’s package manifest and build. Their factories and helper exports are internal implementation contracts; application callers use the public package root or runtime assembly. Calculation task IDs and review gates remain unchanged.

Module inventory

Package roots expose named service contracts and supported entry points, without wildcard exports. Detailed module contracts below retain the calculation design and acceptance requirements; an internal export does not imply a public package export. Read development tasks for implementation and review status.

contracts

Path: packages/western. Files: src/profile.ts, src/rulebook.ts, src/upstream.ts, src/capability.ts, src/feature.ts, src/result.ts, src/errors.ts, src/derived-point.ts. Task: W-12.

Exports the single runtime value WesternError (stable codes plus optional structured detail) and types WesternProfile, WesternProfileReference, WesternTechnique, TechniqueIdentity, RulebookReference, TechniqueBundle<T>, AdmittedRules<T>, WesternRulebookManifest, WesternCapability, MissingRequirement, WesternFeature<TRequest, TResult>, WesternFeatureContext, WesternFeatureRequirements, WesternResult<T>, MissingLayer, WesternUpstreamGateId, WesternUpstreamStatus, WesternUpstreamBindings and DerivedPointOrigin. Requires shared context/snapshot/port types; every non-error export is a type, so importing the package starts no provider, registry, rulebook or calculation. A profile pins its identity/version, zodiac (tropical or sidereal with a named ayanamsa), position origin (geocentric or topocentric), bodies, node/speed choices, house system and frame, aspect policy, rulership scheme, rulebook reference, technique identities and convention sources. A feature declares snapshot and upstream requirements, inspects support without I/O and evaluates asynchronously to a value plus RuleMatch[]. AdmittedRules<T> binds validated payload to technique/version/variant, resource hash and rulebook identity, so the engine can reject an unregistered revision. Acceptance: W-12 proves natal, harmonic and engine consumers compile without provider/technique imports.

profiles

Path: packages/western. Files: src/catalog.ts, src/resolve.ts, src/validate.ts. Task: W-01.

Exports createWesternProfileCatalog(profiles), resolveWesternProfile(catalog, id, version), resolveWesternProfileReference(catalog, reference), validateWesternProfile(value), toChartContextInput(profile, request, options?) and types WesternProfileCatalog, WesternChartRequest, WesternChartContextOptions. Requires supplied immutable profiles; returns a deep-frozen profile or the explicit UNKNOWN_PROFILE/INVALID_REQUEST error. Records position origin, zodiac/ayanamsa, body/node, houses, aspect/orb, rulership and technique choices with rulebook identity and convention sources. It does not execute techniques. toChartContextInput is the outbound Composer seam: it emits the shared request shape from the profile, refuses observers that contradict the pinned origin, and with { houses: false } composes positions only (houseSystem: null, lagna frame becomes none). Acceptance: W-01 rejects unreviewed variants, blended conventions and implicit sidereal conversion/default changes.

rulebooks

Path: packages/western. Files: src/registry.ts, src/manifest.ts, src/integrity.ts. Task: W-13.

Exports createWesternRulebookRegistry(bundles), resolveWesternRulebook(registry, reference), assertRulebookCompatible(handle, profile), getWesternTechniqueRules<T>(handle, technique, validate), hashTechniqueRules(payload), verifyRulebookTechniques(manifest, techniques), validateRulebookManifest(value), and types WesternRulebookBundle, WesternRulebookRegistry, WesternRulebookHandle. Requires manifest and supplied technique resources/validators. Returns an immutable admitted handle whose identity hash covers the manifest and therefore every technique hash. One selected bundle governs a response; unrelated runtime table revisions cannot be mixed. Acceptance: W-13 verifies duplicate/missing/tampered resources, content hashes and profile compatibility without importing any technique or engine implementation.

upstream

Path: packages/western. Files: src/gates.ts, src/adapters.ts, src/binder.ts. Task: — (dependency seam for W-02/W-11 and later techniques).

Exports UPSTREAM_GATES, upstreamGate(id), geometryChartFrom(snapshot), bindWesternUpstream(ports) and types UpstreamGate, WesternUpstreamBinding. Requires an injected ComposerPort. The binder inspects Composer capabilities once per engine call and records positions, houses, geometry, cross-chart-geometry and probes as open or closed with the owning task, so no technique fabricates an astronomy or geometry answer while an upstream task is pending. connect(gates, probe?) hands a feature only the ports it named. geometryChartFrom copies snapshot bodies, angles and cusps into the shared GeometryChart, keeping observed origins and evidence; it never recomputes a position. Acceptance: the binder and adapter tests run against a synthetic Composer and require no provider, ephemeris file or network.

natal

Path: packages/western. Files: src/distributions.ts, src/rulership.ts, src/dignity.ts, src/patterns.ts, src/rules/. Task: W-02.

Exports validateNatalRules(value): WesternNatalRules, evaluateWesternNatal(snapshot, contacts, rules): WesternNatalResult, evaluateNatal(facts, aspects, rules), toNatalFacts(snapshot), toNatalAspects(contacts), createNatalFeature(admitted), and types WesternNatalRules, WesternNatalResult. createNatalFeature takes AdmittedRules<WesternNatalRules> and returns a WesternFeature<void, WesternNatalResult> that reads the engine’s snapshot and evaluated contacts from the feature context. Requires the chosen body set, shared houses where needed, Composer-calculated aspects and named rulership/aspect-pattern tables. Returns factor counts, judgments, patterns, rule IDs and gaps; the feature adds the deciding RuleMatch[]. Missing houses or absent geometry degrade only the factors that need them (missing-houses, missing-aspects) instead of blocking the rest. Acceptance: W-02 checks reviewed natal fixtures and precise missing-input behavior. It is pure; no geometry, astronomy or profile resolution is repeated here.

transit

Path: packages/western. Files: src/contacts.ts, src/scanner.ts, src/solver.ts, src/rules/. Task: W-03.

Exports validateWesternTransitRules(value): WesternTransitRules, evaluateWesternTransits(reference, moving, geometry, rules): WesternTransitSnapshot, scanWesternTransits(request, ports, rules): Promise<WesternTransitWindow>, createTransitFeature(rules), and types WesternTransitRules, WesternTransitSnapshot, WesternTransitWindow. Requires admitted reference, explicit moving instant/window and pair/orb policy; window search also requires probes and solver limits. Snapshot mode uses supplied charts and geometry only. The natal reference has zero derivative relative to the transit time parameter; it must not use its birth-time speed as a moving reference in applying/separating evaluation. Acceptance: W-03 covers repeated retrograde contacts, solved event boundaries and no-event/budget outcomes.

synastry

Path: packages/western. Files: src/admission.ts, src/contacts.ts, src/overlays.ts, src/rules/. Task: W-04.

Exports validateSynastryRules(value): SynastryRules, evaluateSynastry(pair, geometry, rules): SynastryResult, createSynastryFeature(rules), and types SynastryPair, SynastryRules, SynastryResult. Requires two immutable context-tagged charts, explicit direction and Composer GeometryPort. Returns source/target contacts, directional overlays and rule evidence. Does not acquire charts or build a composite. Acceptance: W-04 verifies reversed pairs, context compatibility and unavailable target houses. Timeless pairs report unknown applying/separating phase unless a selected technique explicitly defines that motion. Geometry contact types come from compose/contracts, not a static dependency on the geometry implementation.

composite

Path: packages/western. Files: src/methods.ts, src/construct.ts, src/requirements.ts, src/rules/. Tasks: W-05 composite definition, W-06.

Exports validateCompositeRules(value): CompositeRules, constructComposite(pair, policy, ports?): Promise<CompositeChart>, createCompositeFeature(rules), and types CompositeMethod, CompositeRules, CompositeChart, CompositeRequest. Requires two admitted charts and the W-05 midpoint definition (composite@1/midpoint). Midpoint-only methods need no astronomy; time/place-derived methods need explicit contexts and Composer access. Results label transformed points and any newly observed astronomy separately. Acceptance: W-06 resolves wrap/opposite-point ambiguities and verifies method-specific references.

progressions

Path: packages/western. Files: src/time-mapping.ts, src/angles.ts, src/calculate.ts, src/rules/. Tasks: W-05 progression definition, W-07.

Exports validateProgressionRules(value): ProgressionRules, mapProgressionContext(request, rules): ChartContextInput, calculateProgression(request, composer, rules): Promise<ProgressionResult>, createProgressionFeature(rules), and types ProgressionRules, ProgressionRequest, ProgressionResult. Requires reference context, target date, defined year/day and angle policy (progressions@1/secondary-day-for-year); Composer supplies astronomy at the mapped context. No dependency on the natal implementation. Acceptance: W-07 verifies mapping and angle fixtures and retains both target/mapped contexts.

returns

Path: packages/western. Files: src/target.ts, src/bracket.ts, src/solver.ts, src/event-chart.ts, src/rules/. Tasks: W-05 return definition, W-08.

Exports validateReturnRules(value): ReturnRules, findReturnEvents(request, probePort, rules): Promise<ReturnSearchResult>, calculateReturnChart(event, locationPolicy, composer): Promise<ReturnChartResult>, createReturnFeature(rules), and types ReturnRules, ReturnRequest, ReturnEvent, ReturnSearchResult, ReturnChartResult. Requires target body/reference longitude, bounded search/tolerances, candidate selection and explicit event-chart location (returns@1/solar). Search remains independently testable from event-chart assembly. Acceptance: W-08 distinguishes no/multiple/exhausted outcomes and passes wrap/retrograde/residual fixtures.

directions

Path: packages/western. Files: src/arc.ts, src/transform.ts, src/contacts.ts, src/rules/. Tasks: W-05 direction definition, W-09.

Exports validateDirectionRules(value): DirectionRules, calculateSolarArc(input, rules): DirectedChart, evaluateDirectedContacts(directed, reference, geometry, rules), createDirectionFeature(rules), and types DirectionRules, SolarArcInput, DirectedChart. Requires a reference, target date, selected solar-arc definition (directions@1/solar-arc-naibod) and any corresponding mapped astronomy already obtained by the coordinator. It does not import progressions merely to reuse an unspecified convention. Acceptance: W-09 verifies arc/angle/contact fixtures and rejects primary directions.

harmonics

Path: packages/western. Files: src/factor.ts, src/transform.ts, src/contacts.ts, src/rules/. Tasks: W-05 harmonic definition, W-10.

Exports validateHarmonicRules(value): HarmonicRules, transformHarmonic(snapshot, factor, rules): HarmonicChart, evaluateHarmonicContacts(chart, geometry, rules), createHarmonicFeature(rules), and types HarmonicRules, HarmonicFactor, HarmonicChart. Requires reference coordinates, allowed factor and explicit angle/house treatment (harmonics@1/harmonic-n). Transformation is pure; contacts use the supplied geometry port and explicitly identify derived-point origins. Acceptance: W-10 verifies normalized mapping, unsupported factors and no silent reuse of natal houses.

engine

Path: packages/western. Files: src/engine.ts, src/dependencies.ts, src/capabilities.ts, src/result.ts. Task: W-11.

Exports createWesternEngine(options), constant WESTERN_ENGINE_VERSION, assembleResult, assessFeature, assessFeatures, planLayers, gatesFor, dependentsOf, and types WesternEngineOptions, WesternEngine, WesternChartRequest, WesternChartResult, WesternFeatureMap, PlanOptions. Methods: capabilities(profile), compose(request), chart(request) and operation(request). compose acquires one profile-pinned reference; operation routes supplied pairs, mapped charts and bounded searches without an unrelated acquisition. Feature probeRequest preflight declares the session context/budget; only Composer-declaring features receive acquisition access. Outputs propagate source identities, probe evidence, derived origins and reported factor gaps to the envelope. chart plans only the requested techniques plus required prerequisites, composes one snapshot (positions only when no runnable technique needs houses), evaluates shared geometry once when a runnable technique asks for contacts, then evaluates features in dependency order and assembles one envelope. Techniques added later (transit, synastry, composite, progressions, returns, directions, harmonics) register through the same feature contract. Requires profile catalog, rulebook registry, injected ComposerPort and explicitly registered feature instances. The host imports/enables individual techniques; the engine checks profile election, declared bundle hash/version/variant and requirements, sequences ports and retains evidence. Partial output is opt-in and lists unavailable techniques with blocked dependents. Generic WesternEngineOptions<TFeatures>/WesternEngine<TFeatures> infer results from shared feature contracts rather than importing unregistered technique types or implementations. Acceptance: W-11/S-02 verify minimal natal-only construction, unsupported unregistered methods, correct dependency execution and one profile/rulebook per response.