LoRA Merge: Prove the Adapter Became Weights

A LoRA merge is not proven because merge_and_unload returned without an error. You need to recompute the adapter delta, compare active and merged outputs, reject non-finite values, and bind the standalone weight to its exact base and adapter identities.

LoRA merge begins with a pinned identity ledger

A trustworthy LoRA merge starts before multiplication. Record the exact base-model revision, adapter revision, target module path, tensor names, shapes, rank, alpha, scaling convention, source dtype, merge dtype, and serialization format. If any identity is floating, output agreement today cannot explain what a future loader will reconstruct.

For one linear layer, freeze a base weight W with shape out×in. The adapter supplies A with shape rank×in and B with shape out×rank. The update is ΔW=(alpha/rank)BA, and the standalone weight is W′=W+ΔW. Bias handling, fan-in/fan-out conventions, and module-specific transposition must be declared rather than inferred from filenames.

The original LoRA paper motivates low-rank updates and freezes the pretrained weights during adaptation. That evidence explains the factorization; it does not certify a particular exported checkpoint. A release receipt has to connect the paper-level equation to the tensors that were actually loaded.

The lab deliberately accepts small finite matrices, not arbitrary checkpoints. That bounded surface makes every product and sum visible, lets a separate oracle recompute the update, and turns identity drift into a failed hash instead of a mysterious downstream regression. The LoRA merge proof therefore begins with custody: exactly which base and adapter were combined under which arithmetic contract.

Recompute the low-rank update independently

Do not let the code that performs the LoRA merge also grade itself. The primary path multiplies B by A row by row, applies alpha/rank, then adds the result to W. The oracle traverses output coordinates, rank coordinates, and input coordinates in a separately written loop and compares each cell against the primary delta within a declared tolerance.

Shape checks come first. B columns must equal A rows; W rows must equal B rows; W columns must equal A columns; rank must equal the shared inner dimension; and alpha must be finite. Wrong BA order is often dimensionally impossible, but square fixtures can allow the bug to produce a plausible matrix. The test suite therefore includes a non-square case that kills order and transpose mistakes.

The scaling term is part of the adapter contract. Omitting alpha/rank may preserve direction while changing magnitude, which can look reasonable in a visual table. The receipt stores raw factors, scale, unscaled product, scaled delta, and merged weight so the discrepancy has nowhere to hide.

This arithmetic is adjacent to, but different from, QLoRA fine-tuning memory choices. Quantized training representations can reduce memory while a release merge still needs a declared reconstruction dtype. A tiny matrix proof establishes equation and implementation parity only; it does not establish that a full checkpoint used the same conventions everywhere.

Compare active-adapter and merged-model outputs

Weight parity becomes useful when it predicts the same layer output. For each frozen input vector x, the active path computes Wx plus the scaled adapter branch B(Ax). The merged path computes W′x. A valid LoRA merge makes those outputs agree within the tolerance appropriate to the declared arithmetic.

One vector is not enough. A zero vector can conceal every mistake, and a basis vector sees only one input column. The lab uses the zero vector, every basis vector, mixed-sign vectors, and one deterministic fractional vector. This set is still bounded, but it exposes each column plus cancellation and scale behavior. The single-vector-only mutant is killed by requiring the full suite.

Report maximum absolute error, maximum relative error with a safe denominator, and the exact vector and coordinate where each peak occurs. A single pass/fail light discards the evidence needed to debug a mismatch. Output rows also preserve active and merged values so a reviewer can determine whether the error is arithmetic, rounding, or identity drift.

The phrase merged model parity should remain scoped. Layer outputs on declared vectors are stronger than matching files by name, but weaker than whole-model generation equivalence. Tokenization, tied weights, nonlinear layers, cache behavior, runtime kernels, and sampling can introduce other differences. This stage proves the local algebra before a broader checkpoint evaluation begins.

Treat dtype and quantization as release policy

A LoRA merge performed in float64 for inspection, float32 for release, and low precision for storage describes three different numeric surfaces. The receipt must state where factors were decoded, where BA was accumulated, when rounding occurred, and which tolerance judged output parity. “Same model” is otherwise an ambiguous claim.

The lab offers named rounding modes that emulate a bounded release step. It never claims to reproduce a hardware kernel or a quantizer. The exact-quantized-merge mutant demands bitwise equality after rounding and is rejected because active and merged routes may round at different points while remaining within a justified tolerance. Conversely, a loose tolerance can bless a missing scale, so mutation fixtures constrain the acceptable range.

The PEFT checkpoint guide documents that adapter checkpoints retain adapter parameters and configuration rather than a complete base model; its checkpoint format guidance is an identity dependency for this workflow. Pin the library revision as well as the files because names, save behavior, and conventions can change.

A production export should also scan every resulting tensor for NaN and infinity before serialization. The NaN-accepted mutant demonstrates why comparisons alone are insufficient: many floating-point comparisons with NaN return false in ways that can bypass an incautious maximum calculation. Finiteness is a hard gate, not a metric to average.

Map merge_and_unload to the explicit proof

In PEFT LoRA workflows, merge_and_unload is convenient because it returns a model whose adapter contribution has been folded into base weights. Convenience does not remove the need to establish the function's preconditions and postconditions. Confirm that the intended adapter is active, target modules match the manifest, no unexpected adapter remains attached, and the resulting object can load without the adapter directory.

The PEFT LoRA API reference is the authority for the library surface, while the receipt owns the concrete run. Capture the callable path, library version, model class, selected adapter, safe-merge setting, device placement, and dtype. Then compare representative tensors against an independent reconstruction rather than trusting a success return.

Adapter merging should be reversible at the release-management level even when the numeric operation is not. Keep the base revision, adapter revision, unmerged evaluation record, and generated standalone artifact related by immutable identifiers. The merged file is a derived release, not a replacement for its ingredients.

For deployment selection, live model routing should point to that derived identity explicitly. A router label such as “support-model-latest” is not enough. The routing record, weight digest, tokenizer digest, configuration digest, and parity receipt should converge on one release identifier before traffic moves.

Build a tamper-evident LoRA merge receipt

Canonicalize the evidence rather than hashing whichever JSON formatting happened to be emitted. Sort object keys, preserve array order, reject non-finite numbers, and bind base identity, adapter identity, target path, shapes, scale, arithmetic policy, vectors, deltas, merged weights, output comparisons, tolerances, and invariant results into the digest.

The hash-missing-identities mutant constructs two receipts with identical toy matrices but different base or adapter identifiers. Their hashes must differ. This matters because arithmetic parity cannot reveal that the wrong source files happened to contain the same small fixture. Provenance belongs inside the signed payload, not beside it in a mutable filename.

Export both JSON and CSV. JSON preserves the structured proof; CSV provides a reviewable row per output coordinate plus a canonical JSON field. The validator reparses each download, reconstructs the calculation, recomputes the hash, and rejects a modified scale, identity, matrix cell, or pass flag. A download button alone is not evidence of a valid export.

The resulting digest can feed an AI model weight-signing workflow, but signing answers only who attested to these bytes and data. It cannot make an incomplete receipt complete. First bind the identities and parity evidence; then sign the release closure that includes the standalone model, configuration, tokenizer, license material, and evaluation references.

Kill mistakes that still look plausible

Good LoRA merge tests need negative controls chosen for plausible failure. Multiply A by B when square dimensions permit it. Omit alpha/rank. Transpose one factor. Demand exact equality after a named rounding step. Accept a NaN. Test only a zero vector. Remove source identities from the canonical hash. Every mutant should fail for a specific invariant or fixture.

Mutation results are more informative when they name the observation that killed them. Wrong order should disagree with the independent delta. Missing scale should exceed output tolerance. A transposed factor should fail shape validation or cell parity. NaN should trip the finiteness gate before metrics. The weak vector suite should fail coverage. Missing identities should produce a hash collision fixture.

Keep malformed-input cases separate from mutants. Empty matrices, ragged rows, zero rank, mismatched shapes, non-finite alpha, excessive dimensions, invalid tolerance, and an unknown rounding policy should all be rejected before work begins. The lab caps dimensions, vectors, and operations so an accidental paste cannot turn the browser into an unbounded matrix runner.

These tests establish that the proof surface is sensitive to the mistakes it names. They do not certify framework compatibility, file completeness, or downstream quality. That broader boundary prevents a green teaching lab from becoming a release claim it was never designed to support.

Release only after widening the evidence

Use the lab as the first rung. Next, enumerate every target tensor in the real adapter and compare its reconstructed delta with the merged checkpoint. Confirm the standalone load has no adapter dependency, compare representative hidden states or logits on a frozen prompt set, and run task evaluation against the unmerged active-adapter baseline.

The release gate should preserve the exact runtime and tolerance policy. If full-model output differs, localize the first divergent layer before relaxing thresholds. Check tied parameters, quantization boundaries, fan-in/fan-out settings, device casts, and modules excluded from the adapter manifest. A global text comparison is too late and too noisy to diagnose those causes. If the deployment keeps adapters separate, use multi-LoRA serving instead of pretending a standalone merge and routed adapters have the same custody model.

When parity passes, produce one closure: base digest, adapter digest, merged digest, tokenizer and configuration digests, tool revisions, tensor inventory, local arithmetic results, model-level comparisons, safety and quality evaluation references, and rollback target. A standalone file without that chain is deployable but not accountable.

The truth boundary remains strict. This toy LoRA merge proves bounded matrix arithmetic, declared-vector output parity, finiteness, export validation, and identity-bound hashing. It does not prove full-checkpoint completeness, generated-output quality, framework compatibility, quantized safety, or latency. Treat the receipt as permission to continue into those checks, not permission to skip them.

Runnable local artifact — Toy matrix parity does not prove full-checkpoint completeness, generated-output quality, framework compatibility, quantized safety, or latency.

Enter bounded W, A, B, alpha, vector probes, tolerance, base and adapter identities, and a named rounding policy; inspect delta and output parity, kill seven mutants, and validate JSON or CSV exports.