Structural validation and message polarity resolution, including rejection of unsupported frozen factors.
Sources: code:
polarity_resolution.jlTheory (CT-ML wiki): Lax Functor · Bayesian Inversion · Bayesian Lens · Lens · Functor
Implements: the step with no counterpart in Lux — deciding, per message, which way to run a factor. Theory: Polarity Resolution, Channels and Polarity.
The rule
target channel -> Unobserved()
channels with a message (excluding target) -> Observed()
all other declared channels -> Latent()
then LenticulumCore.assemble(factor, polarity) gives a lens and the message is an inversion
(Messages are Inversions).
Two legality checks that are genuinely different
check_legalon the edge directions: anEmittingedge may not beObserved(), anAbsorbingedge may not beUnobserved(). A property of the wiring.supports_polarityon the factor: can it be run this way at all? A property of the factor.
The direction check fires first and names the channel, which matters for error quality:
“edge is Absorbing, so channel :pred cannot be Unobserved” says where the wiring is wrong;
supports_polarity returning false says only that something is.
Together they replace Lux’s acyclicity restriction: a Lux Chain is well-formed iff the wiring
is a DAG; a Mycelium graph is well-formed iff every scheduled message passes both.
validate
Pre-flight checks: declared channels, no isolated factors or variables, and a warning for
multiple emitting edges with no reader. Structural validation is optional and separate from
build. Both accept frozen factors: the parameter driver pins selected coordinates
and preserves input derivatives. The old option-2 rejection is recorded in LP-011’s
historical section. Freeze paths are checked against actual parameter trees at use.
Implementation difficulties
1. Missing channels methods are skipped
validate uses hasmethod before consulting LenticulumCore.channels(fn.factor).
If no method exists, the declared-channel check is skipped; exceptions from an existing
method propagate. The earlier note claiming a bare try swallowed these errors was stale.
Requiring a channel declaration for every factor remains a separate interface decision.
2. Exactly one Unobserved() per message
Deliberate v0 restriction. When a factor’s inversion couples several unobserved channels, sending them separately discards the correlation — which is the mean-field laxness of Remark 16 appearing at the message level, measured by the same mutual information.
The generalisation is a joint message over a set of channels delivered to a composite variable. Not implemented, and not an oversight: fixing it means deciding where to pay for joint belief representations, which is the decision Composition of Bayesian Lenses says should be exposed at the graph level rather than hidden.
3. NamedTuple{decl}(vals) is type-unstable
decl comes from LenticulumCore.channels(factor) at runtime, so the polarity’s type is not
known to the compiler at the call site even though it is concrete once built. Every message
therefore pays a dynamic dispatch to construct its polarity.
The fix is for channels to be a compile-time property of the factor’s type (a type parameter,
as AbstractLenticulumContainerFactor{factors} already does for its sub-factors) rather than a
runtime field. That is a LenticulumCore change and it is probably right, since the whole
argument for putting polarity in the type domain (channels) is undermined if the names
arrive dynamically.
Cached per graph (2026-11-12). A profile of a sweep on bench/state_scaling.jl’s chain
(800 steps, 2 401 factors, 50 sweeps, 8 267 samples) put about a quarter of the sweep in
resolve_polarity. Building NamedTuple{decl} with run-time names took 997 samples in that line
alone, and rebuilding decl from channels(factor) took 909. FactorGraph now keeps, per
factor, a Dict from (target, available) to the polarity, behind a lock. The graph and its
factors are immutable, so an entry never goes stale. Only a successful resolution is stored, so
an invalid key throws on every call. After the change resolve_polarity takes about 100 of
6 296 samples, and the sweep takes 14.0 ms instead of 18.9 (best of 5,
one machine). The dynamic dispatch on the polarity’s type in _rule_message remains; the type-level fix
above would remove it too. Test: “polarity resolution” in test/runtests.jl, which compares the
cached polarity with a fresh _resolve_polarity for every target and every subset of the other
channels, given as a tuple, a vector and a set. Reviewed by Mistral (no defects; it also checked
the graph-edit paths, eight tasks resolving at once, and Zygote and ForwardDiff through step!).
Planned per graph (2026-11-12, the rest of I18). After the cache, _step! still paid per message
for what the cache does not hold: available_channels built a Tuple from a Vector, the cache key
was a tuple of names, check_legal ran (a dispatch on the polarity’s type, a loop over the edges and
supports_polarity), _inputs looked each input’s edge up by name, and every field of the
FactorNode was read through a dynamic getproperty. None of it depends on more than the graph, the
edge and which inputs are informative. _step! now keeps, in g.emit_plans and behind the same lock,
an _EmitPlan per (edge, bit mask of the factor’s edges with an informative input): the factor, the
rule, the checked polarity and the input names in its type, and the input edges. A message computes
the mask (no allocation), looks the plan up, and _emit calls the rule with everything but the
beliefs known to the compiler. A plan of nothing is the TrivialBelief() case; an illegal key is
not stored and throws on every call; a factor with more than 64 edges plans each message afresh.
Mean-field nodes keep the old path. This is not the type-level fix above: the beliefs in the store
are still type-erased, so one dynamic dispatch into factor_message per message remains, and
channels is still a run-time property.
Measured with bench/sweep_profile.jl (T = 800, 2 401 factors, best of 5, one machine): 9.94 ms per
sweep instead of 12.02, 13.2 MB allocated instead of 14.6; _step! holds 1 367 profile samples
instead of 1 686. What is left around the factor’s own work is reading the type-erased messages
(getproperty on Message, about 100 samples) and the dispatch into the factor. A new set of
informative inputs is a new NamedTuple type and compiles once on either path; a scratch comparison
(not kept in the repository) on a 20-channel factor gave the same compile time per new set, about
70 ms, before and after. Test: test/emit_plan.jl, which compares step! with the old sequence
(resolve, check, gather by name, call the rule) on random wirings, edge directions, store contents
and rules, for factors of 1 to 70 channels; checks that an illegal plan is not stored; and runs 8
tasks with their own stores on one graph. Reviewed by Mistral: no defect
(LP-027 Findings of the review of the I18 plans).
4. check_legal’s error picks an arbitrary channel
When supports_polarity returns false the error names
first(unobserved_channels(p)) — the target — which is usually right but is a guess. The factor
knows why it refused and has no way to say so. A supports_polarity returning a reason
(nothing for yes, a String for no) would be strictly better and is a small interface change.
Related: Polarity Resolution, Channels and Polarity, messages
LP-011 implementation (2026-10-27)
Frozen factors are now legal in both build and validate; parameter freezing lives in the parameter/gradient driver and preserves input cotangents. The 2026-10-26 frozen-factor rejection described above is historical. Polarity legality and direction checks remain unchanged.
Evidence: lib/MyceliumLearning.jl/test/gradient_couplings.jl and
test/gradient_couplings.jl. API, mixed Jacobians, costs and unsupported combinations
are specified in gradient_couplings and L-SPEC-002 Stop Gradient.