Harmonic Chart harmonic-n@1 — Specification (W-05)

Status: Implemented v1 convention · Task: W-05 · Updated: 2026-10-25 · Implementation: W-10 package.

A harmonic chart multiplies every ecliptic longitude by an integer factor. It is the smallest transformation in the engine and the easiest one to mislabel: the output is derived coordinates, not astronomy, and the transformed chart does not inherit the natal house ring.

1. Admitted variant

Rule payload (validated by validateHarmonicRules):

{
  "transform": "multiply",
  "angles": "transformed",
  "houses": "none",
  "minFactor": 2,
  "maxFactor": 64,
  "allowedFactors": null
}

factor is a request parameter, constrained by the payload. allowedFactors: [4, 5, 7, 9] pins a reviewed subset; null admits every integer in [minFactor, maxFactor]. The factor is part of the result and of the rule evidence, never of the technique identity.

2. Inputs

No ComposerPort and no ProbePort: the transformation is pure and needs no new astronomy.

3. Transformation

λ_h = wrap360(n × λ_0)

wrap360 is defined in the composite specification §3.1. The multiplication is done in full precision and wrapped once, at the end. Wrapping an earlier intermediate value is equivalent modulo 360, but it hides the single normalisation point and makes fixture diffs harder to read.

Every transformed point is:

{ "kind": "derived", "method": "harmonics.transform", "version": "1",
  "sources": ["<reference snapshot hash>"] }

The factor is retained in the technique result and in the deciding RuleMatch.facts ({ factor: n }), because DerivedPointOrigin has no factor field. Two results with different factors are never merged or cached as one.

4. Speeds

The transformation has an exact derivative:

s_h = (s_0 === null) ? null : n × s_0

This is the derivative of the transformed coordinate, not a claim about the body’s physical motion, and it is the only reason harmonic contacts can carry a phase. Unknown source speed stays null and reaches the shared geometry as phase: 'unknown'; zero is never substituted.

Contacts are evaluated with motion: "returned-speeds" so both derived derivatives are used. If the source chart was composed without speeds, every harmonic phase is unknown and the contacts are still reported.

5. Angles and houses

Natal cusps are never attached to the harmonic chart. A harmonic chart is not a relocated natal chart, and a transformed point does not occupy a natal house. A request for harmonic house placement is LAYER_UNSUPPORTED; an overlay evaluated against the natal chart is a separate, explicit consumer choice and is not produced here.

6. Contacts (optional)

policy   = { ...profile.aspectPolicy, motion: 'returned-speeds' }
contacts = geometry.evaluateChartAspects(harmonicGeometry, policy)

• Same-chart contacts of the harmonic chart, not a re-labelling of natal aspects.
• Orb set and aspect ids are the profile’s; the harmonic technique adds no orb table.
• harmonicGeometry carries points from §3, derived origins, derived speeds and no cusps.
• With geometry absent, contacts is omitted with missing-aspects; the harmonic chart is still a successful result.

7. Result

The original reference snapshot is returned unchanged and is never mutated. Repeated calls with the same snapshot and factor are byte-identical.

8. Composer facts and ports

Declared requirements: snapshot: 'houses', upstream: ['positions', 'houses'], optionalUpstream: ['geometry'], dependencies: [].

The admitted variant transforms the reference angles, so the snapshot requirement is houses. A host without a house observer fails context assembly explicitly; a positions-only harmonic variant is a different version. The missing-angles row in §9 applies to snapshots supplied directly to the pure transformation.

9. Failures

10. Worked examples

n is the factor, λ the reference longitude.

H-F6 is the arithmetic check that catches a missing wrap: 7 × 300 = 2100, and 2100 mod 360 is 300, so the transformed point must equal the source. H-F2, H-F3 and H-F4 catch per-step wrapping and off-by-one sign errors.

11. Unsupported variants

12. Prerequisites before W-10

The implementation and coordinator integration now satisfy these runtime seams; convention sources remain the responsibility of each supplied production rulebook. See the package tests.