Publish verified Mamba2-8B Resurface adapter and reproducibility package

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -0,0 +1,201 @@
+---
+license: gpl-3.0
+language:
+  - en
+base_model: nvidia/mamba2-8b-3t-4k
+base_model_relation: adapter
+pipeline_tag: text-generation
+inference: false
+tags:
+  - mamba2
+  - state-space-model
+  - adapter
+  - resurface
+  - recall
+  - custom-runtime
+datasets:
+  - Salesforce/wikitext
+---
+
+# Mamb2_8B_Recall
+
+A **post-D Resurface-style readout adapter** for the uncompressed, pure
+[`nvidia/mamba2-8b-3t-4k`](https://huggingface.co/nvidia/mamba2-8b-3t-4k)
+language model. On the verified evaluation protocol, normal numeric multi-key
+recall improved from **147/384 (38.28%) to 365/384 (95.05%)**, while WikiText-2
+validation perplexity improved from **7.3341759473 to 7.0520635156**.
+
+This repository distributes the **2,374,143-byte adapter**, with 1,154,104 FP16
+parameters. Inference requires the separately downloaded 8B base weights and
+the custom native runtime. The adapter is not a standalone 2.37 MB language
+model, a PEFT checkpoint, or an `AutoModel.from_pretrained` package.
+
+Source and reproduction code:
+[`EndlessChasing/mamb2_8B_Recall`](https://github.com/EndlessChasing/mamb2_8B_Recall/tree/4478c034aff9e5dab7af47efa84214287824138d),
+pinned at commit `4478c034aff9e5dab7af47efa84214287824138d`.
+
+## Verified results
+
+| Model | WikiText-2 validation PPL | Normal MK | N=16 | N=64 | Target removed |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Base model in FP16 runtime | 7.334175947318572 | 147/384 (38.28%) | 113/192 | 34/192 | 0/384 |
+| Base model + this adapter | **7.052063515606311** | **365/384 (95.05%)** | **191/192** | **174/192** | 0/384 |
+
+PPL covers all **130 reset windows**, up to 2,048 next-token targets per window,
+and **264,764 targets** in the pinned WikiText-2 validation split. Each window
+starts with zero state and uses parallel SSD scan computation. MK uses three
+synthetic numeric templates, 16 or 64 key/value bindings, and prompt lengths
+of 257–1,236 tokens. Generation is greedy, at most 12 new tokens, over the full
+256K vocabulary; scoring matches the first standalone six-digit integer.
+The 384 normal prompts have 384 paired target-removed controls. MK uses native
+prefill followed by recurrent decoding with fresh FP16 cache.
+
+A fresh public GitHub clone was replayed on an RTX PRO 6000 Blackwell on
+2026-09-28. Across the two arms, all **260 per-window NLLs and 1,536 MK
+generation records matched exactly**. An independent audit recalculated the
+metrics, decoded generated token IDs and checked regenerated input identities.
+See the [verification report](https://github.com/EndlessChasing/mamb2_8B_Recall/blob/4478c034aff9e5dab7af47efa84214287824138d/docs/VERIFICATION.md)
+and its linked raw receipts.
+
+## Method and training
+
+The base has 56 Mamba2 blocks, 8 SSM groups, 8,236,999,680 parameters, and no
+attention or MoE blocks. Its official BF16 weights are cast to FP16 by the
+native runtime and frozen. The adapter modifies readout at the gated RMSNorm
+inputs, after the D skip term, with a learned head-mixing residual and a soft
+sigmoid gate. The same gate operates on prose and recall inputs. It adds no
+recurrent cache.
+
+This is a Resurface-style adaptation based on the
+[Resurface reference](https://github.com/Oso1106/Resurface-Multi-Binding-Recall-Is-Latent-in-Mamba-s-State),
+with a different insertion site. It is not an exact reproduction of the
+reference's private checkpoint, data or code.
+
+Training completed 1,536 successful AdamW updates with FP32 adapter masters,
+one pass over 1,536 synthetic numeric TRAIN examples, and paired prose from
+448 pinned WikiText-2 TRAIN windows. The objective combines recall answer CE,
+prose CE, KL to a separately loaded frozen base teacher, and a prose gate
+closure penalty. Six overflow retries occurred within the declared budget.
+The final step was the sole candidate. Full settings and source hashes are
+in the [frozen protocol](https://github.com/EndlessChasing/mamb2_8B_Recall/blob/4478c034aff9e5dab7af47efa84214287824138d/docs/PROTOCOL.md).
+
+## Download and use
+
+Use a Linux CUDA environment. The tested environment was Python 3.10.12,
+PyTorch 2.11.0+cu128, Mamba-SSM 2.3.2.post1, Triton 3.6.0, NumPy 1.26.4,
+datasets 4.8.5 and SentencePiece 0.2.1. Install CUDA-compatible PyTorch first;
+building Mamba-SSM requires a matching CUDA toolkit/compiler.
+
+```bash
+# Download the small adapter, runtime, scripts and verification receipts.
+hf download EndlessChasing/Mamb2_8B_Recall --local-dir mamb2-recall
+cd mamb2-recall
+python -m pip install -e .
+python -m pip install --no-build-isolation 'mamba-ssm==2.3.2.post1'
+
+# Separately download the original checkpoint and tokenizer (~16.48 GB).
+hf download nvidia/mamba2-8b-3t-4k \
+  release/mp_rank_00/model_optim_rng.pt \
+  mt_nlg_plus_multilingual_ja_zh_the_stack_frac_015_256k.model \
+  --revision b915550c63ba9359f88f44d1f6a600d85af27302 \
+  --local-dir models/source
+```
+
+The base loader verifies its pinned checkpoint/tokenizer hashes. Verify the
+adapter and use the project's runtime explicitly:
+
+```python
+from pathlib import Path
+import hashlib
+import torch
+from mamba2_recall import runtime, resurface_native
+from mamba2_recall.evaluation import generate_greedy
+
+adapter = Path("artifacts/source_resurface_v1/adapter_fp16.pt")
+assert hashlib.sha256(adapter.read_bytes()).hexdigest() == (
+    "e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0"
+)
+torch.backends.cuda.matmul.allow_tf32 = False
+torch.set_float32_matmul_precision("highest")
+tokenizer = runtime.SentencePieceTokenizer("models/source")
+model = runtime.load_source_model("models/source")
+payload = resurface_native.read_fp16(adapter)
+assert payload["binding"]["source_checkpoint_sha256"] == runtime.SOURCE_CHECKPOINT_SHA256
+
+prompt = "Key-value records:\n123456: 654321\n234567: 765432\n\nLookup the value for key 123456.\nValue:"
+with resurface_native.install_fp16(
+    model, adapter, expected_binding=payload["binding"]
+):
+    text, token_ids, prompt_tokens, cache_bytes = generate_greedy(
+        model, tokenizer, prompt, max_new_tokens=12, execution="prefill"
+    )
+    print(text)
+```
+
+This example shows the loading API; the small example prompt is not a reported
+benchmark result. Measured peak PyTorch CUDA allocation during paired
+evaluation was **17.08 GB** and during two-model training was **34.59 GB**.
+These measurements exclude some device and host overhead and are not minimum
+hardware requirements. Full base weights remain resident during inference.
+
+## Reproduce PPL and MK
+
+From the downloaded repository after the commands above:
+
+```bash
+CUDA_VISIBLE_DEVICES= python scripts/prepare_data.py \
+  --split confirm --source-dir models/source
+confirm_manifest_sha=$(python -c "import hashlib; from pathlib import Path; print(hashlib.sha256(Path('training_data/numeric_v1/confirm/manifest.json').read_bytes()).hexdigest())")
+python scripts/evaluate.py \
+  --source-dir models/source \
+  --adapter artifacts/source_resurface_v1/adapter_fp16.pt \
+  --data-root training_data/numeric_v1 \
+  --eval-manifest-sha256 "$confirm_manifest_sha" \
+  --split confirm \
+  --report reports/hf_adapter_evaluation.json
+```
+
+This evaluates the base and serialized adapter in the same process, with full
+PPL and both MK conditions, then checks baseline restoration after removing
+the adapter. The output path must be new. The preparation script and evaluator
+validate frozen data content; use the newly generated manifest's SHA because
+its Python build metadata may vary. See the
+[reproduction guide](https://github.com/EndlessChasing/mamb2_8B_Recall/blob/4478c034aff9e5dab7af47efa84214287824138d/docs/REPRODUCE.md)
+for training and the independent saved-report audit.
+
+`resurface_config.json` describes this custom adapter format and its base
+binding; it is not a Transformers or PEFT configuration. The release includes
+`checksum_manifest.json` for checking its packaged files.
+
+## Limitations
+
+- The numeric CONFIRM instances/template family and WikiText-2 validation
+  corpus had been observed during earlier project development. The reported
+  results establish performance on this specified replay protocol, rather
+  than an untouched holdout. TRAIN and CONFIRM numeric identities were
+  separately checked to be disjoint.
+- Unseen template families, longer recall distances, full 4K recall, other
+  languages, broad downstream task quality and untouched prose have not been
+  established by these measurements.
+- Target-removed 0/384 means the absent answer was not recovered; it does not
+  measure calibrated refusal behavior.
+- The runtime casts the official BF16 source to FP16. Native Megatron BF16
+  parity and tokenwise FP16-state-rounding PPL have not been established.
+- Exact replay was observed in the recorded environment. Other GPU, CUDA,
+  PyTorch or Mamba kernel versions can change numerical outputs.
+- The published adapter is bound to the specified uncompressed source.
+  Transfer to a quantized or different checkpoint needs separate validation.
+
+## License and attribution
+
+The `gpl-3.0` card metadata reflects this release's existing GitHub repository
+license; see the bundled `LICENSE`. The custom runtime derives from the
+associated [E8/W5 project](https://github.com/EndlessChasing/mamba2-8b-e8w5).
+The original NVIDIA model is downloaded separately under its Apache-2.0
+license, and its own model card and terms apply to those base weights.
+This release does not redistribute those weights. The metadata does not
+relicense the NVIDIA model or create an additional adapter-specific license.
+
+Method credit: [Resurface — Multi-Binding Recall Is Latent in Mamba's State](https://github.com/Oso1106/Resurface-Multi-Binding-Recall-Is-Latent-in-Mamba-s-State).
+Implementation and experiment details are available in the pinned GitHub
+repository linked above.

artifacts/source_resurface_v1/adapter_fp16.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0
+size 2374143

checksum_manifest.json

@@ -0,0 +1,173 @@
+{
+  "format": "MAMBA2_RESURFACE_HF_CHECKSUM_MANIFEST_V1",
+  "repo_id": "EndlessChasing/Mamb2_8B_Recall",
+  "source_commit": "4478c034aff9e5dab7af47efa84214287824138d",
+  "scope": "All distributed files except this checksum manifest itself",
+  "files": [
+    {
+      "path": ".gitattributes",
+      "bytes": 41,
+      "sha256": "4009e8f5faf67ca3607a646c9b12350d8237e344e6853c59bf9dbad697db3952"
+    },
+    {
+      "path": "LICENSE",
+      "bytes": 35149,
+      "sha256": "3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986"
+    },
+    {
+      "path": "README.md",
+      "bytes": 9722,
+      "sha256": "6cccc0796a4e8e843fd1c086298fff0b6b9b57f7cf6d93e518942be3cbcb8519"
+    },
+    {
+      "path": "artifacts/source_resurface_v1/adapter_fp16.pt",
+      "bytes": 2374143,
+      "sha256": "e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0"
+    },
+    {
+      "path": "docs/PROTOCOL.md",
+      "bytes": 4537,
+      "sha256": "dee9457bfaca067b63837dcd3bc94bf9ef9a3d805b1ab04227db05a4b92c54c2"
+    },
+    {
+      "path": "docs/REPRODUCE.md",
+      "bytes": 3393,
+      "sha256": "8e993bc5745875e16580d41ad3f47345c137ef5c50834435f931902bc533556c"
+    },
+    {
+      "path": "docs/RESULTS.md",
+      "bytes": 3620,
+      "sha256": "16cbb30bb287abfffa01b52948b4f7afcd195257d294848610c9ad4924165e16"
+    },
+    {
+      "path": "docs/VERIFICATION.md",
+      "bytes": 5405,
+      "sha256": "53e16aace1f7eb0f7da9c1c313fcc58a3bbc8873f3a75b984a820bf84f18efa9"
+    },
+    {
+      "path": "docs/confirm_manifest.json",
+      "bytes": 2411,
+      "sha256": "227737dd5fbb301d76e583457ff8ee29246047661b3e9a64ebd068a6f34f376c"
+    },
+    {
+      "path": "docs/prose_train_manifest.json",
+      "bytes": 126611,
+      "sha256": "facb2ca461615a4199781bd21784d642d6674f5b862641b3b9edac3fb499b89d"
+    },
+    {
+      "path": "mamba2_recall/__init__.py",
+      "bytes": 56,
+      "sha256": "79b32606ac476c3248911c55571bf97f96689770067856ce8347837478ef33fd"
+    },
+    {
+      "path": "mamba2_recall/calibration.py",
+      "bytes": 1941,
+      "sha256": "54e178521abfe2513fb7bac2aed2ef178fc01b63135222ecc212001ee3ce0a04"
+    },
+    {
+      "path": "mamba2_recall/evaluation.py",
+      "bytes": 10299,
+      "sha256": "95cba0b201e37f92e6cbfadb9b3e9d79ba7b0cdc9efda6a58a6216b0d84d35e0"
+    },
+    {
+      "path": "mamba2_recall/resurface_data.py",
+      "bytes": 21740,
+      "sha256": "1a547fe3cedca406d6e3db85f65c3ce554558691e3b29b9c92d8fd6bd1c1ba35"
+    },
+    {
+      "path": "mamba2_recall/resurface_loss.py",
+      "bytes": 10656,
+      "sha256": "ec045368583b6e49f484341b2d718658bb59e8d11050710377742752c1c67294"
+    },
+    {
+      "path": "mamba2_recall/resurface_native.py",
+      "bytes": 28603,
+      "sha256": "2dd08c7ee8958c832f0ae9da7cf5f261dceeff3e528e493c905c7c52df7166d7"
+    },
+    {
+      "path": "mamba2_recall/runtime.py",
+      "bytes": 9912,
+      "sha256": "73a405b4286dda403f252cf0b73d367adcfead96298a1e6f440b65f5b309530c"
+    },
+    {
+      "path": "pyproject.toml",
+      "bytes": 398,
+      "sha256": "6378c4de2788a21d36d6e5a96aba9c2277158c9eb1ff3252d8e155f6a998da0b"
+    },
+    {
+      "path": "reports/four_arm_comparison_v1.json",
+      "bytes": 1965,
+      "sha256": "d4b75b7a68028e36e93130cd31d3400442fb83e4bff30f67a011702598983e20"
+    },
+    {
+      "path": "reports/source_resurface_v1_confirm_full.json",
+      "bytes": 1123173,
+      "sha256": "4c99694d66af1db71924bd9d3113f1ea2f0a9b93191ed229f3d26f2320c8c940"
+    },
+    {
+      "path": "reports/source_resurface_v1_train.json",
+      "bytes": 837067,
+      "sha256": "72c5c46ffff8e9981b8747a2fe10cb9ab67695d1555f2deb43d497ec7caed5e1"
+    },
+    {
+      "path": "reports/verification_audit_v1.json",
+      "bytes": 53942,
+      "sha256": "16ab2fcf54b3786554b9d45770c1818f715d54c6fc0d61a295aa38cffd17ca91"
+    },
+    {
+      "path": "reports/verification_hub_metadata_v1.json",
+      "bytes": 739,
+      "sha256": "194839dc297df34b749a69d7ddfd9b4f62c3d733b0918e43eddad6cf6b76bbd8"
+    },
+    {
+      "path": "reports/verification_origin_v1.json",
+      "bytes": 2286,
+      "sha256": "53fdecf6395bf9ebdf2d0e04be816ba0906aab4f1df761c088aac6fc85f852e6"
+    },
+    {
+      "path": "reports/verification_replay_v1.json",
+      "bytes": 1123172,
+      "sha256": "a83faedb5f25150ff8c3bf93a312619c11191e5dd06677d236cb7658c8173779"
+    },
+    {
+      "path": "reports/verification_token_receipts_v1.json",
+      "bytes": 827,
+      "sha256": "ec95ed2c5a1bfb04a9aa0f538cf2f9c5fd881549e012cc26bbf67736b8ae1d6f"
+    },
+    {
+      "path": "resurface_config.json",
+      "bytes": 2903,
+      "sha256": "08f481f3218092abd1d1b68935ca641dd1239b80ffd25e9b3ac96dd4655ac96d"
+    },
+    {
+      "path": "scripts/compare_four_arms.py",
+      "bytes": 5376,
+      "sha256": "6e41f9ab4f6e39c5a23da6ad1edc29e5b10da57e93e2ea008f4d153c8f195e3b"
+    },
+    {
+      "path": "scripts/evaluate.py",
+      "bytes": 8114,
+      "sha256": "825acc58d957abe9c755b44c783970c7a379594dfd15e0a67f0ff9a0638f74bb"
+    },
+    {
+      "path": "scripts/prepare_data.py",
+      "bytes": 1815,
+      "sha256": "11d5e6872382fb8a62987937ec37006422b38e4b1650431a4794d5834c6a4604"
+    },
+    {
+      "path": "scripts/prepare_prose.py",
+      "bytes": 2371,
+      "sha256": "f63659bab565f2428629f2c9239ba2bdb4ccfb6c647accc44be71b2f419a7c7e"
+    },
+    {
+      "path": "scripts/train.py",
+      "bytes": 12177,
+      "sha256": "3ea5ef8beadf5d4f14650e9fe15949cd6116e247ddd7641d7f024c5763aa8eb2"
+    },
+    {
+      "path": "scripts/verify_replay.py",
+      "bytes": 28920,
+      "sha256": "8b08f0e9f8e8f5239764646e44c816dfb8ba9987ffb1c6dd936aea90ed652b2f"
+    }
+  ]
+}

docs/PROTOCOL.md

@@ -0,0 +1,77 @@
+# Full precision Mamba2-8B Resurface control
+
+Declared 2026-09-28 before fitting this repository's adapter. The purpose is to
+measure the effect of the same readout adapter and training budget on NVIDIA's
+uncompressed pure Mamba2-8B. The E8/W5 experiment is a historical comparator,
+not a training dependency. All metrics are reported at the actually measured
+precision and protocol, without assuming equality to native Megatron BF16.
+
+## Frozen model and intervention
+
+Load `nvidia/mamba2-8b-3t-4k` revision
+`b915550c63ba9359f88f44d1f6a600d85af27302`, checkpoint SHA256
+`47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb`
+and tokenizer SHA256
+`5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09`.
+Cast the 507 original BF16 tensors to FP16 in the native state-spaces Mamba2
+runtime; freeze all 8,236,999,680 base parameters. Verify strict source tensor
+mapping, model geometry and no shared embedding/output storage.
+
+Use the same post-D adapter as the compressed experiment at all 56 native
+gated RMSNorm inputs: `y + sigmoid(w dot u+b) * g*(V@y)` across 128 heads.
+Its 224 tensors contain 1,154,104 FP32 trainable master parameters, exported
+as FP16 for inference. Initialize V=0, g=1, w=0, b=-4; use soft sigmoid at
+train and eval, no task switch, EMA, or new recurrent cache. The adapter is
+external to the frozen base; check its identities and absence of base grads.
+
+## Training
+
+Reuse the *same exact data generator contract and seeds* as the compressed
+adapter: 1,536 TRAIN numeric bindings over three templates and N=16/64,
+disjoint six-digit key/value intervals; full 256K CE on every answer suffix
+token. Use seed 2026092803 and `torch.randperm(1536)` once for example order.
+Each step pairs one MK example with a 512-token segment from the already
+prepared 448 WikiText-2 TRAIN windows. Their historical manifest and file
+SHA256 are pinned by the train command. Heldout and validation windows are
+not included in training. Reusing this fixed TRAIN text gives the control the
+same training exposures as the compressed arm.
+
+Use a second, independently loaded **uncompressed FP16** model as the frozen
+prose teacher. This is the direct counterpart to the compressed experiment's
+teacher, which was its own unadapted compressed base. The fixed per-step loss is
+`MK answer CE + 0.5 prose CE + 0.5 KL(own unadapted teacher || student) + 3 C`,
+where C is the same prose-only router closure, with budget 0.006 and excess
+coefficient 10. Temperature 1, 511 prose targets per step, 64-token staged
+head chunks, and one optimizer update after both task gradients.
+
+AdamW FP32 masters: V/g LR 1e-4, w/b LR 3e-4, betas (.9,.999), eps 1e-8,
+weight decay 0, clip norm 1. Multiplicative schedule
+`0.1+0.9*(1+cos(pi*j/1535))/2` at successful index j. Native FP16 forward,
+block checkpointing, gradient scale 1024 with growth interval 2000. Overflow
+retries the exact same pair without optimizer/master update, at most 8 retries
+and 1,544 total attempts. Run 1,536 **successful** updates; the final step is
+the only candidate. Small GPU smokes are discarded before formal training.
+
+## Evaluation and interpretation
+
+After training, restore the actual serialized FP16 adapter onto the same
+uncompressed base. Evaluate baseline, adapter enabled and restored baseline
+in a single process, with identical tokenizer, MK prompts and full WikiText-2
+validation windows. For MK use full 256K greedy generation up to 12 tokens,
+first standalone six-digit number, normal and target-removed controls, native
+prefill plus recurrent decode with fresh FP16 cache. For PPL use all 130
+nonoverlapping reset windows and all 264,764 next-token targets. Record all
+raw scores, differences and file hashes; no early selection or task switch.
+
+The earlier compressed arm's independent CONFIRM set has now been observed and
+uses the same three template families. Running this source control on it gives
+a matched historical comparison, **not a newly untouched holdout**. The
+WikiText-2 validation text also informed earlier development. We will not
+promote a source+adapter result to a general recall conclusion without new
+templates, longer distances and a truly untouched corpus.
+
+Report all four observed arms explicitly: source FP16, source+adapter,
+compressed/readapted, compressed/readapted+adapter. The source and compressed
+teachers differ by construction. Report PPL and recall together; any cross-arm
+claim remains limited by shared test protocols and the historical numerical
+replay discrepancy in the compressed project.

docs/REPRODUCE.md

@@ -0,0 +1,67 @@
+# Reproduce the source control
+
+Use the verified NVIDIA `nvidia/mamba2-8b-3t-4k` source checkpoint and
+tokenizer revision recorded in [PROTOCOL.md](PROTOCOL.md). The source model
+is downloaded separately; the repository supplies the 2.37 MB adapter.
+The measured environment was PyTorch 2.11.0+cu128, `mamba-ssm`
+2.3.2.post1, `sentencepiece` 0.2.1 and `datasets` 4.8.5 on an RTX PRO 6000
+Blackwell. `train.py` loads two FP16 copies of the source, so its measured
+peak PyTorch CUDA allocation was 34.59 GB.
+
+Install a CUDA-compatible PyTorch first. The native GPU extension is a
+separate prerequisite; `pip install -e .` alone does not install it:
+
+```bash
+python -m pip install -e .
+python -m pip install --no-build-isolation 'mamba-ssm==2.3.2.post1'
+```
+
+Building the extension requires a matching CUDA toolkit/compiler. Use the
+package versions in the [verification environment receipt](../reports/verification_origin_v1.json) when comparing
+numerical replay results.
+
+From the repository root, replace `/path/to/source` with the directory
+containing the official source checkpoint and tokenizer:
+
+```bash
+CUDA_VISIBLE_DEVICES= python scripts/prepare_prose.py \
+  --source-dir /path/to/source \
+  --out training_data/prose/training_tokens.pt
+CUDA_VISIBLE_DEVICES= python scripts/prepare_data.py \
+  --split train --source-dir /path/to/source
+CUDA_VISIBLE_DEVICES= python scripts/prepare_data.py \
+  --split confirm --source-dir /path/to/source
+train_manifest_sha=$(python -c "import hashlib; from pathlib import Path; print(hashlib.sha256(Path('training_data/numeric_v1/train/manifest.json').read_bytes()).hexdigest())")
+confirm_manifest_sha=$(python -c "import hashlib; from pathlib import Path; print(hashlib.sha256(Path('training_data/numeric_v1/confirm/manifest.json').read_bytes()).hexdigest())")
+python scripts/train.py \
+  --source-dir /path/to/source \
+  --data-root training_data/numeric_v1 \
+  --train-manifest-sha256 "$train_manifest_sha" \
+  --prose-manifest docs/prose_train_manifest.json \
+  --prose-tokens training_data/prose/training_tokens.pt \
+  --out-dir artifacts/reproduction_1
+python scripts/evaluate.py \
+  --source-dir /path/to/source \
+  --adapter artifacts/reproduction_1/adapter_fp16.pt \
+  --data-root training_data/numeric_v1 \
+  --eval-manifest-sha256 "$confirm_manifest_sha" \
+  --split confirm \
+  --report reports/reproduction_1.json
+```
+
+Use the hashes of your newly prepared manifests (also printed by preparation).
+Manifests record `sys.version`, so a different Python build can change the
+whole-file hash even when all generated prompts and tokens are identical.
+The historical hashes remain in the published reports as run receipts. The
+loaders independently check the frozen generator, tokenizer, protocol and
+all generated raw/token data; computing the local manifest hash does not
+replace those content checks. All scripts
+refuse to overwrite existing result paths. To score the published adapter
+without retraining, use
+`artifacts/source_resurface_v1/adapter_fp16.pt` with `scripts/evaluate.py`.
+For the four-arm comparison, supply the two historical compressed reports to
+`scripts/compare_four_arms.py`; it verifies their SHA-256 values and every
+MK/PPL input identity before computing the table.
+
+Reproduction may differ numerically across CUDA, PyTorch and Mamba kernel
+versions. The published reports retain the actual tested output and hashes.

docs/RESULTS.md

@@ -0,0 +1,61 @@
+# Mamba2-8B source Resurface control: completed results
+
+This is a **post-D Resurface-style adapter** on the uncompressed, pure NVIDIA
+Mamba2-8B source. The official BF16 checkpoint is cast to FP16 in the native
+Mamba2 runtime. All 8,236,999,680 base parameters stay frozen. The serialized
+adapter contains 1,154,104 FP16 parameters across 56 layers and is
+[2,374,143 bytes](../artifacts/source_resurface_v1/adapter_fp16.pt).
+
+## Matched four-arm comparison
+
+All four arms were checked against the same 768 tokenized MK prompts and the
+same 130 WikiText-2 validation windows (264,764 next-token targets). For MK,
+the denominator is 384 normal prompts and 384 target-removed controls per arm.
+
+| Arm | Normal MK | Target removed | WikiText-2 PPL |
+| --- | ---: | ---: | ---: |
+| Source FP16 | 147/384 (38.28%) | 0/384 | 7.33418 |
+| Source FP16 + Resurface | **365/384 (95.05%)** | 0/384 | **7.05206** |
+| E8/W5 compressed, readapted base | 91/384 (23.70%) | 0/384 | 7.62240 |
+| E8/W5 compressed, readapted base + Resurface | 340/384 (88.54%) | 0/384 | 7.59316 |
+
+On the source, the adapter gained 222 previously wrong normal prompts and lost
+4 previously correct prompts: net +218/384, or **+56.77 percentage points**.
+Its PPL changed by -0.28211 (-3.85%). The compressed arm's normal recall gain
+was +249/384 (+64.84 points), with a PPL change of -0.02923 (-0.38%). The
+8.07-point difference between these *gains* is descriptive; it does not
+isolate the effect of quantization, since the compressed base also had 448
+small-tensor readaptation updates and the two adapters used different frozen
+base teachers for their KL losses.
+
+## Run and verification
+
+- Final candidate: 1,536 successful optimizer updates, 1,542 attempts, six
+  numerical overflow retries within the frozen eight-retry budget. All 1,536
+  TRAIN examples appeared once; no checkpoint was chosen using validation.
+- Four saved optimizer checkpoints independently matched their recorded
+  SHA-256 values. The final adapter passed exact FP16 tensor roundtrip and
+  source-checkpoint binding checks. Adapter SHA-256:
+  `e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0`.
+- Evaluation loaded the **serialized** adapter, scored source and adapter in
+  one process, then removed it. The first eight baseline MK outputs were
+  reproduced exactly after removal. Frozen-base parameter identity, version
+  counters and absence of gradients were checked; a full bytewise rescan of
+  all 16 GB of base weights was not performed.
+- `compare_four_arms.py` required exact ordered prompt token hashes for all
+  768 MK rows and exact token hashes for every PPL window across all four
+  arms. Both checks passed. The old compressed reports were also verified by
+  their pinned SHA-256 values.
+- Peak PyTorch CUDA allocation was 34.59 GB during two-model training and
+  17.08 GB during single-model paired evaluation. These are GPU allocation
+  measurements, not total device or host memory requirements.
+
+The [protocol](PROTOCOL.md) was frozen before this adapter was trained. Raw
+[training](../reports/source_resurface_v1_train.json),
+[paired evaluation](../reports/source_resurface_v1_confirm_full.json) and
+[four-arm comparison](../reports/four_arm_comparison_v1.json) reports are
+included for audit. The numeric CONFIRM template family and instances had
+already been observed in the earlier compressed project, and WikiText-2
+validation was used in prior development. These results establish performance
+on this specified replay protocol; they do not establish generalization to
+unseen template families, longer recall distances, or untouched prose.

docs/VERIFICATION.md

@@ -0,0 +1,97 @@
+# Independent verification of published PPL and MK
+
+The published adapter and metrics at commit
+`e4137a43ef87cb95b70243ea2271f8e9b3d93d27` passed a fresh GPU replay on
+2026-09-28. A new, clean clone was downloaded from public GitHub, all Python
+source hashes were compared with that commit, and the numeric CONFIRM data
+were regenerated. The adapter SHA-256 was
+`e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0`.
+The original reports were retained.
+
+| Arm | WikiText-2 validation PPL | Normal MK | N=16 | N=64 | Target removed |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Source FP16 | 7.334175947318572 | 147/384 | 113/192 | 34/192 | 0/384 |
+| Source FP16 + Resurface | 7.052063515606311 | 365/384 | 191/192 | 174/192 | 0/384 |
+
+The replay was **exact for the measured outputs**: both arms matched every
+one of their 130 per-window NLLs, with maximum absolute NLL error 0, and all
+768 MK generated-token sequences, decoded strings, predictions and correctness
+flags. The final eight baseline probes after adapter removal also matched.
+Across the two arms, this covers 260 PPL windows and 1,536 MK generations.
+Run timestamps and GPU memory receipts are separate from this equality claim.
+
+Normal MK increased by 218/384, or 56.77 percentage points: 222 previously
+wrong cases became correct and four previously correct cases became wrong.
+PPL decreased by 0.2821124317, or 3.8465%, on this validation protocol.
+
+## Checks independent of the inference loop
+
+- A standard-library audit recomputed PPL as `exp(sum(NLL)/sum(targets))`
+  from every window and rescored each output string with the declared
+  six-digit matcher. It checked exact input identities, paired gains/losses,
+  summary arithmetic and the actual adapter file SHA. Its 17 self-tests
+  exercise corrupt identities, wrong counts, numerical drift and receipt
+  preservation.
+- A separate CPU pass used the pinned SentencePiece tokenizer to decode all
+  3,088 saved output records across the original/replay reports, including
+  restoration probes. It regenerated and checked their prompt token hashes
+  and expected answers. All 520 PPL window receipts across both reports and
+  arms were checked against newly loaded, pinned WikiText tokens. There were
+  zero mismatches.
+- Regenerating the 1,536 numeric TRAIN examples and 768 CONFIRM rows found
+  zero shared case IDs, prompts, record keys or record values between those
+  splits. The training receipt contains exactly one successful update for
+  each TRAIN example and six overflow retries.
+- The pinned NVIDIA model revision and WikiText revision resolved on the
+  Hugging Face Hub. Official model/tokenizer LFS SHA-256 values matched the
+  runtime pins. The GPU loader verifies the 16,474,189,490-byte checkpoint
+  before strict tensor mapping into the native model.
+
+The actual environment was Python 3.10.12, PyTorch 2.11.0+cu128, Mamba-SSM
+2.3.2.post1, Triton 3.6.0, NumPy 1.26.4, datasets 4.8.5 and SentencePiece
+0.2.1 on an RTX PRO 6000 Blackwell Server Edition, with TF32 matmul disabled.
+
+## Receipts and reproduction
+
+- [Fresh GPU replay](../reports/verification_replay_v1.json)
+- [Independent metric and exact-output audit](../reports/verification_audit_v1.json)
+- [Tokenizer and regenerated-input checks](../reports/verification_token_receipts_v1.json)
+- [Clean-clone origin, source hashes, command and environment](../reports/verification_origin_v1.json)
+- [Pinned official Hub metadata](../reports/verification_hub_metadata_v1.json)
+
+Recheck the saved reports without a GPU or PyTorch:
+
+```bash
+python3 scripts/verify_replay.py \
+  --published reports/source_resurface_v1_confirm_full.json \
+  --replay reports/verification_replay_v1.json \
+  --adapter artifacts/source_resurface_v1/adapter_fp16.pt \
+  --output reports/my_verification_audit.json
+```
+
+An audit exit code of zero means internally valid reports; inspect
+`exact_replay` and `status` for equality. Valid numerical differences are
+reported explicitly. The script refuses to overwrite an existing receipt.
+For a fresh GPU run, follow [REPRODUCE.md](REPRODUCE.md) with a new output path.
+
+The review found a documentation portability defect: numeric manifests embed
+the Python build string, so their whole-file SHA can differ even for identical
+data. The reproduction commands now use each newly generated manifest's SHA;
+the loaders still validate the frozen generator, tokenizer, protocol and all
+raw/token content. The docs also clarify the separate native Mamba extension
+installation. Neither change alters the measured model or scoring protocol.
+
+## Scope
+
+PPL uses WikiText-2 **validation**, 130 reset windows of up to 2,048 next-token
+targets (264,764 targets total), with parallel SSD scan precision. The model
+is the official BF16 source cast to FP16 in the native runtime; this does not
+establish native Megatron BF16 parity or tokenwise FP16-state rounding.
+
+MK uses three synthetic numeric templates with 16 or 64 bindings and prompt
+lengths of 257-1,236 tokens. The CONFIRM instances and validation corpus had
+been observed during earlier development. Exact replay confirms these
+reported scores, not unseen-template or full-4K recall generalization.
+Target-removed 0/384 means the absent answer was not recovered; it is not a
+refusal-calibration metric. Base freezing was checked by identities, version
+counters and gradients, not a complete post-training bytewise weight scan.

docs/confirm_manifest.json

@@ -0,0 +1 @@
+{"answer_target_tokens":0,"answer_token_count_histogram":{},"automatic_bos_eos":false,"complete":true,"confirmation_loaded_for_training":false,"contract":{"control_key_base":490000,"control_value_base":990000,"key_range":[400000,480000],"normal_count":384,"positions":"floor(sample*(N-1)/63)","removed_count":384,"samples_per_cell":64,"seed":2026092802,"value_ranges":[[691000,700000],[791000,800000],[891000,900000],[991000,1000000]]},"evaluation_supervised_targets_stored":false,"files":{"raw.jsonl":{"bytes":1465048,"sha256":"7af8c4721ada3b9813e4ea6a6b14a53efc4cda56c2406d90dc17a967c74d2ef2"},"tokens.jsonl":{"bytes":3607304,"sha256":"f7e00c83ad20a1aa910587d8de28ca4ceef679f3ad8dff16b3d9ac8f2c63a00f"}},"format":"MAMBA2_RESURFACE_NUMERIC_DATA_V1","full_vocabulary":256000,"helper_source_sha256":"1a547fe3cedca406d6e3db85f65c3ce554558691e3b29b9c92d8fd6bd1c1ba35","prompt_tokens_max":1236,"prompt_tokens_total":517120,"proof":{"exact_binding_and_control_absence":true,"normal_count":384,"raw_rows_sha256":"7af8c4721ada3b9813e4ea6a6b14a53efc4cda56c2406d90dc17a967c74d2ef2","removed_count":384,"split":"confirm","template_scope":"Same three template families; only instances/key-value ranges are separated.","unique_prompts":768},"protocol_sha256":"dee9457bfaca067b63837dcd3bc94bf9ef9a3d805b1ab04227db05a4b92c54c2","public_generator_sha256":null,"python_version":"3.10.12 (main, Mar  3 2026, 11:56:32) [GCC 11.4.0]","row_count":768,"sizes":[16,64],"split":"confirm","templates":[0,1,2],"tokenizer_sha256":"5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09","value_pool_statistics":{"bands":[{"binding_value_occurrences":3898,"pool_cardinality":9000,"range_half_open":[691000,700000],"target_value_occurrences":90},{"binding_value_occurrences":3869,"pool_cardinality":9000,"range_half_open":[791000,800000],"target_value_occurrences":101},{"binding_value_occurrences":3826,"pool_cardinality":9000,"range_half_open":[891000,900000],"target_value_occurrences":98},{"binding_value_occurrences":3767,"pool_cardinality":9000,"range_half_open":[991000,1000000],"target_value_occurrences":95}],"normal_binding_value_occurrences":15360,"normal_target_value_occurrences":384,"paired_removed_controls_included_in_draw_totals":false,"pool_cardinality":36000,"sampling":"Uniform without replacement within each prompt over the pooled bands; not exact per-prompt band balancing.","unique_normal_values":12602}}

mamba2_recall/__init__.py

@@ -0,0 +1 @@
+"""Full-precision Mamba2-8B Resurface readout study."""

mamba2_recall/calibration.py

@@ -0,0 +1,47 @@
+"""Pinned WikiText tokenization and window selection for recall controls."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import time
+from pathlib import Path
+
+import torch
+
+from .runtime import (MODEL_CONFIG, SOURCE_CHECKPOINT_SHA256, SentencePieceTokenizer,
+                      environment_receipt, gpu_memory_receipt, load_source_model, sha256_file, token_digest)
+
+WIKITEXT_REVISION = "b08601e04326c79dfdd32d625aee71d232d685c3"
+
+
+def window_starts(token_count, seqlen, nwin, offset=0):
+    """Evenly spread, nonoverlapping windows; never silently reuse short data."""
+    usable = token_count - offset
+    if seqlen <= 0 or nwin <= 0 or usable < seqlen * nwin:
+        raise ValueError("Insufficient tokens for the requested nonoverlapping windows")
+    if nwin == 1:
+        return [offset]
+    span = usable - seqlen
+    starts = [offset + (index * span) // (nwin-1) for index in range(nwin)]
+    if any(b-a < seqlen for a, b in zip(starts, starts[1:])):
+        raise ValueError("Calibration windows overlap")
+    return starts
+
+
+def load_wikitext_tokens(tokenizer, split, revision=WIKITEXT_REVISION):
+    from datasets import load_dataset
+    kwargs = {"revision": revision} if revision else {}
+    dataset = load_dataset("Salesforce/wikitext", "wikitext-2-raw-v1", split=split, **kwargs)
+    text = "\n\n".join(dataset["text"])
+    ids = tokenizer.encode(text)
+    metadata = {
+        "dataset": "Salesforce/wikitext", "configuration": "wikitext-2-raw-v1",
+        "split": split, "revision_argument": revision, "dataset_fingerprint": dataset._fingerprint,
+        "document_join": "two newline characters", "text_sha256": hashlib.sha256(text.encode()).hexdigest(),
+        "token_stream_sha256_int64le": token_digest(ids), "total_tokens": len(ids),
+        "tokenizer_sha256": tokenizer.sha256, "automatic_special_tokens": False,
+    }
+    return torch.tensor(ids, dtype=torch.long), metadata
+
+

mamba2_recall/evaluation.py

@@ -0,0 +1,190 @@
+"""Frozen prose PPL and a public synthetic multi-key recall protocol.
+
+This MK protocol is new and is not interchangeable with private Resurface scores.
+Use --execution tokenwise to round the recurrent FP16 state after every token.
+The faster prefill protocol is reported separately and is never called tokenwise.
+The source-only experiment uses these scoring functions with an external adapter.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import random
+import re
+import time
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+
+from .calibration import WIKITEXT_REVISION, load_wikitext_tokens, window_starts
+from .runtime import (SOURCE_CHECKPOINT_SHA256, SentencePieceTokenizer, backbone_tokenwise,
+                      cache_bytes, load_source_model, make_cache,
+                      environment_receipt, gpu_memory_receipt, sha256_file, token_digest)
+
+
+def ppl_windows(ids, seqlen, nwin=None):
+    if nwin is not None:
+        starts = window_starts(len(ids), seqlen+1, nwin)
+        return [(start, ids[start:start+seqlen+1]) for start in starts]
+    return [(start, ids[start:min(start+seqlen+1, len(ids))])
+            for start in range(0, len(ids)-1, seqlen)]
+
+
+@torch.inference_mode()
+def evaluate_ppl(model, windows, execution="prefill", logits_chunk=64):
+    device = next(model.parameters()).device
+    nll, count, rows = 0.0, 0, []
+    started = time.time()
+    state_memory = None
+    for index, (start, window) in enumerate(windows):
+        tokens = window.to(device)
+        if execution == "tokenwise":
+            hidden, cache = backbone_tokenwise(model, tokens[:-1][None], torch.float16)
+            state_memory = cache_bytes(cache)
+            if any(t.dtype != torch.float16 for pair in cache.key_value_memory_dict.values() for t in pair):
+                raise RuntimeError("Tokenwise protocol requires FP16 state and conv cache")
+            del cache
+        else:
+            hidden = model.backbone(tokens[:-1][None])
+        if not torch.isfinite(hidden).all():
+            raise RuntimeError(f"Nonfinite hidden states in PPL window {index}")
+        window_nll = 0.0
+        for position in range(0, hidden.shape[1], logits_chunk):
+            end = min(position+logits_chunk, hidden.shape[1])
+            logits = model.lm_head(hidden[:, position:end]).float()
+            if not torch.isfinite(logits).all():
+                raise RuntimeError(f"Nonfinite logits in PPL window {index}")
+            loss = F.cross_entropy(logits.reshape(-1, logits.shape[-1]),
+                                   tokens[position+1:end+1], reduction="sum")
+            window_nll += float(loss)
+            if not math.isfinite(window_nll):
+                raise RuntimeError(f"Nonfinite loss in PPL window {index}")
+            del logits, loss
+        targets = len(window)-1
+        nll += window_nll
+        count += targets
+        rows.append({"start": start, "input_tokens": targets, "target_tokens": targets,
+                     "token_sha256_int64le": token_digest(window.numpy()),
+                     "nll": window_nll, "ppl": math.exp(window_nll/targets)})
+        del hidden, tokens
+        if (index+1) % 4 == 0 or index == 0:
+            print(f"[PPL {execution}] {index+1}/{len(windows)}, ppl={math.exp(nll/count):.6f}, "
+                  f"{time.time()-started:.1f}s", flush=True)
+    return {"ppl": math.exp(nll/count), "nll": nll, "target_tokens": count,
+            "execution": execution, "windows": rows, "elapsed_seconds": time.time()-started,
+            "cache_dtype": "float16 each token" if execution == "tokenwise" else "SSD scan internal precision",
+            "cache_bytes": state_memory, "logits_chunk_tokens": logits_chunk,
+            "score": "next-token cross entropy; no BOS/EOS added; each window starts from zero state"}
+
+
+def synthetic_mk_cases(split="test", samples_per_cell=8, sizes=(16, 64)):
+    """Frozen public prompts; dev and test use disjoint keys and value ranges."""
+    if split not in ("validation", "test"):
+        raise ValueError(split)
+    offset = 0 if split == "validation" else 100000
+    rng = random.Random(834901 if split == "validation" else 834902)
+    cases = []
+    for size in sizes:
+        for template in range(3):
+            for sample in range(samples_per_cell):
+                keys = rng.sample(range(100000+offset, 180000+offset), size)
+                values = rng.sample(range(600000+offset, 680000+offset), size)
+                pairs = list(zip(keys, values))
+                # Query positions cycle across the sequence, including both ends.
+                target_position = (sample * max(1, size-1)) // max(1, samples_per_cell-1)
+                key, value = pairs[target_position]
+
+                def render(records):
+                    if template == 0:
+                        body = "\n".join(f"{k}: {v}" for k, v in records)
+                        return f"Key-value records:\n{body}\n\nLookup the value for key {key}.\nValue:"
+                    if template == 1:
+                        body = "\n".join(f"Key {k} has value {v}." for k, v in records)
+                        return f"{body}\n\nQuestion: What is the value of key {key}?\nAnswer:"
+                    body = "\n".join(f"{k} -> {v}" for k, v in records)
+                    return f"Dictionary:\n{body}\n\nReturn the stored value.\n{key} ->"
+
+                case_id = f"{split}-n{size}-t{template}-s{sample}"
+                cases.append({"id": case_id, "N": size, "template": template,
+                              "query_position": target_position, "key": key, "answer": str(value),
+                              "prompt": render(pairs), "condition": "normal"})
+                # Controls replace the target with an unrelated held-out key/value.
+                # Keep record count and template fixed; the target value is absent.
+                removed = pairs.copy()
+                removed[target_position] = (190000+offset+sample, 690000+offset+sample)
+                cases.append({"id": case_id+"-removed", "N": size, "template": template,
+                              "query_position": target_position, "key": key, "answer": str(value),
+                              "prompt": render(removed), "condition": "target_removed"})
+    return cases
+
+
+@torch.inference_mode()
+def generate_greedy(model, tokenizer, prompt, max_new_tokens=12, execution="prefill"):
+    device = next(model.parameters()).device
+    ids = torch.tensor(tokenizer.encode(prompt), dtype=torch.long, device=device)[None]
+    if ids.shape[1] == 0:
+        raise ValueError("Empty recall prompt")
+    cache = make_cache(model, ids.shape[1]+max_new_tokens, state_dtype=torch.float16)
+    if execution == "tokenwise":
+        for position in range(ids.shape[1]):
+            cache.seqlen_offset = position
+            hidden = model.backbone(ids[:, position:position+1], inference_params=cache)
+    else:
+        hidden = model.backbone(ids, inference_params=cache)
+        hidden = hidden[:, -1:]
+    generated = []
+    for position in range(max_new_tokens):
+        logits = model.lm_head(hidden[:, -1:])
+        if not torch.isfinite(logits).all():
+            raise RuntimeError("Nonfinite generation logits")
+        token = int(logits.argmax(-1).item())
+        generated.append(token)
+        if token == tokenizer.eos_token_id:
+            break
+        cache.seqlen_offset = ids.shape[1]+position
+        hidden = model.backbone(torch.tensor([[token]], device=device), inference_params=cache)
+    return tokenizer.decode(generated), generated, ids.shape[1], cache_bytes(cache)
+
+
+def evaluate_mk(model, tokenizer, split="test", samples_per_cell=8, execution="prefill"):
+    cases = synthetic_mk_cases(split, samples_per_cell)
+    rows = []
+    started = time.time()
+    for index, case in enumerate(cases):
+        output, generated, count, memory = generate_greedy(model, tokenizer, case["prompt"], execution=execution)
+        first = re.search(r"(?<!\d)\d{6}(?!\d)", output)
+        prediction = first.group() if first else None
+        ids = tokenizer.encode(case["prompt"])
+        rows.append({**{k: v for k, v in case.items() if k != "prompt"},
+                     "prompt_tokens": count, "prompt_token_sha256_int64le": token_digest(ids),
+                     "prompt": case["prompt"], "output": output, "generated_ids": generated,
+                     "prediction": prediction, "correct": prediction == case["answer"],
+                     "cache_bytes": memory})
+        if (index+1) % 8 == 0 or index == 0:
+            print(f"[public MK {execution}] {index+1}/{len(cases)}, {time.time()-started:.1f}s", flush=True)
+    summary = {}
+    for condition in ("normal", "target_removed"):
+        selected = [row for row in rows if row["condition"] == condition]
+        correct = sum(row["correct"] for row in selected)
+        summary[condition] = {"correct": correct, "count": len(selected), "accuracy": correct/len(selected)}
+    cells = []
+    for size in (16, 64):
+        for template in range(3):
+            for condition in ("normal", "target_removed"):
+                selected = [row for row in rows if row["N"] == size and row["template"] == template
+                            and row["condition"] == condition]
+                cells.append({"N": size, "template": template, "condition": condition,
+                              "correct": sum(row["correct"] for row in selected), "count": len(selected),
+                              "query_positions": [row["query_position"] for row in selected],
+                              "paired_case_ids": [row["id"] for row in selected]})
+    return {"protocol": "public-mamba8-mk-v1", "split": split,
+            "execution": execution, "cache_dtype": "float16",
+            "prefill_rounding": "each token" if execution == "tokenwise" else "at end of prefill",
+            "generation": "greedy, at most 12 tokens, stop at EOS",
+            "matching": "first standalone six-digit integer equals answer",
+            "private_resurface_comparable": False, "summary": summary, "cells": cells, "rows": rows,
+            "interpretation": "Small engineering screen; not statistical equivalence. Near-zero baseline recall cannot establish retained recall capacity.",
+            "elapsed_seconds": time.time()-started}
+

mamba2_recall/resurface_data.py

@@ -0,0 +1,391 @@
+"""CPU-only, split-isolated numeric recall data for the proposed readout study.
+
+Importing this module generates no examples and opens no dataset. The training
+loader opens only the literal train subdirectory. Confirmation data have a
+separate, explicit evaluation loader. Generation is not permission to train or
+to inspect confirmation scores; the caller must freeze its protocol first.
+"""
+from __future__ import annotations
+
+from collections import Counter
+import hashlib
+import json
+from pathlib import Path
+import random
+import re
+import sys
+
+FORMAT = 'MAMBA2_RESURFACE_NUMERIC_DATA_V1'
+PUBLIC_EVALUATION_SHA = '95cba0b201e37f92e6cbfadb9b3e9d79ba7b0cdc9efda6a58a6216b0d84d35e0'
+TOKENIZER_SHA = '5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09'
+SIZES = (16, 64)
+TEMPLATES = (0, 1, 2)
+CONTRACT = {
+    'train': {'seed':2026092801, 'key_range':[300000,380000],
+        'value_ranges':[[681000,690000],[781000,790000],[881000,890000],[981000,990000]],
+        'samples_per_cell':256,
+        'normal_count':1536, 'removed_count':0, 'positions':'independent uniform rng.randrange(N)'},
+    'dev': {'seed':834901, 'key_range':[100000,180000],
+        'value_ranges':[[600000,680000]], 'samples_per_cell':64,
+        'normal_count':384, 'removed_count':384, 'positions':'floor(sample*(N-1)/63)',
+        'control_key_base':190000, 'control_value_base':690000,
+        'generator':'frozen public-mamba8-mk-v1 validation, samples_per_cell=64'},
+    'confirm': {'seed':2026092802, 'key_range':[400000,480000],
+        'value_ranges':[[691000,700000],[791000,800000],[891000,900000],[991000,1000000]],
+        'samples_per_cell':64,
+        'normal_count':384, 'removed_count':384, 'positions':'floor(sample*(N-1)/63)',
+        'control_key_base':490000, 'control_value_base':990000},
+}
+
+
+def in_value_pool(value, spec):
+    return any(low<=value<high for low,high in spec['value_ranges'])
+
+
+def value_pool_statistics(rows, split):
+    """Actual normal-row counts; controls are excluded from these draw totals."""
+    ranges = CONTRACT[split]['value_ranges']
+    normal = [row for row in rows if row['condition']=='normal']
+    values = [value for row in normal for _,value in row['records']]
+    targets = [int(row['answer']) for row in normal]
+    return {'pool_cardinality':sum(high-low for low,high in ranges),
+        'normal_binding_value_occurrences':len(values),'normal_target_value_occurrences':len(targets),
+        'unique_normal_values':len(set(values)),
+        'bands':[{'range_half_open':[low,high],'pool_cardinality':high-low,
+            'binding_value_occurrences':sum(low<=value<high for value in values),
+            'target_value_occurrences':sum(low<=value<high for value in targets)} for low,high in ranges],
+        'sampling':'Uniform without replacement within each prompt over the pooled bands; not exact per-prompt band balancing.',
+        'paired_removed_controls_included_in_draw_totals':False}
+
+
+def sha_bytes(value):
+    return hashlib.sha256(value).hexdigest()
+
+
+def sha_file(path):
+    digest = hashlib.sha256()
+    with Path(path).open('rb') as stream:
+        for chunk in iter(lambda:stream.read(1 << 20),b''):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def canonical_bytes(value):
+    return (json.dumps(value,sort_keys=True,separators=(',',':'),ensure_ascii=False,allow_nan=False)+'\n').encode('utf-8')
+
+
+def token_digest(ids):
+    if not isinstance(ids,list) or any(type(x) is not int or not 0 <= x < 256000 for x in ids):
+        raise ValueError('Expected a plain list of valid native256K integer token ids')
+    return sha_bytes(b''.join(x.to_bytes(8,'little',signed=True) for x in ids))
+
+
+def render(records, key, template):
+    """The three public-v1 surface forms; no answer appended to the prompt."""
+    if template == 0:
+        body = '\n'.join(f'{k}: {v}' for k,v in records)
+        return f'Key-value records:\n{body}\n\nLookup the value for key {key}.\nValue:'
+    if template == 1:
+        body = '\n'.join(f'Key {k} has value {v}.' for k,v in records)
+        return f'{body}\n\nQuestion: What is the value of key {key}?\nAnswer:'
+    if template == 2:
+        body = '\n'.join(f'{k} -> {v}' for k,v in records)
+        return f'Dictionary:\n{body}\n\nReturn the stored value.\n{key} ->'
+    raise ValueError('Unsupported public template')
+
+
+def parse_records(prompt, template):
+    if template == 0:
+        body = prompt.removeprefix('Key-value records:\n').split('\n\nLookup the value for key ',1)[0]
+        pattern = r'([0-9]{6}): ([0-9]{6})'
+    elif template == 1:
+        body = prompt.split('\n\nQuestion: What is the value of key ',1)[0]
+        pattern = r'Key ([0-9]{6}) has value ([0-9]{6})\.'
+    elif template == 2:
+        body = prompt.removeprefix('Dictionary:\n').split('\n\nReturn the stored value.\n',1)[0]
+        pattern = r'([0-9]{6}) -> ([0-9]{6})'
+    else:
+        raise ValueError('Unsupported public template')
+    records = []
+    for line in body.splitlines():
+        match = re.fullmatch(pattern,line)
+        if match is None:
+            raise ValueError('Malformed record text')
+        records.append([int(match[1]),int(match[2])])
+    return records
+
+
+def _finish_row(row, records, split, sample):
+    result = {**row,'split':split,'sample':sample,'records':[list(pair) for pair in records]}
+    result['prompt_sha256_utf8'] = sha_bytes(result['prompt'].encode('utf-8'))
+    result['row_sha256'] = sha_bytes(canonical_bytes(result))
+    return result
+
+
+def generate_cases(split):
+    """Explicit lazy generation; train and confirm are independent RNG streams."""
+    if split not in ('train','confirm'):
+        raise ValueError('Use frozen_development_cases() for the immutable public development suite')
+    spec = CONTRACT[split]
+    rng = random.Random(spec['seed'])
+    value_pool = [value for low,high in spec['value_ranges'] for value in range(low,high)]
+    rows = []
+    for size in SIZES:
+        for template in TEMPLATES:
+            for sample in range(spec['samples_per_cell']):
+                keys = rng.sample(range(*spec['key_range']),size)
+                values = rng.sample(value_pool,size)
+                records = list(zip(keys,values))
+                position = (rng.randrange(size) if split=='train'
+                    else sample*(size-1)//(spec['samples_per_cell']-1))
+                key,value = records[position]
+                row = {'id':f'resurface-{split}-n{size}-t{template}-s{sample}',
+                    'N':size,'template':template,'query_position':position,'key':key,
+                    'answer':str(value),'prompt':render(records,key,template),'condition':'normal'}
+                rows.append(_finish_row(row,records,split,sample))
+                if split == 'confirm':
+                    removed = records.copy()
+                    removed[position] = (spec['control_key_base']+sample,spec['control_value_base']+sample)
+                    control = {**row,'id':row['id']+'-removed','condition':'target_removed',
+                        'prompt':render(removed,key,template)}
+                    rows.append(_finish_row(control,removed,split,sample))
+    validate_cases(rows,split)
+    return rows
+
+
+def frozen_development_cases():
+    """Called by preparation/evaluation only, never by training loaders."""
+    path = Path(__file__).with_name('evaluation.py')
+    if sha_file(path) != PUBLIC_EVALUATION_SHA:
+        raise ValueError('Frozen public-v1 generator changed')
+    from .evaluation import synthetic_mk_cases
+    rows = []
+    for row in synthetic_mk_cases('validation',samples_per_cell=64,sizes=SIZES):
+        sample = int(re.search(r'-s(\d+)(?:-removed)?$',row['id'])[1])
+        rows.append(_finish_row(row,parse_records(row['prompt'],row['template']),'dev',sample))
+    validate_cases(rows,'dev')
+    return rows
+
+
+def validate_cases(rows, split):
+    if split not in CONTRACT or not isinstance(rows,list):
+        raise ValueError('Unknown split or malformed case list')
+    spec = CONTRACT[split]
+    if len(rows) != spec['normal_count']+spec['removed_count']:
+        raise ValueError('Declared split count differs')
+    identifiers, prompts, by_id, cells = set(),set(),{},Counter()
+    order = []
+    for size in SIZES:
+        for template in TEMPLATES:
+            for sample in range(spec['samples_per_cell']):
+                prefix = 'validation' if split=='dev' else f'resurface-{split}'
+                normal = f'{prefix}-n{size}-t{template}-s{sample}'
+                order.append(normal)
+                if split!='train':
+                    order.append(normal+'-removed')
+    if [row.get('id') for row in rows] != order:
+        raise ValueError('Case ids/order/cell balancing differ')
+    for row in rows:
+        if row.get('split') != split or row['id'] in identifiers or row['prompt'] in prompts:
+            raise ValueError('Wrong split or duplicate case/prompt')
+        identifiers.add(row['id']);prompts.add(row['prompt']);by_id[row['id']] = row
+        for name in ('N','template','sample','query_position','key'):
+            if type(row.get(name)) is not int:
+                raise ValueError('Case integers must not be floats or booleans')
+        size,template,sample,position = [row[k] for k in ('N','template','sample','query_position')]
+        if size not in SIZES or template not in TEMPLATES or not 0<=sample<spec['samples_per_cell'] or not 0<=position<size:
+            raise ValueError('Case geometry differs')
+        if split!='train' and position != sample*(size-1)//(spec['samples_per_cell']-1):
+            raise ValueError('Evaluation query positions must spread across the whole sequence')
+        if not isinstance(row.get('answer'),str) or re.fullmatch(r'[0-9]{6}',row['answer']) is None:
+            raise ValueError('Expected a six-digit answer string')
+        answer = int(row['answer'])
+        if not spec['key_range'][0]<=row['key']<spec['key_range'][1] or not in_value_pool(answer,spec):
+            raise ValueError('Query/answer split range differs')
+        records = row.get('records')
+        if (not isinstance(records,list) or len(records)!=size
+                or any(not isinstance(pair,list) or len(pair)!=2 or any(type(v) is not int for v in pair) for pair in records)
+                or len({k for k,_ in records})!=size or len({v for _,v in records})!=size):
+            raise ValueError('Unique integral bindings required')
+        condition = row['condition']
+        if condition not in ('normal','target_removed') or (split=='train' and condition!='normal'):
+            raise ValueError('Training permits normal binding CE only')
+        for index,(key,value) in enumerate(records):
+            control = condition=='target_removed' and index==position
+            if control:
+                if [key,value]!=[spec['control_key_base']+sample,spec['control_value_base']+sample]:
+                    raise ValueError('Control must replace only the target binding')
+            elif not spec['key_range'][0]<=key<spec['key_range'][1] or not in_value_pool(value,spec):
+                raise ValueError('Record key/value split range differs')
+        if row['prompt'] != render(records,row['key'],template) or parse_records(row['prompt'],template)!=records:
+            raise ValueError('Prompt is not the exact reconstruction of declared bindings')
+        if row['prompt_sha256_utf8']!=sha_bytes(row['prompt'].encode('utf-8')):
+            raise ValueError('Prompt text hash differs')
+        content = {k:v for k,v in row.items() if k!='row_sha256'}
+        if row['row_sha256']!=sha_bytes(canonical_bytes(content)):
+            raise ValueError('Raw row hash differs')
+        if condition=='normal':
+            if records[position]!=[row['key'],answer]:
+                raise ValueError('Queried key is not bound to the exact supervised answer')
+        else:
+            if row['key'] in {k for k,_ in records} or answer in {v for _,v in records}:
+                raise ValueError('Removed binding/answer remains in records')
+            if re.search(r'(?<!\d)'+re.escape(row['answer'])+r'(?!\d)',row['prompt']):
+                raise ValueError('Removed answer still appears in rendered prompt')
+            normal = by_id[row['id'].removesuffix('-removed')]
+            if (any(row[k]!=normal[k] for k in ('N','template','sample','query_position','key','answer'))
+                    or [i for i,(a,b) in enumerate(zip(normal['records'],records)) if a!=b]!=[position]):
+                raise ValueError('Control is not paired to its normal case')
+        cells[size,template,condition] += 1
+    expected = {(size,template,condition):spec['samples_per_cell'] for size in SIZES for template in TEMPLATES
+        for condition in (('normal',) if split=='train' else ('normal','target_removed'))}
+    if dict(cells)!=expected:
+        raise ValueError('Unbalanced split cells')
+    return {'split':split,'normal_count':spec['normal_count'],'removed_count':spec['removed_count'],
+        'unique_prompts':len(prompts),'exact_binding_and_control_absence':True,
+        'raw_rows_sha256':sha_bytes(b''.join(canonical_bytes(row) for row in rows)),
+        'template_scope':'Same three template families; only instances/key-value ranges are separated.'}
+
+
+def _encode(tokenizer, text):
+    ids = list(tokenizer.encode(text))
+    token_digest(ids)
+    if not ids:
+        raise ValueError('Empty encoded sequence')
+    return ids
+
+
+def tokenize_case(row, tokenizer):
+    """Use answer suffix labels only for TRAIN, never for control/evaluation rows."""
+    prompt_ids = _encode(tokenizer,row['prompt'])
+    if len(prompt_ids)+12>4096:
+        raise ValueError('Prompt plus frozen12-token generation exceeds native4K context')
+    result = {'id':row['id'],'split':row['split'],'raw_row_sha256':row['row_sha256'],
+        'prompt_ids':prompt_ids,'prompt_tokens':len(prompt_ids),
+        'prompt_token_sha256_int64le':token_digest(prompt_ids)}
+    if row['split']=='train':
+        if row['condition']!='normal':
+            raise ValueError('Removed controls are never supervised training answers')
+        full_text = row['prompt']+' '+row['answer']
+        full = _encode(tokenizer,full_text)
+        length = len(prompt_ids)
+        if full[:length]!=prompt_ids or not length<len(full)<=4096:
+            raise ValueError('Prompt+answer tokenization is not prefix-stable within native4K context')
+        suffix = full[length:]
+        if tokenizer.decode(suffix).strip()!=row['answer']:
+            raise ValueError('Token suffix does not decode to the whole six-digit answer')
+        result.update(full_ids=full,full_text_sha256_utf8=sha_bytes(full_text.encode('utf-8')),
+            full_token_sha256_int64le=token_digest(full),answer_ids=suffix,answer_target_count=len(suffix),
+            answer_token_positions=list(range(length,len(full))),
+            ce_hidden_positions=list(range(length-1,len(full)-1)),
+            prefix_stability_verified=True,
+            loss_scope='Full256K CE on every answer-suffix token only; no EOS or prompt-token CE.')
+    return result
+
+
+def prepare_split(dataset_root, split, tokenizer, *, protocol_path, protocol_sha256, tokenizer_sha256):
+    """Write one explicit new split, only after a caller-pinned protocol exists.
+
+    This function is never called at import. TRAIN preparation does not generate
+    or read DEV/CONFIRM; the caller invokes their preparations separately.
+    """
+    if (split not in CONTRACT or tokenizer_sha256!=TOKENIZER_SHA
+            or getattr(tokenizer,'sha256',None)!=TOKENIZER_SHA):
+        raise ValueError('Declared split and pinned native tokenizer required')
+    protocol_path = Path(protocol_path)
+    if (not re.fullmatch(r'[0-9a-f]{64}',protocol_sha256) or not protocol_path.is_file()
+            or sha_file(protocol_path)!=protocol_sha256):
+        raise ValueError('A frozen existing protocol with exactSHA is required before generation')
+    output = Path(dataset_root)/split
+    if output.exists() or output.is_symlink():
+        raise FileExistsError('Fresh split directory only; preserve existing preparations')
+    rows = frozen_development_cases() if split=='dev' else generate_cases(split)
+    proof = validate_cases(rows,split)
+    tokens = [tokenize_case(row,tokenizer) for row in rows]
+    prompt_hashes = [row['prompt_token_sha256_int64le'] for row in tokens]
+    if len(set(prompt_hashes))!=len(prompt_hashes):
+        raise ValueError('Duplicate prompt tokens within a split')
+    raw = b''.join(canonical_bytes(row) for row in rows)
+    encoded = b''.join(canonical_bytes(row) for row in tokens)
+    output.mkdir(parents=True,exist_ok=False)
+    (output/'raw.jsonl').write_bytes(raw)
+    (output/'tokens.jsonl').write_bytes(encoded)
+    manifest = {'format':FORMAT,'complete':True,'split':split,'contract':CONTRACT[split],
+        'sizes':list(SIZES),'templates':list(TEMPLATES),'proof':proof,
+        'protocol_sha256':protocol_sha256,'tokenizer_sha256':tokenizer_sha256,
+        'helper_source_sha256':sha_file(__file__),'python_version':sys.version,
+        'value_pool_statistics':value_pool_statistics(rows,split),
+        'public_generator_sha256':PUBLIC_EVALUATION_SHA if split=='dev' else None,
+        'files':{'raw.jsonl':{'bytes':len(raw),'sha256':sha_bytes(raw)},
+                 'tokens.jsonl':{'bytes':len(encoded),'sha256':sha_bytes(encoded)}},
+        'row_count':len(rows),'prompt_tokens_total':sum(t['prompt_tokens'] for t in tokens),
+        'prompt_tokens_max':max(t['prompt_tokens'] for t in tokens),
+        'answer_target_tokens':sum(t.get('answer_target_count',0) for t in tokens),
+        'answer_token_count_histogram':{str(k):v for k,v in sorted(Counter(t['answer_target_count'] for t in tokens if split=='train').items())},
+        'automatic_bos_eos':False,'full_vocabulary':256000,
+        'evaluation_supervised_targets_stored':False,
+        'confirmation_loaded_for_training':False}
+    (output/'manifest.json').write_bytes(canonical_bytes(manifest))
+    return manifest
+
+
+def _load_split(dataset_root, split, expected_manifest_sha256, tokenizer):
+    if getattr(tokenizer,'sha256',None)!=TOKENIZER_SHA:
+        raise ValueError('Actual native tokenizer identity differs')
+    directory = Path(dataset_root)/split
+    if directory.is_symlink() or {p.name for p in directory.iterdir()}!={'manifest.json','raw.jsonl','tokens.jsonl'}:
+        raise ValueError('Expected one complete isolated split directory')
+    mp = directory/'manifest.json'
+    if mp.is_symlink() or sha_file(mp)!=expected_manifest_sha256:
+        raise ValueError('Pinned split manifest differs')
+    manifest = json.loads(mp.read_text())
+    if (manifest.get('format')!=FORMAT or manifest.get('complete') is not True or manifest.get('split')!=split
+            or manifest.get('contract')!=CONTRACT[split] or manifest.get('tokenizer_sha256')!=TOKENIZER_SHA
+            or manifest.get('helper_source_sha256')!=sha_file(__file__)
+            or set(manifest.get('files',{}))!={'raw.jsonl','tokens.jsonl'}):
+        raise ValueError('Prepared split provenance/format differs')
+    parsed = {}
+    for name,entry in manifest['files'].items():
+        path = directory/name
+        if (path.is_symlink() or not path.is_file() or type(entry.get('bytes')) is not int
+                or path.stat().st_size!=entry['bytes'] or sha_file(path)!=entry['sha256']):
+            raise ValueError('Prepared split file identity differs')
+        parsed[name] = [json.loads(line) for line in path.read_text().splitlines()]
+    rows,tokens = parsed['raw.jsonl'],parsed['tokens.jsonl']
+    if validate_cases(rows,split)!=manifest['proof'] or len(tokens)!=len(rows):
+        raise ValueError('Prepared raw case proof differs')
+    expected_rows = frozen_development_cases() if split=='dev' else generate_cases(split)
+    if rows!=expected_rows:
+        raise ValueError('Prepared cases differ from the exact frozen seed/generator')
+    if manifest.get('value_pool_statistics')!=value_pool_statistics(rows,split):
+        raise ValueError('Declared/observed pooled value distribution differs')
+    if [tokenize_case(row,tokenizer) for row in rows]!=tokens:
+        raise ValueError('Actual tokenizer/prefix/answer-label reconstruction differs')
+    return manifest,rows,tokens
+
+
+def load_training(dataset_root, expected_manifest_sha256, tokenizer):
+    """Literal TRAIN-only path; never opens any development or confirmation file."""
+    return _load_split(dataset_root,'train',expected_manifest_sha256,tokenizer)
+
+
+def load_evaluation(dataset_root, split, expected_manifest_sha256, tokenizer):
+    if split not in ('dev','confirm'):
+        raise ValueError('Explicit dev or confirm evaluation split required')
+    return _load_split(dataset_root,split,expected_manifest_sha256,tokenizer)
+
+
+def audit_split_overlap(*split_rows):
+    """Preparation/evaluation audit only; never called by load_training."""
+    seen_ids,seen_text,seen_tokens = set(),set(),set()
+    for rows,tokens in split_rows:
+        if len(rows)!=len(tokens):
+            raise ValueError('Raw/token row counts differ')
+        current_ids = {row['id'] for row in rows}
+        current_text = {row['prompt_sha256_utf8'] for row in rows}
+        current_tokens = {row['prompt_token_sha256_int64le'] for row in tokens}
+        if seen_ids&current_ids or seen_text&current_text or seen_tokens&current_tokens:
+            raise ValueError('Cross-split id/text/token input overlap')
+        seen_ids.update(current_ids);seen_text.update(current_text);seen_tokens.update(current_tokens)
+    return {'splits':len(split_rows),'unique_cases':len(seen_ids),'id_overlap':0,'text_overlap':0,'token_overlap':0,
+        'scope':'Exact prompt identity plus declared disjoint key/value ranges; shared template families are intentional.'}

mamba2_recall/resurface_loss.py

@@ -0,0 +1,179 @@
+"""Full-vocabulary staged head gradients plus one joint backbone/gate backward.
+
+MK selects every answer-suffix target with an explicit bool mask; prose selects
+all targets. Only loss-position selection uses the mask: it is never a router
+input. Chunk sums divide by the complete selected target count. Head GEMMs are
+FP16, CE/KL are FP32, temperature is one, teacher is detached. The scaler applies
+once to the hidden derivative and once to the separate gate-auxiliary branch.
+"""
+from __future__ import annotations
+import argparse
+import json
+import math
+import torch
+import torch.nn.functional as F
+
+
+def staged_loss_backward(student_hidden, targets, student_head, *, gates=None,
+                         scaler=None, teacher_hidden=None, teacher_head=None,
+                         answer_mask=None, ce_weight=1., kl_weight=0.,
+                         closure_weight=0., opening_mask=None, opening_weight=0.,
+                         chunk_tokens=64):
+    weights = (ce_weight, kl_weight, closure_weight, opening_weight)
+    if any(not math.isfinite(x) or x < 0 for x in weights) or sum(weights) <= 0:
+        raise ValueError('Invalid objective coefficients')
+    if (student_hidden.ndim != 3 or student_hidden.dtype != torch.float16
+            or targets.dtype != torch.int64 or targets.shape != student_hidden.shape[:2]
+            or targets.device != student_hidden.device or not student_hidden.requires_grad
+            or type(chunk_tokens) is not int or chunk_tokens < 1):
+        raise ValueError('Invalid native FP16 hidden/target/chunk geometry')
+    if answer_mask is None:
+        answer_mask = torch.ones_like(targets, dtype=torch.bool)
+    if (answer_mask.dtype != torch.bool or answer_mask.shape != targets.shape
+            or answer_mask.device != targets.device or not bool(answer_mask.any())):
+        raise ValueError('Answer selection must be nonempty bool[batch,tokens]')
+    count = int(answer_mask.sum())
+    if not torch.isfinite(student_hidden).all():
+        raise FloatingPointError('Nonfinite student hidden')
+    if any(p.requires_grad for p in student_head.parameters()):
+        raise ValueError('Student vocabulary head must be frozen')
+    if kl_weight:
+        if (teacher_hidden is None or teacher_head is None or teacher_hidden.shape != student_hidden.shape
+                or teacher_hidden.dtype != torch.float16 or teacher_hidden.device != student_hidden.device
+                or not torch.isfinite(teacher_hidden).all()
+                or any(p.requires_grad for p in teacher_head.parameters())):
+            raise ValueError('Invalid frozen teacher')
+    if (closure_weight or opening_weight) and gates is None:
+        raise ValueError('Gate objective requires same-invocation capture')
+    if gates is not None and (gates.logits.shape[1:] != targets.shape or gates.logits.device != targets.device):
+        raise ValueError('Gate capture does not correspond to this hidden sequence')
+    if gates is not None and not torch.isfinite(gates.logits).all():
+        raise FloatingPointError('Nonfinite router logits, including sigmoid-saturated values')
+    gradient = torch.zeros_like(student_hidden)
+    ce_parts, kl_parts, sizes = [], [], []
+    with torch.autocast(device_type=student_hidden.device.type, enabled=False):
+        for first in range(0, student_hidden.shape[1], chunk_tokens):
+            last = min(first+chunk_tokens, student_hidden.shape[1])
+            mask = answer_mask[:, first:last]
+            selected = int(mask.sum())
+            if not selected:
+                continue
+            chunk = student_hidden[:, first:last].detach().requires_grad_(True)
+            logits16 = student_head(chunk[mask])
+            if logits16.dtype != torch.float16 or not torch.isfinite(logits16).all():
+                raise FloatingPointError('Invalid native student head output')
+            logits = logits16.float()
+            ce = F.cross_entropy(logits, targets[:, first:last][mask], reduction='sum')
+            kl = logits.new_zeros(())
+            if kl_weight:
+                with torch.no_grad():
+                    teacher_logits16 = teacher_head(teacher_hidden[:, first:last][mask])
+                    if (teacher_logits16.dtype != torch.float16 or teacher_logits16.shape != logits16.shape
+                            or not torch.isfinite(teacher_logits16).all()):
+                        raise FloatingPointError('Invalid native teacher head output')
+                    teacher_logp = F.log_softmax(teacher_logits16.float(), dim=-1)
+                kl = F.kl_div(F.log_softmax(logits, dim=-1), teacher_logp, reduction='sum', log_target=True)
+            loss = (ce_weight*ce+kl_weight*kl)/count
+            if not torch.isfinite(loss):
+                raise FloatingPointError('Nonfinite chunk objective')
+            scaled = scaler.scale(loss) if scaler is not None else loss
+            grad, = torch.autograd.grad(scaled, chunk)
+            gradient[:, first:last].copy_(grad)
+            ce_parts.append(float(ce.detach())); kl_parts.append(float(kl.detach())); sizes.append(selected)
+        auxiliary, close, opening = None, 0., 0.
+        if closure_weight:
+            term = gates.closure_loss()
+            close = float(term.detach())
+            auxiliary = closure_weight*term
+        if opening_weight:
+            term = gates.opening_loss(opening_mask)
+            opening = float(term.detach())
+            term = opening_weight*term
+            auxiliary = term if auxiliary is None else auxiliary+term
+        if auxiliary is not None:
+            if not torch.isfinite(auxiliary):
+                raise FloatingPointError('Nonfinite gate objective')
+            scaled_auxiliary = scaler.scale(auxiliary) if scaler is not None else auxiliary
+            torch.autograd.backward((student_hidden, scaled_auxiliary), (gradient, None))
+        else:
+            student_hidden.backward(gradient)
+    ce_mean, kl_mean = math.fsum(ce_parts)/count, math.fsum(kl_parts)/count
+    return {'targets': count, 'forward_positions': targets.numel(), 'chunks': len(sizes),
+            'chunk_selected_targets': sizes, 'ce': ce_mean, 'teacher_to_student_kl': kl_mean,
+            'closure': close, 'opening': opening, 'weighted_closure': closure_weight*close,
+            'weighted_opening': opening_weight*opening,
+            'loss': ce_weight*ce_mean+kl_weight*kl_mean+closure_weight*close+opening_weight*opening,
+            'ce_coefficient': ce_weight, 'kl_coefficient': kl_weight, 'temperature': 1.,
+            'scaled_hidden_gradient_finite': bool(torch.isfinite(gradient).all()),
+            'scaled_hidden_gradient_nonzero': int(torch.count_nonzero(gradient)),
+            'scaled_hidden_gradient_elements': gradient.numel(),
+            'backbone_backward_calls': 1, 'gate_and_hidden_backward_joint': auxiliary is not None}
+
+
+def self_test():
+    from .resurface_native import GateCapture
+    torch.manual_seed(3289)
+    torch.set_num_threads(8)
+    head = torch.nn.Linear(5, 19, bias=False, dtype=torch.float16).requires_grad_(False)
+    targets = torch.tensor([[1, 2, 3, 4, 5, 6, 7]])
+    seed = torch.randn(1, 7, 5)*.25
+    teacher = (seed+.1).half()
+    mask = torch.tensor([[False, False, True, True, False, True, True]])
+    opening_mask = torch.tensor([[False, False, False, False, False, True, True]])
+    class Scale:
+        def scale(self, loss): return 8*loss
+    tests = []
+    for label, selected, klw, closew, openw in [('masked MK', mask, 0., 0., .02),
+                                               ('prose', torch.ones_like(mask), .5, 3., 0.)]:
+        gradients, losses = [], []
+        cew = .5 if klw else 1.
+        for staged in (False, True):
+            master = seed.clone().requires_grad_()
+            hidden = master.half()
+            gates = GateCapture(master.mean(-1).unsqueeze(0))
+            if staged:
+                row = staged_loss_backward(hidden, targets, head, gates=gates, scaler=Scale(),
+                    teacher_hidden=teacher, teacher_head=head, answer_mask=selected, ce_weight=cew,
+                    kl_weight=klw, closure_weight=closew, opening_mask=opening_mask,
+                    opening_weight=openw, chunk_tokens=3)
+                losses.append(row['loss'])
+                assert row['targets'] == int(selected.sum()) and row['chunk_selected_targets'][-1] == 1
+                assert row['backbone_backward_calls'] == 1 and row['scaled_hidden_gradient_finite']
+            else:
+                logits = head(hidden[selected]).float()
+                ce = F.cross_entropy(logits, targets[selected], reduction='sum')/selected.sum()
+                with torch.no_grad(): teacher_logp = F.log_softmax(head(teacher[selected]).float(), -1)
+                kl = F.kl_div(F.log_softmax(logits, -1), teacher_logp, reduction='sum', log_target=True)/selected.sum()
+                loss = cew*ce+klw*kl+closew*gates.closure_loss()+openw*gates.opening_loss(opening_mask)
+                (8*loss).backward(); losses.append(float(loss.detach()))
+            gradients.append(master.grad)
+        torch.testing.assert_close(gradients[0], gradients[1], rtol=.002, atol=.0001)
+        assert abs(losses[0]-losses[1]) < 2e-6
+        tests.append(label+': direct gradient, short tail, gate branch and scale once')
+    # Non-answer labels cannot affect masked-MK objective or gradient.
+    rows = []
+    for changed in (False, True):
+        master = seed.clone().requires_grad_()
+        modified = targets.clone()
+        if changed: modified[~mask] = (modified[~mask]+4)%19
+        receipt = staged_loss_backward(master.half(), modified, head, answer_mask=mask, chunk_tokens=3)
+        rows.append((receipt['loss'], master.grad))
+    assert rows[0][0] == rows[1][0] and torch.equal(rows[0][1], rows[1][1])
+    tests.append('Prompt-label changes cannot affect answer-only CE')
+    invalid = GateCapture(torch.full((1, 1, 7), float('inf')))
+    try:
+        staged_loss_backward(seed.clone().requires_grad_().half(), targets, head, gates=invalid, answer_mask=mask)
+    except FloatingPointError:
+        pass
+    else:
+        raise AssertionError('Nonfinite gate logits accepted by MK with zero closure weight')
+    tests.append('Reject nonfinite router logits even when MK closure coefficient is zero')
+    return {'complete': True, 'tests': tests, 'passed': len(tests),
+            'cuda_initialized': torch.cuda.is_initialized(), 'scope': 'CPU small vocabulary loss algebra only'}
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--self-test', action='store_true', required=True)
+    parser.parse_args()
+    print(json.dumps(self_test(), indent=2))

mamba2_recall/resurface_native.py

@@ -0,0 +1,557 @@
+"""Experimental post-D Resurface-inspired adapter for the frozen native runtime.
+
+This is NOT the original pre-D Resurface insertion: native SSD already includes
+D*x when norm's prehook sees y. No scan, norm, projection or cache is replaced.
+Each layer applies y + sigmoid(w*u+b)*g*(V@y), without EMA or any extra state.
+
+Usage (keep the bank alive through backward, including checkpoint replay):
+    bank = ResurfaceNative(model, gate_mode='soft', expected_base_hashes=hashes)
+    hidden, gates = bank.forward_hidden(ids, use_checkpoint=True)
+    loss = task_loss(hidden) + gates.closure_loss() + gates.opening_loss(mask)
+    loss.backward()
+    bank.export_fp16(path, binding={'base_manifest_sha256': ...})
+    bank.close()
+    with install_fp16(model, path, expected_base_hashes=hashes) as deployed:
+        logits = model(ids).logits  # Same gate mode for every evaluation task.
+
+The external ModuleDict never becomes a child of the base model. Hooks support
+native prefill and native model(..., inference_params=...) recurrent decoding;
+calling mixer.step() directly bypasses the mixer-input hook and is unsupported.
+Gate capture is returned by EACH checkpoint invocation, never appended during
+replay. Hooks are synchronous/non-reentrant; concurrent forwards fail closed.
+Hard mode uses threshold(logit > 0), with a sigmoid STE only during training.
+V=0 plus a closed hard gate is a dead point for answer CE alone: explicit opening
+loss or an independently declared soft warmup is required. This module chooses
+neither a training recipe nor a quality gate.
+"""
+from __future__ import annotations
+
+import argparse
+from contextlib import contextmanager
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path
+import tempfile
+import weakref
+
+import torch
+from torch import nn
+import torch.nn.functional as F
+from torch.utils.checkpoint import checkpoint
+
+FORMAT = 'MAMBA2_POST_D_RESURFACE_FP16_V1'
+FIELDS = ('V_read', 'g_read', 'router_w', 'router_b')
+VARIANT = 'post-D native norm-prehook; memoryless cross-head mixing'
+_OWNERS = weakref.WeakKeyDictionary()
+
+
+def tensor_hash(value):
+    value = value.detach()
+    digest = hashlib.sha256()
+    if value.ndim == 0:
+        digest.update(value.cpu().contiguous().numpy().tobytes())
+    else:
+        for first in range(0, value.shape[0], 128):
+            digest.update(value[first:first+128].cpu().contiguous().numpy().tobytes())
+    return digest.hexdigest()
+
+
+def file_hash(path):
+    digest = hashlib.sha256()
+    with Path(path).open('rb') as stream:
+        for block in iter(lambda: stream.read(8*1024*1024), b''):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+@dataclass(frozen=True)
+class GateCapture:
+    """FP32 logits [layers,batch,tokens]; all terms are differentiable."""
+    logits: torch.Tensor
+
+    def soft_probabilities(self):
+        return torch.sigmoid(self.logits)
+
+    def closure_loss(self, budget=0.006, budget_coefficient=10.0):
+        if not 0 <= budget <= 1 or budget_coefficient < 0:
+            raise ValueError('Invalid closure budget/coefficient')
+        # Mean BCE and per-layer mean-openness penalty, then mean over layers.
+        close = F.softplus(self.logits).mean(dim=(1, 2))
+        openness = self.soft_probabilities().mean(dim=(1, 2))
+        return (close + budget_coefficient * F.relu(openness-budget)).mean()
+
+    def opening_loss(self, mask):
+        """Mean BCE(logit,1) only at explicit TRAIN query-token positions."""
+        if mask.dtype != torch.bool or tuple(mask.shape) != tuple(self.logits.shape[1:]):
+            raise ValueError('Opening mask must be bool[batch,tokens]')
+        if mask.device != self.logits.device or not bool(mask.any()):
+            raise ValueError('Opening mask must share device and select tokens')
+        return F.softplus(-self.logits[:, mask]).mean()
+
+
+class _Adapter(nn.Module):
+    def __init__(self, width, heads, *, device, trainable):
+        super().__init__()
+        dtype = torch.float32 if trainable else torch.float16
+        for name, value in {
+            'V_read': torch.zeros(heads, heads, device=device, dtype=dtype),
+            'g_read': torch.ones(heads, device=device, dtype=dtype),
+            'router_w': torch.zeros(width, device=device, dtype=dtype),
+            'router_b': torch.tensor(-4.0, device=device, dtype=dtype),
+        }.items():
+            self.register_parameter(name, nn.Parameter(value, requires_grad=trainable))
+
+    def forward(self, y, u, heads, head_dim, mode, trainable):
+        # Cast INSIDE the hook, hence inside every checkpoint replay.
+        V, g, w, b = (getattr(self, name).to(torch.float16) for name in FIELDS)
+        logits = (torch.einsum('...d,d->...', u, w) + b).float()
+        soft = torch.sigmoid(logits)
+        if mode == 'soft':
+            gate = soft
+        else:
+            hard = (logits > 0).to(soft.dtype)
+            gate = hard + (soft-soft.detach()) if trainable and torch.is_grad_enabled() else hard
+        yh = y.reshape(*y.shape[:-1], heads, head_dim)
+        mix = torch.einsum('ij,...jp->...ip', V, yh)
+        correction = gate.to(y.dtype)[..., None, None] * g[..., None] * mix
+        return (yh+correction).reshape_as(y), logits
+
+
+class ResurfaceNative:
+    """Separate adapter parameters; original model keeps its exact parameter set."""
+    def __init__(self, model, gate_mode='soft', *, expected_base_hashes=None,
+                 trainable=True, production=True):
+        if gate_mode not in ('soft', 'hard'):
+            raise ValueError('Gate mode must be explicitly soft or hard')
+        if model in _OWNERS and _OWNERS[model]() is not None:
+            raise RuntimeError('A Resurface adapter is already attached to this model')
+        self.model, self._gate_mode = model, gate_mode
+        self.trainable, self.production = bool(trainable), bool(production)
+        self.adapters = nn.ModuleDict()
+        self._frames, self._requests, self._handles = {}, {}, []
+        self.closed = False
+        self._base = dict(model.named_parameters())
+        if any(p.dtype != torch.float16 or p.requires_grad or p.grad is not None for p in self._base.values()):
+            raise ValueError('Load an already-frozen FP16 base with no gradients')
+        if production and (len(self._base) != 507 or sum(p.numel() for p in self._base.values()) != 8236999680):
+            raise ValueError('Production base must cover507 tensors/8,236,999,680 parameters')
+        self._identities = {name: (id(p), p.data_ptr(), p._version) for name, p in self._base.items()}
+        self._base_hashes = dict(expected_base_hashes) if expected_base_hashes is not None else None
+        if self._base_hashes is not None and set(self._base_hashes) != set(self._base):
+            raise ValueError('Expected base ledger must cover every original parameter')
+        backbone = model.backbone
+        if backbone.fused_add_norm or backbone.residual_in_fp32:
+            raise ValueError('Only frozen unfused FP16 residual orchestration is supported')
+        if production and len(backbone.layers) != 56:
+            raise ValueError('Production layer count must be56')
+        self.geometry = []
+        for index, layer in enumerate(backbone.layers):
+            mx = layer.mixer
+            if layer.fused_add_norm or layer.residual_in_fp32 or layer.mlp is not None:
+                raise ValueError('Unsupported native block')
+            if mx.use_mem_eff_path or not mx.rmsnorm:
+                raise ValueError('Native explicit gated norm must execute on every call')
+            width, heads, head_dim = mx.d_model, mx.nheads, mx.headdim
+            if mx.d_ssm != heads*head_dim:
+                raise ValueError('Unsupported head geometry')
+            if production and (width, heads, head_dim, mx.ngroups) != (4096, 128, 64, 8):
+                raise ValueError('Production Mamba2 geometry differs')
+            self.geometry.append({'width': width, 'heads': heads, 'head_dim': head_dim})
+            self.adapters[f'layer{index}'] = _Adapter(width, heads, device=mx.in_proj.weight.device,
+                                                     trainable=self.trainable)
+        self.masters = {f'{key}.{name}': p for key, module in self.adapters.items()
+                        for name, p in module.named_parameters()}
+        _OWNERS[model] = weakref.ref(self)
+        try:
+            for index, layer in enumerate(backbone.layers):
+                self._handles.append(layer.mixer.register_forward_pre_hook(self._input_hook(index), with_kwargs=True))
+                self._handles.append(layer.mixer.norm.register_forward_pre_hook(self._norm_hook(index), with_kwargs=True))
+                self._handles.append(layer.mixer.register_forward_hook(self._end_hook(index), with_kwargs=True, always_call=True))
+        except Exception:
+            self.close()
+            raise
+
+    def parameters(self):
+        return list(self.masters.values())
+
+    @property
+    def gate_mode(self):
+        return self._gate_mode
+
+    def _require_open(self):
+        if self.closed:
+            raise RuntimeError('Adapter was closed before this invocation/replay')
+
+    def _input_hook(self, index):
+        def hook(module, args, kwargs):
+            self._require_open()
+            if index in self._frames:
+                raise RuntimeError('Concurrent/reentrant mixer invocation is unsupported')
+            u = args[0] if args else kwargs.get('u')
+            if not isinstance(u, torch.Tensor) or u.ndim not in (2, 3):
+                raise ValueError('Mixer input must be rank2/3 tensor')
+            if u.dtype != torch.float16 or u.shape[-1] != self.geometry[index]['width']:
+                raise ValueError('Mixer input geometry/dtype differs')
+            frame = self._requests.get(index, {})
+            frame.update(u=u, logits=None, consumed=False)
+            self._frames[index] = frame
+        return hook
+
+    def _norm_hook(self, index):
+        def hook(module, args, kwargs):
+            frame = self._frames.get(index)
+            if frame is None or frame['consumed']:
+                raise RuntimeError('Norm hook has no unique corresponding mixer input')
+            y = args[0] if args else kwargs.get('x')
+            geo = self.geometry[index]
+            if not isinstance(y, torch.Tensor) or y.ndim not in (2, 3) or y.dtype != torch.float16:
+                raise ValueError('Native norm input must be rank2/3 FP16')
+            if y.shape[-1] != geo['heads']*geo['head_dim']:
+                raise ValueError('Native norm/head shape differs')
+            u = frame['u']
+            if u.numel()//geo['width'] != y.numel()//y.shape[-1]:
+                raise ValueError('Mixer input and readout token counts differ')
+            u = u.reshape(*y.shape[:-1], geo['width'])
+            adapted, logits = self.adapters[f'layer{index}'](y, u, geo['heads'], geo['head_dim'],
+                                                            self.gate_mode, self.trainable)
+            frame.update(u=None, consumed=True, logits=logits)
+            if args:
+                return (adapted, *args[1:]), kwargs
+            return args, {**kwargs, 'x': adapted}
+        return hook
+
+    def _end_hook(self, index):
+        def hook(module, args, kwargs, output):
+            frame = self._frames.pop(index, None)
+            if frame is not None:
+                frame['u'] = None
+                if output is not None and not frame['consumed']:
+                    raise RuntimeError('Native mixer bypassed adapter injection')
+        return hook
+
+    @contextmanager
+    def _capture(self, index):
+        self._require_open()
+        if index in self._requests or index in self._frames:
+            raise RuntimeError('Overlapping gate capture')
+        frame = {}
+        self._requests[index] = frame
+        try:
+            yield frame
+        finally:
+            self._requests.pop(index, None)
+            active = self._frames.pop(index, None)
+            if active is not None:
+                active['u'] = None
+            frame.pop('u', None)
+
+    def forward_hidden(self, input_ids, use_checkpoint=True):
+        """Native blocks/final norm; only adapter leaves receive gradients."""
+        self._require_open()
+        hidden = self.model.backbone.embedding(input_ids)
+        residual, all_logits = None, []
+        for index, layer in enumerate(self.model.backbone.layers):
+            def run(h, r, index=index, layer=layer):
+                with self._capture(index) as frame:
+                    h, r = layer(h, r, inference_params=None)
+                    if frame.get('logits') is None:
+                        raise RuntimeError('Gate capture missing from this block invocation')
+                    return h, r, frame['logits']
+            if use_checkpoint and torch.is_grad_enabled():
+                hidden, residual, logits = checkpoint(run, hidden, residual, use_reentrant=False,
+                                                       preserve_rng_state=True)
+            else:
+                hidden, residual, logits = run(hidden, residual)
+            all_logits.append(logits)  # Once per OUTER layer, never inside replay.
+        residual = hidden+residual if residual is not None else hidden
+        hidden = self.model.backbone.norm_f(residual.to(self.model.backbone.norm_f.weight.dtype))
+        return hidden, GateCapture(torch.stack(all_logits))
+
+    def state_dict(self):
+        return {name: p.detach().cpu().clone() for name, p in self.masters.items()}
+
+    def load_state_dict(self, values):
+        dtype = torch.float32 if self.trainable else torch.float16
+        if set(values) != set(self.masters):
+            raise ValueError('Adapter keys differ')
+        for name, value in values.items():
+            if value.shape != self.masters[name].shape or value.dtype != dtype or not torch.isfinite(value).all():
+                raise ValueError(f'Invalid adapter tensor: {name}')
+        with torch.no_grad():
+            for name, value in values.items():
+                self.masters[name].copy_(value)
+
+    def assert_base_frozen(self, check_values=False):
+        now = dict(self.model.named_parameters())
+        if set(now) != set(self._base):
+            raise RuntimeError('Base parameter inventory changed')
+        for name, p in now.items():
+            if (id(p), p.data_ptr(), p._version) != self._identities[name] or p.requires_grad or p.grad is not None:
+                raise RuntimeError(f'Base identity/version/gradient changed: {name}')
+        if check_values:
+            if self._base_hashes is None:
+                raise ValueError('Content audit requires an independently supplied base hash ledger')
+            for name, p in now.items():
+                if tensor_hash(p) != self._base_hashes[name]:
+                    raise RuntimeError(f'Base content changed: {name}')
+        return {'tensors': len(now), 'parameters': sum(p.numel() for p in now.values()),
+                'identity_version_gradients_unchanged': True, 'actual_content_checked': check_values}
+
+    def export_fp16(self, path, binding=None):
+        self.assert_base_frozen()
+        values = {name: p.detach().cpu().half() for name, p in self.masters.items()}
+        if not all(torch.isfinite(v).all() for v in values.values()):
+            raise FloatingPointError('Nonfinite FP16 export')
+        payload = {'format': FORMAT, 'variant': VARIANT, 'gate_mode': self.gate_mode,
+                   'geometry': self.geometry, 'binding': dict(binding or {}), 'tensors': values}
+        path = Path(path)
+        with path.open('xb') as stream:
+            torch.save(payload, stream)
+        restored = read_fp16(path, expected_binding=payload['binding'])
+        hashes = {name: tensor_hash(value) for name, value in values.items()}
+        if hashes != {name: tensor_hash(value) for name, value in restored['tensors'].items()}:
+            raise RuntimeError('Actual FP16 file roundtrip differs')
+        return {'file': path.name, 'bytes': path.stat().st_size, 'sha256': file_hash(path),
+                'parameters': sum(v.numel() for v in values.values()),
+                'payload_bytes': sum(v.numel()*v.element_size() for v in values.values()),
+                'tensor_sha256': hashes, 'gate_mode': self.gate_mode, 'roundtrip_bitwise_equal': True}
+
+    def close(self):
+        for handle in self._handles:
+            handle.remove()
+        self._handles.clear()
+        self._frames.clear()
+        self._requests.clear()
+        if self.model in _OWNERS and _OWNERS[self.model]() is self:
+            del _OWNERS[self.model]
+        self.closed = True
+
+    def __enter__(self):
+        self._require_open()
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+def read_fp16(path, expected_binding=None):
+    payload = torch.load(path, map_location='cpu', weights_only=True)
+    if (set(payload) != {'format', 'variant', 'gate_mode', 'geometry', 'binding', 'tensors'}
+            or payload['format'] != FORMAT or payload['variant'] != VARIANT
+            or payload['gate_mode'] not in ('soft', 'hard') or not isinstance(payload['binding'], dict)):
+        raise ValueError('Invalid Resurface export header')
+    if expected_binding is not None and payload['binding'] != expected_binding:
+        raise ValueError('Resurface binding differs')
+    expected = {}
+    for index, geo in enumerate(payload['geometry']):
+        if set(geo) != {'width', 'heads', 'head_dim'} or any(type(v) is not int or v <= 0 for v in geo.values()):
+            raise ValueError('Invalid export geometry')
+        expected.update({f'layer{index}.{name}': shape for name, shape in {
+            'V_read': (geo['heads'], geo['heads']), 'g_read': (geo['heads'],),
+            'router_w': (geo['width'],), 'router_b': (),
+        }.items()})
+    if not expected or set(payload['tensors']) != set(expected):
+        raise ValueError('Export tensor inventory differs')
+    for name, shape in expected.items():
+        v = payload['tensors'][name]
+        if not isinstance(v, torch.Tensor) or v.dtype != torch.float16 or tuple(v.shape) != shape or not torch.isfinite(v).all():
+            raise ValueError(f'Invalid exported tensor: {name}')
+    return payload
+
+
+def install_fp16(model, path, *, expected_binding=None, expected_base_hashes=None, production=True):
+    """Fresh eval-only adapter loaded from actual serialized half tensors."""
+    payload = read_fp16(path, expected_binding)
+    bank = ResurfaceNative(model, payload['gate_mode'], expected_base_hashes=expected_base_hashes,
+                           trainable=False, production=production)
+    try:
+        if bank.geometry != payload['geometry']:
+            raise ValueError('Export does not fit actual native model')
+        bank.load_state_dict(payload['tensors'])
+    except Exception:
+        bank.close()
+        raise
+    return bank
+
+
+def self_test():
+    """Bounded CPU hook tests; not an 8B native-kernel or quality validation."""
+    torch.set_num_threads(8)
+    torch.manual_seed(9231)
+
+    class Norm(nn.Module):
+        def __init__(self, width):
+            super().__init__()
+            self.weight = nn.Parameter(torch.ones(width, dtype=torch.float16))
+        def forward(self, x, z=None):
+            if z is not None:
+                x = x*F.silu(z)
+            return (x.float()*torch.rsqrt(x.float().square().mean(-1, keepdim=True)+1e-5)).half()*self.weight
+
+    class Mixer(nn.Module):
+        d_model, d_ssm, nheads, headdim, ngroups = 4, 4, 2, 2, 1
+        use_mem_eff_path, rmsnorm = False, True
+        def __init__(self, index):
+            super().__init__()
+            self.index, self.fail = index, False
+            self.in_proj = nn.Linear(4, 8, bias=False, dtype=torch.float16)
+            self.norm = Norm(4)
+            self.out_proj = nn.Linear(4, 4, bias=False, dtype=torch.float16)
+        def forward(self, u, inference_params=None):
+            if self.fail:
+                raise RuntimeError('intentional toy mixer failure')
+            if inference_params is not None and u.shape[1] == 1:
+                return self.step(u, inference_params)
+            x, z = self.in_proj(u).chunk(2, -1)
+            if inference_params is not None:
+                inference_params[self.index] = x[:, -1].clone()
+            return self.out_proj(self.norm(x, z))
+        def step(self, u, cache):
+            x, z = self.in_proj(u[:, 0]).chunk(2, -1)
+            x = x+cache.get(self.index, torch.zeros_like(x))*0.125
+            cache[self.index] = x.clone()
+            return self.out_proj(self.norm(x, z)).unsqueeze(1)
+
+    class Block(nn.Module):
+        fused_add_norm, residual_in_fp32, mlp = False, False, None
+        def __init__(self, index):
+            super().__init__()
+            self.norm, self.mixer = Norm(4), Mixer(index)
+        def forward(self, hidden, residual=None, inference_params=None):
+            residual = hidden+residual if residual is not None else hidden
+            return self.mixer(self.norm(residual), inference_params=inference_params), residual
+
+    class Model(nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.backbone = nn.Module()
+            self.backbone.fused_add_norm = self.backbone.residual_in_fp32 = False
+            self.backbone.embedding = nn.Embedding(17, 4, dtype=torch.float16)
+            self.backbone.layers = nn.ModuleList([Block(i) for i in range(2)])
+            self.backbone.norm_f = Norm(4)
+            self.lm_head = nn.Linear(4, 17, bias=False, dtype=torch.float16)
+        def forward(self, ids, inference_params=None):
+            h, r = self.backbone.embedding(ids), None
+            for layer in self.backbone.layers:
+                h, r = layer(h, r, inference_params=inference_params)
+            return self.lm_head(self.backbone.norm_f(h+r))
+
+    model = Model().eval().requires_grad_(False)
+    ids = torch.tensor([[1, 2, 3, 4, 5, 6, 7]])
+    hashes = {name: tensor_hash(p) for name, p in model.named_parameters()}
+    tests = []
+    def passed(name): tests.append(name)
+    def rejects(call):
+        try: call()
+        except (ValueError, RuntimeError, FileExistsError): return
+        raise AssertionError('Expected fail-closed rejection')
+    def zero_grads(bank):
+        for p in bank.parameters(): p.grad = None
+    def cached():
+        cache = {}
+        prefill = model(ids[:, :4], inference_params=cache)
+        step = model(ids[:, 4:5], inference_params=cache)
+        return tensor_hash(prefill), tensor_hash(step), {k: tensor_hash(v) for k, v in cache.items()}
+
+    with torch.no_grad():
+        baseline, base_cache = tensor_hash(model(ids)), cached()
+    bank = ResurfaceNative(model, expected_base_hashes=hashes, production=False)
+    with torch.no_grad():
+        assert tensor_hash(model(ids)) == baseline and cached() == base_cache
+    bank.assert_base_frozen(check_values=True)
+    passed('zero soft adapter native prefill/recurrent-call/cache parity; external inventory')
+
+    hidden, gates = bank.forward_hidden(ids, use_checkpoint=False)
+    model.lm_head(hidden).float().square().mean().backward()
+    for name, p in bank.masters.items():
+        assert p.grad is not None and torch.isfinite(p.grad).all()
+        assert bool(torch.count_nonzero(p.grad)) == name.endswith('.V_read'), name
+    passed('soft zero-V staggered gradients: V nonzero; router and amplitudes zero')
+
+    with torch.no_grad():
+        for key, adapter in bank.adapters.items():
+            adapter.V_read.copy_(torch.tensor([[.0713, -.0927], [.1319, .0423]]))
+            adapter.router_w.copy_(torch.tensor([.0371, -.0447, .0233, .0631]))
+    mask = torch.tensor([[False, False, False, False, False, True, True]])
+    outputs, gradients = [], []
+    for checkpointed in (False, True):
+        zero_grads(bank)
+        hidden, gates = bank.forward_hidden(ids, use_checkpoint=checkpointed)
+        assert gates.logits.shape == (2, 1, 7)
+        manual = F.binary_cross_entropy_with_logits(gates.logits[:, mask], torch.ones_like(gates.logits[:, mask]))
+        torch.testing.assert_close(gates.opening_loss(mask), manual, rtol=0, atol=0)
+        loss = model.lm_head(hidden).float().square().mean()+.03*gates.closure_loss()+.02*gates.opening_loss(mask)
+        loss.backward()
+        outputs.append((tensor_hash(hidden), tensor_hash(gates.logits)))
+        gradients.append({name: p.grad.detach().clone() for name, p in bank.masters.items()})
+        assert not bank._frames and not bank._requests
+    assert outputs[0] == outputs[1]
+    for name in gradients[0]:
+        torch.testing.assert_close(gradients[0][name], gradients[1][name], rtol=0, atol=0)
+        assert torch.isfinite(gradients[1][name]).all() and torch.count_nonzero(gradients[1][name]), name
+    with torch.no_grad():
+        hidden, _ = bank.forward_hidden(ids, use_checkpoint=False)
+        assert tensor_hash(model.lm_head(hidden)) == tensor_hash(model(ids))
+    passed('checkpoint/native outputs, returned capture and every adapter gradient exact')
+
+    model.backbone.layers[0].mixer.fail = True
+    rejects(lambda: bank.forward_hidden(ids))
+    assert not bank._frames and not bank._requests
+    model.backbone.layers[0].mixer.fail = False
+    rejects(lambda: gates.opening_loss(torch.zeros_like(mask)))
+    rejects(lambda: ResurfaceNative(model, production=False))
+    passed('exception cleanup, empty opening mask and duplicate attachment rejected')
+
+    with tempfile.TemporaryDirectory(prefix='resurface-native-cpu-') as temporary:
+        path = Path(temporary)/'adapter.pt'
+        with torch.no_grad(): expected = tensor_hash(model(ids))
+        receipt = bank.export_fp16(path, binding={'toy_base': 'fixed'})
+        expected_values = {name: p.detach().half().clone() for name, p in bank.masters.items()}
+        rejects(lambda: bank.export_fp16(path))
+        bank.close()
+        with install_fp16(model, path, expected_binding={'toy_base': 'fixed'}, expected_base_hashes=hashes,
+                          production=False) as deployed:
+            assert not any(p.requires_grad for p in deployed.parameters())
+            assert all(p.dtype == torch.float16 for p in deployed.parameters())
+            for name, p in deployed.masters.items(): assert tensor_hash(p) == tensor_hash(expected_values[name])
+            with torch.no_grad(): assert tensor_hash(model(ids)) == expected
+            deployed.assert_base_frozen(check_values=True)
+        assert tensor_hash(model(ids)) == baseline
+        invalid = read_fp16(path)
+        invalid['tensors']['layer0.router_b'] = torch.tensor(float('nan'), dtype=torch.float16)
+        bad = Path(temporary)/'bad.pt'
+        torch.save(invalid, bad)
+        rejects(lambda: read_fp16(bad))
+        passed('real FP16 file roundtrip/native parity/no overwrite/nonfinite rejection/hook removal')
+
+    with ResurfaceNative(model, gate_mode='hard', expected_base_hashes=hashes, production=False) as hard:
+        hidden, gates = hard.forward_hidden(ids)
+        model.lm_head(hidden).float().square().mean().backward()
+        assert all(p.grad is not None and not torch.count_nonzero(p.grad) for p in hard.parameters())
+        zero_grads(hard)
+        _, gates = hard.forward_hidden(ids)
+        gates.opening_loss(mask).backward()
+        for name, p in hard.masters.items():
+            if '.router_' in name: assert p.grad is not None and torch.count_nonzero(p.grad)
+        with torch.no_grad():
+            for adapter in hard.adapters.values():
+                adapter.V_read.fill_(.25)
+            assert tensor_hash(model(ids)) == baseline
+            for adapter in hard.adapters.values(): adapter.router_b.fill_(1.)
+            assert tensor_hash(model(ids)) != baseline
+        hard.assert_base_frozen(check_values=True)
+    passed('hard closed-gate dead point, explicit opening gradients and threshold inference')
+    assert tensor_hash(model(ids)) == baseline and not _OWNERS
+    rejects(lambda: ResurfaceNative(model, gate_mode='task_detector', production=False))
+    passed('no task-specific gate mode; all base tensors/content unchanged')
+    return {'complete': True, 'tests': tests, 'passed': len(tests), 'cuda_initialized': torch.cuda.is_initialized(),
+            'production_trainables': 56*(128*128+128+4096+1), 'production_fp16_payload_bytes': 2308208,
+            'toy_export_bytes': receipt['bytes'], 'scope': 'CPU toy hooks only; native8B GPU parity/quality unmeasured'}
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--self-test', action='store_true', required=True)
+    parser.parse_args()
+    print(json.dumps(self_test(), indent=2))

mamba2_recall/runtime.py

@@ -0,0 +1,235 @@
+"""Pinned NVIDIA Mamba-2 8B source loader and exact tokenizer.
+
+Execution uses state-spaces/mamba (Apache-2.0). The Megatron key mapping follows
+NVIDIA's public checkpoint layout. Source BF16 weights are cast to FP16 for the
+native quality reference; this is not native Megatron BF16 parity.
+"""
+from __future__ import annotations
+
+import argparse
+import enum
+import gc
+import hashlib
+import importlib
+import json
+import platform
+import re
+from pathlib import Path
+
+import torch
+from torch import nn
+
+SOURCE_CHECKPOINT_SHA256 = "47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb"
+TOKENIZER_SHA256 = "5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09"
+TOKENIZER_FILENAME = "mt_nlg_plus_multilingual_ja_zh_the_stack_frac_015_256k.model"
+MODEL_CONFIG = {
+    "d_model": 4096, "d_intermediate": 0, "n_layer": 56, "vocab_size": 256000,
+    "ssm_cfg": {"layer": "Mamba2", "d_state": 128, "d_conv": 4, "expand": 2,
+                "headdim": 64, "ngroups": 8, "chunk_size": 128,
+                "rmsnorm": True, "norm_before_gate": False,
+                "use_mem_eff_path": False},
+    "rms_norm": True, "residual_in_fp32": False, "fused_add_norm": False,
+    "pad_vocab_size_multiple": 128, "tie_embeddings": False,
+}
+_VERIFIED_FILES = {}
+
+
+class _MegatronModelType(enum.Enum):
+    # Passive metadata enum from NVIDIA Megatron-LM core_r0.10.0/core/enums.py.
+    encoder_or_decoder = 1
+    encoder_and_decoder = 2
+    retro_encoder = 3
+    retro_decoder = 4
+
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for chunk in iter(lambda: stream.read(8 * 1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def token_digest(ids):
+    import numpy as np
+    return hashlib.sha256(np.asarray(ids, dtype="<i8").tobytes()).hexdigest()
+
+
+def environment_receipt():
+    import importlib.metadata
+    packages = {}
+    for name in ("torch", "mamba-ssm", "numpy", "triton", "datasets", "sentencepiece"):
+        try:
+            packages[name] = importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError:
+            packages[name] = None
+    return {"python": platform.python_version(), "packages": packages,
+            "cuda_runtime": torch.version.cuda,
+            "gpu": torch.cuda.get_device_name() if torch.cuda.is_available() else None,
+            "tf32_matmul": torch.backends.cuda.matmul.allow_tf32}
+
+
+def gpu_memory_receipt():
+    if not torch.cuda.is_available():
+        return None
+    return {"peak_allocated_bytes": torch.cuda.max_memory_allocated(),
+            "peak_reserved_bytes": torch.cuda.max_memory_reserved(),
+            "current_allocated_bytes": torch.cuda.memory_allocated(),
+            "note": "Original BF16 source cast to native FP16 runtime"}
+
+
+def checkpoint_path(source_dir):
+    directory = Path(source_dir)
+    if directory.is_file():
+        return directory
+    for relative in ("model_optim_rng.pt", "release/mp_rank_00/model_optim_rng.pt"):
+        candidate = directory / relative
+        if candidate.is_file():
+            return candidate
+    raise FileNotFoundError(f"NVIDIA checkpoint missing under {directory}")
+
+
+def normalize_source_key(key):
+    """Anchored mapping: decoder.layers.1 must never match layer 10 or 11."""
+    special = {"embedding.word_embeddings.weight": "backbone.embedding.weight",
+               "decoder.final_norm.weight": "backbone.norm_f.weight",
+               "output_layer.weight": "lm_head.weight"}
+    if key in special:
+        return special[key]
+    match = re.fullmatch(r"decoder\.layers\.(\d+)\.(.+)", key)
+    if match:
+        return f"backbone.layers.{int(match[1])}.{match[2]}"
+    # The loader can inspect an already mapped state without changing its keys.
+    if key.startswith("backbone.") or key == "lm_head.weight":
+        return key.replace("backbone.embeddings.", "backbone.embedding.", 1)
+    raise ValueError(f"Unrecognized model tensor key: {key}")
+
+
+def normalize_source_state(state):
+    result = {}
+    for name, value in state.items():
+        if not isinstance(value, torch.Tensor):
+            raise TypeError(f"Unexpected non-tensor model entry {name}: {type(value).__name__}")
+        target = normalize_source_key(name)
+        if target in result:
+            raise ValueError(f"Duplicate normalized tensor: {target}")
+        result[target] = value
+    return result
+
+
+def load_source_state(source_dir, expected_sha256=SOURCE_CHECKPOINT_SHA256):
+    """Load a pinned official CPU checkpoint without an unrestricted unpickler.
+
+    Megatron stores an argparse namespace, a model-kind enum, and NumPy RNG state.
+    Only those inspected passive metadata types are additionally allowed.
+    Unexpected pickle globals fail closed. mmap avoids a second disk copy.
+    """
+    path = checkpoint_path(source_dir)
+    stat = path.stat()
+    cache_key = (str(path.resolve()), stat.st_size, stat.st_mtime_ns)
+    digest = _VERIFIED_FILES.get(cache_key)
+    if digest is None:
+        digest = sha256_file(path)
+        _VERIFIED_FILES[cache_key] = digest
+    if digest != expected_sha256:
+        raise ValueError(f"Source checkpoint SHA-256 mismatch: {digest}")
+    import numpy as np
+    reconstruct = importlib.import_module("numpy.core.multiarray")._reconstruct
+    allowed = [argparse.Namespace, np.ndarray, np.dtype, type(np.dtype("uint32")),
+               (reconstruct, "numpy.core.multiarray._reconstruct"),
+               (_MegatronModelType, "megatron.core.enums.ModelType")]
+    try:
+        with torch.serialization.safe_globals(allowed):
+            checkpoint = torch.load(path, map_location="cpu", mmap=True, weights_only=True)
+    except Exception as error:
+        unsafe = torch.serialization.get_unsafe_globals_in_checkpoint(path)
+        raise RuntimeError(f"Safe checkpoint loading failed; inspect globals {unsafe}") from error
+    state = checkpoint["model"] if "model" in checkpoint else checkpoint
+    result = normalize_source_state(state)
+    del checkpoint
+    return result
+
+
+def make_model(config=None, device="meta", dtype=torch.float16):
+    from mamba_ssm.models.config_mamba import MambaConfig
+    from mamba_ssm.models.mixer_seq_simple import MambaLMHeadModel
+    config = json.loads(json.dumps(MODEL_CONFIG if config is None else config))
+    model = MambaLMHeadModel(MambaConfig(**config), device=device, dtype=dtype)
+    for block in model.backbone.layers:
+        block.mixer.use_mem_eff_path = False
+        expected_group_size = block.mixer.d_ssm // block.mixer.ngroups
+        if block.mixer.norm.group_size != expected_group_size:
+            raise RuntimeError("Runtime does not implement grouped gated RMSNorm")
+    return model.eval().requires_grad_(False)
+
+
+def load_source_model(source_dir, device="cuda", dtype=torch.float16,
+                      expected_sha256=SOURCE_CHECKPOINT_SHA256):
+    model = make_model()
+    state = load_source_state(source_dir, expected_sha256=expected_sha256)
+    model.load_state_dict(state, strict=True, assign=True)
+    del state
+    model = model.to(device=device, dtype=dtype)
+    if model.backbone.embedding.weight.data_ptr() == model.lm_head.weight.data_ptr():
+        raise RuntimeError("8B source requires independent embedding and output head")
+    model._package_receipt = {"format": "original BF16 checkpoint cast to requested dtype",
+                              "source_checkpoint_sha256": expected_sha256,
+                              "parameter_count": sum(p.numel() for p in model.parameters())}
+    return model.eval().requires_grad_(False)
+
+
+class SentencePieceTokenizer:
+    """NVIDIA GPTSentencePiece token IDs without automatic BOS/EOS insertion."""
+    def __init__(self, path):
+        import sentencepiece as spm
+        path = Path(path)
+        if path.is_dir():
+            path = path / TOKENIZER_FILENAME
+        self.path = path
+        self.processor = spm.SentencePieceProcessor(model_file=str(path))
+        self.eos_token_id = self.processor.eos_id()
+        self.bos_token_id = self.processor.bos_id()
+        self.pad_token_id = self.processor.pad_id()
+        self.vocab_size = self.processor.vocab_size()
+        self.sha256 = sha256_file(path)
+        if self.sha256 != TOKENIZER_SHA256:
+            raise ValueError("Tokenizer does not match the pinned original NVIDIA SentencePiece model")
+
+    def encode(self, text, add_special_tokens=False):
+        if add_special_tokens:
+            raise ValueError("This protocol never inserts BOS/EOS automatically")
+        return self.processor.encode_as_ids(text)
+
+    def decode(self, ids, skip_special_tokens=False):
+        if isinstance(ids, torch.Tensor):
+            ids = ids.detach().cpu().tolist()
+        if skip_special_tokens:
+            ids = [i for i in ids if i not in (self.eos_token_id, self.bos_token_id, self.pad_token_id)]
+        return self.processor.decode_ids(ids)
+
+
+def make_cache(model, max_seqlen, batch_size=1, state_dtype=torch.float16):
+    """Native one-token cache: state is rounded to the requested dtype each step."""
+    from mamba_ssm.utils.generation import InferenceParams
+    cache = InferenceParams(max_seqlen=max_seqlen, max_batch_size=batch_size)
+    cache.key_value_memory_dict = model.allocate_inference_cache(
+        batch_size, max_seqlen, dtype=state_dtype)
+    return cache
+
+
+def cache_bytes(cache):
+    return sum(tensor.numel() * tensor.element_size()
+               for pair in cache.key_value_memory_dict.values() for tensor in pair)
+
+
+@torch.inference_mode()
+def backbone_tokenwise(model, ids, state_dtype=torch.float16):
+    cache = make_cache(model, ids.shape[1], ids.shape[0], state_dtype)
+    result = []
+    for position in range(ids.shape[1]):
+        cache.seqlen_offset = position
+        result.append(model.backbone(ids[:, position:position+1], inference_params=cache))
+    return torch.cat(result, dim=1), cache
+
+
+load_model = load_source_model

pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mamb2-8b-recall"
+version = "0.1.0"
+description = "Full precision Mamba2-8B Resurface readout control"
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.26", "torch>=2.6", "sentencepiece", "datasets", "huggingface-hub", "einops"]
+
+[tool.setuptools.packages.find]
+include = ["mamba2_recall*"]

reports/four_arm_comparison_v1.json

@@ -0,0 +1,67 @@
+{
+  "format": "MAMBA2_SOURCE_COMPRESSED_FOUR_ARM_COMPARISON_V1",
+  "complete": true,
+  "source_report_sha256": "4c99694d66af1db71924bd9d3113f1ea2f0a9b93191ed229f3d26f2320c8c940",
+  "compressed_mk_report_sha256": "306ae9e8ed5e78756f7c8ea39c8db40dbebf3895ced3c5c279722be5100a344b",
+  "compressed_ppl_report_sha256": "06a71c11fc0a12a52add6e7bf5d28b8a8eb9f832b2ec1cb846d9acaf30afe961",
+  "exact_mk_prompt_identity": true,
+  "exact_ppl_window_identity": true,
+  "metrics": {
+    "source_fp16": {
+      "mk": {
+        "normal": {
+          "correct": 147,
+          "count": 384
+        },
+        "target_removed": {
+          "correct": 0,
+          "count": 384
+        }
+      },
+      "ppl": 7.334175947318572
+    },
+    "source_resurface": {
+      "mk": {
+        "normal": {
+          "correct": 365,
+          "count": 384
+        },
+        "target_removed": {
+          "correct": 0,
+          "count": 384
+        }
+      },
+      "ppl": 7.052063515606311
+    },
+    "compressed_base": {
+      "mk": {
+        "normal": {
+          "correct": 91,
+          "count": 384
+        },
+        "target_removed": {
+          "correct": 0,
+          "count": 384
+        }
+      },
+      "ppl": 7.622396587826496
+    },
+    "compressed_resurface": {
+      "mk": {
+        "normal": {
+          "correct": 340,
+          "count": 384
+        },
+        "target_removed": {
+          "correct": 0,
+          "count": 384
+        }
+      },
+      "ppl": 7.593163113563457
+    }
+  },
+  "source_adapter_gain_pp": 56.77083333333333,
+  "compressed_adapter_gain_pp": 64.84375,
+  "difference_of_gains_pp": 8.072916666666671,
+  "interpretation": "Descriptive four-arm comparison on already observed numeric/template and validation data; the compressed base also received 448 small-tensor readaptation updates before adapter training, and each arm has its own unadapted-base KL teacher. Do not infer a causal quantization-only interaction or unseen-template generalization."
+}

reports/verification_audit_v1.json

@@ -0,0 +1,2175 @@
+{
+  "format": "MAMBA2_RESURFACE_REPLAY_AUDIT_V1",
+  "arithmetic_tolerance": {
+    "relative": 1e-12,
+    "absolute": 1e-09
+  },
+  "actual_adapter_sha256": "e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0",
+  "pins": {
+    "source_checkpoint_sha256": "47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb",
+    "tokenizer_sha256": "5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09",
+    "protocol_sha256": "dee9457bfaca067b63837dcd3bc94bf9ef9a3d805b1ab04227db05a4b92c54c2",
+    "adapter_sha256": "e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0"
+  },
+  "published_metadata_pins": {
+    "data_manifest_sha256": "227737dd5fbb301d76e583457ff8ee29246047661b3e9a64ebd068a6f34f376c",
+    "dataset_fingerprint": "51d84d52d095f90d"
+  },
+  "scope": "Offline raw-report arithmetic, content identity, regex rescore, and fresh-report comparison. exact_replay covers scientific inputs and outputs; environment-dependent metadata equality is reported separately.",
+  "limitations": [
+    "The verifier does not run the model or independently recompute logits.",
+    "Token hashes are compared; raw prompt/PPL token bytes are not embedded in these reports.",
+    "SentencePiece decoding is not rerun. Equal generated IDs must have equal output text across reports.",
+    "Original frozen-base receipt checks identities, version counters, and gradients, not full tensor contents.",
+    "CONFIRM templates/instances and WikiText validation were previously observed."
+  ],
+  "published": {
+    "baseline": {
+      "ppl": {
+        "windows": 130,
+        "target_tokens": 264764,
+        "nll_recomputed": 527554.2002649307,
+        "ppl_recomputed": 7.334175947318572,
+        "stored_nll_minus_recomputed": 0.0,
+        "stored_ppl_minus_recomputed": 0.0
+      },
+      "mk": {
+        "summary": {
+          "normal": {
+            "correct": 147,
+            "count": 384,
+            "accuracy": 0.3828125
+          },
+          "target_removed": {
+            "correct": 0,
+            "count": 384,
+            "accuracy": 0.0
+          }
+        },
+        "normal_by_N": {
+          "16": {
+            "correct": 113,
+            "count": 192,
+            "accuracy": 0.5885416666666666
+          },
+          "64": {
+            "correct": 34,
+            "count": 192,
+            "accuracy": 0.17708333333333334
+          }
+        },
+        "generated_length_histogram": {
+          "10": 3,
+          "12": 765
+        }
+      }
+    },
+    "adapter": {
+      "ppl": {
+        "windows": 130,
+        "target_tokens": 264764,
+        "nll_recomputed": 517168.8882961273,
+        "ppl_recomputed": 7.052063515606311,
+        "stored_nll_minus_recomputed": 0.0,
+        "stored_ppl_minus_recomputed": 0.0
+      },
+      "mk": {
+        "summary": {
+          "normal": {
+            "correct": 365,
+            "count": 384,
+            "accuracy": 0.9505208333333334
+          },
+          "target_removed": {
+            "correct": 0,
+            "count": 384,
+            "accuracy": 0.0
+          }
+        },
+        "normal_by_N": {
+          "16": {
+            "correct": 191,
+            "count": 192,
+            "accuracy": 0.9947916666666666
+          },
+          "64": {
+            "correct": 174,
+            "count": 192,
+            "accuracy": 0.90625
+          }
+        },
+        "generated_length_histogram": {
+          "12": 768
+        }
+      }
+    },
+    "mk_comparison": {
+      "normal": {
+        "both_correct": 143,
+        "both_wrong": 15,
+        "gained": 222,
+        "lost": 4,
+        "count": 384,
+        "baseline_correct": 147,
+        "adapter_correct": 365,
+        "delta_percentage_points": 56.770833333333336
+      },
+      "target_removed": {
+        "both_correct": 0,
+        "both_wrong": 384,
+        "gained": 0,
+        "lost": 0,
+        "count": 384,
+        "baseline_correct": 0,
+        "adapter_correct": 0,
+        "delta_percentage_points": 0.0
+      }
+    },
+    "ppl_delta_percent_recomputed": -3.846545729727191,
+    "restored_probe": {
+      "summary": {
+        "normal": {
+          "correct": 4,
+          "count": 4,
+          "accuracy": 1.0
+        },
+        "target_removed": {
+          "correct": 0,
+          "count": 4,
+          "accuracy": 0.0
+        }
+      },
+      "normal_by_N": {
+        "16": {
+          "correct": 4,
+          "count": 4,
+          "accuracy": 1.0
+        }
+      },
+      "generated_length_histogram": {
+        "12": 8
+      }
+    }
+  },
+  "replay": {
+    "baseline": {
+      "ppl": {
+        "windows": 130,
+        "target_tokens": 264764,
+        "nll_recomputed": 527554.2002649307,
+        "ppl_recomputed": 7.334175947318572,
+        "stored_nll_minus_recomputed": 0.0,
+        "stored_ppl_minus_recomputed": 0.0
+      },
+      "mk": {
+        "summary": {
+          "normal": {
+            "correct": 147,
+            "count": 384,
+            "accuracy": 0.3828125
+          },
+          "target_removed": {
+            "correct": 0,
+            "count": 384,
+            "accuracy": 0.0
+          }
+        },
+        "normal_by_N": {
+          "16": {
+            "correct": 113,
+            "count": 192,
+            "accuracy": 0.5885416666666666
+          },
+          "64": {
+            "correct": 34,
+            "count": 192,
+            "accuracy": 0.17708333333333334
+          }
+        },
+        "generated_length_histogram": {
+          "10": 3,
+          "12": 765
+        }
+      }
+    },
+    "adapter": {
+      "ppl": {
+        "windows": 130,
+        "target_tokens": 264764,
+        "nll_recomputed": 517168.8882961273,
+        "ppl_recomputed": 7.052063515606311,
+        "stored_nll_minus_recomputed": 0.0,
+        "stored_ppl_minus_recomputed": 0.0
+      },
+      "mk": {
+        "summary": {
+          "normal": {
+            "correct": 365,
+            "count": 384,
+            "accuracy": 0.9505208333333334
+          },
+          "target_removed": {
+            "correct": 0,
+            "count": 384,
+            "accuracy": 0.0
+          }
+        },
+        "normal_by_N": {
+          "16": {
+            "correct": 191,
+            "count": 192,
+            "accuracy": 0.9947916666666666
+          },
+          "64": {
+            "correct": 174,
+            "count": 192,
+            "accuracy": 0.90625
+          }
+        },
+        "generated_length_histogram": {
+          "12": 768
+        }
+      }
+    },
+    "mk_comparison": {
+      "normal": {
+        "both_correct": 143,
+        "both_wrong": 15,
+        "gained": 222,
+        "lost": 4,
+        "count": 384,
+        "baseline_correct": 147,
+        "adapter_correct": 365,
+        "delta_percentage_points": 56.770833333333336
+      },
+      "target_removed": {
+        "both_correct": 0,
+        "both_wrong": 384,
+        "gained": 0,
+        "lost": 0,
+        "count": 384,
+        "baseline_correct": 0,
+        "adapter_correct": 0,
+        "delta_percentage_points": 0.0
+      }
+    },
+    "ppl_delta_percent_recomputed": -3.846545729727191,
+    "restored_probe": {
+      "summary": {
+        "normal": {
+          "correct": 4,
+          "count": 4,
+          "accuracy": 1.0
+        },
+        "target_removed": {
+          "correct": 0,
+          "count": 4,
+          "accuracy": 0.0
+        }
+      },
+      "normal_by_N": {
+        "16": {
+          "correct": 4,
+          "count": 4,
+          "accuracy": 1.0
+        }
+      },
+      "generated_length_histogram": {
+        "12": 8
+      }
+    }
+  },
+  "metadata_comparison": {
+    "manifests_equal": true,
+    "published_data_manifest_sha256": "227737dd5fbb301d76e583457ff8ee29246047661b3e9a64ebd068a6f34f376c",
+    "replay_data_manifest_sha256": "227737dd5fbb301d76e583457ff8ee29246047661b3e9a64ebd068a6f34f376c",
+    "dataset_fingerprints_equal": true,
+    "published_dataset_fingerprint": "51d84d52d095f90d",
+    "replay_dataset_fingerprint": "51d84d52d095f90d",
+    "interpretation": "The data manifest embeds Python version and dataset fingerprints depend on environment. These metadata may differ while all ordered prompt/token hashes, answers, dataset text/token digests, and revision remain identical."
+  },
+  "comparison": {
+    "baseline": {
+      "ppl": {
+        "aggregate_nll_exact": true,
+        "aggregate_ppl_exact": true,
+        "nll_delta": 0.0,
+        "ppl_delta": 0.0,
+        "max_abs_window_nll_error": 0.0,
+        "max_abs_window_ppl_error": 0.0,
+        "exact_nll_windows": 130,
+        "windows": [
+          {
+            "index": 0,
+            "start": 0,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 1,
+            "start": 2048,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 2,
+            "start": 4096,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 3,
+            "start": 6144,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 4,
+            "start": 8192,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 5,
+            "start": 10240,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 6,
+            "start": 12288,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 7,
+            "start": 14336,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 8,
+            "start": 16384,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 9,
+            "start": 18432,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 10,
+            "start": 20480,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 11,
+            "start": 22528,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 12,
+            "start": 24576,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 13,
+            "start": 26624,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 14,
+            "start": 28672,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 15,
+            "start": 30720,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 16,
+            "start": 32768,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 17,
+            "start": 34816,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 18,
+            "start": 36864,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 19,
+            "start": 38912,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 20,
+            "start": 40960,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 21,
+            "start": 43008,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 22,
+            "start": 45056,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 23,
+            "start": 47104,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 24,
+            "start": 49152,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 25,
+            "start": 51200,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 26,
+            "start": 53248,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 27,
+            "start": 55296,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 28,
+            "start": 57344,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 29,
+            "start": 59392,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 30,
+            "start": 61440,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 31,
+            "start": 63488,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 32,
+            "start": 65536,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 33,
+            "start": 67584,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 34,
+            "start": 69632,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 35,
+            "start": 71680,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 36,
+            "start": 73728,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 37,
+            "start": 75776,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 38,
+            "start": 77824,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 39,
+            "start": 79872,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 40,
+            "start": 81920,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 41,
+            "start": 83968,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 42,
+            "start": 86016,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 43,
+            "start": 88064,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 44,
+            "start": 90112,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 45,
+            "start": 92160,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 46,
+            "start": 94208,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 47,
+            "start": 96256,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 48,
+            "start": 98304,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 49,
+            "start": 100352,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 50,
+            "start": 102400,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 51,
+            "start": 104448,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 52,
+            "start": 106496,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 53,
+            "start": 108544,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 54,
+            "start": 110592,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 55,
+            "start": 112640,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 56,
+            "start": 114688,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 57,
+            "start": 116736,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 58,
+            "start": 118784,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 59,
+            "start": 120832,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 60,
+            "start": 122880,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 61,
+            "start": 124928,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 62,
+            "start": 126976,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 63,
+            "start": 129024,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 64,
+            "start": 131072,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 65,
+            "start": 133120,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 66,
+            "start": 135168,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 67,
+            "start": 137216,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 68,
+            "start": 139264,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 69,
+            "start": 141312,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 70,
+            "start": 143360,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 71,
+            "start": 145408,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 72,
+            "start": 147456,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 73,
+            "start": 149504,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 74,
+            "start": 151552,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 75,
+            "start": 153600,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 76,
+            "start": 155648,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 77,
+            "start": 157696,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 78,
+            "start": 159744,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 79,
+            "start": 161792,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 80,
+            "start": 163840,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 81,
+            "start": 165888,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 82,
+            "start": 167936,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 83,
+            "start": 169984,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 84,
+            "start": 172032,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 85,
+            "start": 174080,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 86,
+            "start": 176128,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 87,
+            "start": 178176,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 88,
+            "start": 180224,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 89,
+            "start": 182272,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 90,
+            "start": 184320,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 91,
+            "start": 186368,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 92,
+            "start": 188416,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 93,
+            "start": 190464,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 94,
+            "start": 192512,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 95,
+            "start": 194560,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 96,
+            "start": 196608,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 97,
+            "start": 198656,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 98,
+            "start": 200704,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 99,
+            "start": 202752,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 100,
+            "start": 204800,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 101,
+            "start": 206848,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 102,
+            "start": 208896,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 103,
+            "start": 210944,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 104,
+            "start": 212992,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 105,
+            "start": 215040,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 106,
+            "start": 217088,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 107,
+            "start": 219136,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 108,
+            "start": 221184,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 109,
+            "start": 223232,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 110,
+            "start": 225280,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 111,
+            "start": 227328,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 112,
+            "start": 229376,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 113,
+            "start": 231424,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 114,
+            "start": 233472,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 115,
+            "start": 235520,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 116,
+            "start": 237568,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 117,
+            "start": 239616,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 118,
+            "start": 241664,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 119,
+            "start": 243712,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 120,
+            "start": 245760,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 121,
+            "start": 247808,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 122,
+            "start": 249856,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 123,
+            "start": 251904,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 124,
+            "start": 253952,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 125,
+            "start": 256000,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 126,
+            "start": 258048,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 127,
+            "start": 260096,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 128,
+            "start": 262144,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 129,
+            "start": 264192,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          }
+        ]
+      },
+      "mk": {
+        "rows": 768,
+        "all_generated_ids_exact": true,
+        "all_output_text_exact": true,
+        "all_predictions_exact": true,
+        "all_correctness_exact": true,
+        "changed_rows": 0,
+        "differences": []
+      }
+    },
+    "adapter": {
+      "ppl": {
+        "aggregate_nll_exact": true,
+        "aggregate_ppl_exact": true,
+        "nll_delta": 0.0,
+        "ppl_delta": 0.0,
+        "max_abs_window_nll_error": 0.0,
+        "max_abs_window_ppl_error": 0.0,
+        "exact_nll_windows": 130,
+        "windows": [
+          {
+            "index": 0,
+            "start": 0,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 1,
+            "start": 2048,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 2,
+            "start": 4096,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 3,
+            "start": 6144,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 4,
+            "start": 8192,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 5,
+            "start": 10240,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 6,
+            "start": 12288,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 7,
+            "start": 14336,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 8,
+            "start": 16384,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 9,
+            "start": 18432,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 10,
+            "start": 20480,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 11,
+            "start": 22528,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 12,
+            "start": 24576,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 13,
+            "start": 26624,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 14,
+            "start": 28672,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 15,
+            "start": 30720,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 16,
+            "start": 32768,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 17,
+            "start": 34816,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 18,
+            "start": 36864,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 19,
+            "start": 38912,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 20,
+            "start": 40960,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 21,
+            "start": 43008,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 22,
+            "start": 45056,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 23,
+            "start": 47104,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 24,
+            "start": 49152,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 25,
+            "start": 51200,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 26,
+            "start": 53248,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 27,
+            "start": 55296,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 28,
+            "start": 57344,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 29,
+            "start": 59392,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 30,
+            "start": 61440,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 31,
+            "start": 63488,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 32,
+            "start": 65536,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 33,
+            "start": 67584,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 34,
+            "start": 69632,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 35,
+            "start": 71680,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 36,
+            "start": 73728,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 37,
+            "start": 75776,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 38,
+            "start": 77824,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 39,
+            "start": 79872,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 40,
+            "start": 81920,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 41,
+            "start": 83968,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 42,
+            "start": 86016,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 43,
+            "start": 88064,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 44,
+            "start": 90112,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 45,
+            "start": 92160,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 46,
+            "start": 94208,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 47,
+            "start": 96256,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 48,
+            "start": 98304,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 49,
+            "start": 100352,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 50,
+            "start": 102400,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 51,
+            "start": 104448,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 52,
+            "start": 106496,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 53,
+            "start": 108544,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 54,
+            "start": 110592,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 55,
+            "start": 112640,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 56,
+            "start": 114688,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 57,
+            "start": 116736,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 58,
+            "start": 118784,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 59,
+            "start": 120832,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 60,
+            "start": 122880,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 61,
+            "start": 124928,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 62,
+            "start": 126976,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 63,
+            "start": 129024,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 64,
+            "start": 131072,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 65,
+            "start": 133120,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 66,
+            "start": 135168,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 67,
+            "start": 137216,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 68,
+            "start": 139264,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 69,
+            "start": 141312,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 70,
+            "start": 143360,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 71,
+            "start": 145408,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 72,
+            "start": 147456,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 73,
+            "start": 149504,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 74,
+            "start": 151552,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 75,
+            "start": 153600,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 76,
+            "start": 155648,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 77,
+            "start": 157696,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 78,
+            "start": 159744,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 79,
+            "start": 161792,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 80,
+            "start": 163840,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 81,
+            "start": 165888,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 82,
+            "start": 167936,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 83,
+            "start": 169984,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 84,
+            "start": 172032,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 85,
+            "start": 174080,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 86,
+            "start": 176128,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 87,
+            "start": 178176,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 88,
+            "start": 180224,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 89,
+            "start": 182272,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 90,
+            "start": 184320,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 91,
+            "start": 186368,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 92,
+            "start": 188416,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 93,
+            "start": 190464,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 94,
+            "start": 192512,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 95,
+            "start": 194560,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 96,
+            "start": 196608,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 97,
+            "start": 198656,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 98,
+            "start": 200704,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 99,
+            "start": 202752,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 100,
+            "start": 204800,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 101,
+            "start": 206848,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 102,
+            "start": 208896,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 103,
+            "start": 210944,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 104,
+            "start": 212992,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 105,
+            "start": 215040,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 106,
+            "start": 217088,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 107,
+            "start": 219136,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 108,
+            "start": 221184,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 109,
+            "start": 223232,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 110,
+            "start": 225280,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 111,
+            "start": 227328,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 112,
+            "start": 229376,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 113,
+            "start": 231424,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 114,
+            "start": 233472,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 115,
+            "start": 235520,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 116,
+            "start": 237568,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 117,
+            "start": 239616,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 118,
+            "start": 241664,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 119,
+            "start": 243712,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 120,
+            "start": 245760,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 121,
+            "start": 247808,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 122,
+            "start": 249856,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 123,
+            "start": 251904,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 124,
+            "start": 253952,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 125,
+            "start": 256000,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 126,
+            "start": 258048,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 127,
+            "start": 260096,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 128,
+            "start": 262144,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          },
+          {
+            "index": 129,
+            "start": 264192,
+            "nll_delta": 0.0,
+            "ppl_delta": 0.0,
+            "nll_exact": true
+          }
+        ]
+      },
+      "mk": {
+        "rows": 768,
+        "all_generated_ids_exact": true,
+        "all_output_text_exact": true,
+        "all_predictions_exact": true,
+        "all_correctness_exact": true,
+        "changed_rows": 0,
+        "differences": []
+      }
+    }
+  },
+  "errors": [],
+  "integrity_passed": true,
+  "exact_replay": true,
+  "status": "exact_replay",
+  "files": {
+    "published": {
+      "path": "/Users/Kun/Documents/ChatGPT/mamb2_8B_Recall/reports/source_resurface_v1_confirm_full.json",
+      "sha256": "4c99694d66af1db71924bd9d3113f1ea2f0a9b93191ed229f3d26f2320c8c940"
+    },
+    "replay": {
+      "path": "/Users/Kun/Documents/ChatGPT/mamb2_8B_Recall/reports/verification_replay_v1.json",
+      "sha256": "a83faedb5f25150ff8c3bf93a312619c11191e5dd06677d236cb7658c8173779"
+    },
+    "adapter": {
+      "path": "/Users/Kun/Documents/ChatGPT/mamb2_8B_Recall/artifacts/source_resurface_v1/adapter_fp16.pt",
+      "sha256": "e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0"
+    }
+  }
+}

reports/verification_hub_metadata_v1.json

@@ -0,0 +1,20 @@
+{
+  "method": "huggingface_hub.HfApi model_info(files_metadata=True) and dataset_info at pinned revisions",
+  "verified_date": "2026-09-28",
+  "model": "nvidia/mamba2-8b-3t-4k",
+  "model_revision": "b915550c63ba9359f88f44d1f6a600d85af27302",
+  "files": [
+    {
+      "file": "mt_nlg_plus_multilingual_ja_zh_the_stack_frac_015_256k.model",
+      "bytes": 4573028,
+      "sha256": "5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09"
+    },
+    {
+      "file": "release/mp_rank_00/model_optim_rng.pt",
+      "bytes": 16474189490,
+      "sha256": "47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb"
+    }
+  ],
+  "dataset": "Salesforce/wikitext",
+  "dataset_revision": "b08601e04326c79dfdd32d625aee71d232d685c3"
+}

reports/verification_origin_v1.json

@@ -0,0 +1,48 @@
+{
+  "git_commit": "e4137a43ef87cb95b70243ea2271f8e9b3d93d27",
+  "git_clean": true,
+  "environment": {
+    "python": "3.10.12",
+    "packages": {
+      "torch": "2.11.0+cu128",
+      "mamba-ssm": "2.3.2.post1",
+      "numpy": "1.26.4",
+      "triton": "3.6.0",
+      "datasets": "4.8.5",
+      "sentencepiece": "0.2.1"
+    },
+    "cuda_runtime": "12.8",
+    "gpu": "NVIDIA RTX PRO 6000 Blackwell Server Edition",
+    "tf32_matmul": false
+  },
+  "command": [
+    "/home/horde/.venvs/lodram/bin/python",
+    "scripts/evaluate.py",
+    "--source-dir",
+    "/home/horde/Mamba2-8B-E8W5/models/source",
+    "--adapter",
+    "/home/horde/mamb2_8B_Recall_verify_e4137a4/artifacts/source_resurface_v1/adapter_fp16.pt",
+    "--data-root",
+    "/home/horde/mamb2_8B_Recall_verify_e4137a4/training_data/numeric_v1",
+    "--eval-manifest-sha256",
+    "227737dd5fbb301d76e583457ff8ee29246047661b3e9a64ebd068a6f34f376c",
+    "--split",
+    "confirm",
+    "--report",
+    "/home/horde/mamb2_8B_Recall_verify_e4137a4/reports/verification_replay_v1.json"
+  ],
+  "code_sha256": {
+    "mamba2_recall/__init__.py": "79b32606ac476c3248911c55571bf97f96689770067856ce8347837478ef33fd",
+    "mamba2_recall/calibration.py": "54e178521abfe2513fb7bac2aed2ef178fc01b63135222ecc212001ee3ce0a04",
+    "mamba2_recall/evaluation.py": "95cba0b201e37f92e6cbfadb9b3e9d79ba7b0cdc9efda6a58a6216b0d84d35e0",
+    "mamba2_recall/resurface_data.py": "1a547fe3cedca406d6e3db85f65c3ce554558691e3b29b9c92d8fd6bd1c1ba35",
+    "mamba2_recall/resurface_loss.py": "ec045368583b6e49f484341b2d718658bb59e8d11050710377742752c1c67294",
+    "mamba2_recall/resurface_native.py": "2dd08c7ee8958c832f0ae9da7cf5f261dceeff3e528e493c905c7c52df7166d7",
+    "mamba2_recall/runtime.py": "73a405b4286dda403f252cf0b73d367adcfead96298a1e6f440b65f5b309530c",
+    "scripts/compare_four_arms.py": "6e41f9ab4f6e39c5a23da6ad1edc29e5b10da57e93e2ea008f4d153c8f195e3b",
+    "scripts/evaluate.py": "825acc58d957abe9c755b44c783970c7a379594dfd15e0a67f0ff9a0638f74bb",
+    "scripts/prepare_data.py": "11d5e6872382fb8a62987937ec37006422b38e4b1650431a4794d5834c6a4604",
+    "scripts/prepare_prose.py": "f63659bab565f2428629f2c9239ba2bdb4ccfb6c647accc44be71b2f419a7c7e",
+    "scripts/train.py": "3ea5ef8beadf5d4f14650e9fe15949cd6116e247ddd7641d7f024c5763aa8eb2"
+  }
+}

reports/verification_token_receipts_v1.json

@@ -0,0 +1,22 @@
+{
+  "complete": true,
+  "passed": true,
+  "method": "CPU-only regenerated numeric prompts and pinned WikiText tokens; SentencePiece decode of saved generated IDs; independent little-endian int64 token hashing",
+  "tokenizer_sha256": "5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09",
+  "reports_sha256": {
+    "source_resurface_v1_confirm_full.json": "4c99694d66af1db71924bd9d3113f1ea2f0a9b93191ed229f3d26f2320c8c940",
+    "verification_replay_v1.json": "a83faedb5f25150ff8c3bf93a312619c11191e5dd06677d236cb7658c8173779"
+  },
+  "generated_outputs_checked": 3088,
+  "prompt_receipts_checked": 3088,
+  "ppl_window_receipts_checked": 520,
+  "train_rows": 1536,
+  "confirm_rows": 768,
+  "numeric_train_confirm_overlap_counts": {
+    "ids": 0,
+    "prompts": 0,
+    "keys": 0,
+    "values": 0
+  },
+  "errors": []
+}

resurface_config.json

@@ -0,0 +1,68 @@
+{
+  "format": "MAMBA2_SOURCE_RESURFACE_HF_RELEASE_V1",
+  "repo_id": "EndlessChasing/Mamb2_8B_Recall",
+  "source_repository": "https://github.com/EndlessChasing/mamb2_8B_Recall",
+  "source_commit": "4478c034aff9e5dab7af47efa84214287824138d",
+  "base_model": {
+    "repo_id": "nvidia/mamba2-8b-3t-4k",
+    "revision": "b915550c63ba9359f88f44d1f6a600d85af27302",
+    "checkpoint_path": "release/mp_rank_00/model_optim_rng.pt",
+    "checkpoint_sha256": "47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb",
+    "tokenizer_path": "mt_nlg_plus_multilingual_ja_zh_the_stack_frac_015_256k.model",
+    "tokenizer_sha256": "5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09",
+    "parameters": 8236999680,
+    "blocks": 56,
+    "architecture": "pure Mamba2; no attention or MoE",
+    "source_dtype": "bfloat16",
+    "runtime_dtype": "float16",
+    "download_separately": true
+  },
+  "adapter": {
+    "path": "artifacts/source_resurface_v1/adapter_fp16.pt",
+    "bytes": 2374143,
+    "sha256": "e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0",
+    "parameters": 1154104,
+    "payload_bytes": 2308208,
+    "gate_mode": "soft",
+    "format": "MAMBA2_POST_D_RESURFACE_FP16_V1",
+    "insertion_site": "post-D, before grouped gated RMSNorm",
+    "additional_recurrent_cache_bytes": 0,
+    "binding": {
+      "source_checkpoint_sha256": "47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb",
+      "tokenizer_sha256": "5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09",
+      "protocol_sha256": "dee9457bfaca067b63837dcd3bc94bf9ef9a3d805b1ab04227db05a4b92c54c2",
+      "train_manifest_sha256": "e711c87378dcee84c9ff5023ae15aa11c5abe6c64fbe68c52c543eaea70103b8",
+      "prose_manifest_sha256": "facb2ca461615a4199781bd21784d642d6674f5b862641b3b9edac3fb499b89d",
+      "prose_tokens_sha256": "e54b02e5162e042a9cdd504f4eb1b1652724fb240bbc2c97608967aa26297233",
+      "prose_tokens_int64le_sha256": "049dfb6847d778897fd19b67653c3189f29fbc19a36022e8a4801306d08228bc",
+      "prose_file_exact_historical": true,
+      "adapter": "MAMBA2_POST_D_RESURFACE_FP16_V1",
+      "successful_updates": 1536
+    }
+  },
+  "custom_runtime": {
+    "loader": "mamba2_recall.runtime.load_source_model",
+    "installer": "mamba2_recall.resurface_native.install_fp16",
+    "requires_gpu": "CUDA",
+    "transformers_auto_model_compatible": false,
+    "peft_compatible": false
+  },
+  "metrics": {
+    "source_ppl": 7.334175947318572,
+    "adapter_ppl": 7.052063515606311,
+    "source_normal_mk": {
+      "correct": 147,
+      "count": 384,
+      "accuracy": 0.3828125
+    },
+    "adapter_normal_mk": {
+      "correct": 365,
+      "count": 384,
+      "accuracy": 0.9505208333333334
+    },
+    "protocol": "docs/PROTOCOL.md",
+    "verification": "docs/VERIFICATION.md",
+    "verification_report": "reports/verification_audit_v1.json",
+    "untouched_holdout": false
+  }
+}

scripts/compare_four_arms.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Compare paired source/compressed Resurface results on identical inputs."""
+from __future__ import annotations
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+OLD_MK_SHA='306ae9e8ed5e78756f7c8ea39c8db40dbebf3895ced3c5c279722be5100a344b'
+OLD_PPL_SHA='06a71c11fc0a12a52add6e7bf5d28b8a8eb9f832b2ec1cb846d9acaf30afe961'
+IDENTITY=('id','condition','prompt_token_sha256_int64le')
+
+
+def sha256_file(path):
+    digest=hashlib.sha256()
+    with Path(path).open('rb') as stream:
+        for chunk in iter(lambda:stream.read(8<<20),b''):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def identity(rows):
+    return [tuple(row[k] for k in IDENTITY) for row in rows]
+
+
+def summary(rows):
+    result={}
+    for condition in ('normal','target_removed'):
+        relevant=[r for r in rows if r['condition']==condition]
+        result[condition]={'correct':sum(r['correct'] for r in relevant),
+                           'count':len(relevant)}
+    return result
+
+
+def main():
+    p=argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--source-report',type=Path,required=True)
+    p.add_argument('--compressed-mk-report',type=Path,required=True)
+    p.add_argument('--compressed-ppl-report',type=Path,required=True)
+    p.add_argument('--output',type=Path,required=True)
+    a=p.parse_args()
+    if a.output.exists():raise FileExistsError(a.output)
+    if (sha256_file(a.compressed_mk_report)!=OLD_MK_SHA or
+            sha256_file(a.compressed_ppl_report)!=OLD_PPL_SHA):
+        raise ValueError('Historical compressed reports differ from published receipts')
+    source=json.loads(a.source_report.read_text())
+    mk=json.loads(a.compressed_mk_report.read_text())
+    ppl=json.loads(a.compressed_ppl_report.read_text())
+    if (source.get('complete') is not True or source.get('smoke') is not False
+            or source.get('split')!='confirm' or mk.get('complete') is not True
+            or ppl.get('complete') is not True):
+        raise ValueError('Only complete full source/COMPRESSED reports are comparable')
+    rows={
+        'source_fp16':source['baseline_mk']['rows'],
+        'source_resurface':source['adapter_mk']['rows'],
+        'compressed_base':mk['arms']['current_readapted']['rows'],
+        'compressed_resurface':mk['arms']['active_resurface']['rows'],
+    }
+    if (any(len(item)!=768 for item in rows.values()) or
+            len({tuple(identity(item)) for item in rows.values()})!=1):
+        raise ValueError('Different MK prompt ordering, tokens or split')
+    for name,item in rows.items():
+        if summary(item)['normal']['count']!=384 or summary(item)['target_removed']['count']!=384:
+            raise ValueError(f'Incomplete MK condition coverage: {name}')
+    source_ppl_windows=source['baseline_ppl']['windows']
+    source_active_windows=source['adapter_ppl']['windows']
+    compressed_ppl_windows=ppl['ppl']['current_readapted']['windows']
+    compressed_active_windows=ppl['ppl']['active_resurface']['windows']
+    def windows_id(items):
+        return [(r['start'],r['target_tokens'],r['token_sha256_int64le']) for r in items]
+    if (any(len(item)!=130 for item in (source_ppl_windows,source_active_windows,
+                                         compressed_ppl_windows,compressed_active_windows)) or
+            len({tuple(windows_id(item)) for item in (source_ppl_windows,source_active_windows,
+                compressed_ppl_windows,compressed_active_windows)})!=1 or
+            sum(r['target_tokens'] for r in source_ppl_windows)!=264764):
+        raise ValueError('PPL tokenizer/window/target coverage differs')
+    metrics={name:{'mk':summary(item)} for name,item in rows.items()}
+    for name,value in zip(metrics,(
+        source['baseline_ppl']['ppl'],source['adapter_ppl']['ppl'],
+        ppl['ppl']['current_readapted']['summary']['ppl'],
+        ppl['ppl']['active_resurface']['summary']['ppl'])):
+        metrics[name]['ppl']=value
+    score=lambda name:100*metrics[name]['mk']['normal']['correct']/384
+    source_gain=score('source_resurface')-score('source_fp16')
+    compressed_gain=score('compressed_resurface')-score('compressed_base')
+    result={'format':'MAMBA2_SOURCE_COMPRESSED_FOUR_ARM_COMPARISON_V1',
+        'complete':True,'source_report_sha256':sha256_file(a.source_report),
+        'compressed_mk_report_sha256':OLD_MK_SHA,'compressed_ppl_report_sha256':OLD_PPL_SHA,
+        'exact_mk_prompt_identity':True,'exact_ppl_window_identity':True,
+        'metrics':metrics,'source_adapter_gain_pp':source_gain,
+        'compressed_adapter_gain_pp':compressed_gain,
+        'difference_of_gains_pp':compressed_gain-source_gain,
+        'interpretation':'Descriptive four-arm comparison on already observed numeric/template and validation data; the compressed base also received 448 small-tensor readaptation updates before adapter training, and each arm has its own unadapted-base KL teacher. Do not infer a causal quantization-only interaction or unseen-template generalization.'}
+    a.output.parent.mkdir(parents=True,exist_ok=True)
+    a.output.write_text(json.dumps(result,indent=2,allow_nan=False)+'\n')
+    print(json.dumps({'complete':True,'source_adapter_gain_pp':source_gain,
+        'compressed_adapter_gain_pp':compressed_gain,
+        'difference_of_gains_pp':compressed_gain-source_gain}),flush=True)
+
+
+if __name__=='__main__':main()

scripts/evaluate.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Paired FP16 source/readout recall and WikiText-2 validation evaluation."""
+from __future__ import annotations
+import argparse
+import json
+import math
+from pathlib import Path
+import re
+import sys
+import time
+import traceback
+
+import torch
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0,str(ROOT))
+from mamba2_recall import calibration, evaluation, resurface_data as data
+from mamba2_recall import resurface_native as native, runtime
+
+MATCH = re.compile(r'(?<!\d)\d{6}(?!\d)')
+
+
+def write_json(path,value):
+    path = Path(path)
+    path.parent.mkdir(parents=True,exist_ok=True)
+    temporary = path.with_suffix(path.suffix+'.tmp')
+    temporary.write_text(json.dumps(value,indent=2,allow_nan=False)+'\n')
+    temporary.replace(path)
+
+
+@torch.inference_mode()
+def score_mk(model,tokenizer,cases,limit=None):
+    rows=[]
+    for index,case in enumerate(cases[:limit] if limit is not None else cases):
+        output,generated,tokens,cache_bytes = evaluation.generate_greedy(
+            model,tokenizer,case['prompt'],max_new_tokens=12,execution='prefill')
+        match = MATCH.search(output)
+        prediction = match.group() if match else None
+        rows.append({'id':case['id'],'condition':case['condition'],
+            'N':case['N'],'template':case['template'],
+            'prompt_token_sha256_int64le':data.token_digest(tokenizer.encode(case['prompt'])),
+            'expected':case['answer'],'prediction':prediction,
+            'correct':prediction==case['answer'],'generated_ids':generated,
+            'output':output,'prompt_tokens':tokens,'cache_bytes':cache_bytes})
+        if cache_bytes!=122028032:
+            raise RuntimeError('FP16 native cache bytes differ')
+        if (index+1)%32==0 or index==0:
+            print(json.dumps({'mk_completed':index+1,'mk_total':len(cases) if limit is None else limit}),flush=True)
+    summary={}
+    for condition in ('normal','target_removed'):
+        selected=[r for r in rows if r['condition']==condition]
+        if selected:
+            summary[condition]={'correct':sum(r['correct'] for r in selected),
+                'count':len(selected),'accuracy':sum(r['correct'] for r in selected)/len(selected)}
+    return {'rows':rows,'summary':summary,'generation':'greedy max12, full256K, fresh FP16 cache',
+            'matching':'first standalone six-digit integer'}
+
+
+def compare_mk(baseline,active):
+    result={}
+    for condition in ('normal','target_removed'):
+        counts={'both_correct':0,'both_wrong':0,'gained':0,'lost':0}
+        a=[row for row in baseline['rows'] if row['condition']==condition]
+        b=[row for row in active['rows'] if row['condition']==condition]
+        if len(a)!=len(b):
+            raise ValueError('MK arm length differs')
+        for before,after in zip(a,b):
+            if any(before[key]!=after[key] for key in ('id','condition','expected','prompt_token_sha256_int64le')):
+                raise ValueError('Paired MK prompt identity differs')
+            bucket={(False,False):'both_wrong',(True,True):'both_correct',
+                    (False,True):'gained',(True,False):'lost'}[(before['correct'],after['correct'])]
+            counts[bucket]+=1
+        result[condition]={**counts,'count':len(a),
+            'baseline_correct':sum(r['correct'] for r in a),
+            'adapter_correct':sum(r['correct'] for r in b),
+            'delta_percentage_points':100*(counts['gained']-counts['lost'])/len(a)}
+    return result
+
+
+def main():
+    p=argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--source-dir',type=Path,required=True)
+    p.add_argument('--adapter',type=Path,required=True)
+    p.add_argument('--data-root',type=Path,required=True)
+    p.add_argument('--eval-manifest-sha256',required=True)
+    p.add_argument('--split',choices=('dev','confirm'),default='confirm')
+    p.add_argument('--report',type=Path,required=True)
+    p.add_argument('--smoke',action='store_true',help='First 8 MK rows and 2 prose windows only')
+    args=p.parse_args()
+    if args.report.exists():
+        raise FileExistsError('Preserve existing report')
+    torch.set_num_threads(8)
+    torch.backends.cuda.matmul.allow_tf32=False
+    torch.set_float32_matmul_precision('highest')
+    tokenizer=runtime.SentencePieceTokenizer(args.source_dir)
+    manifest,cases,tokens=data.load_evaluation(args.data_root,args.split,args.eval_manifest_sha256,tokenizer)
+    if (manifest['protocol_sha256']!=data.sha_file(ROOT/'docs'/'PROTOCOL.md')
+            or any(data.token_digest(tokenizer.encode(row['prompt']))!=tok['prompt_token_sha256_int64le']
+                   for row,tok in zip(cases,tokens))):
+        raise ValueError('Evaluation data/protocol identity differs')
+    adapter=native.read_fp16(args.adapter)
+    if adapter['binding'].get('source_checkpoint_sha256')!=runtime.SOURCE_CHECKPOINT_SHA256:
+        raise ValueError('Adapter bound to another base')
+    if adapter['binding'].get('protocol_sha256')!=manifest['protocol_sha256']:
+        raise ValueError('Adapter and evaluation split use different protocol')
+    report={'format':'MAMBA2_SOURCE_RESURFACE_EVAL_V1','complete':False,
+        'started_unix':time.time(),'smoke':args.smoke,'split':args.split,
+        'source_checkpoint_sha256':runtime.SOURCE_CHECKPOINT_SHA256,
+        'tokenizer_sha256':tokenizer.sha256,'protocol_sha256':manifest['protocol_sha256'],
+        'data_manifest_sha256':args.eval_manifest_sha256,
+        'adapter_sha256':data.sha_file(args.adapter),
+        'dataset_status':'previously observed template family and numeric CONFIRM instances',
+        'model_precision':'source BF16 cast to native FP16'}
+    write_json(args.report,report)
+    try:
+        ids,dataset=calibration.load_wikitext_tokens(tokenizer,'validation')
+        windows=evaluation.ppl_windows(ids,2048)
+        if not args.smoke and (len(windows)!=130 or sum(len(w)-1 for _,w in windows)!=264764):
+            raise ValueError('Full WikiText validation target/window count differs')
+        if args.smoke:
+            windows=windows[:2]
+        report['dataset']=dataset
+        report['ppl_windows']=len(windows)
+        report['mk_cases']=len(cases) if not args.smoke else 8
+        model=runtime.load_source_model(args.source_dir)
+        report['baseline_ppl']=evaluation.evaluate_ppl(model,windows)
+        write_json(args.report,report)
+        report['baseline_mk']=score_mk(model,tokenizer,cases,8 if args.smoke else None)
+        write_json(args.report,report)
+        with native.install_fp16(model,args.adapter,expected_binding=adapter['binding']) as bank:
+            report['adapter_ppl']=evaluation.evaluate_ppl(model,windows)
+            write_json(args.report,report)
+            report['adapter_mk']=score_mk(model,tokenizer,cases,8 if args.smoke else None)
+            report['frozen_base_check']=bank.assert_base_frozen()
+        report['mk_comparison']=compare_mk(report['baseline_mk'],report['adapter_mk'])
+        report['ppl_delta_percent']=100*(report['adapter_ppl']['ppl']/report['baseline_ppl']['ppl']-1)
+        report['restored_probe']=score_mk(model,tokenizer,cases,8)
+        if report['restored_probe']['rows']!=report['baseline_mk']['rows'][:8]:
+            raise RuntimeError('Adapter removal failed exact same-process MK replay')
+        if args.smoke:
+            report['quality_claim']='smoke only; no full MK or PPL conclusion'
+        else:
+            report['quality_claim']='full specified protocol, reused known template family; no untouched generalization claim'
+        report['gpu_memory']=runtime.gpu_memory_receipt()
+        report['complete']=True
+        print(json.dumps({'complete':True,'baseline_ppl':report['baseline_ppl']['ppl'],
+            'adapter_ppl':report['adapter_ppl']['ppl'],
+            'mk':{k:v['delta_percentage_points'] for k,v in report['mk_comparison'].items()}}),flush=True)
+    except BaseException as error:
+        report.update(error=repr(error),traceback=traceback.format_exc())
+        raise
+    finally:
+        report['finished_unix']=time.time()
+        write_json(args.report,report)
+
+
+if __name__=='__main__':
+    main()

scripts/prepare_data.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Prepare one provenance-bound numeric split without initializing CUDA."""
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from mamba2_recall import resurface_data as data
+from mamba2_recall.runtime import SentencePieceTokenizer
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--split', choices=('train', 'dev', 'confirm'), required=True)
+    parser.add_argument('--source-dir', type=Path, required=True)
+    parser.add_argument('--data-root', type=Path, default=ROOT/'training_data'/'numeric_v1')
+    args = parser.parse_args()
+    if os.environ.get('CUDA_VISIBLE_DEVICES') != '':
+        raise RuntimeError('Set CUDA_VISIBLE_DEVICES= for CPU data preparation')
+    protocol = ROOT/'docs'/'PROTOCOL.md'
+    tokenizer = SentencePieceTokenizer(args.source_dir)
+    manifest = data.prepare_split(args.data_root, args.split, tokenizer,
+        protocol_path=protocol, protocol_sha256=data.sha_file(protocol),
+        tokenizer_sha256=data.TOKENIZER_SHA)
+    path = args.data_root/args.split/'manifest.json'
+    loaded, _, _ = (data.load_training(args.data_root, data.sha_file(path), tokenizer)
+                    if args.split == 'train' else
+                    data.load_evaluation(args.data_root, args.split, data.sha_file(path), tokenizer))
+    if loaded != manifest:
+        raise RuntimeError('Prepared split failed exact readback')
+    print(json.dumps({'split': args.split, 'rows': manifest['row_count'],
+                      'manifest_sha256': data.sha_file(path),
+                      'protocol_sha256': data.sha_file(protocol),
+                      'cuda_initialized': False}), flush=True)
+
+
+if __name__ == '__main__':
+    main()

scripts/prepare_prose.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Regenerate the exact historical 448 WikiText TRAIN token windows by content."""
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+import torch
+
+ROOT=Path(__file__).resolve().parents[1]
+sys.path.insert(0,str(ROOT))
+from mamba2_recall import calibration, runtime
+
+MANIFEST_SHA='facb2ca461615a4199781bd21784d642d6674f5b862641b3b9edac3fb499b89d'
+
+
+def main():
+    p=argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--source-dir',type=Path,required=True)
+    p.add_argument('--out',type=Path,required=True)
+    args=p.parse_args()
+    if os.environ.get('CUDA_VISIBLE_DEVICES')!='':
+        raise RuntimeError('Set CUDA_VISIBLE_DEVICES= to keep this CPU-only')
+    if args.out.exists():
+        raise FileExistsError(args.out)
+    manifest_path=ROOT/'docs'/'prose_train_manifest.json'
+    if runtime.sha256_file(manifest_path)!=MANIFEST_SHA:
+        raise ValueError('Historical prose selection manifest changed')
+    manifest=json.loads(manifest_path.read_text())
+    tokenizer=runtime.SentencePieceTokenizer(args.source_dir)
+    ids,dataset=calibration.load_wikitext_tokens(tokenizer,'train')
+    starts=manifest['training_starts']
+    if (len(starts)!=448 or len(ids)!=2533678 or dataset!=manifest['dataset']
+            or len(set(starts))!=448 or any(type(s) is not int or s<0 or s+2048>len(ids) for s in starts)):
+        raise ValueError('Historical corpus/windows identity differs')
+    tokens=torch.stack([ids[start:start+2048] for start in starts])
+    content_sha=runtime.token_digest(tokens.flatten().numpy())
+    if content_sha!=manifest['training_tokens_sha256_int64le']:
+        raise ValueError('Recreated TRAIN token content differs')
+    args.out.parent.mkdir(parents=True,exist_ok=True)
+    with args.out.open('xb') as stream:
+        torch.save(tokens,stream)
+    roundtrip=torch.load(args.out,map_location='cpu',weights_only=True)
+    if not torch.equal(roundtrip,tokens):
+        raise RuntimeError('Serialized TRAIN windows differ')
+    print(json.dumps({'windows':448,'tokens':int(tokens.numel()),
+        'content_sha256':content_sha,'file_sha256':runtime.sha256_file(args.out),
+        'historical_file_sha256':manifest['training_tokens_file_sha256'],
+        'identical_file':runtime.sha256_file(args.out)==manifest['training_tokens_file_sha256']}))
+
+
+if __name__=='__main__':main()

scripts/train.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Train the frozen-source Resurface control with the compressed arm's schedule."""
+from __future__ import annotations
+import argparse
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import sys
+import time
+import traceback
+
+import torch
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from mamba2_recall import resurface_data as data, resurface_native as native
+from mamba2_recall import resurface_loss as objective
+from mamba2_recall import runtime
+
+STEPS = 1536
+PROSE_MANIFEST_SHA = 'facb2ca461615a4199781bd21784d642d6674f5b862641b3b9edac3fb499b89d'
+PROSE_TOKENS_SHA = 'e54b02e5162e042a9cdd504f4eb1b1652724fb240bbc2c97608967aa26297233'
+
+
+def write_json(path, value):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix+'.tmp')
+    temporary.write_text(json.dumps(value, indent=2, allow_nan=False)+'\n')
+    temporary.replace(path)
+
+
+def lr_factor(j):
+    return .1 + .9*(1+math.cos(math.pi*j/(STEPS-1)))/2
+
+
+def schedule():
+    return torch.randperm(STEPS, generator=torch.Generator(device='cpu').manual_seed(2026092803)).tolist()
+
+
+def load_training_inputs(args):
+    tokenizer = runtime.SentencePieceTokenizer(args.source_dir)
+    manifest, _, examples = data.load_training(args.data_root,
+        args.train_manifest_sha256, tokenizer)
+    protocol_sha = data.sha_file(ROOT/'docs'/'PROTOCOL.md')
+    if manifest['protocol_sha256'] != protocol_sha or len(examples) != STEPS:
+        raise ValueError('Prepared numeric TRAIN split differs from frozen protocol')
+    if data.sha_file(args.prose_manifest) != PROSE_MANIFEST_SHA:
+        raise ValueError('Pinned WikiText TRAIN manifest differs')
+    prose_manifest = json.loads(args.prose_manifest.read_text())
+    windows = torch.load(args.prose_tokens, map_location='cpu', weights_only=True)
+    prose_file_sha = data.sha_file(args.prose_tokens)
+    if (not prose_manifest.get('complete') or
+            prose_manifest.get('training_tokens_file_sha256') != PROSE_TOKENS_SHA or
+            tuple(windows.shape) != (448,2048) or windows.dtype != torch.int64 or
+            sorted(prose_manifest['schedule']) != list(range(448)) or
+            runtime.token_digest(windows.flatten().numpy()) !=
+                prose_manifest['training_tokens_sha256_int64le']):
+        raise ValueError('Expected 448 disjoint, pinned prose TRAIN windows')
+    binding = {'source_checkpoint_sha256': runtime.SOURCE_CHECKPOINT_SHA256,
+               'tokenizer_sha256': tokenizer.sha256,
+               'protocol_sha256': protocol_sha,
+               'train_manifest_sha256': args.train_manifest_sha256,
+               'prose_manifest_sha256': PROSE_MANIFEST_SHA,
+               'prose_tokens_sha256': prose_file_sha,
+               'prose_tokens_int64le_sha256': prose_manifest['training_tokens_sha256_int64le'],
+               'prose_file_exact_historical': prose_file_sha == PROSE_TOKENS_SHA,
+               'adapter': native.FORMAT, 'successful_updates': STEPS}
+    return tokenizer, examples, windows, prose_manifest['schedule'], binding
+
+
+def pair_for(j, ordered, examples, windows, prose_order):
+    row = examples[ordered[j]]
+    full = torch.tensor(row['full_ids'], dtype=torch.long, device='cuda')[None]
+    answer_mask = torch.zeros_like(full[:,:-1], dtype=torch.bool)
+    answer_mask[:,row['ce_hidden_positions']] = True
+    if int(answer_mask.sum()) != row['answer_target_count']:
+        raise ValueError('Numeric answer suffix mask differs')
+    prose_index = prose_order[j%448]
+    prose_start = 512*((j//448)%4)
+    prose = windows[prose_index,prose_start:prose_start+512].to('cuda')[None]
+    if tuple(prose.shape) != (1,512):
+        raise ValueError('Prose segment geometry differs')
+    return {'id': row['id'], 'schedule_entry': ordered[j],
+            'prose_window': prose_index, 'prose_start': prose_start,
+            'mk_ids': full[:,:-1], 'mk_targets': full[:,1:], 'answer_mask': answer_mask,
+            'prose_ids': prose[:,:-1], 'prose_targets': prose[:,1:]}
+
+
+def optimizer_for(bank):
+    mix = [p for name,p in bank.masters.items() if name.endswith(('.V_read','.g_read'))]
+    router = [p for name,p in bank.masters.items() if name.endswith(('.router_w','.router_b'))]
+    return torch.optim.AdamW([{'params':mix,'lr':1e-4,'base_lr':1e-4},
+                              {'params':router,'lr':3e-4,'base_lr':3e-4}],
+                             betas=(.9,.999),eps=1e-8,weight_decay=0.)
+
+
+def attempt(bank, teacher, pair, optimizer, scaler, j):
+    optimizer.zero_grad(set_to_none=True)
+    for group in optimizer.param_groups:
+        group['lr'] = group['base_lr']*lr_factor(j)
+    hidden,gates = bank.forward_hidden(pair['mk_ids'], use_checkpoint=True)
+    mk = objective.staged_loss_backward(hidden,pair['mk_targets'],bank.model.lm_head,
+        gates=gates,scaler=scaler,answer_mask=pair['answer_mask'],ce_weight=1.,
+        kl_weight=0.,closure_weight=0.,chunk_tokens=64)
+    del hidden,gates
+    with torch.no_grad():
+        teacher_hidden = teacher.backbone(pair['prose_ids'])
+    hidden,gates = bank.forward_hidden(pair['prose_ids'],use_checkpoint=True)
+    prose = objective.staged_loss_backward(hidden,pair['prose_targets'],bank.model.lm_head,
+        gates=gates,scaler=scaler,teacher_hidden=teacher_hidden,
+        teacher_head=teacher.lm_head,ce_weight=.5,kl_weight=.5,
+        closure_weight=3.,chunk_tokens=64)
+    del hidden,gates,teacher_hidden
+    scaler.unscale_(optimizer)
+    gradients = [p.grad for p in bank.parameters()]
+    if any(g is None for g in gradients):
+        raise RuntimeError('Missing adapter gradient')
+    overflow = (not all(bool(torch.isfinite(g).all()) for g in gradients)
+                or not mk['scaled_hidden_gradient_finite']
+                or not prose['scaled_hidden_gradient_finite'])
+    if overflow:
+        scaler.update(new_scale=scaler.get_scale()*.5)
+        magnitude = None
+    else:
+        magnitude = float(torch.nn.utils.clip_grad_norm_(bank.parameters(),1.,error_if_nonfinite=True))
+        scaler.step(optimizer)
+        scaler.update()
+        if any(not bool(torch.isfinite(p).all()) or not bool(torch.isfinite(p.half()).all())
+               for p in bank.parameters()):
+            raise FloatingPointError('Nonfinite updated adapter master or FP16 cast')
+    bank.assert_base_frozen()
+    return {'mk_ce':mk['ce'], 'prose_ce':prose['ce'],
+            'prose_kl':prose['teacher_to_student_kl'],
+            'prose_closure':prose['closure'], 'overflow':overflow,
+            'gradient_norm_before_clip':magnitude, 'loss_scale':scaler.get_scale()}
+
+
+def save_checkpoint(path, bank, optimizer, scaler, binding, success, attempts):
+    if path.exists():
+        raise FileExistsError(path)
+    temporary = path.with_suffix('.pt.tmp')
+    if temporary.exists():
+        raise FileExistsError(temporary)
+    with temporary.open('wb') as stream:
+        torch.save({'format':'MAMBA2_SOURCE_RESURFACE_CHECKPOINT_V1',
+                    'binding':binding,'successful_updates':success,'attempts':attempts,
+                    'masters':bank.state_dict(),'optimizer':optimizer.state_dict(),
+                    'scaler':scaler.state_dict()}, stream)
+        stream.flush(); os.fsync(stream.fileno())
+    temporary.replace(path)
+    return {'path':str(path),'bytes':path.stat().st_size,'sha256':data.sha_file(path)}
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--source-dir',type=Path,required=True)
+    p.add_argument('--data-root',type=Path,required=True)
+    p.add_argument('--train-manifest-sha256',required=True)
+    p.add_argument('--prose-manifest',type=Path,required=True)
+    p.add_argument('--prose-tokens',type=Path,required=True)
+    p.add_argument('--out-dir',type=Path,required=True)
+    p.add_argument('--smoke',action='store_true',help='Discard one GPU update; no adapter export')
+    args = p.parse_args()
+    if args.out_dir.exists():
+        raise FileExistsError('New output directory required')
+    args.out_dir.mkdir(parents=True)
+    torch.set_num_threads(8)
+    torch.manual_seed(2026092803); torch.cuda.manual_seed_all(2026092803)
+    torch.backends.cuda.matmul.allow_tf32 = False
+    torch.backends.cudnn.allow_tf32 = False
+    torch.set_float32_matmul_precision('highest')
+    report = {'format':'MAMBA2_SOURCE_RESURFACE_TRAIN_V1','complete':False,
+              'mode':'smoke' if args.smoke else 'formal',
+              'started_unix':time.time(),'source_sha256':data.sha_file(__file__),
+              'history':[],'checkpoints':[]}
+    try:
+        tokenizer, examples, windows, prose_order, binding = load_training_inputs(args)
+        report['binding'] = binding
+        write_json(args.out_dir/'report.json',report)
+        student = runtime.load_source_model(args.source_dir)
+        teacher = runtime.load_source_model(args.source_dir)
+        if sum(p.numel() for p in student.parameters()) != 8236999680:
+            raise RuntimeError('Wrong source model parameter count')
+        bank = native.ResurfaceNative(student,'soft')
+        if len(bank.masters)!=224 or sum(p.numel() for p in bank.parameters())!=1154104:
+            raise RuntimeError('Wrong adapter geometry')
+        optimizer = optimizer_for(bank)
+        scaler = torch.amp.GradScaler('cuda',init_scale=1024.,growth_factor=2.,
+                                      backoff_factor=.5,growth_interval=2000)
+        ordered = schedule()
+        successful = attempts = 0
+        limit = 1 if args.smoke else STEPS
+        while successful < limit:
+            if attempts >= limit+8:
+                raise RuntimeError('Overflow retry budget exceeded')
+            pair = pair_for(successful,ordered,examples,windows,prose_order)
+            start = time.monotonic()
+            result = attempt(bank,teacher,pair,optimizer,scaler,successful)
+            attempts += 1
+            if not result['overflow']:
+                successful += 1
+            row = {'attempt':attempts,'successful_updates':successful,
+                   'case_id':pair['id'],'schedule_entry':pair['schedule_entry'],
+                   'prose_window':pair['prose_window'],'prose_start':pair['prose_start'],
+                   'answer_targets':int(pair['answer_mask'].sum()),
+                   'seconds':time.monotonic()-start,**result}
+            report['history'].append(row)
+            if not args.smoke and successful and successful%384==0 and not result['overflow']:
+                report['checkpoints'].append(save_checkpoint(args.out_dir/f'checkpoint_{successful:04d}.pt',
+                    bank,optimizer,scaler,binding,successful,attempts))
+            if attempts%16==0 or successful==limit or result['overflow']:
+                report.update(successful_updates=successful,attempts=attempts,
+                              gpu_memory=runtime.gpu_memory_receipt())
+                write_json(args.out_dir/'report.json',report)
+                print(json.dumps({'updates':successful,'attempts':attempts,
+                                  'mk_ce':result['mk_ce'],'prose_ce':result['prose_ce'],
+                                  'overflow':result['overflow']}),flush=True)
+        if not args.smoke:
+            adapter_path = args.out_dir/'adapter_fp16.pt'
+            exported = bank.export_fp16(adapter_path,binding=binding)
+            if native.read_fp16(adapter_path,expected_binding=binding)['gate_mode']!='soft':
+                raise RuntimeError('Export roundtrip differs')
+            report['adapter'] = exported
+            report['frozen_base_check'] = bank.assert_base_frozen()
+            report['teacher_base_parameters_frozen'] = all(
+                not p.requires_grad and p.grad is None for p in teacher.parameters())
+        report.update(complete=True,successful_updates=successful,attempts=attempts,
+                      gpu_memory=runtime.gpu_memory_receipt())
+        bank.close()
+    except BaseException as error:
+        report.update(error=repr(error),traceback=traceback.format_exc())
+        raise
+    finally:
+        report['finished_unix'] = time.time()
+        write_json(args.out_dir/'report.json',report)
+
+
+if __name__=='__main__':
+    main()

scripts/verify_replay.py

@@ -0,0 +1,488 @@
+#!/usr/bin/env python3
+"""Independently audit raw PPL/MK reports and compare a fresh v1 GPU replay.
+
+Only the Python standard library is required. Exit 1 means an identity,
+structure, or arithmetic check failed. Exit 0 means both reports are internally
+valid; inspect ``exact_replay`` and ``status`` for numerical/output differences.
+No tokenizer decoding or model inference is performed by this offline audit.
+"""
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+import copy
+import hashlib
+import json
+import math
+from pathlib import Path
+import re
+import sys
+import tempfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PINS = {
+    'source_checkpoint_sha256': '47c2766f6aad89d73beafbeaecb334aab902d7370906d081764a90bb7a8bbbcb',
+    'tokenizer_sha256': '5862e2f71caf762bc9845662be5fec2867deb58d874568235a02a36c5111cd09',
+    'protocol_sha256': 'dee9457bfaca067b63837dcd3bc94bf9ef9a3d805b1ab04227db05a4b92c54c2',
+    'adapter_sha256': 'e8b2b4dfe69f8e85dc9e147c9aeaa3297cff14f4043e558bb1795ad476c1fca0',
+}
+PUBLISHED_METADATA_PINS = {
+    'data_manifest_sha256': '227737dd5fbb301d76e583457ff8ee29246047661b3e9a64ebd068a6f34f376c',
+    'dataset_fingerprint': '51d84d52d095f90d',
+}
+DATASET_PINS = {
+    'dataset': 'Salesforce/wikitext', 'configuration': 'wikitext-2-raw-v1',
+    'split': 'validation', 'revision_argument': 'b08601e04326c79dfdd32d625aee71d232d685c3',
+    'document_join': 'two newline characters',
+    'text_sha256': 'b44fb967f92b525731216a507d1fbc44b97446b7ef0a2b4d1a893f81f1bbc29e',
+    'token_stream_sha256_int64le': '5bbeae08ba8eb34a482f3b6e9d17b182e67229dd14b2853d87f89fc72e5ad027',
+    'total_tokens': 264765, 'tokenizer_sha256': PINS['tokenizer_sha256'],
+    'automatic_special_tokens': False,
+}
+MATCH = re.compile(r'(?<!\d)\d{6}(?!\d)')
+SHA = re.compile(r'[0-9a-f]{64}')
+IDENTITY_FIELDS = ('id', 'condition', 'N', 'template', 'expected',
+                   'prompt_token_sha256_int64le', 'prompt_tokens', 'cache_bytes')
+PPL_IDENTITY_FIELDS = ('start', 'input_tokens', 'target_tokens', 'token_sha256_int64le')
+ARITHMETIC_REL_TOL = 1e-12
+ARITHMETIC_ABS_TOL = 1e-9
+
+
+def file_sha256(path):
+    digest = hashlib.sha256()
+    with Path(path).open('rb') as handle:
+        for block in iter(lambda: handle.read(1 << 20), b''):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def load_json(path):
+    def reject_duplicates(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError('Duplicate JSON key: ' + key)
+            result[key] = value
+        return result
+
+    def reject_constant(value):
+        raise ValueError('Nonfinite JSON constant: ' + value)
+
+    return json.loads(Path(path).read_text(), object_pairs_hook=reject_duplicates,
+                      parse_constant=reject_constant)
+
+
+def write_new_audit(path, result):
+    """Preserve existing receipts, including if a path appears during auditing."""
+    serialized = json.dumps(result, indent=2, allow_nan=False) + '\n'
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('x') as handle:
+        handle.write(serialized)
+
+
+def expected_mk_order():
+    return [(f'resurface-confirm-n{size}-t{template}-s{sample}' +
+             ('-removed' if condition == 'target_removed' else ''),
+             condition, size, template)
+            for size in (16, 64) for template in range(3) for sample in range(64)
+            for condition in ('normal', 'target_removed')]
+
+
+class Audit:
+    def __init__(self):
+        self.errors = []
+        self.decoded_outputs = {}
+
+    def check(self, condition, message):
+        if not condition:
+            self.errors.append(message)
+
+    def number(self, value, label, minimum=0):
+        valid = type(value) in (int, float) and math.isfinite(value) and value >= minimum
+        self.check(valid, label + ': expected finite number >= ' + str(minimum))
+        if not valid:
+            raise ValueError(label + ': invalid numeric value')
+        return value
+
+    def integer(self, value, label, minimum=0):
+        self.check(type(value) is int and value >= minimum, label + ': invalid integer')
+
+    def equal(self, actual, expected, label):
+        self.check(type(actual) is type(expected) and actual == expected,
+                   label + ': inconsistent value')
+
+    def arithmetic(self, actual, expected, label):
+        actual = self.number(actual, label, minimum=-math.inf)
+        self.check(math.isclose(actual, expected, rel_tol=ARITHMETIC_REL_TOL,
+                                abs_tol=ARITHMETIC_ABS_TOL),
+                   f'{label}: stored={actual!r}, recomputed={expected!r}')
+
+    def ppl(self, block, label):
+        rows = block['windows']
+        self.equal(len(rows), 130, label + '.window_count')
+        self.equal(block['execution'], 'prefill', label + '.execution')
+        self.equal(block['cache_dtype'], 'SSD scan internal precision', label + '.cache_dtype')
+        self.equal(block['cache_bytes'], None, label + '.cache_bytes')
+        self.equal(block['logits_chunk_tokens'], 64, label + '.logits_chunk_tokens')
+        self.equal(block['score'], 'next-token cross entropy; no BOS/EOS added; each window starts from zero state',
+                   label + '.score')
+        losses, targets = [], []
+        for index, row in enumerate(rows):
+            tag = f'{label}.windows[{index}]'
+            target_count = 2048 if index < 129 else 572
+            self.equal(row['start'], index * 2048, tag + '.start')
+            self.equal(row['target_tokens'], target_count, tag + '.target_tokens')
+            self.equal(row['input_tokens'], target_count, tag + '.input_tokens')
+            self.check(isinstance(row['token_sha256_int64le'], str) and
+                       SHA.fullmatch(row['token_sha256_int64le']) is not None, tag + '.token_hash')
+            loss = self.number(row['nll'], tag + '.nll')
+            losses.append(loss)
+            targets.append(row['target_tokens'])
+            self.arithmetic(row['ppl'], math.exp(loss / target_count), tag + '.ppl')
+        target_total, nll = sum(targets), math.fsum(losses)
+        self.equal(target_total, 264764, label + '.target_count')
+        self.equal(block['target_tokens'], target_total, label + '.target_tokens')
+        self.arithmetic(block['nll'], nll, label + '.nll')
+        ppl = math.exp(nll / target_total)
+        self.arithmetic(block['ppl'], ppl, label + '.ppl')
+        return {'windows': len(rows), 'target_tokens': target_total, 'nll_recomputed': nll,
+                'ppl_recomputed': ppl, 'stored_nll_minus_recomputed': block['nll'] - nll,
+                'stored_ppl_minus_recomputed': block['ppl'] - ppl}
+
+    def mk(self, block, label, probe=False):
+        rows = block['rows']
+        order = expected_mk_order()[:8] if probe else expected_mk_order()
+        self.equal(len(rows), len(order), label + '.row_count')
+        self.equal(block['generation'], 'greedy max12, full256K, fresh FP16 cache', label + '.generation')
+        self.equal(block['matching'], 'first standalone six-digit integer', label + '.matching')
+        self.equal(len(set(row['id'] for row in rows)), len(rows), label + '.unique_ids')
+        self.equal(len(set(row['prompt_token_sha256_int64le'] for row in rows)), len(rows),
+                   label + '.unique_prompt_hashes')
+        correct = []
+        for index, row in enumerate(rows):
+            tag = f'{label}.rows[{index}]'
+            if index < len(order):
+                self.equal(tuple(row[key] for key in ('id', 'condition', 'N', 'template')),
+                           order[index], tag + '.ordered_case_identity')
+            self.check(isinstance(row['expected'], str) and
+                       re.fullmatch(r'[0-9]{6}', row['expected']) is not None, tag + '.expected')
+            self.check(isinstance(row['output'], str), tag + '.output must be text')
+            self.check(isinstance(row['prompt_token_sha256_int64le'], str) and
+                       SHA.fullmatch(row['prompt_token_sha256_int64le']) is not None, tag + '.prompt_hash')
+            self.integer(row['prompt_tokens'], tag + '.prompt_tokens', minimum=1)
+            self.equal(row['cache_bytes'], 122028032, tag + '.cache_bytes')
+            generated = row['generated_ids']
+            self.check(isinstance(generated, list) and 1 <= len(generated) <= 12,
+                       tag + '.generated_ids count outside greedy max12')
+            self.check(all(type(token) is int and 0 <= token < 256000 for token in generated),
+                       tag + '.generated_ids outside vocabulary')
+            if generated:
+                self.check(3 not in generated[:-1], tag + '.tokens after EOS')
+                self.check(len(generated) == 12 or generated[-1] == 3,
+                           tag + '.short generation without EOS')
+            token_key = tuple(generated)
+            if token_key in self.decoded_outputs:
+                self.equal(row['output'], self.decoded_outputs[token_key], tag + '.same_ids_different_output')
+            else:
+                self.decoded_outputs[token_key] = row['output']
+            match = MATCH.search(row['output'])
+            prediction = match.group(0) if match else None
+            score = prediction == row['expected']
+            self.equal(row['prediction'], prediction, tag + '.prediction regex rescore')
+            self.equal(row['correct'], score, tag + '.correct regex rescore')
+            correct.append(score)
+            if index % 2:
+                self.equal(row['expected'], rows[index - 1]['expected'], tag + '.paired_expected')
+        summary = {}
+        for condition in ('normal', 'target_removed'):
+            selected = [i for i, row in enumerate(rows) if row['condition'] == condition]
+            count, successes = len(selected), sum(correct[i] for i in selected)
+            summary[condition] = {'correct': successes, 'count': count,
+                                  'accuracy': successes / count if count else None}
+            stored = block['summary'][condition]
+            self.equal(stored['correct'], successes, label + '.' + condition + '.correct')
+            self.equal(stored['count'], count, label + '.' + condition + '.count')
+            if count:
+                self.arithmetic(stored['accuracy'], successes / count, label + '.' + condition + '.accuracy')
+        per_n = {}
+        for size in (16, 64):
+            selected = [i for i, row in enumerate(rows) if row['condition'] == 'normal' and row['N'] == size]
+            if selected:
+                count, successes = len(selected), sum(correct[i] for i in selected)
+                per_n[str(size)] = {'correct': successes, 'count': count, 'accuracy': successes / count}
+        if not probe:
+            self.equal(sum(r['prompt_tokens'] for r in rows), 517120, label + '.total_prompt_tokens')
+            self.equal(max(r['prompt_tokens'] for r in rows), 1236, label + '.max_prompt_tokens')
+        return {'summary': summary, 'normal_by_N': per_n,
+                'generated_length_histogram': dict(sorted(Counter(len(r['generated_ids']) for r in rows).items()))}
+
+    def paired_mk(self, report, label):
+        before, after = report['baseline_mk']['rows'], report['adapter_mk']['rows']
+        self.equal(len(before), len(after), label + '.paired row count')
+        for index, (old, new) in enumerate(zip(before, after)):
+            self.equal(tuple(old[k] for k in IDENTITY_FIELDS), tuple(new[k] for k in IDENTITY_FIELDS),
+                       f'{label}.paired.rows[{index}].identity')
+        results = {}
+        for condition in ('normal', 'target_removed'):
+            counts = {'both_correct': 0, 'both_wrong': 0, 'gained': 0, 'lost': 0}
+            for old, new in zip(before, after):
+                if old['condition'] != condition:
+                    continue
+                old_match, new_match = MATCH.search(old['output']), MATCH.search(new['output'])
+                a = old_match is not None and old_match.group() == old['expected']
+                b = new_match is not None and new_match.group() == new['expected']
+                name = {(True, True): 'both_correct', (False, False): 'both_wrong',
+                        (False, True): 'gained', (True, False): 'lost'}[(a, b)]
+                counts[name] += 1
+            counts.update(count=sum(counts.values()),
+                          baseline_correct=counts['both_correct'] + counts['lost'],
+                          adapter_correct=counts['both_correct'] + counts['gained'])
+            counts['delta_percentage_points'] = 100 * (counts['gained'] - counts['lost']) / counts['count']
+            for field, value in counts.items():
+                stored = report['mk_comparison'][condition][field]
+                if type(value) is float:
+                    self.arithmetic(stored, value, label + '.mk_comparison.' + condition + '.' + field)
+                else:
+                    self.equal(stored, value, label + '.mk_comparison.' + condition + '.' + field)
+            results[condition] = counts
+        return results
+
+    def report(self, report, label):
+        self.equal(report['format'], 'MAMBA2_SOURCE_RESURFACE_EVAL_V1', label + '.format')
+        self.equal(report['complete'], True, label + '.complete')
+        self.equal(report['smoke'], False, label + '.smoke')
+        self.equal(report['split'], 'confirm', label + '.split')
+        self.equal(report['ppl_windows'], 130, label + '.ppl_windows')
+        self.equal(report['mk_cases'], 768, label + '.mk_cases')
+        self.equal(report['model_precision'], 'source BF16 cast to native FP16', label + '.precision')
+        for key, expected in PINS.items():
+            self.equal(report[key], expected, label + '.' + key)
+        manifest_sha = report['data_manifest_sha256']
+        fingerprint = report['dataset']['dataset_fingerprint']
+        self.check(isinstance(manifest_sha, str) and SHA.fullmatch(manifest_sha) is not None,
+                   label + '.data_manifest_sha256: invalid SHA256')
+        self.check(isinstance(fingerprint, str) and bool(fingerprint.strip()),
+                   label + '.dataset.dataset_fingerprint: expected nonempty string')
+        if label == 'published':
+            self.equal(manifest_sha, PUBLISHED_METADATA_PINS['data_manifest_sha256'],
+                       label + '.data_manifest_sha256')
+            self.equal(fingerprint, PUBLISHED_METADATA_PINS['dataset_fingerprint'],
+                       label + '.dataset.dataset_fingerprint')
+        for key, expected in DATASET_PINS.items():
+            self.equal(report['dataset'][key], expected, label + '.dataset.' + key)
+        base = report['frozen_base_check']
+        self.equal(base['tensors'], 507, label + '.base.tensors')
+        self.equal(base['parameters'], 8236999680, label + '.base.parameters')
+        self.equal(base['identity_version_gradients_unchanged'], True, label + '.base.frozen')
+        result = {}
+        for arm in ('baseline', 'adapter'):
+            result[arm] = {'ppl': self.ppl(report[arm + '_ppl'], label + '.' + arm + '_ppl'),
+                           'mk': self.mk(report[arm + '_mk'], label + '.' + arm + '_mk')}
+        for index, (a, b) in enumerate(zip(report['baseline_ppl']['windows'], report['adapter_ppl']['windows'])):
+            self.equal(tuple(a[k] for k in PPL_IDENTITY_FIELDS), tuple(b[k] for k in PPL_IDENTITY_FIELDS),
+                       f'{label}.paired.ppl.windows[{index}].identity')
+        result['mk_comparison'] = self.paired_mk(report, label)
+        delta = 100 * (result['adapter']['ppl']['ppl_recomputed'] / result['baseline']['ppl']['ppl_recomputed'] - 1)
+        self.arithmetic(report['ppl_delta_percent'], delta, label + '.ppl_delta_percent')
+        result['ppl_delta_percent_recomputed'] = delta
+        result['restored_probe'] = self.mk(report['restored_probe'], label + '.restored_probe', probe=True)
+        self.equal(report['restored_probe']['rows'], report['baseline_mk']['rows'][:8], label + '.restored_probe_exact')
+        return result
+
+
+def verify_reports(published, replay, actual_adapter_sha):
+    audit = Audit()
+    result = {
+        'format': 'MAMBA2_RESURFACE_REPLAY_AUDIT_V1',
+        'arithmetic_tolerance': {'relative': ARITHMETIC_REL_TOL, 'absolute': ARITHMETIC_ABS_TOL},
+        'actual_adapter_sha256': actual_adapter_sha, 'pins': PINS,
+        'published_metadata_pins': PUBLISHED_METADATA_PINS,
+        'scope': 'Offline raw-report arithmetic, content identity, regex rescore, and fresh-report comparison. exact_replay covers scientific inputs and outputs; environment-dependent metadata equality is reported separately.',
+        'limitations': [
+            'The verifier does not run the model or independently recompute logits.',
+            'Token hashes are compared; raw prompt/PPL token bytes are not embedded in these reports.',
+            'SentencePiece decoding is not rerun. Equal generated IDs must have equal output text across reports.',
+            'Original frozen-base receipt checks identities, version counters, and gradients, not full tensor contents.',
+            'CONFIRM templates/instances and WikiText validation were previously observed.',
+        ],
+    }
+    audit.equal(actual_adapter_sha, PINS['adapter_sha256'], 'actual adapter SHA256')
+    for label, report in (('published', published), ('replay', replay)):
+        try:
+            result[label] = audit.report(report, label)
+        except (KeyError, TypeError, ValueError, ZeroDivisionError, OverflowError, IndexError) as error:
+            audit.errors.append(f'{label}: malformed report: {error}')
+    differences = {}
+    try:
+        for key in PINS:
+            audit.equal(published[key], replay[key], 'replay identity.' + key)
+        for key in DATASET_PINS:
+            audit.equal(published['dataset'][key], replay['dataset'][key], 'replay dataset identity.' + key)
+        result['metadata_comparison'] = {
+            'manifests_equal': published['data_manifest_sha256'] == replay['data_manifest_sha256'],
+            'published_data_manifest_sha256': published['data_manifest_sha256'],
+            'replay_data_manifest_sha256': replay['data_manifest_sha256'],
+            'dataset_fingerprints_equal': published['dataset']['dataset_fingerprint'] == replay['dataset']['dataset_fingerprint'],
+            'published_dataset_fingerprint': published['dataset']['dataset_fingerprint'],
+            'replay_dataset_fingerprint': replay['dataset']['dataset_fingerprint'],
+            'interpretation': 'The data manifest embeds Python version and dataset fingerprints depend on environment. These metadata may differ while all ordered prompt/token hashes, answers, dataset text/token digests, and revision remain identical.',
+        }
+        for arm in ('baseline', 'adapter'):
+            a, b = published[arm + '_ppl'], replay[arm + '_ppl']
+            for source_name, block in (('published', a), ('replay', b)):
+                for field in ('nll', 'ppl'):
+                    audit.number(block[field], f'{source_name}.{arm}.comparison.{field}')
+            window_deltas = []
+            for index, (old, new) in enumerate(zip(a['windows'], b['windows'])):
+                audit.equal(tuple(old[k] for k in PPL_IDENTITY_FIELDS), tuple(new[k] for k in PPL_IDENTITY_FIELDS),
+                            f'replay.{arm}.ppl.windows[{index}].identity')
+                for source_name, row in (('published', old), ('replay', new)):
+                    for field in ('nll', 'ppl'):
+                        audit.number(row[field], f'{source_name}.{arm}.comparison.windows[{index}].{field}')
+                delta = new['nll'] - old['nll']
+                window_deltas.append({'index': index, 'start': old['start'], 'nll_delta': delta,
+                                      'ppl_delta': new['ppl'] - old['ppl'], 'nll_exact': old['nll'] == new['nll']})
+            before, after = published[arm + '_mk']['rows'], replay[arm + '_mk']['rows']
+            mk_deltas = []
+            for index, (old, new) in enumerate(zip(before, after)):
+                audit.equal(tuple(old[k] for k in IDENTITY_FIELDS), tuple(new[k] for k in IDENTITY_FIELDS),
+                            f'replay.{arm}.mk.rows[{index}].identity')
+                fields = [key for key in ('generated_ids', 'output', 'prediction', 'correct') if old[key] != new[key]]
+                if fields:
+                    mk_deltas.append({'index': index, 'id': old['id'], 'changed_fields': fields,
+                                      'published_prediction': old['prediction'], 'replay_prediction': new['prediction'],
+                                      'published_correct': old['correct'], 'replay_correct': new['correct']})
+            differences[arm] = {
+                'ppl': {'aggregate_nll_exact': a['nll'] == b['nll'], 'aggregate_ppl_exact': a['ppl'] == b['ppl'],
+                        'nll_delta': b['nll'] - a['nll'], 'ppl_delta': b['ppl'] - a['ppl'],
+                        'max_abs_window_nll_error': max(abs(row['nll_delta']) for row in window_deltas),
+                        'max_abs_window_ppl_error': max(abs(row['ppl_delta']) for row in window_deltas),
+                        'exact_nll_windows': sum(row['nll_exact'] for row in window_deltas),
+                        'windows': window_deltas},
+                'mk': {'rows': len(before), 'all_generated_ids_exact': all(a['generated_ids'] == b['generated_ids'] for a, b in zip(before, after)),
+                       'all_output_text_exact': all(a['output'] == b['output'] for a, b in zip(before, after)),
+                       'all_predictions_exact': all(a['prediction'] == b['prediction'] for a, b in zip(before, after)),
+                       'all_correctness_exact': all(a['correct'] == b['correct'] for a, b in zip(before, after)),
+                       'changed_rows': len(mk_deltas), 'differences': mk_deltas},
+            }
+    except (KeyError, TypeError, ValueError, ZeroDivisionError, OverflowError, IndexError) as error:
+        audit.errors.append('replay comparison: malformed report: ' + str(error))
+    result['comparison'] = differences
+    result['errors'] = audit.errors
+    result['integrity_passed'] = not audit.errors
+    result['exact_replay'] = not audit.errors and len(differences) == 2 and all(
+        row['ppl']['aggregate_nll_exact'] and row['ppl']['aggregate_ppl_exact']
+        and row['ppl']['exact_nll_windows'] == 130 and row['ppl']['max_abs_window_ppl_error'] == 0
+        and row['mk']['changed_rows'] == 0 for row in differences.values())
+    result['status'] = ('integrity_failure' if audit.errors else
+                        'exact_replay' if result['exact_replay'] else 'valid_reports_with_replay_differences')
+    return result
+
+
+def self_test(published, actual_sha):
+    checks = []
+
+    def expect(name, candidate, valid, exact=False):
+        result = verify_reports(published, candidate, actual_sha)
+        assert result['integrity_passed'] is valid, (name, result['errors'])
+        assert result['exact_replay'] is exact, name
+        checks.append(name)
+
+    expect('published versus itself', published, True, True)
+    for name, mutate in (
+        ('source hash tamper', lambda r: r.update(source_checkpoint_sha256='0' * 64)),
+        ('malformed replay manifest hash', lambda r: r.update(data_manifest_sha256='invalid')),
+        ('empty replay dataset fingerprint', lambda r: r['dataset'].update(dataset_fingerprint='')),
+        ('PPL arithmetic tamper', lambda r: r['adapter_ppl'].update(nll=r['adapter_ppl']['nll'] + 1)),
+        ('PPL token identity tamper', lambda r: r['adapter_ppl']['windows'][0].update(token_sha256_int64le='0' * 64)),
+        ('MK regex correctness tamper', lambda r: r['adapter_mk']['rows'][0].update(correct=False)),
+        ('MK duplicate identity tamper', lambda r: r['adapter_mk']['rows'][1].update(id=r['adapter_mk']['rows'][0]['id'])),
+        ('MK paired counts tamper', lambda r: r['mk_comparison']['normal'].update(gained=223)),
+        ('restored probe tamper', lambda r: r['restored_probe']['rows'][0].update(output='000000')),
+        ('same token IDs inconsistent decode', lambda r: r['adapter_mk']['rows'][0].update(output=r['adapter_mk']['rows'][0]['output'] + ' ')),
+        ('nonfinite NLL tamper', lambda r: r['adapter_ppl']['windows'][0].update(nll=float('nan'))),
+    ):
+        candidate = copy.deepcopy(published)
+        mutate(candidate)
+        expect(name, candidate, False)
+    candidate = copy.deepcopy(published)
+    block = candidate['adapter_ppl']
+    block['windows'][0]['nll'] += 1e-7
+    block['windows'][0]['ppl'] = math.exp(block['windows'][0]['nll'] / block['windows'][0]['target_tokens'])
+    block['nll'] = math.fsum(row['nll'] for row in block['windows'])
+    block['ppl'] = math.exp(block['nll'] / block['target_tokens'])
+    candidate['ppl_delta_percent'] = 100 * (block['ppl'] / candidate['baseline_ppl']['ppl'] - 1)
+    expect('consistent tiny NLL difference reported without integrity failure', candidate, True)
+    candidate = copy.deepcopy(published)
+    candidate['adapter_mk']['rows'][-1]['generated_ids'][-1] = 251555
+    candidate['adapter_mk']['rows'][-1]['output'] += '!'
+    expect('changed MK IDs and text reported without inventing decoder validation', candidate, True)
+    candidate = copy.deepcopy(published)
+    candidate['data_manifest_sha256'] = 'a' * 64
+    candidate['dataset']['dataset_fingerprint'] = 'same-data-different-environment'
+    expect('environment metadata differs but identical content and scores are accepted', candidate, True, True)
+    metadata = verify_reports(published, candidate, actual_sha)['metadata_comparison']
+    assert metadata['manifests_equal'] is False
+    assert metadata['dataset_fingerprints_equal'] is False
+    assert metadata['replay_data_manifest_sha256'] == 'a' * 64
+    assert metadata['replay_dataset_fingerprint'] == 'same-data-different-environment'
+    bad_sha = verify_reports(published, published, '0' * 64)
+    assert not bad_sha['integrity_passed']
+    checks.append('actual adapter hash tamper')
+    with tempfile.TemporaryDirectory(prefix='mamba2-audit-selftest-') as directory:
+        path = Path(directory) / 'receipt.json'
+        write_new_audit(path, {'receipt': 'original'})
+        original = path.read_bytes()
+        try:
+            write_new_audit(path, {'receipt': 'overwrite attempt'})
+        except FileExistsError:
+            pass
+        else:
+            raise AssertionError('Existing audit receipt was overwritten')
+        assert path.read_bytes() == original
+    checks.append('existing audit receipt preserved by exclusive creation')
+    return {'passed': len(checks), 'checks': checks}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--published', type=Path)
+    parser.add_argument('--replay', type=Path)
+    parser.add_argument('--adapter', type=Path)
+    parser.add_argument('--output', type=Path)
+    parser.add_argument('--self-test', action='store_true', help='Audit bundled published report and exercise tamper cases')
+    args = parser.parse_args()
+    if args.self_test:
+        published = load_json(args.published or ROOT / 'reports/source_resurface_v1_confirm_full.json')
+        digest = file_sha256(args.adapter or ROOT / 'artifacts/source_resurface_v1/adapter_fp16.pt')
+        print(json.dumps(self_test(published, digest), indent=2, allow_nan=False))
+        return 0
+    if any(value is None for value in (args.published, args.replay, args.adapter, args.output)):
+        parser.error('--published, --replay, --adapter, and --output are required')
+    if args.output.exists():
+        print(f'Refusing to overwrite existing audit receipt: {args.output}', file=sys.stderr)
+        return 1
+    try:
+        result = verify_reports(load_json(args.published), load_json(args.replay), file_sha256(args.adapter))
+        result['files'] = {key: {'path': str(path.resolve()), 'sha256': file_sha256(path)}
+                           for key, path in (('published', args.published), ('replay', args.replay), ('adapter', args.adapter))}
+    except (OSError, ValueError, TypeError) as error:
+        result = {'format': 'MAMBA2_RESURFACE_REPLAY_AUDIT_V1', 'integrity_passed': False,
+                  'exact_replay': False, 'status': 'integrity_failure', 'errors': [str(error)]}
+    try:
+        write_new_audit(args.output, result)
+    except FileExistsError:
+        print(f'Refusing to overwrite existing audit receipt: {args.output}', file=sys.stderr)
+        return 1
+    except OSError as error:
+        print(f'Cannot write audit receipt {args.output}: {error}', file=sys.stderr)
+        return 1
+    print(json.dumps({key: result[key] for key in ('status', 'integrity_passed', 'exact_replay', 'errors')},
+                     indent=2, allow_nan=False))
+    return 0 if result['integrity_passed'] else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())