Metamorphic AD verification catalogue¶

This page is the operator-facing guide for gradient correctness beyond one-off examples: a versioned catalogue of metamorphic laws, fail-closed refuse paths (including invent-green hardware formal proofs), and pure residual band checks.

Related surfaces:

Transform algebra suite: scpn_quantum_control.differentiable_transform_algebra
Unsuitable / anti-silent fixtures: Unsuitable scenario registry
Module: scpn_quantum_control.metamorphic_ad_verification

Outcomes¶

Outcome	Meaning
`executable_local`	Pure residual APIs can evaluate pass/fail locally
`evidence_gated`	Claim maps to an in-tree audit suite; not invent-green without running it
`permanent_boundary`	Explicit refuse (anti-silent-wrong class)
`refuse_invent_green`	Marketing formal-proof / hardware ITP claims refused

Claim boundary:

metamorphic AD verification catalogue only; executable_local laws are pure or local residual checks, permanent_boundary and refuse_invent_green rows never promote hardware formal-proof or silent-wrong recovery claims

Public API¶

from scpn_quantum_control.metamorphic_ad_verification import (
    evaluate_linearity_residual,
    probe_metamorphic_law,
    build_metamorphic_ad_registry,
    assert_metamorphic_registry_integrity,
)

# Pure metamorphic residual (real shipped check)
lin = evaluate_linearity_residual(1.0, 2.0, 3.0)
assert lin.passed is True

# Anti-silent / invent-green refuse
boundary = probe_metamorphic_law("law:anti_silent.di_jl_compiled_tape")
assert boundary.refused is True
formal = probe_metamorphic_law("law:formal.hardware_interactive_proof")
assert formal.refused is True

# Unknown IDs fail closed
try:
    probe_metamorphic_law("law:missing")
except ValueError:
    pass

registry = assert_metamorphic_registry_integrity(build_metamorphic_ad_registry())

API reference¶

All public objects are exported by scpn_quantum_control.metamorphic_ad_verification; registry and to_dict() payloads contain JSON-ready primitives.

Types and constants¶

API	Contract
`LawKind`	Literal family: `metamorphic_identity`, `fd_agreement_band`, `anti_silent_wrong`, or `formal_boundary`.
`LawOutcome`	Literal outcome: `executable_local`, `evidence_gated`, `permanent_boundary`, or `refuse_invent_green`.
`METAMORPHIC_AD_VERIFICATION_SCHEMA`	Stable registry schema, currently `metamorphic_ad_verification.v1`.
`METAMORPHIC_AD_CLAIM_BOUNDARY`	Shared non-promotional boundary copied into rows, results, and registries.

Data models¶

MetamorphicLawRecord is a frozen, slotted catalogue row containing the law id, kind, expected outcome, relation, evidence-module pointers, reason, positive default tolerance, and claim boundary. Executable rows must have no reason; every non-executable row requires one. to_dict() serialises evidence modules as a list.

MetamorphicCheckResult is a frozen, slotted probe/residual result containing the law id, pass flag, optional residual and tolerance, operator message, refusal flag, and claim boundary. Refused results cannot pass; residuals must be non-negative and tolerances positive. to_dict() returns the complete JSON-ready result.

Catalogue and probes¶

Function	Behavior
`list_metamorphic_law_ids()`	Returns canonical ids in stable order.
`get_metamorphic_law(law_id)`	Returns one row; raises `ValueError` for blank or unknown ids.
`iter_metamorphic_laws(*, kind=None, expected_outcome=None)`	Returns rows satisfying both optional filters.
`probe_metamorphic_law(law_id, *, unknown_policy="raise")`	Returns deterministic catalogue metadata without running external evidence suites.

Known executable laws probe as ready for local residual evaluation, with passed=False and no residual until values are actually checked. Evidence-gated laws return passed=False, refused=False until their named suite is run. Permanent and invent-green boundaries return refused results. Unknown ids raise by default or return a structured refusal with unknown_policy="refuse"; other policy values raise ValueError.

Residual evaluators¶

evaluate_linearity_residual(f_a, f_b, f_ab, *, law_id=..., tolerance=None) evaluates abs((f_a + f_b) - f_ab). Its default band is 1e-12.

evaluate_chain_rule_residual(outer_at_inner, inner_derivative, composite_derivative, *, law_id=..., tolerance=None) evaluates abs(outer_at_inner * inner_derivative - composite_derivative). Its default band is 1e-10.

Both functions require their canonical executable law, finite numeric inputs, and a positive override tolerance. They return pass/fail results and perform no automatic differentiation, framework execution, or hardware work.

from scpn_quantum_control.metamorphic_ad_verification import (
    evaluate_chain_rule_residual,
    evaluate_linearity_residual,
)

assert evaluate_linearity_residual(1.0, 2.0, 3.0).passed
assert evaluate_chain_rule_residual(2.0, 3.0, 6.0).passed
assert not evaluate_linearity_residual(1.0, 2.0, 3.1).passed

Independent scalar conformance¶

IndependentConformanceProtocol declares the estimand, domain, oracle class and reference, SHA-256 digests of the exact oracle, input, product source and dataset objects, comparator version, runtime and positive finite absolute budget. Finite positive integer budgets are normalized to float before identity calculation; booleans, nonnumeric and overflowing values refuse at construction. Its identity includes every field. Record the source objects and derive the oracle independently; matching digest strings alone do not establish independence.

evaluate_independent_scalar_conformance compares observed primal and gradient values against separately supplied oracle values. It rejects non-finite values and accepts only analytic or numerical oracle classes. A wrong value returns a failed IndependentConformanceResult; it does not silently widen the budget. require_current_conformance checks that result against the current protocol identity and both residuals, so a changed source, dataset, comparator version or budget requires a new execution. Metamorphic, empirical and formal evidence need their own evaluation and cannot be promoted by this scalar comparator.

The dedicated test runs the public finite-difference owner for f(x)=x³ at x=2, comparing its actual result with the independently derived primal 8 and derivative 12. It also substitutes a wrong primal or derivative and verifies failure. The result supports only that input, float64 domain and declared error budget. Registering a law or importing an optional dependency does not execute a numerical comparison.

Registry and integrity¶

build_metamorphic_ad_registry() assembles the schema, claim boundary, law count, per-outcome counts, blank count, and canonical rows. assert_metamorphic_registry_integrity(payload=None) validates a supplied registry or builds the canonical one. It raises ValueError for empty or malformed rows, invalid outcomes, missing non-executable reasons, blanks, or inconsistent counts.

Safety and side effects¶

Catalogue, probe, residual and scalar-comparison APIs are pure and deterministic.
Evidence-module entries are pointers, not evidence that a suite passed.
No API runs AD frameworks, benchmarks, theorem provers, QPU/provider jobs, network calls, credential access, evidence mutation, or publication.
Passing a local residual is not a hardware formal proof, universal gradient guarantee, scientific promotion, or release approval.

Bounded product status¶

Shipped: versioned catalogue · pure residual checks · fail-closed probe · public docs.

Open: claim-ledger map generator · four full-suite integrations · CI drift job.

Authored by Anulum Fortis & Arcane Sapience (protoscience@anulum.li)