Vedic 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/vedic. Files: src/profile.ts, src/result.ts, src/rulebook.ts, src/capability.ts, src/feature.ts. Task: V-16.

Exports types VedicProfile, VedicProfileId, VedicRulebookManifest, RuleFamilyId, RuleFamilyBundle<T>, VedicResult<T>, RuleMatch, MissingLayer, VedicCapability, VedicFeature<TRequest, TResult> and VedicFeatureContext. Requires shared chart/context/port types. Defines common identities and envelopes, not every feature’s DTO or tables. VedicFeature contains ID, requirements, capability inspection and an evaluation method; exact sync/async adapter shape is frozen by V-16. Feature registration binds an exact rule-family content hash. Generic feature-map types allow engine result inference without the engine importing every calculator’s DTO.

Acceptance: V-16 compiles dasha, matching and engine consumer examples without importing their implementations. Importing the contracts performs no work.

Implemented deviations: the root also exports VedicError, a side-effect-free class, as its only runtime value so every package shares one error discriminator; features therefore declare a runtime (not type-only) dependency on contracts. src/upstream.ts adds UpstreamGateId, RiseSetPort, DeclinationPort, MeanLongitudePort, VedicUpstreamPorts, UpstreamStatus and UpstreamBindings; feature requirements gained optionalUpstream and optionalDependencies. create*Feature takes the AdmittedRules<T> returned by getVedicRuleFamily, which carries the family hash the engine compares with the selected bundle.

Request shapes relaxed during review: the dasha, strengths and varga requests are optional (defaults: depth 3, every factor, D9 only), so the engine can run them as prerequisites. Strengths names varga as an optional dependency that runs when registered and supported. The transit window request no longer carries binderEngine; the scan reads it from its own first grid sample. Engine operations type their results from the registered features, and probe windows are checked against probeBudget.maxWindowMilliseconds before a session opens.

upstream

Path: packages/vedic. Files: src/gates.ts, src/adapters.ts, src/binder.ts.

Some layers need astronomy that Composer does not serve yet. This package is the single place where those dependencies are named and connected, so calculators and the engine never change when one becomes available.

Exports UPSTREAM_GATES, upstreamGate(id), riseSetFrom(source), declinationFrom(source), meanLongitudeFrom(source) and bindVedicUpstream(ports). The binder reads Composer capabilities once, records which optional ports the host supplied, exposes status for capabilities, and connect(gates) hands a feature only the ports it named or fails with LAYER_UNSUPPORTED and the gate’s owner. Adapters return null while an upstream object lacks the read, so a closed gate is never answered with fabricated data. Acceptance: closed gates name their owner; connecting a port opens exactly that gate.

profiles

Path: packages/vedic. Files: src/catalog.ts, src/resolve.ts, src/validate.ts. Task: V-01.

Exports createVedicProfileCatalog(profiles), resolveVedicProfile(catalog, id, version) and type VedicProfileCatalog. Requires explicitly supplied immutable profiles; returns a resolved VedicProfile or the named profile error. It selects position origin, zodiac/ayanamsa, node/houses, varga/dasha/drishti/sunrise conventions and rulebook identity. It does not load feature code. Acceptance: V-01 rejects unknown versions and records all convention choices.

rulebooks

Path: packages/vedic. Files: src/registry.ts, src/manifest.ts, src/integrity.ts. Task: V-17.

Exports createVedicRulebookRegistry(bundles), resolveVedicRulebook(registry, identity), getVedicRuleFamily<T>(handle, familyId, validate), and types VedicRulebookRegistry, VedicRulebookHandle. Requires manifest, supplied family resources and feature validators. Returns one immutable admitted handle; lookup validates the family payload instead of an unchecked cast. Acceptance: V-17 verifies manifest/family hashes, missing/duplicate families and profile compatibility; no registry import loads an engine, provider or unrelated feature.

chart-judgments

Path: packages/vedic. HLD: chart-core judgments. Files: src/dignity.ts, src/combustion.ts, src/war.ts, src/rules/. Task: V-02.

Exports validateJudgmentRules(value): JudgmentRules, evaluateDignities(snapshot, rules), evaluateCombustion(snapshot, rules), evaluatePlanetaryWar(snapshot, rules), createJudgmentFeature(rules), and types JudgmentRules, ChartJudgmentResult. Requires Binder-returned bodies without further rounding, Sun/speeds for relevant combustion rules and reviewed tables. Returns per-body states/pair outcomes with rule evidence. Acceptance: V-02’s threshold, missing-Sun and equal-longitude cases pass without fetching astronomy.

drishti

Path: packages/vedic. Files: src/policy.ts, src/evaluate.ts, src/rules/. Task: V-18.

Exports validateDrishtiPolicy(value): DrishtiPolicy, evaluateDrishti(snapshot, policy): DrishtiResult, createDrishtiFeature(policy), and types DrishtiPolicy, DrishtiResult, DrishtiRelationship. Requires supplied body geometry/signs and explicit graha/node school. Returns directed source-to-target signs/bodies with selected rule IDs. Reuse resolveDrishti from existing semantics; Vedic owns selection and judgments. Acceptance: V-18 tests classical special counts and distinguishes absent node rules from an empty match list.

varga

Path: packages/vedic. HLD: varga HLD. Files: src/catalog.ts, src/parts.ts, src/mapping.ts, src/chart.ts, src/rules/. Tasks: V-03 D9, V-04 remaining catalog.

Exports validateVargaRules(value): VargaRules, mapVargaPoint(point, vargaId, rules): VargaPoint, buildVargaChart(snapshot, vargaId, rules): VargaChart, evaluateVargottama(d1, d9), createVargaFeature(rules), and types VargaId, VargaPoint, VargaChart, VargaRules. Requires sidereal D1 longitude/sign/lagna (ascendant) and named varga schemes. Reuses chart-core’s sign-distance house/roster functions, not its astronomy acquisition. Acceptance: V-03/V-04 pass total mapping, half-open part, D30 and same-mapper-for-lagna cases; no invented varga degrees.

dasha

Path: packages/vedic. HLD: dasha HLD. Files: src/balance.ts, src/divider.ts, src/timeline.ts, src/lookup.ts, src/rules/. Task: V-05.

Exports validateVimshottariRules(value): VimshottariRules, computeBirthBalance(moonFacts, rules), dividePeriod(parent, weights), buildVimshottariTimeline(input, rules): DashaTimeline, findActivePeriods(timeline, asOf), createDashaFeature(rules), and types DashaInput, DashaPeriod, DashaTimeline, VimshottariRules. Requires birth instant, Moon longitude/Binder nakshatra ID, year length, depth and optional asOf. It needs no houses, full natal judgment, Composer instance or I/O. Acceptance: V-05’s reviewed balance, nesting, cycle and rounding invariants pass; the divider has one implementation.

ashtakavarga

Path: packages/vedic. HLD: transit BAV/SAV. Files: src/contributions.ts, src/bav.ts, src/sav.ts, src/score.ts, src/rules/. Task: V-07.

Exports validateAshtakavargaRules(value): AshtakavargaRules, computeAshtakavarga(natalFacts, rules): AshtakavargaResult, scoreTransitSign(result, body, sign): number | null, createAshtakavargaFeature(rules), and types AshtakavargaRules, AshtakavargaResult. Requires natal body/lagna signs and contribution/reduction convention. Acceptance: V-07 verifies reviewed BAV (per-planet bindu table) and unreduced SAV (sum across planets) 337 of ashtakavarga; missing body-specific BAV stays null. Transit can consume its result without importing its calculator.

strengths

Path: packages/vedic. Files: src/requirements.ts, src/factors.ts, src/assemble.ts, src/rules/. Tasks: V-06 specification, V-19 gated implementation.

Target exports after V-06: getStrengthRequirements(system), evaluateStrengthFactors(input, rules): StrengthResult, createStrengthFeature(rules), and types StrengthInput, StrengthFactor, StrengthRules, StrengthResult. Requires the chosen system’s audited astronomical/chart factors, optionally supplied varga/BAV results as explicitly typed input. No dependency on all other Vedic calculations is assumed. Acceptance: V-19 proves each advertised system’s factor completeness and reviewed numerical fixtures. Shadbala stays unimplemented/unadvertised until V-06 defines it; do not publish placeholder totals.

panchang

Path: packages/vedic. HLD: panchang HLD. Files: src/day.ts, src/limbs.ts, src/solver.ts, src/assemble.ts, src/rules/. Task: V-08.

Exports validatePanchangRules(value): PanchangRules, calculatePanchang(request, probePort, rules): Promise<PanchangDay>, createPanchangFeature(rules), and types PanchangRequest, PanchangRules, PanchangDay, LimbInterval, BoundaryPrecision. Requires resolved local-day context, observer, actual rise/set capability, Sun/Moon probes and solver budget. Owns limb definitions/solver; astronomy comes through injected ProbePort. Acceptance: V-08 verifies five panchang limbs, one-second tolerance, no partial day and published almanac fixtures.

transit

Path: packages/vedic. HLD: transit HLD. Files: src/admission.ts, src/gochara.ts, src/vedha.ts, src/sade-sati.ts, src/scanner.ts, src/solver.ts, src/rules/. Tasks: V-09, V-10.

Exports validateTransitRules(value): VedicTransitRules, evaluateGochara(reference, movingSnapshot, rules): VedicTransitSnapshot, scanVedicTransits(request, probePort, rules): Promise<VedicTransitWindow>, createTransitFeature(rules), and types TransitReference, VedicTransitRules, VedicTransitSnapshot, VedicTransitWindow. Requires admitted natal Moon/lagna/version facts, explicit asOf/window and optional supplied BAV. TransitReference defines the minimal readonly BAV view it consumes, structurally compatible with AshtakavargaResult; snapshot mode without bindus has no compile/runtime dependency on that calculator. Window mode needs probes; snapshot mode is pure. Acceptance: V-09/V-10 verify Moon-based houses, repeated retrograde phases, solved boundaries and reference-version admission.

matching

Path: packages/vedic. HLD: matching HLD. Files: src/admission.ts, src/kootas.ts, src/cancellations.ts, src/score.ts, src/rules/. Task: V-11.

Exports validateMatchingRules(value): MatchingRules, evaluateAshtakoota(pair, rules): MatchingResult, createMatchingFeature(rules), and types MatchingSubject, MatchingPair, MatchingRules, KootaScore, MatchingResult. Requires two ordered Moon fact references, compatible versions, exact scoring matrices and cancellation rules. No full-chart request or astronomy port is required. Acceptance: V-11 verifies all eight exact ashtakoota scores, total/threshold, directionality and retained dosha cancellation evidence.

yoga-dosha

Path: packages/vedic. Files: src/requirements.ts, src/evaluate.ts, src/cancellations.ts, src/rules/. Task: V-12.

Exports validateYogaDoshaPack(value): YogaDoshaPack, evaluateYogaDosha(input, pack): YogaDoshaResult, createYogaDoshaFeature(pack), and types YogaDoshaInput, YogaDoshaPack, YogaDoshaResult. Requires only facts enumerated by the pack, possibly supplied drishti/judgment results; never invokes their calculators implicitly. Acceptance: V-12’s selected positive/negative/cancellation/ missing-input fixtures pass. The API does not promise an undefined complete catalog.

muhurta

Path: packages/vedic. Files: src/requirements.ts, src/intervals.ts, src/evaluate.ts, src/rules/. Tasks: V-13 pack definition, V-14 implementation.

Exports validateMuhurtaPack(value): MuhurtaPack, selectMuhurtaWindows(input, pack): MuhurtaResult, createMuhurtaFeature(pack), and types MuhurtaInput, MuhurtaPack, MuhurtaWindow, MuhurtaResult. Requires already calculated panchang intervals and the specific chart/judgment facts named by the purpose pack. Pure interval selection returns accepted/excluded windows and rule reasons. The engine obtains panchang/chart dependencies; this leaf does not fetch them. Acceptance: V-13/V-14 verify precedence, exact interval boundaries, empty results and explicit missing factors. Optional yoga/dosha factors use the common RuleMatch evidence shape; a purpose that does not request such a pack must not require its implementation merely to compile.

engine

Path: packages/vedic. Files: src/engine.ts, src/dependencies.ts, src/capabilities.ts, src/result.ts. Task: V-15.

Exports createVedicEngine(options): VedicEngine, constant VEDIC_ENGINE_VERSION, and types VedicEngineOptions, VedicEngine, VedicChartRequest, VedicChartResult. Methods implement HLD operations capabilities, chart, panchang, transits, matching, muhurta. Options supply profile catalog, rulebook registry, ComposerPort and registered feature instances. The host imports only the feature packages it enables and creates them from the admitted rules. Engine validation selects a binding matching the selected bundle’s family hash or reports unavailable; it never reuses a binding from a different rulebook. Generic VedicEngineOptions<TFeatures>/VedicEngine<TFeatures> infer registered result types through the shared feature contract, without static type/runtime imports of unregistered packages.

Engine owns dependency planning and response completeness, not formulas. Optional features are explicitly registered; missing ones produce unsupported capability, not a fake empty result. Acceptance: V-15/S-02 prove minimal dasha and matching consumers need no unrelated feature implementations, and a full chart runs only selected prerequisites under one profile/rulebook.