open-problem

Status: resolved (2026-10-27), for the declared exact, approximate-message and deliberately non-game domains below. The 2026-10-23 resolution named a function that did not exist. Related: L-SPEC-001 The Factor Interface, GitHub issue #8.

Sources: original to this vault; code: lib/LenticulumCore.jl/test/support/factor_conformance.jl, lib/Lenticulum.jl/test/game_composition.jl, lib/LenticulumCore.jl/test/support/conformance_capture.jl; package test/conformance.jl files; lib/AdversarialFactors.jl/test/transport.jl, lib/AlgebraicFactors.jl/test/game_exact.jl, lib/VariationalDiffusion.jl/test/bound.jl.

Theory (CT-ML wiki): Statistical Game · Bayesian Lens.

Problem. The factor interface is tested factor by factor. Issue #8 was a mismatch between two parts of the contract (scalarisation and energy) that no test covered, because each factor’s tests exercised only the paths it used. Other factor types (the diffusion, equilibrium, neural-ODE and adversarial factors) may have similar gaps.

Options.

  1. A conformance test: a function check_factor(f, ps, st, samples) in a test utility that runs every applicable part of L-SPEC-001 The Factor Interface (§1–§5) and the consistency conditions between them, called from each package’s tests for each factor type.
  2. Keep per-factor tests and add the cross-checks by hand.

Resolution through 2026-10-25 (history). The review-argon commits claimed option 1 (check_factor_conformance) but only added a loop over traits; the function did not exist (LP-013 Defects found in the review of master). Since bb3af9e9 it does, in lib/LenticulumCore.jl/test/support/factor_conformance.jl: for a factor and polarity it checks the testable parts of L-SPEC-001 The Factor Interface §1–§5 (traits, invert = combine(π, likelihood_message), the pointwise energy and its scalarisation, game-level free_energy and entropy in energyspace). It runs over every supported polarity of GaussianFactor, GaussianPrior, LinearConstraintFactor, NonlinearFactor and LikelihoodFactor (297 checks). Since 2026-10-25 the checker also has a direct-message path (direct_message = true, with independently computed site and posterior fixtures) for factors that implement factor_message without a lens; AlgebraicFactors.ToricFactor runs through it over every supported polarity at arities one to three. Open as of 2026-10-25: the factors of Mycelium, ImplicitLayers, VariationalDiffusion and AdversarialFactors are not run through it yet.

2026-10-27: exact-domain conformance and complete subtype audit

This section supersedes the 2026-10-26 rollout table and its remaining-work list. LP-009 Game-level free energy is declared but not implemented supplies the agreed bounds-plus-exact-cases semantics; the common checker now exercises each implemented exact domain without inventing a density, posterior entropy or wiring convention.

The default scope=:wired retains all existing checks and opt-out defaults. Independent expected_free_energy and expected_entropy fixtures additionally compare individual energy coordinates; wired runs also compare graph free energy with the expected value. Gaussian distributional observations already fit game_y, so they need no special-case factor dispatch. scope=:game checks parameters/states, game spaces, entropy/free-energy coordinates and default/custom scalarisation, requiring both independent fixtures. It makes no channel, pointwise, inversion or graph claim. scope=:bound requires full evidence, API keyword arguments and an independently computed finite exact negative log evidence; it checks an evaluated FreeEnergyUpperBound, finiteness, rejection by scalarise, and bound.value >= exact - 1e-10 (roundoff only). A sampled estimate cannot satisfy the type check. Neither scope silently substitutes for a wired sink: both explicitly use p=nothing.

The Gaussian composition sites/posteriors now come from matrix Gaussian multiplication, rather than the collapsed implementation’s lens. Game fixtures use residual covariance and Gaussian entropy, including the full joint posterior for soft observations. Tensor fixtures check every nested branch, with GaussianFactor, GaussianPrior, collapsed pair and independent product components. Polynomial fixtures use scalar Gaussian conditioning for all four Dirac/Gaussian input/output pairs, in addition to both wired polarities, row gauges, bases and damping. Plucker checks both placements of the Gaussian input. Transport fixtures use the affine output covariance and standard-normal entropy. Diffusion fixtures propagate the finite reverse chain’s mean and variance independently, including stationary equality, displaced-score strict gaps and nonstationary variances. Negative checker tests reject a graded fixture with cancelling coordinate errors and a falsely increased exact NLL; captured intentional failures are asserted, not counted as suite passes.

Current rollout table

lens means the default assembled-lens/message/graph path, direct the independently specified message/posterior path, game the explicit game-only scope, and bound the explicit bound-only scope. Test locations identify the owning package or explicitly say top-level. The table records fixture domains, not a claim about every belief family or dimension.

Concrete factorChecker path and fixture domainDeliberate semantic boundary / test location
GaussianFactorlens; both directionsGaussian/Dirac incoming games; top-level test/runtests.jl; exact Gaussian reference
GaussianPriorlens; unary; also tensor game componentGaussian/point pooling; top-level test/runtests.jl, lib/Lenticulum.jl/test/game_composition.jl
LinearConstraintFactorlens; every supported fixture polaritylinear-Gaussian residual; top-level test/runtests.jl
NonlinearFactorlens; both directionsdeclared Gauss–Newton message algorithm, not an exact nonlinear posterior; top-level test/runtests.jl
LikelihoodFactorlens; both directionsdeclared quadrature/moment projection, not universal exact integration; top-level test/runtests.jl
ComposedFactorlens; Gaussian pair both endpoint directions; game with Dirac and soft Gaussian observationscollapsed endpoint law, no internal-channel path game; unsupported components/nested compositions/noise hyperpriors explicitly rejected; lib/Lenticulum.jl/test/game_composition.jl, Core scope tests
TensorFactorgame; independent Gaussian/point branches and nested productsindependent game combinator, deliberately no graph/channel wiring or correlated-joint projection; lib/Lenticulum.jl/test/game_composition.jl, Core scope tests
DataFactordirect; unaryconstant-zero clamped-source accounting; Mycelium test/conformance.jl
PriorFactordirect; unary categorical, separate Dirac identityarbitrary nlogp has no generic Gaussian expectation; Mycelium test/conformance.jl
LossFactorwired sink; scalar/vector terminal point gamesnamed observations have no canonical x/a/y split or outgoing message; pointwise/message gaps retained; Mycelium test/conformance.jl
RelayFactordirect; both directionsidentity point game; Mycelium test/conformance.jl
OptimiserFactordirect; unarystateful update rule, deliberately no pointwise/statistical game; pointwise/game gaps and rejection tests retained; Mycelium test/conformance.jl
LuxFactorlens; forwardconditional point game, zero accounting; ImplicitLayers test/conformance.jl
DEQFactorlens; both directionsincoming Dirac game; solved-point lens/anchor game separately checked; soft/singular anchors deliberately refused; ImplicitLayers test/conformance.jl
NeuralODEFactorlens; both directionsincoming Dirac game; solved-point lens/anchor game separately checked (including SciML); same anchor boundary; ImplicitLayers test/conformance.jl, test/sciml.jl
NoiseSourcelens; unary fixed draw; game; unconditional standard normal at dimensions 1,3repeated stochastic particle draws are not identical-message fixtures; custom samplers provide no density law; AdversarialFactors test/conformance.jl, test/transport.jl
GeneratorFactorlens; forward point and affine Gaussian gamessquare nonsingular affine map, identity input adapter, no output conditioning; nonlinear certified bijections expose estimates only, singular maps no Lebesgue density; AdversarialFactors test/conformance.jl, test/transport.jl
RatioFactorlens; unary Dirac gameparticle messages checked separately (LP-016); non-Dirac exact games lack analytic normaliser/reweighted entropy, empirical entropy not substituted; AdversarialFactors test/conformance.jl
DiffusionFactorlens; all five binary assignments and unary; bound; analytic Gaussian finite reverse chainsscore/prox graph surrogate has no exact posterior game, so wired game gaps remain; full-evidence chain bound is a distinct model, not graph free energy; VariationalDiffusion test/conformance.jl, test/bound.jl
ToricFactordirect; all supported polarities at arities 1–3normalised exact finite-state games; AlgebraicFactors test/runtests.jl
PluckerFactordirect; forward point games at r=2,4 and scalar Gaussian images at r=2one fixed vector/one proper Gaussian, no output conditioning, positive variance, zero jitter; other images may be singular/non-Gaussian; AlgebraicFactors test/runtests.jl, test/game_exact.jl
PolynomialFactorlens; both binary degree-one polarities; game; all four Dirac/Gaussian pairssingle branch, invertible output block, SPD residual covariance, proper pooled posterior; nonlinear/branch-mixture densities deliberately not inferred from local metrics; AlgebraicFactors test/game_exact.jl

Test-only concrete subtypes

These fixtures intentionally implement only the operation being tested; promoting them to production statistical games would change the purpose of their tests.

Concrete test fixtureExplicit reason no common full checker is claimed
CouplingGuardFactorparameter/composition coupling rejection only; Core test/runtests.jl
CircleResidualpointwise Sampson scalarisation/Jacobian residual only; Core test/runtests.jl
StatefulResidualpointwise localisation/state-threading sentinel only; Core test/runtests.jl
BilinearResidualmixed pointwise derivative fixture only; Core test/runtests.jl
LazyPolarityFactorlazy enumeration/capped-list predicate fixture only; Core test/runtests.jl
ParameterResidualparameter-AD fixture with a deliberately pointwise surrogate free_energy; no channels/posterior/entropy; Core test/parameter_ad.jl
FreezeTraitFactorgraph construction rejection/trait fixture only; Mycelium test/runtests.jl
GaugeResidualpointwise Sampson gauge obligation only; AlgebraicFactors test/runtests.jl

Audit command (run from the repository root, excluding local working material):

rg -n -U '^(mutable )?struct [^\n]*<:\s*(LenticulumCore\.)?AbstractLenticulum(Factor|ContainerFactor|WrapperFactor)' --glob '*.jl' --glob '!meta/**'

The grep found 22 production types and eight test-only types (including multiline supertype declarations and the container subtype). There are no concrete wrapper-factor subtypes. Every match is accounted for above. The previous table omitted the five top-level factors and ToricFactor; those omissions are corrected here.

Remaining scope, deliberately excluded: general ratio/reweighted entropy, nonlinear transport exact expectations, singular or non-Gaussian Plucker images, nonlinear/multiple polynomial branches, arbitrary/nested composition laws, tensor graph wiring/correlated beliefs, and exact diffusion prox/posterior games or partial-evidence bounds. These are the explicit semantic boundaries agreed in LP-009, rather than implemented APIs awaiting checker coverage. All implemented new exact domains now reach the common checker. Existing callers had no obsolete game/message keyword exemptions for those domains; the obsolete exemptions were the historical rollout claims. The only real game/message opt-outs left are Optimiser’s non-game, Loss’s terminal message and the diffusion surrogate game, with their reasons above. LP-008 is therefore resolved; extending those semantics would require new laws and fixtures, not removal of an unexplained checker exemption.

Verification, 2026-10-27

All seven full package suites passed, with no failures, errors or broken assertions. Commands were julia --project=<package> -e 'using Pkg; Pkg.test()', using . for Lenticulum and lib/<Package>.jl for the others, on Julia 1.13.1 with OPENBLAS_NUM_THREADS=1 and JULIA_NUM_PRECOMPILE_TASKS=2. Counts sum the package entry points’ top-level test summaries once; elapsed wall times include package setup and compilation. Some commands ran concurrently, so these are validation timings, not comparative benchmarks.

EnvironmentPassing assertionsElapsed seconds
Lenticulum1143233.48
LenticulumCore31647.12
Mycelium51811.56
ImplicitLayers1231461.65
AdversarialFactors3749.65
AlgebraicFactors15985166.81
VariationalDiffusion1408433.85

Total: 20975 passing assertions. The affected exact-domain testsets contribute 202 (composition/products), 108 (transport/source), 1411 (polynomial), 99 (Plucker) and 265 (diffusion bounds) assertions. These counts include existing LP-009 checks as well as the extended common-checker calls; they are not counts of newly added assertions alone. The bound fixture covers stationary equality and strict/nonstationary gaps. Intentional checker-rejection tests assert exactly one captured failure each and reject unexpected errors.

julia --project=docs docs/make.jl also passed in 41.32 seconds, producing 26 API HTML pages and 253 vault HTML pages with cached tutorial renderings. It used a disposable Quartz engine under /tmp with the Git restoration hook removed; QUARTZ_DIR selected that engine and its npm cache was also in the disposable directory. The original Quartz script, config, layout and static files retain their pre-build SHA-256 hashes. Deployment was skipped by Documenter in the local environment.

The standalone docs/site/build.sh run with the same explicit QUARTZ_DIR passed in 7.25 seconds, producing 253 HTML pages without KaTeX errors. A final rebuild checks this completed verification record. git diff --check passes. No checkout, clean, reset, stash or commit command was run, including in the disposable engine; its restoration hook was removed before either build. No local working material was touched.

2026-10-26 rollout (history)

The single checker stays in lib/LenticulumCore.jl/test/support/factor_conformance.jl and is included by relative path from each package. This is the least invasive reuse: test environments already have its libraries; Mycelium’s test project only needs direct LuxCore/Random visibility. It adds nonempty reason-string opt-outs pointwise_gap, game_gap, message_gap, polarity_gap, plus p=nothing for sinks. Defaults retain all checks, and game/graph agreement now compares every energy coordinate, not just their scalar sum. Independent site/posterior fixtures also work on the default lens path.

FactorChecker path and polaritiesExplicit scope/gap
DataFactordirect; unaryconstant-zero point/source game
PriorFactordirect; unarycategorical closed-form fixture, separate Dirac option-1 check; arbitrary Gaussian expectations still refused
LossFactorsink (p=nothing)scalar/vector terminal games; no message, lens or canonical pointwise split
RelayFactordirect; both directionsidentity point game
OptimiserFactordirect; unaryno pointwise energy or statistical game; game methods throw
LuxFactordefault lens; forwardconditional point game with zero accounting
DEQFactordefault lens; both directionsfull incoming Dirac game; solved-point lens game and Jacobian-anchor identity checked separately (LP-009 item 1 resolved)
NeuralODEFactordefault lens; both directionsfull incoming Dirac game; solved-point lens game and both zero-flow identities checked (LP-009 item 1 resolved)
NoiseSourcedefault lens; unaryinjected fixed one-particle draw; game conditioned on a Dirac draw, no cloud entropy
GeneratorFactordefault lens; forwardDirac latent fixture, no distributional entropy
RatioFactordefault lens; unaryDirac game; particle likelihood, posterior energy contribution, and two-ratio graph checked (LP-016 resolved)
DiffusionFactordefault lens; all five accepted binary role assignments and unaryfixed-node Gaussian/point fixtures and joint messages; game gap remains; LP-017 enumeration/joint inversion resolved; other backends not certified
PluckerFactordirect; sole forward polarity at r=2,4trivially extended Dirac-input game; no assembled lens/inverse fibre/distributional entropy
PolynomialFactorunchanged independent per-polarity testsno local/game free energy or normalised joint branch model; full checker inapplicable
ComposedFactor, TensorFactorchecker inapplicable; Core tests verify scopeparameter/energy-space containers without channels, inversion or evaluated game laws

Remaining as of 2026-10-26 (superseded above): particle game entropy for Ratio (LP-006/009); diffusion game contracts (LP-009); normalized branch/game laws for Polynomial; wired container semantics. The rollout tests do not establish conformance for arbitrary belief families or diffusion backends. No placeholders or new approximation have been introduced for these gaps.

A small DEQ trait defect was fixed during the polarity audit: latent/unobserved pairs were accepted although neither solve has an observed companion point. supports_polarity now requires one observed channel; two regression assertions cover the rejected splits.

Earlier validation run, 2026-10-26 (history)

All commands below completed with zero unexpected failures/errors. Broken assertions are intentional executable records of the conflicts above, not passing conformance claims.

EnvironmentPassBroken
LenticulumCore2160
Mycelium4590
Lenticulum (top level)7750
ImplicitLayers3124
AdversarialFactors2323
AlgebraicFactors143960
VariationalDiffusion10664

Each package command was julia --project=lib/<Package>.jl -e 'using Pkg; Pkg.test()'; the top level used julia --project=. -e 'using Pkg; Pkg.test()'. VariationalDiffusion’s full suite ran once after the changes (its original testset: 889 passes in 6m48s; added partial conformance: 177 passes, 4 broken). Its touched testset also ran separately as a script containing the header of test/runtests.jl plus include("conformance.jl"), with --project=lib/VariationalDiffusion.jl/test: 177 passes, 4 broken. ImplicitLayers’ touched testset was also run as a header-plus-testset script while iterating; final full-suite counts above include the subsequent domain-rejection tests.

Broken counts: DEQ/NeuralODE incoming-versus-solved energy (four); Ratio particle pooling, target exclusion and expectation mismatch (three, LP-016); Diffusion enumeration and joint posterior dimension (four, LP-017).

The diffusion counts above record the earlier LP-008 run. LP-017 subsequently replaced its four broken assertions with passing checks and added complete enumeration, a lazy iterator, structural predicates and joint point/Gaussian/mixture tests; see LP-017 DiffusionFactor omits supported polarities. Ratio’s three broken assertions were later replaced by LP-016 (below). At the LP-017 run, ImplicitLayers recorded the incoming/solved energy mismatch as passing inequality checks. LP-009 item 1 now replaces those checks with two explicit games and the identity linking them.

Files in the 2026-10-26 rollout (history)

Source and test changes (abbreviated paths on a package line are relative to that package):

  • lib/LenticulumCore.jl/test/support/factor_conformance.jl
  • lib/Mycelium.jl/src/factors.jl, test/Project.toml, test/runtests.jl, test/conformance.jl
  • lib/ImplicitLayers.jl/src/luxfactor.jl, src/deq.jl, test/runtests.jl, test/conformance.jl
  • lib/AdversarialFactors.jl/src/generator.jl, src/ratio.jl, test/runtests.jl, test/conformance.jl
  • lib/AlgebraicFactors.jl/src/plucker.jl, test/runtests.jl
  • lib/VariationalDiffusion.jl/test/runtests.jl, test/conformance.jl
  • lib/LenticulumCore.jl/test/runtests.jl

Companion notes: Mycelium factors.md; ImplicitLayers luxfactor.md, deq.md, neuralode.md; AdversarialFactors generator.md, ratio.md; AlgebraicFactors plucker.md, polynomial.md, AlgebraicFactors.md; VariationalDiffusion factor.md; LenticulumCore statistical_game.md (all under their package src/). Package pages under docs/src/packages/: mycelium.md, implicitlayers.md, adversarial.md, algebraicfactors.md, lenticulumcore.md, variationaldiffusion/factors.md. Project records: LP-008, LP-009, new LP-016 and LP-017, Problem Log, and L-SPEC-001. The existing LP-011 implementation is preserved.

LP-016 subsequently replaced its three broken assertions with passing checks: RatioFactor now emits a log-potential, excludes target inputs, and averages its graph energy under the reweighted cavity. The two-ratio graph test checks multiplication once per factor. Particle game entropy remains unsupported; the earlier counts above record the pre-LP-016 run.

LP-009 item 1 validation, 2026-10-26

The incoming factor and solved-point lens games now have separate methods; DEQ/NeuralODE run the full common game checker without exemptions in both polarities. Linear tests derive 1/8 (DEQ) and 2 (zero flow) using energy_jacobian to form the Gaussian anchor precision. A quadratic DEQ checks cubic absolute energy error for the Gauss–Newton approximation. Matrix anchors, custom channel names, stopped solves, reverse-flow residuals and state threading have separate checks in lib/ImplicitLayers.jl/test/conformance.jl.

All seven full package suites passed with no broken assertions, using the package commands above and their repository test/runtests.jl entry points:

EnvironmentPass
LenticulumCore236
Mycelium494
Lenticulum (top level)775
ImplicitLayers480
AdversarialFactors254
AlgebraicFactors14396
VariationalDiffusion1143