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

contracts module

Western domain contract shared by the engine and its technique packages. Public imports use the package root. See the package specification and task W-12.

Run pnpm --filter @astrology/western build, check, and test after building Compose. The only runtime export is WesternError; every other export is a type. Importing this package starts no provider, registry, rulebook or calculation.

Contents

• WesternProfile, WesternProfileReference, WesternZodiac, RulershipScheme, TechniqueIdentity and WesternTechnique — the convention set a request is resolved against. variant is required, so an unreviewed technique version cannot become an implicit default, and sidereal profiles name an ayanamsa (the offset between tropical and sidereal zero points) instead of inheriting a provider default. sources records where each convention came from.
• RulebookReference, WesternRulebookManifest, TechniqueEntry, TechniqueBundle<T> and AdmittedRules<T> — admission envelopes. AdmittedRules binds the validated payload to technique/version/variant, resource hash and rulebook identity; domain table validation stays with the technique owner.
• WesternFeature<TRequest, TResult>, WesternFeatureRequirements and WesternFeatureContext — the registered binding the engine invokes. A feature declares its snapshot and upstream gates, inspects support without I/O and always evaluates asynchronously to { value, rules }. bundleHash is the admitted resource hash the engine compares before running.
• WesternCapability and MissingRequirement — availability the engine reports before execution.
• WesternResult<T>, WesternProvenance, RuleMatch and MissingLayer — the response envelope with profile, rulebook, engine/Composer identities, snapshot and probe references, derived points, rule matches and explicit omissions. complete is true only when missing is empty.
• WesternUpstreamGateId, WesternUpstreamStatus and WesternUpstreamBindings — which external capabilities are open, who owns a closed one, and the ports a feature receives.
• DerivedPointOrigin — technique output versus read astronomy; it stays assignable to Compose’s PointOrigin.

Boundaries

Technique result schemas are not defined here; each package owns its request/result types. The envelope adds only what every response shares. Nothing is filled in silently: an omitted technique is named in missing with its reason and blocked dependents, and a factor-level limitation is reported by the owning technique.

Consumer example

import type { AdmittedRules, WesternFeature } from './api/index.js';

const feature: WesternFeature<void, { readonly chartId: string }> = {
  technique: 'natal',
  identity: { technique: 'natal', version: '1', variant: 'standard' },
  bundleHash: 'admitted-hash',
  requirements: { snapshot: 'houses', upstream: ['positions', 'houses'], dependencies: [] },
  inspect: (_profile, upstream) => ({
    technique: 'natal',
    identity: { technique: 'natal', version: '1', variant: 'standard' },
    supported: upstream.houses.available,
    variants: ['standard'],
    missing: [],
  }),
  evaluate: async (_request, context) => ({
    value: { chartId: context.snapshot?.identity.hash ?? '' },
    rules: [],
  }),
};

const admitted: AdmittedRules<unknown> = {
  technique: 'natal',
  version: '1',
  variant: 'standard',
  hash: 'admitted-hash',
  rulebook: { id: 'western-rules', version: '1', hash: 'rulebook-hash' },
  rules: {},
};

Not implemented here

No catalog, registry, feature registration, hashing or evaluation. Those belong to @astrology/western, @astrology/western, the technique packages and @astrology/western.