feat: add complex-number (phasor) arithmetic support

[Mearman]

Closes #2

Adds complex as a computed-value kind, complexLiteral as an expression node, and complex support across arithmetic, compare, memberOf and negate. Complex/phasor arithmetic comes out of the exclusion list, and Design principles gains the scope test that call is now written down as.

The representation decision

The issue flagged rectangular vs. polar as an open question. I went with one canonical rectangular form — { kind: "complex"; re: number; im: number; unit?: Unit } — with no form discriminant, and four exported conversion helpers for the polar view. Three reasons, in the order I weighted them:

1. A second form makes equality ambiguous. Polar doesn't encode a value uniquely: phase is only defined modulo a full turn, and a zero-magnitude value has no meaningful phase at all, so the same number has unboundedly many polar encodings. eq/memberOf are exact equality everywhere else in this package; supporting two forms would mean either normalising on every comparison or inventing an approximate equality for this one kind. Neither is something I wanted to introduce for a representational choice.
2. A discriminant would double the branching in every operator (quadruple it for a binary one) while changing no value — every operator would convert to rectangular internally anyway, because that's where the closed forms are.
3. Rectangular is what the operators need. add/subtract are component-wise in it; multiply, divide, negate and integer power all have standard closed forms in it. Polar's advantage (multiply as one product of magnitudes plus one sum of angles) doesn't extend to addition at all.

So polar lives at the edges as conversions rather than as a second encoding: complexFromPolar / complexLiteralFromPolar going in, complexMagnitude / complexPhase coming back out — magnitude as a real number in the value's own unit, phase as a dimensionless real number of radians.

Semantics

• add/subtract component-wise, requiring identical unit maps exactly as real numbers do.
• multiply/divide as real complex multiplication and division, units combining by the same dimensional analysis. A zero divisor means both components zero — a purely imaginary divisor divides fine, which has its own test.
• power for a real integer exponent, as the repeated multiplication that integer exponentiation is; a negative exponent reuses the divide above rather than re-deriving the reciprocal, so a zero base inherits that operator's own division-by-zero domain-error. Dimensionless operands required, same as real power.
• modulo is domain-error.
• gt/gte/lt/lte are wrong-type for a complex operand; eq/neq are exact equality across both components, and memberOf matches the same way.
• negate flips both components.

Two judgement calls beyond what the issue spelled out, both documented in the README:

A real operand is promoted in arithmetic, not rejected. The issue's own motivation is formulas mixing real and complex terms in one tree, and scaling or offsetting a complex value by a real one is the common case — forcing every real literal to be rewritten as a complex one would defeat the point. The promotion is exact, total and canonical (every real is a complex with zero imaginary part), unlike the temporal cross-kind combinations, which had to be enumerated one by one precisely because no such embedding exists between an instant and a duration. The result is complex whenever either operand is, even when the imaginary part comes out zero: a node's result kind follows its operand kinds, never the values flowing through it.

compare stays kind-strict, so complex-vs-real is wrong-type there. That asymmetry with arithmetic is deliberate: arithmetic produces a value, so promoting loses nothing, whereas a comparison consumes two and this design already treats a kind difference between them as a modelling error worth surfacing — the same reason an instant is never compared against a plain number despite being a millisecond count underneath.

The one deliberate limitation

power with a non-integer real exponent, or with a complex exponent, is wrong-type rather than supported. An arbitrary complex exponent needs the complex logarithm, which is multivalued and so needs a branch-cut convention this design hasn't chosen. wrong-type rather than domain-error is the consistent reading of those two codes here: domain-error is for cases where no answer exists (division by zero, an empty max), wrong-type for "an answer exists, but this operator doesn't accept this operand" — which is also how power's existing dimensionless-operands requirement is already classified.

Reaching an ordering comparison over a complex quantity

There's no accessor node kind in the grammar, and no built-in function set to add one to (call resolves through a consumer-supplied registry by design). A tree that needs |z| > limit registers a one-line function over the exported helper:

const functions: FunctionRegistry = {
  magnitude: (args) =>
    args[0]?.kind === "complex"
      ? complexMagnitude(args[0])
      : { domainError: "expected a complex argument" },
};

test/integration/complex-arithmetic.test.ts exercises exactly that end to end, alongside complex operands arriving from a resolver and being combined with a real one in the same expression.

Also worth a look

reference's unit expectation now accepts a complex resolution. It previously required the resolved value to be a number, which would have left a complex-valued reference unable to declare its unit at all — a hole in the feature rather than a separate change.

Testing

Built strictly red-green: every behaviour above has a test that failed first for the right reason. Locally green across unit (364), integration (55), smoke (63) and workers (9), plus pnpm lint, pnpm typecheck, publint and attw --pack.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-01T13:59:50.863241Z	372687f	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

🎉 This PR is included in version 1.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀