@@ -243,15 +243,32 @@ export interface ComparisonRequest extends AnalysisRequest {
   aggregate?: boolean
 }
 
+export interface PermanovaTerm {
+  term: string
+  r2: number
+  f_statistic: number | null
+  /** Null when the term could not be tested; `untestable_reason` says why. */
+  p_value: number | null
+  /** Set when within-block permutation cannot change this term. */
+  untestable_reason?: string | null
+}
+
 export interface PermanovaResult {
   text: string
+  /** The first term (group, when it varies); r2, f_statistic and p_value are its own. */
+  term?: string
   r2: number | null
   f_statistic: number | null
   p_value: number | null
+  untestable_reason?: string | null
+  /** Permutations actually performed: fewer than 999 when the blocks admit fewer. */
+  permutations?: number
+  /** Smallest p-value attainable with that many permutations. */
+  min_p_value?: number
   /** True when permutations were restricted within individuals. */
   blocked?: boolean
   /** One row per model term, tested sequentially in formula order. */
-  terms?: { term: string; r2: number; f_statistic: number | null; p_value: number | null }[]
+  terms?: PermanovaTerm[]
   /** PERMDISP on the same distances: do the groups differ in spread? */
   dispersion?: PermdispResult | { error: string }
 }
 
@@ -99,19 +99,20 @@ export function DiversityPanel({ study, runs, option, aggregate }: {
         <div className="card" style={{ fontFamily: 'monospace', fontSize: '.82rem', whiteSpace: 'pre-wrap' }}>
           <div className="card-title">PERMANOVA Results</div>
           <pre style={{ margin: 0 }}>{permanova.text}</pre>
-          {(permanova.terms?.length
-            ? permanova.terms
-            : permanova.p_value != null
-              ? [{ term: 'model', r2: permanova.r2 ?? NaN, f_statistic: permanova.f_statistic, p_value: permanova.p_value }]
-              : []
-          ).map(t => (
+          {(permanova.terms ?? []).map(t => (
             <p key={t.term} style={{ marginTop: 8, fontFamily: 'inherit' }}>
-              {t.term}: R&sup2; = {t.r2.toFixed(3)} · F = {t.f_statistic?.toFixed(2) ?? 'n/a'} · p = {t.p_value?.toFixed(4) ?? 'n/a'}
+              {t.term}: R&sup2; = {t.r2.toFixed(3)} · F = {t.f_statistic?.toFixed(2) ?? 'n/a'} ·{' '}
+              {t.untestable_reason ? `p not reported: ${t.untestable_reason}` : `p = ${t.p_value?.toFixed(4) ?? 'n/a'}`}
             </p>
           ))}
           {(permanova.terms?.length ?? 0) > 1 && (
             <p style={{ marginTop: 4, fontFamily: 'inherit' }}>Terms are tested in order, each after the ones above it.</p>
           )}
+          {permanova.permutations != null && permanova.min_p_value != null && (
+            <p style={{ marginTop: 4, fontFamily: 'inherit' }}>
+              {permanova.permutations} permutations; the smallest attainable p is {permanova.min_p_value.toFixed(4)}.
+            </p>
+          )}
           {permanova.blocked && (
             <p style={{ marginTop: 4, fontFamily: 'inherit' }}>Permutations restricted within individuals.</p>
           )}
 
@@ -1423,14 +1423,38 @@ function run_nmds(mat::Matrix{Float64}; seed::Integer=123, transform::String="no
     end
 end
 
+"""
+    _varies_within_any_block(values, blocks) -> Bool
+
+Whether `values` takes at least two distinct values among the samples of some
+block in `blocks` (one label per sample).
+"""
+function _varies_within_any_block(values::AbstractVector, blocks::AbstractVector)
+    first_seen = Dict{eltype(blocks),eltype(values)}()
+    for (v, b) in zip(values, blocks)
+        isequal(get!(first_seen, b, v), v) || return true
+    end
+    false
+end
+
 """
     run_permanova(mat, metadata; seed=123, transform="none", blocks=nothing) -> Union{NamedTuple, Nothing}
 
-PERMANOVA via vegan::adonis2 with 999 permutations.
+PERMANOVA via vegan::adonis2 with up to 999 permutations.
 `metadata` is a DataFrame with one row per sample and covariate columns.
+Each covariate is tested as its own term (`by = "terms"`), sequentially in
+column order, so each row is conditioned on the terms before it. The top-level
+`term`, `r2`, `f_statistic` and `p_value` are those of the first term.
 `blocks`, one label per sample (e.g. the individual a sample came from),
 restricts permutations to within blocks. It is ignored when no label repeats,
-since singleton blocks admit no permutation at all.
+since singleton blocks admit no permutation at all. A term that is constant
+within every block cannot be tested by within-block permutation (each sample
+never leaves its block, so the permutations never exchange that term's labels
+and the p-value does not test it), so its p-value is withheld and
+`untestable_reason` says why.
+`permutations` is the number of permutations actually performed, which is fewer
+than 999 when the blocks admit fewer, and `min_p_value` the smallest p-value
+that number can produce.
 `transform` is applied before `vegdist`; see [`run_nmds`](@ref).
 """
 function run_permanova(mat::Matrix{Float64}, metadata::DataFrame; seed::Integer=123,
@@ -1443,6 +1467,10 @@ function run_permanova(mat::Matrix{Float64}, metadata::DataFrame; seed::Integer=
     formula_rhs = join(covariates, " + ")
     mat = transform_counts(mat; method=transform)
     blocked = !isnothing(blocks) && length(blocks) == size(mat, 1) && !allunique(blocks)
+    # Within-block permutation never exchanges the labels of a term that is
+    # constant inside every block, so its p-value does not test that term.
+    untestable = blocked ? [c for c in covariates if !_varies_within_any_block(metadata[!, c], blocks)] :
+                           String[]
 
     with_r_lock(; timeout=R_WAIT_SECONDS[]) do
         meta_r = copy(metadata)
@@ -1452,6 +1480,7 @@ function run_permanova(mat::Matrix{Float64}, metadata::DataFrame; seed::Integer=
         RCall.globalEnv[:seed] = Int(seed)
         RCall.globalEnv[:perm_blocks] = blocked ? String.(blocks) : String[]
         RCall.globalEnv[:disp_cols] = String.(covariates)
+        RCall.globalEnv[:perm_untestable] = String.(untestable)
         RCall.reval("""
             set.seed(seed, kind = "Mersenne-Twister", normal.kind = "Inversion", sample.kind = "Rejection")
             dist_mat <- vegdist(mat, method = "bray")
@@ -1463,12 +1492,25 @@ function run_permanova(mat::Matrix{Float64}, metadata::DataFrame; seed::Integer=
                 999
             }
             perm_err <- NULL
+            perm_n <- NA_integer_
             perm_res <- tryCatch(
-                adonis2(form, data = meta_r, permutations = perm_ctrl, parallel = 1),
-                error = function(e) { perm_err <<- conditionMessage(e); NULL }
-            )
+                # vegan 2.7 defaults to by = NULL, one test of the whole model.
+                adonis2(form, data = meta_r, permutations = perm_ctrl, by = "terms", parallel = 1),
+                error = function(e) { perm_err <<- conditionMessage(e); NULL })
             if (!is.null(perm_res)) {
-                perm_text <- paste(capture.output(print(perm_res)), collapse = "\\n")
+                # permute enumerates every permutation instead of drawing 999 when
+                # the blocks admit fewer, which small blocks make likely; the
+                # control adonis2 used records how many it ran.
+                perm_n <- attr(perm_res, "control")[["nperm"]]
+                # Within-block permutation never exchanges such a term's labels
+                # between blocks, so its p-value does not test that term.
+                untestable_rows <- which(rownames(perm_res) %in% perm_untestable)
+                perm_res[untestable_rows, "Pr(>F)"] <- NA
+                perm_text <- paste(c(capture.output(print(perm_res)),
+                                     if (length(untestable_rows) > 0)
+                                         paste0("Pr(>F) withheld for ", paste(rownames(perm_res)[untestable_rows], collapse = ", "),
+                                                ": constant within every permutation block, so within-block permutation does not test it.")),
+                                   collapse = "\\n")
                 perm_r2 <- perm_res\$R2[1]
                 perm_f <- perm_res\$F[1]
                 perm_p <- perm_res[["Pr(>F)"]][1]
@@ -1506,6 +1548,7 @@ function run_permanova(mat::Matrix{Float64}, metadata::DataFrame; seed::Integer=
         r2 = RCall.rcopy(RCall.reval("perm_r2"))
         f_stat = RCall.rcopy(RCall.reval("perm_f"))
         p_val = RCall.rcopy(RCall.reval("perm_p"))
+        n_perm = RCall.rcopy(RCall.reval("perm_n"))
         # adonis2 tests terms sequentially, so each row is conditioned on the terms above it.
         term_names = String.(vcat(RCall.rcopy(RCall.reval("perm_terms"))))
         term_r2 = vcat(RCall.rcopy(RCall.reval("perm_terms_r2")))
@@ -1520,20 +1563,32 @@ function run_permanova(mat::Matrix{Float64}, metadata::DataFrame; seed::Integer=
             (; groups = [(; group = groups[k], mean = vcat(d[:mean])[k], median = vcat(d[:median])[k]) for k in eachindex(groups)],
                f_statistic = d[:f], df = [Int(d[:df1]), Int(d[:df2])], p_value = d[:p], text = String(d[:text]))
         end
-        RCall.reval("rm(mat, meta_r, formula_rhs, seed, perm_blocks, disp_cols, perm_ctrl, dist_mat, form, perm_res, perm_err, perm_text, perm_r2, perm_f, perm_p, perm_terms, perm_terms_r2, perm_terms_f, perm_terms_p, disp, disp_err); gc()")
+        RCall.reval("rm(mat, meta_r, formula_rhs, seed, perm_blocks, disp_cols, perm_untestable, perm_ctrl, dist_mat, form, perm_res, perm_err, perm_n, perm_text, perm_r2, perm_f, perm_p, perm_terms, perm_terms_r2, perm_terms_f, perm_terms_p, disp, disp_err); if (exists(\"untestable_rows\")) rm(untestable_rows); gc()")
 
         ismissing(txt) && return nothing
         # When R's adonis2 threw, txt is the error message and r2/f/p are missing.
         # Return a named tuple with :message so the route can distinguish and surface it.
         ismissing(r2) && return (; message=string(txt))
+        reason(t) = t in untestable ?
+            "'$t' is constant within every permutation block, and permutations are restricted " *
+            "within blocks, so its labels are never exchanged and the p-value would not test it; " *
+            "a between-block term needs whole blocks permuted" :
+            nothing
+        withheld(t, p) = (t in untestable || ismissing(p)) ? nothing : p
+        terms = [(; term=term_names[k],
+                    r2=term_r2[k],
+                    f_statistic=ismissing(term_f[k]) ? nothing : term_f[k],
+                    p_value=withheld(term_names[k], term_p[k]),
+                    untestable_reason=reason(term_names[k])) for k in eachindex(term_names)]
         (; text=txt,
+           term=term_names[1],
            r2=r2,
            f_statistic=ismissing(f_stat) ? nothing : f_stat,
-           p_value=ismissing(p_val) ? nothing : p_val,
-           terms=[(; term=term_names[k],
-                     r2=term_r2[k],
-                     f_statistic=ismissing(term_f[k]) ? nothing : term_f[k],
-                     p_value=ismissing(term_p[k]) ? nothing : term_p[k]) for k in eachindex(term_names)],
+           p_value=withheld(term_names[1], p_val),
+           untestable_reason=reason(term_names[1]),
+           terms,
+           permutations=Int(n_perm),
+           min_p_value=1 / (Int(n_perm) + 1),
            blocked,
            dispersion)
     end
 
@@ -50,6 +50,7 @@ const UNIT_FILES = [
     "test_sample_reads.jl",
     "test_determinism.jl",
     "test_differential.jl",
+    "test_permanova.jl",
     "test_write_gates.jl",
 ]
 
 
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# PERMANOVA: each covariate is tested as its own sequential term, checked against
+# a direct vegan::adonis2 call; the permutation count and p-value floor are
+# reported; and a term within-block permutation cannot test is refused.
+# Skips loudly when R/vegan is absent.
+
+using MetaManifold
+using MetaManifold.Analysis
+using RCall
+using DataFrames
+using Random
+using Test
+
+const _PERM_R = MetaManifold.Server.r_available()
+_PERM_R || @info "R/vegan unavailable - the PERMANOVA reference tests are SKIPPED"
+
+"""
+    _adonis2_reference(mat, meta, perm_expr) -> DataFrame
+
+Run vegan::adonis2 directly on Bray-Curtis distances of `mat`, with
+`group + run` terms tested sequentially and permutations given by the R
+expression `perm_expr` (which may refer to `ref_meta`), seeded as
+`run_permanova` seeds it. Returns the term rows: term, r2, f, p.
+"""
+function _adonis2_reference(mat, meta, perm_expr)
+    MetaManifold.RRuntime.with_r_lock() do
+        RCall.globalEnv[:ref_mat] = mat
+        RCall.globalEnv[:ref_meta] = meta
+        RCall.reval("""
+            set.seed(123, kind = "Mersenne-Twister", normal.kind = "Inversion", sample.kind = "Rejection")
+            ref_d <- vegdist(ref_mat, method = "bray")
+            ref_res <- adonis2(ref_d ~ group + run, data = ref_meta,
+                               permutations = $perm_expr, by = "terms", parallel = 1)
+            ref_rows <- which(!(rownames(ref_res) %in% c("Residual", "Total")))
+            ref_out <- data.frame(term = rownames(ref_res)[ref_rows], r2 = ref_res\$R2[ref_rows],
+                                  f = ref_res\$F[ref_rows], p = ref_res[["Pr(>F)"]][ref_rows])
+        """)
+        out = rcopy(RCall.reval("ref_out"))
+        RCall.reval("rm(ref_mat, ref_meta, ref_d, ref_res, ref_rows, ref_out)")
+        out
+    end
+end
+
+@testset "PERMANOVA" begin
+    @testset "_varies_within_any_block" begin
+        blocks = ["i1", "i1", "i2", "i2"]
+        @test !Analysis._varies_within_any_block(["a", "a", "b", "b"], blocks)
+        @test Analysis._varies_within_any_block(["r1", "r2", "r1", "r1"], blocks)
+    end
+
+    if _PERM_R
+        rng = MersenneTwister(7)
+        # Six individuals, each sampled in two runs; three individuals per group.
+        mat = Float64.(rand(rng, 0:60, 12, 40))
+        individuals = ["i$(cld(k, 2))" for k in 1:12]
+        meta = DataFrame(sample = ["s$k" for k in 1:12],
+                         group = [cld(k, 2) <= 3 ? "A" : "B" for k in 1:12],
+                         run = repeat(["r1", "r2"], 6))
+
+        @testset "each term is tested on its own, as vegan by = \"terms\"" begin
+            res = Analysis.run_permanova(mat, meta; seed=123)
+            ref = _adonis2_reference(mat, meta, "999")
+            @test [t.term for t in res.terms] == ["group", "run"] == ref.term
+            @test [t.r2 for t in res.terms] ≈ ref.r2
+            @test [t.f_statistic for t in res.terms] ≈ ref.f
+            @test [t.p_value for t in res.terms] == ref.p
+            # The headline result is the group term, not the whole model.
+            @test res.term == "group"
+            @test res.r2 ≈ ref.r2[1] && res.p_value == ref.p[1]
+            @test res.permutations == 999
+            @test res.min_p_value ≈ 1 / 1000
+            @test all(t -> isnothing(t.untestable_reason), res.terms)
+        end
+
+        @testset "within-individual blocks: permutation count, floor and refusal" begin
+            res = Analysis.run_permanova(mat, meta; seed=123, blocks=individuals)
+            ref = _adonis2_reference(mat, meta,
+                                     "permute::how(blocks = factor(rep(paste0('i', 1:6), each = 2)), nperm = 999)")
+            @test res.blocked
+            # Six blocks of two admit 2^6 orderings, the observed one excluded.
+            @test res.permutations == 63
+            @test res.min_p_value ≈ 1 / 64
+            # group is constant within every individual, so within-block
+            # permutation never exchanges its labels. vegan still prints an
+            # ordinary-looking probability for it (the control: that is the
+            # number withheld here), but it does not test a group difference.
+            @test 0 < ref.p[1] <= 1
+            group = res.terms[1]
+            @test group.term == "group" && isnothing(group.p_value)
+            @test occursin("constant within every permutation block", group.untestable_reason)
+            @test isnothing(res.p_value) && res.untestable_reason == group.untestable_reason
+            @test group.r2 ≈ ref.r2[1]
+            @test occursin("withheld for group", res.text)
+            # run varies within individuals and is tested as vegan tests it.
+            run = res.terms[2]
+            @test run.term == "run" && isnothing(run.untestable_reason)
+            @test run.p_value == ref.p[2]
+            @test run.f_statistic ≈ ref.f[2]
+        end
+    end
+end
Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,7 @@ const UNIT_FILES = [`
`50`	`50`	`"test_sample_reads.jl",`
`51`	`51`	`"test_determinism.jl",`
`52`	`52`	`"test_differential.jl",`
	`53`	`+ "test_permanova.jl",`
`53`	`54`	`"test_write_gates.jl",`
`54`	`55`	`]`
`55`	`56`