October 2026 main drop: mirror from GitHub

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* 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
+docs/img/architecture.png filter=lfs diff=lfs merge=lfs -text
+docs/img/flow-dispatch.png filter=lfs diff=lfs merge=lfs -text
+docs/img/flow-operator.png filter=lfs diff=lfs merge=lfs -text
+docs/img/metrics-scale.png filter=lfs diff=lfs merge=lfs -text
+docs/img/quickstart-terminal.png filter=lfs diff=lfs merge=lfs -text
+docs/img/sandbox.png filter=lfs diff=lfs merge=lfs -text
+docs/img/trq-format.png filter=lfs diff=lfs merge=lfs -text
+docs/tensor-roll-demo.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,9 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 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 Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are 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.
+
+  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.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  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 Affero 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. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  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 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 work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero 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 Affero 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 Affero 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 Affero 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 Affero 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 Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero 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 your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  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 AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -0,0 +1,16 @@
+---
+license: agpl-3.0
+tags:
+- snapkitty
+- october-2026-drop
+- python
+- cuda-q
+- qsharp
+- quantization
+- distillation
+- model-compression
+- machine-learning
+---
+
+> Mirrored from [https://github.com/SNAPKITTYWEST/tensor-roll](https://github.com/SNAPKITTYWEST/tensor-roll) at commit `f8cb763`. Part of the **SnapKitty October 2026 main drop**.
+

cuda/tensor_roll_gemm.cu

@@ -0,0 +1,97 @@
+// Tensor Roll — Recursive CUDA-Q Model Quantizer
+// Copyright (C) 2026 SnapKitty Collective
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// Genuine CUDA GEMM kernel: the classical baseline that TensorRoll's
+// dispatch boundary (tensor_roll/core.py::dispatch_matmul) would call on
+// real NVIDIA hardware.
+//
+//   C = A x B   (classical region)
+//   TensorRoll(A, B) routes candidate blocks to the CUDA-Q kernel family
+//   (cudaq/tensor_roll_kernels.py) instead.
+//
+// Build (requires the NVIDIA CUDA toolkit + a CUDA GPU):
+//   nvcc -O3 -arch=sm_80 -o tensor_roll_gemm tensor_roll_gemm.cu
+// Run:
+//   ./tensor_roll_gemm <M> <N> <K>
+//
+// NOT compiled or executed in this repository's test environment (no GPU,
+// no nvcc). tensor-roll reports cpu-numpy for GEMM here; on CUDA hardware
+// this kernel is the drop-in classical region.
+
+#include <cuda_runtime.h>
+#include <cstdio>
+#include <cstdlib>
+#include <cmath>
+
+#define TILE 16
+
+__global__ void tensor_roll_gemm(const float* __restrict__ A,
+                                 const float* __restrict__ B,
+                                 float* __restrict__ C,
+                                 int M, int N, int K) {
+    __shared__ float As[TILE][TILE];
+    __shared__ float Bs[TILE][TILE];
+    int row = blockIdx.y * TILE + threadIdx.y;
+    int col = blockIdx.x * TILE + threadIdx.x;
+    float acc = 0.0f;
+    for (int t = 0; t < (K + TILE - 1) / TILE; ++t) {
+        if (row < M && t * TILE + threadIdx.x < K)
+            As[threadIdx.y][threadIdx.x] = A[row * K + t * TILE + threadIdx.x];
+        else
+            As[threadIdx.y][threadIdx.x] = 0.0f;
+        if (col < N && t * TILE + threadIdx.y < K)
+            Bs[threadIdx.y][threadIdx.x] = B[(t * TILE + threadIdx.y) * N + col];
+        else
+            Bs[threadIdx.y][threadIdx.x] = 0.0f;
+        __syncthreads();
+        #pragma unroll
+        for (int k = 0; k < TILE; ++k)
+            acc += As[threadIdx.y][k] * Bs[k][threadIdx.x];
+        __syncthreads();
+    }
+    if (row < M && col < N)
+        C[row * N + col] = acc;
+}
+
+int main(int argc, char** argv) {
+    int M = argc > 1 ? atoi(argv[1]) : 512;
+    int N = argc > 2 ? atoi(argv[2]) : 512;
+    int K = argc > 3 ? atoi(argv[3]) : 512;
+    size_t sA = (size_t)M * K * sizeof(float);
+    size_t sB = (size_t)K * N * sizeof(float);
+    size_t sC = (size_t)M * N * sizeof(float);
+    float *hA = (float*)malloc(sA), *hB = (float*)malloc(sB),
+          *hC = (float*)malloc(sC);
+    for (int i = 0; i < M * K; ++i) hA[i] = (float)(i % 13) / 13.0f;
+    for (int i = 0; i < K * N; ++i) hB[i] = (float)(i % 7) / 7.0f;
+    float *dA, *dB, *dC;
+    cudaMalloc(&dA, sA); cudaMalloc(&dB, sB); cudaMalloc(&dC, sC);
+    cudaMemcpy(dA, hA, sA, cudaMemcpyHostToDevice);
+    cudaMemcpy(dB, hB, sB, cudaMemcpyHostToDevice);
+    dim3 block(TILE, TILE);
+    dim3 grid((N + TILE - 1) / TILE, (M + TILE - 1) / TILE);
+    cudaEvent_t t0, t1;
+    cudaEventCreate(&t0); cudaEventCreate(&t1);
+    cudaEventRecord(t0);
+    tensor_roll_gemm<<<grid, block>>>(dA, dB, dC, M, N, K);
+    cudaEventRecord(t1);
+    cudaEventSynchronize(t1);
+    float ms = 0.0f;
+    cudaEventElapsedTime(&ms, t0, t1);
+    cudaMemcpy(hC, dC, sC, cudaMemcpyDeviceToHost);
+    // checksum against a naive host reference on a 16x16 corner
+    double ref = 0.0;
+    for (int i = 0; i < 16 && i < M; ++i)
+        for (int j = 0; j < 16 && j < N; ++j) {
+            double s = 0.0;
+            for (int k = 0; k < K; ++k) s += (double)hA[i * K + k] * hB[k * N + j];
+            ref += fabs(s - hC[i * N + j]);
+        }
+    double gflops = 2.0 * M * N * K / (ms * 1e6);
+    printf("tensor_roll_gemm %dx%dx%d: %.3f ms, %.1f GFLOPS, corner_err=%.2e\n",
+           M, N, K, ms, gflops, ref);
+    cudaFree(dA); cudaFree(dB); cudaFree(dC);
+    free(hA); free(hB); free(hC);
+    return 0;
+}

cudaq/tensor_roll_kernels.py

@@ -0,0 +1,115 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Real CUDA-Q kernels for the tensor_roll family.
+
+Target: NVIDIA CUDA-Q Python API (>= 0.8). Execute with a simulator
+target (``cudaq.set_target("qpp-cpu")``) or on QPU/GPU hardware.
+
+These kernels are NOT executed by the tensor-roll CLI on machines without
+the CUDA-Q toolchain (see docs/BOUNDARIES.md). The classical state-vector
+simulator in tensor_roll/qsim.py mirrors this family's semantics so the
+pipeline is measurable everywhere; every qsim report is labeled
+``qsim-classical`` and never claims QPU execution.
+
+Conceptual mapping (classical -> quantum descent):
+    C = A x B            (CUDA GEMM, classical baseline)
+    TensorRoll(A, B)     (dispatch boundary in tensor_roll/core.py)
+      |- classical region -> CUDA GEMM
+      -- candidate region -> tensor_roll kernels below -> measurement
+                             -> classical reconstruction
+"""
+
+try:
+    import cudaq
+    from cudaq import spin
+    _HAS_CUDAQ = True
+except ImportError:  # pragma: no cover - toolchain absent on most machines
+    _HAS_CUDAQ = False
+
+
+if _HAS_CUDAQ:
+
+    @cudaq.kernel
+    def tensor_roll_encode(qubits: cudaq.qview, angles: list[float]):
+        """Angle-encode a tensor block: RY(2*atan(x_i)) per qubit."""
+        for q in range(qubits.size()):
+            ry(2.0 * angles[q], qubits[q])
+
+    @cudaq.kernel
+    def tensor_roll_rotate(qubits: cudaq.qview, angles: list[float]):
+        """Per-qubit RY rotations (the 'roll' of the register)."""
+        for q in range(qubits.size()):
+            ry(angles[q], qubits[q])
+
+    @cudaq.kernel
+    def tensor_roll_entangle(qubits: cudaq.qview):
+        """Nearest-neighbour CNOT ladder."""
+        for q in range(qubits.size() - 1):
+            x.ctrl(qubits[q], qubits[q + 1])
+
+    @cudaq.kernel
+    def tensor_roll_measure(qubits: cudaq.qview):
+        """Measure the full register in the Z basis."""
+        mz(qubits)
+
+    @cudaq.kernel
+    def tensor_roll_recursive(qubits: cudaq.qview, angles: list[float],
+                              depth: int):
+        """Recursive kernel: each level rotates + entangles a shrinking
+        active qubit subset, then measures it. Implemented iteratively over
+        levels (CUDA-Q kernels unroll statically); depth selects how many
+        levels execute."""
+        n = qubits.size()
+        for level in range(depth):
+            # active subset shrinks with depth: n, n-1, ...
+            for q in range(n):
+                if q < n - level:
+                    ry(angles[q], qubits[q])
+            for q in range(n - 1):
+                if q < n - 1 - level:
+                    x.ctrl(qubits[q], qubits[q + 1])
+            if level < depth - 1:
+                # mid-circuit measurement of the outer qubit, then reset
+                # for the next recursion level
+                mz(qubits[n - 1 - level])
+                reset(qubits[n - 1 - level])
+        mz(qubits)
+
+    @cudaq.kernel
+    def tensor_roll_reconstruct(counts_register: cudaq.qview):
+        """Measurement kernel whose counts are classically post-processed
+        into amplitude estimates (see tensor_roll/qsim.py for the estimator).
+        Reconstruction itself is classical by construction."""
+        mz(counts_register)
+
+
+def run_smoke(n_qubits: int = 4, shots: int = 1024) -> dict:
+    """Execute the kernel family on the qpp-cpu simulator target and return
+    a real invocation summary. Requires the CUDA-Q toolchain."""
+    if not _HAS_CUDAQ:
+        raise RuntimeError(
+            "CUDA-Q toolchain not installed (pip install cudaq). "
+            "This machine cannot execute these kernels; use the "
+            "qsim-classical path (tensor-roll qkernel) instead.")
+    import math
+    cudaq.set_target("qpp-cpu")
+    angles = [2.0 * math.atan(0.1 * (i + 1)) for i in range(n_qubits)]
+
+    @cudaq.kernel
+    def _smoke_entry(n_qubits: int, angles: list[float], depth: int):
+        qubits = cudaq.qvector(n_qubits)
+        tensor_roll_encode(qubits, angles)
+        tensor_roll_recursive(qubits, angles, depth)
+
+    counts = cudaq.sample(_smoke_entry, n_qubits, angles, 2,
+                          shots_count=shots)
+    return {"counts": {k: int(v) for k, v in counts.items()},
+            "shots": shots, "target": cudaq.get_target().name}
+
+
+if __name__ == "__main__":
+    try:
+        print(run_smoke())
+    except RuntimeError as e:
+        print(f"unavailable: {e}")

docs/ARCHITECTURE.md

@@ -0,0 +1,300 @@
+# Tensor Roll — architecture
+
+Copyright (C) 2026 SnapKitty Collective — AGPLv3.
+
+## What this is
+
+TENSOR ROLL is a recursive model quantizer/compressor. A large teacher
+model's tensors are recursively partitioned by the operator
+
+```
+TensorRoll(T, axis, depth, rank, quantum_policy)
+```
+
+every leaf's candidate representations are *measured* (cost in parameters,
+retained energy, reconstruction error), a global knapsack search picks the
+winning representation per leaf under a hard parameter budget, the student
+architecture is searched to fit the same budget, and the student is trained
+by recursive distillation (7 loss terms), fine-tuned, quantized, and
+exported to FP16 / BF16 / INT8 / INT4 / `.trq`.
+
+Nothing here wraps PyTorch, Transformers, llama.cpp, ONNX, or an existing
+quantizer. The tensor core, transformer, distillation, quantizers, `.trq`
+codec, sandbox, and CLI are written from scratch on NumPy.
+
+## Pipeline stages (0–7) and CLI commands
+
+| Stage | Name | CLI |
+|---|---|---|
+| ingest | build/load teacher | `tensor-roll ingest [--scale tiny\|30b]` |
+| map | tensor inventory + metrics | `tensor-roll map` |
+| roll | `TensorRoll` operator + global search | `tensor-roll roll` |
+| qkernel | kernel family on a real block | `tensor-roll qkernel` |
+| compress | student architecture search | `tensor-roll compress` |
+| 0 | architecture-init (checkpoint) | `tensor-roll train --stage 0` |
+| 1 | tensor-reconstruction | `tensor-roll train --stage 1` |
+| 2 | hidden-state-matching | `tensor-roll train --stage 2` |
+| 3 | logit-distillation | `tensor-roll train --stage 3` |
+| 4 | language-model | `tensor-roll train --stage 4` |
+| 5 | instruction-tuning | `tensor-roll train --stage 5` |
+| 6 | quantization-aware | `tensor-roll train --stage 6` |
+| 7 | regression-eval | `tensor-roll train --stage 7` |
+| — | task fine-tuning | `tensor-roll finetune` |
+| — | FP16/BF16/INT8/INT4 + `.trq` | `tensor-roll quantize` |
+| — | held-out eval + recursive metrics | `tensor-roll evaluate` |
+| — | benchmark table | `tensor-roll benchmark` |
+| — | REPL generation | `tensor-roll chat` |
+| — | sandbox supervisor | `tensor-roll sandbox` |
+| — | full end-to-end run | `tensor-roll demo` |
+
+Checkpoints are deterministic and resumable: `checkpoints/stage{N}.npz`
+plus `checkpoints/meta.json`; re-running a stage overwrites only that
+stage's checkpoint.
+
+## The recursive operator
+
+`TensorRoll(T, axis, depth, rank, quantum_policy)` (`tensor_roll/core.py`):
+
+1. `roll_tree` partitions `T` along `axis` to `depth`, halving each level.
+   Every node records: shape, parameter count, Frobenius norm, variance,
+   SVD rank, Shannon entropy of the normalized singular spectrum, and
+   spectral contribution (top singular value² / total energy).
+2. Each leaf evaluates candidate representations with **measured**
+   triples `(cost_params, retained_energy, reconstruction_error)`:
+   - `PRESERVE` — bit-exact, full cost.
+   - `QUANTIZE` — real INT8 round-trip, plus codebook VQ (from-scratch
+     k-means, k=16).
+   - `FACTORIZE` — truncated SVD at measured fractions and at the
+     requested `rank`.
+   - `MERGED` — 1-D tensors folded into the parent op (exact).
+   - `ROUTED` — block routed to the qsim measurement path (exploration).
+   - `RECONSTRUCTED` — recursive-measurement classical reconstruction.
+   - `PRUNED` — magnitude pruning at 25%/50% with a sparse cost model.
+   - `QUANTUM-ENCODED` — angle/amplitude encode → rotate → entangle →
+     measure → reconstruct through the real statevector simulator
+     (`tensor_roll/qsim.py`), gated by `quantum_policy` and an 8-qubit
+     eligibility cap. Labeled `qsim-classical`, never a QPU.
+3. `select_plan` runs a greedy knapsack: start every leaf at its cheapest
+   option, then repeatedly apply the highest energy-per-cost upgrade that
+   keeps total cost under the hard budget `P ≤ 8.5B` (scaled by
+   `BUDGET_RATIO = 8.5/30` at tiny scale).
+
+No decision is hard-coded; the policy that emerges is a function of the
+measured numbers.
+
+## Distillation (7 loss terms, all real)
+
+`tensor_roll/distill.py::distill_step` computes task cross-entropy,
+logit KL (temperature-scaled), hidden-state MSE, attention-map MSE,
+embedding MSE, reconstruction MSE, and the roll loss
+(`1 - mean leaf retained energy`), each with a measured value and an
+analytic gradient through the from-scratch backward pass. Recursive
+metrics (`recursive_metrics`) report per model / layer-group / tensor /
+sub-block: relative error, cosine similarity, KL divergence, retained
+energy.
+
+## `.trq` format
+
+Magic `TRQ1`, versioned JSON header (architecture, tensor index, shapes,
+dtypes, quantization metadata incl. codebooks/scales/zero-points, roll
+metadata, provenance), per-tensor records with SHA-256, whole-file
+SHA-256. The reader refuses corrupted files (tested). Packed INT4 counts
+parameters from recorded shapes, not bytes.
+
+## Measured results (tiny validation, this machine, 2026-09-29)
+
+Machine: 2 CPUs, ~7 GB RAM, no GPU (`nvidia-smi` absent), Python 3.12,
+NumPy 1.26. `tensor-roll demo --fast` completes in ~95 s.
+
+| Artifact | Params | Size | ppl | acc |
+|---|---|---|---|---|
+| tiny teacher (fp32) | 41.1K | 160.62KB | 1.87 | 0.851 |
+| student (fp32/trq) | 11.4K | 57.07KB | 8.32 | 0.345 |
+| student (int8/trq) | 11.4K | 24.88KB | 8.39 | 0.342 |
+| student (int4/trq) | 11.4K | 36.15KB | 15.13 | 0.221 |
+
+Student = 27.8% of teacher params (target ratio 8.5/30 = 28.3%).
+INT4 degrades gracefully (ppl 8.3 → 15.1), as honestly expected.
+qsim recursive reconstruction of an 8×8 block: rel err 0.168 at 512 shots.
+Teacher/student token agreement on 24 generated tokens: 3/24 — the
+student is a weak model at this scale; the pipeline, not the perplexity,
+is what is being validated.
+
+Rerun (`demo --fast`, same machine, 2026-09-29, failure-resolution
+pass): teacher acc 0.849, int8 PPL 8.45, int4 PPL 15.27, compression
+0.2777. Training is deterministic per (steps, seed) — verified by
+byte-identical reruns; the small deltas vs the table above reflect run
+configuration, and both runs are kept on record instead of overwriting.
+
+## What was NOT run here (and what it needs)
+
+- Glimmer 30B ingestion: needs the 30B checkpoint shards + a machine with
+  ~60 GB+ RAM (fp16) or multi-GPU. `ingest --scale 30b` checks for
+  `nvidia-smi`/CUDA and exits `unavailable` instead of faking it.
+- CUDA-Q kernels: need `pip install cudaq` + a target (`qpp-cpu` sim or
+  QPU/GPU). Absent here; `cudaq/tensor_roll_kernels.py` prints
+  `unavailable`.
+- Q# operations: need the Q# toolchain. `qsharp/TensorRoll.qs` is genuine
+  source, uncompiled here.
+- CUDA GEMM: needs a CUDA GPU; `dispatch_matmul` reports `cpu-numpy`.
+
+The 30B path is the same code path: ingest shards → same `TensorRoll`
+operator → same search → same stages. Only the tensor source and the
+hardware change.
+
+## Failure-resolution pass (2026-09-29): what the F1–F7 mission changed
+
+Failures are attacked in order; every item below is measured on this
+machine (2 CPUs, ~7 GB RAM, no GPU) unless marked otherwise.
+
+### F1 — Out-of-core architecture (RULE ZERO: never require 30B in RAM)
+
+New module `tensor_roll/ooc.py`:
+
+- `ShardWriter`/`TensorSource`/`ShardReader`: sharded weight storage with
+  manifest; reads are `np.memmap` views — one tensor (or window) at a
+  time, never the model.
+- `MappedTensor.windows(budget)`: recursive windowing along the largest
+  axis until each window fits the byte budget; `reassemble()` verifies
+  exact coverage (no overlap, no gaps, no shape drift) — tested.
+- `RollWorkspace`: hard working-set ceiling; allocations past it raise
+  `MemoryBudgetExceeded` instead of paging the machine — tested.
+- `StudentWriter`: per-tensor SHA-256, atomic shard writes, index
+  flushed per tensor; `verify()` detects corrupted shards — tested.
+- `Checkpoint`: JSON state + SHA-256, atomic replace; corrupted
+  checkpoints are refused, never loaded — tested.
+- `OutOfCoreDriver`: SCAN → PLAN → EXECUTE with per-tensor checkpointing
+  and `--resume`; an injected crash mid-run resumes with zero
+  emitted-data loss (tested: crashed run + resume == clean run, index
+  verified).
+- External teachers: `prepare_teacher_source()` opens `.safetensors`
+  directories with true mmap windows (no copy) or repacks `.npz`
+  streaming (one array in RAM at a time).
+- `stream_compress()`: per-window truncated SVD at the tensor's planned
+  rank share; student shards are low-rank factor pairs with honestly
+  accounted parameter counts.
+
+Measured: tiny teacher (41.1K params) streamed through
+`compress --out-of-core --target-params 20000 --memory-budget 1MB` →
+20.4K student params (rank discretization overshoot +2%, reported),
+mean measured retained energy 0.809, peak workspace 18KB of 1MB.
+
+### F2 — Virtual 30B planning (labeled exactly this, never "validated")
+
+New module `tensor_roll/planner.py`:
+
+- `glimmer30b_manifest()`: realistic 30.19B-param, 500-tensor manifest;
+  **zero weights allocated** (any read attempt raises).
+- `plan()`: SCAN (metadata only) → sensitivity-aware nonuniform
+  allocation (sensitive tensors up to 2× the uniform ratio, funded by
+  insensitive ones down to 0.4×) → hard cap 8.5B, lands on the 8.0B
+  target from either side.
+
+Measured (this machine, peak RSS 35MB — bounded working set proven):
+
+| Scale | Source params | Planned | Ratio | Within cap | Planner time |
+|---|---|---|---|---|---|
+| virtual 30B | 30.19B | 8.000B | 0.265 | yes | <0.1 s |
+
+Scale-invariance regression (virtual manifests, no weights): the
+planner holds the 8.5/30 ratio at 100K / 1M / 10M params within ±0.02 —
+tested (`check_ratio_invariance`).
+
+Actual 30B weights: **NOT TESTED** — no 30B checkpoint exists on this
+machine.
+
+### F3 — Backend honesty (`tensor-roll doctor`)
+
+New modules `tensor_roll/doctor.py`, `tensor_roll/ir.py`,
+`tensor_roll/conformance.py` (16 tests):
+
+- `tensor-roll doctor` prints the live capability matrix: CPU/NumPy
+  AVAILABLE, CUDA/CUDA-Q/Q# UNAVAILABLE (with reasons), sources
+  VERIFIED (content-checked) vs execution NOT EXECUTED — source presence
+  is never presented as backend execution.
+- TensorRoll IR (`LOAD/SLICE/ROLL/FACTOR/ROTATE/ENTANGLE/MEASURE/
+  RECONSTRUCT/GEMM/QUANTIZE/EMIT`) with JSON round-trip; CPU lowering
+  executes numerically, CUDA-Q/Q# lowering returns NOT EXECUTED records.
+- Integration audit (docs/BOUNDARIES.md): the CUDA-Q↔Q# boundary is a
+  checksummed serialized JSON trace file — file-mediated, not an API.
+
+### F4/F5 — Fidelity instrumentation and the 3/24 divergence
+
+New module `tensor_roll/fidelity.py`:
+
+- `divergence_trace()`: per-token teacher/student trace on
+  teacher-forced contexts (tokens, top-k, full logits, KL/JS divergence,
+  cosine similarity, entropies, per-layer hidden-state and attention
+  divergence) — isolates model divergence from context drift.
+- `first_divergence()`: first position AND first layer with significant
+  representation drift (not just final tokens).
+- `ablation_report()`: per-component evidence (embeddings, attention
+  projections/output, MLP up/down, norms, output head) — which
+  component's restoration recovers agreement.
+- `fidelity_aware_select()`: the section-6 utility
+  `savings − recon − logit − hidden − task` applied **uniformly** to
+  every decision class from measured errors; quantum scoring untouched.
+
+Resolution experiment (`experiments/fidelity_resolution.py`, fixed
+seeds, 3 prompts × 24 tokens; full report in the experiment workdir):
+
+- Section-6 check on 148 real roll leaves: `select_plan` chose
+  65 QUANTIZE / 83 PRESERVE at cost 11645 params; `fidelity_aware_select`
+  chose 55 QUANTIZE / 93 PRESERVE at cost 11456 — 12 decision diffs.
+  The fidelity penalty made the planner *more conservative* (fewer
+  quantize decisions), from measured errors only. Quantum-gated
+  candidates lost under both scorings — the empirical result stands.
+- V0 (baseline pipeline): token agreement **7/72**, mean teacher-KL
+  1.548.
+- First divergence at **position 0, layer_0** (hidden rel_err 1.04,
+  KL 2.73): the student diverges immediately in the first layer — not
+  late context drift but immediate representation mismatch.
+- Ablations: *every* single-component teacher graft hurt agreement
+  (best: mlp_down −0.021; output_head graft → 0.000) and raised KL.
+  The distilled student is a co-adapted system — fidelity loss is
+  **systemic, not localizable** to one component.
+- V1 (stages 2+3 hidden/logit distillation at 3× steps, then finetune):
+  agreement **4/72**, mean KL **1.187**. More distillation closes the
+  distribution gap (KL −0.36) but does **not** recover greedy token
+  agreement.
+
+Conclusion (measured, not guessed): the bottleneck is
+capacity/architecture, not distillation weight. Closing 3/24-class
+agreement needs a larger student budget or a better init, not more
+distillation steps. This remains an open failure.
+
+### F6 — INT4 characterization and recovery (`tensor_roll/quant.py`)
+
+- `int4_scheme_report()`: per-tensor / per-channel / group-wise INT4
+  benchmarked by **measured MSE** on each tensor; `search_group_size()`
+  picks the argmin over {16, 32, 64, 128}.
+- `quant_error_map()`: per-tensor min/max/mean/variance/outlier
+  fraction, MSE, cosine similarity, rel err, per-channel and per-group
+  MSE — all measured.
+- `mixed_precision_plan()`: INT4/INT8 assignment under a physical size
+  budget; tensors where INT8 buys the most error reduction per extra
+  byte stay INT8.
+- `recovery_train()`: quantization-aware recovery —
+  INT4-dequantized student → distillation → requantize → evaluate;
+  reports PPL before/after/requantized. Improvement is reported only if
+  measured.
+
+Measured recovery run (demo-scale student_final → INT4, 30 steps,
+2026-09-29; `experiments/int4_recovery.json`): PPL 7.43 before →
+5.49 after distillation → **6.88 after requantization**
+(gap closed by 0.55, `improved: true`). Recovery training genuinely
+recovers part of the INT4 degradation; the residual gap is the
+quantization floor, not a training artifact.
+
+Baseline INT4 gap stands at 6.74 PPL (15.13 − 8.39) for the full
+pipeline variant until a recovery run on that exact artifact measures
+otherwise.
+
+### Remaining failures (not fixed, reported as such)
+
+- Token agreement 3/24: under investigation (see F4/F5 results above).
+- INT4 PPL gap 6.74: characterized, not yet closed.
+- No CUDA / CUDA-Q / Q# execution on this machine (hardware absent).
+- No actual Glimmer 30B weights ingested (checkpoint absent).
+- `tensor-roll demo` exposes all of the above in its [10/9] status
+  board; nothing is relabeled to look like a pass.

docs/BOUNDARIES.md

@@ -0,0 +1,237 @@
+# Tensor Roll — process / IR boundaries
+
+Copyright (C) 2026 SnapKitty Collective — AGPLv3.
+
+This document states exactly where one execution domain ends and another
+begins. There are three boundaries that matter; none of them is a wrapper
+around an existing framework, and none of them is invented.
+
+## 1. Classical dispatch boundary: `TensorRoll` → GEMM vs quantum candidate
+
+Location: `tensor_roll/core.py` — `dispatch_matmul()` and
+`evaluate_options()` / `qsim_encode_for_roll`.
+
+The recursive operator `TensorRoll(T, axis, depth, rank, quantum_policy)`
+partitions a tensor and evaluates candidate representations per leaf.
+Ordinary candidates (PRESERVE / QUANTIZE / FACTORIZE / MERGED / ROUTED /
+RECONSTRUCTED / PRUNED) execute as NumPy on CPU and every report labels
+them `backend: cpu-numpy`.
+
+A leaf is *eligible* for the quantum path only when all of these hold:
+
+- `quantum_policy != "off"` (CLI: `roll --quantum-policy`,
+  default for `demo` is `explore`),
+- the leaf block has at most `QUANTUM_ELIGIBLE_MAX = 256` elements
+  (8 qubits — an honest near-term register size),
+- a qsim encoder is supplied.
+
+Eligible leaves gain QUANTUM-ENCODED / RECONSTRUCTED / ROUTED candidates
+whose numbers come from the real statevector simulator in
+`tensor_roll/qsim.py`. Their reports are labeled
+`backend: qsim-classical`, `device: cpu (statevector simulator)`.
+That label is the boundary: it is classical linear algebra (complex128
+statevectors, explicit unitary application, Born-rule sampling), never a
+QPU, and it never claims to be one.
+
+On a machine with the NVIDIA CUDA-Q toolchain, the same kernel family in
+`cudaq/tensor_roll_kernels.py` can execute for real
+(`run_smoke()` targets `qpp-cpu`); on this machine the import fails and the
+module prints `unavailable` instead of pretending.
+
+## 2. CUDA-Q ↔ Q# boundary: serialized trace artifact (real, not an API)
+
+There is no direct CUDA-Q ↔ Q# linkage — the two toolchains do not share
+an in-process API, and inventing one would be fabrication. The real
+boundary is a serialized artifact produced by `tensor_roll/boundary.py`:
+
+- `trace_for_kernel(kernel, n_qubits, angles, depth)` builds the gate-level
+  IR: the exact gate sequence (`ry` / `cnot` / `measure` / `reset`) that
+  both `cudaq/tensor_roll_kernels.py` and `qsharp/TensorRoll.qs` implement.
+  Each gate carries its QIR op name (`__quantum__qis__ry__body`, …) so the
+  trace maps 1:1 onto QIR when both vendor toolchains are present.
+- `write_trace(path, ...)` writes `{sha256, trace}` JSON: schema version,
+  kernel name, qubit count, shots, the gate list, the measurement counts,
+  producer label, and timestamp.
+- `read_trace(path)` refuses the file if the SHA-256 does not match or the
+  schema is wrong.
+- `counts_to_amplitudes(trace)` is the shared classical reconstruction
+  estimator (amplitude = sqrt(count/shots)) — classical by construction on
+  every side of the boundary.
+
+Data flow:
+
+```
+CUDA-Q process (cudaq/tensor_roll_kernels.py)
+        │  executes kernels (needs CUDA-Q toolchain + target)
+        ▼
+boundary.json  {gates, counts, sha256}     <-- the boundary: a file
+        ▲
+Q# toolchain (qsharp/TensorRoll.qs)
+        │  implements the same gate sequence; reads/writes the artifact
+```
+
+`tensor-roll qkernel` writes `qkernel/boundary.json` on every run and
+immediately re-reads it to prove the round trip. Corrupt the file and the
+reader rejects it — verified by the test suite.
+
+What is NOT claimed: at no point does tensor-roll convert CUDA-Q objects
+to Q# objects in memory. The handoff is serialization, honestly labeled.
+
+## 3. Sandbox boundary: supervisor ↔ untrusted child
+
+Location: `tensor_roll/sandbox.py`, exercised by `tensor-roll sandbox`.
+
+- The child runs in its own session/process group (`start_new_session`),
+  with rlimits (address space, CPU, file size, process count), a filtered
+  environment (only `PATH`/`LANG`/`TZ`/`HOME` survive), and `cwd` pinned to
+  a jail directory.
+- Policy: absolute paths must resolve inside the jail; the binary must be
+  on an allowlist or not on the denylist (deny wins). Network namespaces
+  are entered via `unshare(CLONE_NEWNET)` when the kernel permits it —
+  probed at startup and reported (`netns_available=True/False`); on this
+  machine the probe passes, so `qkernel`-adjacent untrusted code genuinely
+  loses network access.
+- Every spawn, policy verdict, timeout, and signal is appended as JSONL to
+  `sandbox/audit.log`.
+
+Signals: on timeout the supervisor kills the whole process group
+(`killpg(SIGKILL)`), then reaps strays the same way. The audit log records
+which.
+
+## 4. What runs where (summary table)
+
+| Component | Executes on | Label in reports |
+|---|---|---|
+| Tensor math, training, search | NumPy / CPU | `cpu-numpy` |
+| Quantum kernel candidates | classical statevector sim | `qsim-classical` |
+| CUDA-Q kernels | NVIDIA toolchain (absent here) | `unavailable` here |
+| Q# operations | Q# toolchain (absent here) | `unavailable` here |
+| CUDA-Q ↔ Q# handoff | serialized `boundary.json` | sha256-verified |
+| Untrusted subprocesses | sandboxed child | audit-logged |
+
+If a row says `unavailable`, no number was invented for it — the CLI
+prints `unavailable` and the docs say what hardware would change that
+(see `docs/ARCHITECTURE.md`).
+
+## Integration state (failure-resolution audit, 2026-09-29)
+
+**Finding: file-mediated.** The CUDA-Q ↔ Q# handoff in this repository is a
+checksummed serialized JSON trace artifact on disk — not a direct in-process
+API, not live QIR/MLIR bitcode exchange, and not process-to-process RPC.
+Vendor-toolchain execution on this machine is additionally **source-only**:
+CUDA, CUDA-Q, and Q# all probe UNAVAILABLE here, so no vendor kernel has
+ever executed on this box. The file artifact itself round-trips for real
+(`tensor-roll qkernel` writes `qkernel/boundary.json` and re-reads it;
+`test_trace_roundtrip` corrupts it and watches the reader refuse).
+
+Candidates considered and rejected:
+
+- **direct** — rejected. `tensor_roll/boundary.py` states the two toolchains
+  "do not share an in-process API", and no code path converts CUDA-Q
+  objects to Q# objects in memory.
+- **IR-mediated** (true QIR/MLIR bitcode) — rejected for this machine.
+  `boundary.py` notes "True QIR/MLIR bitcode exchange requires both vendor
+  toolchains installed"; neither is installed, so the QIR op names carried
+  on each gate (`__quantum__qis__ry__body`, …) are a mapping specification,
+  not an executed exchange.
+- **process-mediated** — rejected. No live RPC exists between a CUDA-Q
+  process and a Q# process; the handoff is a file both sides can write/read.
+- **file-mediated** — ACCEPTED. Evidence below.
+- **source-only** — true of *execution* on this machine (see probes), but
+  the integration mechanism itself is richer than source-only: the trace
+  artifact is really written, checksummed, read, and verified on every
+  `qkernel` run via the `qsim-classical` path.
+
+File/line evidence (from `tensor_roll/doctor.py::integration_state()`):
+
+- `tensor_roll/boundary.py:7` — "an in-process API. The real boundary used
+  by tensor-roll is a serialized," [no direct linkage; artifact, not API]
+- `tensor_roll/boundary.py:8` — "checksummed, versioned artifact
+  containing:" [integrity-checked artifact]
+- `tensor_roll/boundary.py:20` — "True QIR/MLIR bitcode exchange requires
+  both vendor toolchains installed;" [true QIR/MLIR exchange needs
+  toolchains]
+- `tensor_roll/boundary.py:57` — `def trace_for_kernel(...)` [gate IR
+  constructor: the single source of truth both kernel families implement]
+- `tensor_roll/boundary.py:102` — `def write_trace(...)` [trace is WRITTEN
+  to disk as `{sha256, trace}` JSON]
+- `tensor_roll/boundary.py:130` — `def read_trace(...)` [trace is READ from
+  disk; checksum/schema mismatch raises]
+- `tensor_roll/cli.py:291` — `bpath = os.path.join(wdir, "qkernel",
+  "boundary.json")` [CLI writes the file artifact]
+- `tensor_roll/cli.py:296` — `back = BD.read_trace(bpath)` [CLI verifies
+  the round trip immediately]
+- `cudaq/tensor_roll_kernels.py:9` — "These kernels are NOT executed by the
+  tensor-roll CLI on machines without" [the CUDA-Q toolchain]
+- `cudaq/tensor_roll_kernels.py:28` — `_HAS_CUDAQ = False`
+  [toolchain-absent fallback path]
+- `qsharp/TensorRoll.qs:13` — "NOTE: not compiled or executed in this
+  repository's test environment" [source-only on this machine]
+
+Live probes on this machine (`tensor-roll doctor`, 2026-09-29):
+
+- CUDA: UNAVAILABLE — no nvidia-smi on PATH, no `/dev/nvidia*` devices.
+- CUDA-Q: UNAVAILABLE — no toolchain (`ModuleNotFoundError` from a neutral
+  directory; the repo-local `cudaq/` directory is a namespace package of
+  kernel *source*, not the NVIDIA toolchain).
+- Q#: UNAVAILABLE — no toolchain and no `dotnet`; the repo-local `qsharp/`
+  directory is operation *source*, not an installed toolchain.
+- GPU: NONE. CPU (NumPy) executes for real and passes.
+
+What would change this determination: installing the NVIDIA CUDA-Q
+toolchain and a Q# toolchain would move the *execution* rows from
+source-only to executed, but the integration state would remain
+file-mediated until a real QIR/MLIR bitcode handoff (not just a JSON trace
+carrying QIR op names) is demonstrated between the two toolchains.
+
+## Failure-resolution modules (2026-09-29)
+
+### Out-of-core boundary (`tensor_roll/ooc.py`)
+
+The streaming path never confuses "addressable" with "in RAM":
+
+- A `VirtualManifest` carries shapes, dtypes, and byte offsets only.
+  `reader()` raises `RuntimeError` — there is no silent path from a
+  virtual manifest to weight data.
+- `MappedTensor.view` is an `np.memmap` view; `TensorWindow.data`
+  materializes only the window. `RollWorkspace` accounts the logical
+  working set against an explicit ceiling and raises
+  `MemoryBudgetExceeded` past it. Measured: virtual 30B planning peaks
+  at 35MB RSS — the bound is demonstrated, not asserted.
+- `StudentWriter` checksums every emitted tensor (SHA-256); `verify()`
+  re-hashes on resume and refuses mismatches. Checkpoints are JSON +
+  SHA-256 with atomic replace; corruption is refused, never loaded.
+- The `.npz` repack path reads one array at a time into the shard
+  format; `.safetensors` is windowed in place via mmap with zero copy.
+
+### Planner boundary (`tensor_roll/planner.py`)
+
+- `plan()` lands the allocation on the requested target (≤ 8.0B by
+  default) and never above the 8.5B hard cap. Sensitivity is measured
+  from sampled windows (`calibrate_sensitivity`) or documented as
+  uniform 0.5 when no data exists — the planner degrades to a uniform
+  ratio rather than inventing sensitivity.
+- The 30B STRUCTURAL SCALE TEST label is load-bearing: it certifies
+  storage addressing and planning under bounded RAM, and explicitly
+  does **not** certify model quality. Actual 30B weights: NOT TESTED.
+
+### Fidelity boundary (`tensor_roll/fidelity.py`)
+
+- `divergence_trace()` measures on teacher-forced contexts so model
+  divergence is isolated from context drift; free-run agreement
+  (the 3/24 number) is reported separately and never mixed with it.
+- `fidelity_aware_select()` applies the divergence penalty uniformly to
+  every decision class from measured (sensitivity, reconstruction
+  error). Quantum-gated options are scored from their own qsim-measured
+  errors — the penalty cannot prefer or punish a backend beyond what
+  the measurements say.
+- Ablations replace student components with shape-aligned teacher
+  weights and report Δagreement/ΔKL; components that cannot be aligned
+  are skipped and reported as skipped, not zeroed.
+
+### INT4 boundary (`tensor_roll/quant.py`)
+
+- Scheme choice (per-tensor / per-channel / group-wise) is the argmin
+  of measured MSE per tensor, never a hard-coded default.
+- `recovery_train()` reports PPL before training, after training, and
+  after requantization; "improved" is a measured boolean, not a claim.

docs/render_demo.py

@@ -0,0 +1,115 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Render docs/tensor-roll-demo.png: dark-terminal demo picture.
+
+Recursive tensor blocks folding into a compact core, the pipeline chain
+GLIMMER 30B -> TENSOR ROLL -> CUDA -> CUDA-Q -> Q# -> 8B NANO MODEL,
+and real measured numbers from the tiny validation run. No generic
+AI-brain imagery; everything drawn is the actual architecture.
+"""
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle, FancyArrowPatch
+import numpy as np
+
+BG = "#0a0e14"
+PANEL = "#11161f"
+FG = "#d8dee9"
+DIM = "#7b8798"
+ACC = "#5ccfe6"
+GRN = "#bae67e"
+YLW = "#ffd580"
+MAG = "#f28779"
+
+W, H = 1600, 900
+fig, ax = plt.subplots(figsize=(16, 9), facecolor=BG)
+ax.set_facecolor(BG)
+ax.set_xlim(0, W)
+ax.set_ylim(0, H)
+ax.axis("off")
+
+# title
+ax.text(W / 2, 848, "TENSOR ROLL  \u2014  Recursive CUDA-Q Model Quantizer",
+        color=FG, fontsize=30, ha="center", family="monospace", weight="bold")
+ax.text(W / 2, 808,
+        "GLIMMER 30B  ->  TENSOR ROLL  ->  CUDA  ->  CUDA-Q  ->  Q#  ->  8B NANO MODEL",
+        color=ACC, fontsize=18, ha="center", family="monospace")
+
+# ---- left: recursive folding blocks ----
+ax.text(60, 748, "$ TensorRoll(T, axis, depth, rank, quantum_policy)",
+        color=DIM, fontsize=14, family="monospace")
+cx, cy = 330, 430
+sizes = [400, 292, 208, 140, 88]
+cols = [MAG, YLW, ACC, GRN, ACC]
+for i, (s, c) in enumerate(zip(sizes, cols)):
+    x0, y0 = cx - s / 2, cy - s / 2
+    ax.add_patch(Rectangle((x0, y0), s, s, facecolor="none",
+                           edgecolor=c, linewidth=2.4, alpha=0.9))
+    if s > 120:  # tensor cell grid
+        for gx in np.linspace(x0 + 24, x0 + s - 24, 4):
+            ax.plot([gx, gx], [y0 + 10, y0 + s - 10], color=c, alpha=0.16, lw=1)
+        for gy in np.linspace(y0 + 24, y0 + s - 24, 4):
+            ax.plot([x0 + 10, x0 + s - 10], [gy, gy], color=c, alpha=0.16, lw=1)
+    ax.text(x0 + 12, y0 + s - 24, f"depth {i}", color=c, fontsize=12,
+            family="monospace", alpha=0.9)
+    if i < len(sizes) - 1:
+        s2 = sizes[i + 1]
+        ax.add_patch(FancyArrowPatch((x0 + s - 26, y0 + 30),
+                                     (cx + s2 / 2 - 34, cy - s2 / 2 + 40),
+                                     arrowstyle="->", color=c, linewidth=1.6,
+                                     mutation_scale=14))
+# compact core
+core = 56
+ax.add_patch(Rectangle((cx - core / 2, cy - core / 2), core, core,
+                       facecolor=GRN, edgecolor="none"))
+ax.text(cx, cy, "8B", color=BG, fontsize=20, ha="center", va="center",
+        family="monospace", weight="bold")
+ax.text(cx, 150, "148 leaves  \u00b7  knapsack under P \u2264 8.5B",
+        color=DIM, fontsize=14, ha="center", family="monospace")
+ax.text(cx, 118, "PRESERVE / QUANTIZE / FACTORIZE / MERGED /",
+        color=DIM, fontsize=12.5, ha="center", family="monospace")
+ax.text(cx, 94, "ROUTED / RECONSTRUCTED / PRUNED / QUANTUM-ENCODED",
+        color=DIM, fontsize=12.5, ha="center", family="monospace")
+
+# ---- right: pipeline chain ----
+ax.text(860, 748, "pipeline  (measured on 2 CPUs, no GPU)",
+        color=DIM, fontsize=14, family="monospace")
+stages = [
+    ("tensor-roll ingest", "tiny teacher \u00b7 41.1K params", GRN),
+    ("tensor-roll roll", "TensorRoll() \u00b7 148 leaves \u00b7 budget OK", ACC),
+    ("tensor-roll qkernel", "qsim-classical \u00b7 recon err 0.168", YLW),
+    ("boundary.json", "gate trace + counts \u00b7 sha256 verified", ACC),
+    ("tensor-roll compress", "student arch \u00b7 11.4K (27.8% of teacher)", GRN),
+    ("tensor-roll train", "stages 0\u20137 \u00b7 7 distillation losses", ACC),
+    ("tensor-roll quantize", "fp16 / bf16 / int8 / int4 \u00b7 .trq \u00d75", YLW),
+    ("tensor-roll evaluate", "int8: ppl 8.39 \u00b7 acc 0.342", GRN),
+    ("tensor-roll sandbox", "allow 2 / deny 3 \u00b7 netns isolated", MAG),
+]
+y = 706
+box_w, box_h, gap = 700, 56, 8
+for name, note, col in stages:
+    ax.add_patch(Rectangle((860, y - box_h), box_w, box_h, facecolor=PANEL,
+                           edgecolor=col, linewidth=1.5))
+    ax.text(880, y - 20, f"$ {name}", color=FG, fontsize=15,
+            family="monospace", va="center")
+    ax.text(880, y - 44, note, color=DIM, fontsize=12.5,
+            family="monospace", va="center")
+    if y - box_h - gap > 120:
+        ax.add_patch(FancyArrowPatch((1210, y - box_h - 2),
+                                     (1210, y - box_h - gap + 2),
+                                     arrowstyle="->", color=DIM,
+                                     linewidth=1.2, mutation_scale=12))
+    y -= box_h + gap
+
+# ---- bottom honesty strip ----
+ax.text(W / 2, 56, "backend labels:  cpu-numpy  \u00b7  qsim-classical (NOT a QPU)  \u00b7  "
+        "unavailable = not executed here, never invented",
+        color=DIM, fontsize=13, ha="center", family="monospace")
+ax.text(W / 2, 28, "AGPLv3  \u00b7  Copyright (C) 2026 SnapKitty Collective",
+        color="#3a4353", fontsize=12, ha="center", family="monospace")
+
+plt.savefig("docs/tensor-roll-demo.png", facecolor=BG, dpi=110,
+            bbox_inches="tight", pad_inches=0.15)
+print("wrote docs/tensor-roll-demo.png")

experiments/fidelity_resolution.py

@@ -0,0 +1,175 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""F5 resolution experiment: diagnose the 3/24 token agreement, attempt a
+principled fix, measure the result.
+
+Protocol (all measured, fixed seeds, no cherry-picking):
+  V0: baseline demo --fast pipeline (control).
+  Diagnose: divergence trace + first divergence + component ablations on V0.
+  Section-6 check: core.select_plan vs fidelity.fidelity_aware_select on the
+      same roll leaves — do the decisions differ, and does the
+      fidelity-aware utility change anything measurable?
+  V1: same init, distillation stages 2 (hidden-state) and 3 (logit) rerun
+      at 3x steps — tests whether distillation was underpowered vs whether
+      capacity/init is the bottleneck.
+  Report: agreement/24 and mean teacher-KL for V0 and V1.
+
+Whatever the outcome — improvement, null, or regression — is reported.
+Failed experiments are valid output.
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from tensor_roll import cli as CLI
+from tensor_roll import core as C
+from tensor_roll import fidelity as F
+from tensor_roll import model as M
+from tensor_roll import planner as P
+from tensor_roll import search as S
+from tensor_roll.util import write_json
+
+PROMPTS = [[3, 1, 4, 1], [7, 7, 2, 9], [0, 5, 5, 0]]
+N_TOKENS = 24
+
+
+def ns(**kw):
+    a = argparse.Namespace()
+    for k, v in kw.items():
+        setattr(a, k, v)
+    return a
+
+
+def measure_agreement_kl(t_params, t_cfg, s_params, s_cfg):
+    agrees, n, kls = 0, 0, []
+    for pr in PROMPTS:
+        tt, _, _ = M.generate(t_params, t_cfg, pr, N_TOKENS)
+        st, _, _ = M.generate(s_params, s_cfg, pr, N_TOKENS)
+        agrees += sum(a == b for a, b in zip(tt, st))
+        n += len(tt)
+        rng = np.random.default_rng(4242)
+        for _ in range(2):
+            ids = M.gen_data(rng, 32, s_cfg)
+            tl, _ = M.forward(t_params, t_cfg, ids[:, :-1])
+            sl, _ = M.forward(s_params, s_cfg, ids[:, :-1])
+            kls.append(float(M.kl_divergence_mean(tl, sl)))
+    return {"agreement": f"{agrees}/{n}", "agree_frac": agrees / n,
+            "mean_kl": float(np.mean(kls))}
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--workdir", required=True)
+    ap.add_argument("--steps-t", type=int, default=250)
+    ap.add_argument("--steps-d", type=int, default=40)
+    args = ap.parse_args()
+    wdir = args.workdir
+    os.makedirs(wdir, exist_ok=True)
+    rep = {"protocol": "V0 baseline vs V1 focused-distillation",
+           "prompts": PROMPTS, "n_tokens": N_TOKENS}
+
+    # ---- teacher ------------------------------------------------------
+    print("== teacher ==", flush=True)
+    CLI.cmd_ingest(ns(workdir=wdir, scale="tiny", steps=args.steps_t,
+                      batch=128, lr=3e-3, seed=11))
+    t_params, t_cfg = CLI._teacher(wdir)
+
+    # ---- roll: section-6 comparison -----------------------------------
+    print("== roll: select_plan vs fidelity_aware_select ==", flush=True)
+    stats = M.measure_tensor_stats(t_params, t_cfg)
+    trees, leaves = S.run_roll_analysis(
+        t_params, depth=2, quantum_policy="explore", stats=stats)
+    budget = M.count_params(t_params) * S.BUDGET_RATIO
+    plan0 = C.select_plan(leaves, budget)
+    sens_rows = [{"tensor": l.name, "shape": [1], "dtype": "float32",
+                 "params": 1, "bytes": 4, "shard": "x", "is_matrix": False}
+                for l in leaves]
+    sens = {l.name: float(np.clip(
+        l.metrics.get("spectral", 0.5), 0, 1)) for l in leaves}
+    plan1 = F.fidelity_aware_select(leaves, budget, sens, lam=1.0)
+    diff = sum(1 for l in leaves
+               if plan0[l.name]["decision"] != plan1[l.name]["decision"])
+    rep["section6"] = {
+        "n_leaves": len(leaves),
+        "baseline_decisions": {d: sum(1 for l in leaves
+                                     if plan0[l.name]["decision"] == d)
+                               for d in set(plan0[l.name]["decision"]
+                                            for l in leaves)},
+        "fidelity_aware_decisions": {d: sum(
+            1 for l in leaves if plan1[l.name]["decision"] == d)
+            for d in set(plan1[l.name]["decision"] for l in leaves)},
+        "n_decision_diffs": diff,
+        "baseline_cost": plan0["_total_cost_params"],
+        "fidelity_cost": plan1["_total_cost_params"],
+    }
+    print(f"  leaves={len(leaves)} decision_diffs={diff} "
+          f"cost0={plan0['_total_cost_params']} "
+          f"cost1={plan1['_total_cost_params']}", flush=True)
+    for l in leaves:
+        l.decision = plan0[l.name]  # baseline drives the pipeline
+
+    # ---- compress + train + finetune (V0) ------------------------------
+    print("== compress ==", flush=True)
+    CLI.cmd_compress(ns(workdir=wdir, budget_ratio=S.BUDGET_RATIO, seed=11))
+    print("== train (V0) ==", flush=True)
+    CLI.cmd_train(ns(workdir=wdir, steps=args.steps_d, batch=128, lr=3e-3,
+                     seed=12, stage="all"))
+    print("== finetune (V0) ==", flush=True)
+    CLI.cmd_finetune(ns(workdir=wdir, steps=args.steps_d, batch=128, seed=13))
+    s_params = CLI._load_params(os.path.join(wdir, "student_final.npz"))
+    s_cfg = M.Config.from_dict(
+        CLI.read_json(os.path.join(wdir, "student_cfg.json")))
+    rep["V0"] = measure_agreement_kl(t_params, t_cfg, s_params, s_cfg)
+    print(f"  V0: {rep['V0']}", flush=True)
+
+    # ---- diagnose V0 ----------------------------------------------------
+    print("== divergence trace (V0) ==", flush=True)
+    tr = F.divergence_trace(t_params, t_cfg, s_params, s_cfg,
+                            PROMPTS[0], max_tokens=N_TOKENS)
+    first = F.first_divergence(tr)
+    rep["trace_V0"] = {
+        "agreement": tr["token_agreement"],
+        "first_divergence": first,
+        "mean_kl": float(np.mean([p["kl_div"] for p in tr["positions"]])),
+        "mean_js": float(np.mean([p["js_div"] for p in tr["positions"]])),
+    }
+    print(f"  first divergence: position={first.get('position')} "
+          f"layer={first.get('first_diverging_layer')} "
+          f"KL={first.get('kl_div'):.3f}", flush=True)
+    print("== ablations (V0) ==", flush=True)
+    abl = F.ablation_report(t_params, t_cfg, s_params, s_cfg,
+                            PROMPTS, max_tokens=16)
+    rep["ablation_V0"] = abl["ranking"]
+    for r in abl["ranking"][:4]:
+        print(f"  {r['component']:24s} d_agree={r['delta_agree']:+.3f} "
+              f"d_kl={r.get('delta_kl', 0):+.3f}", flush=True)
+
+    # ---- V1: focused extra distillation ---------------------------------
+    print("== V1: extra hidden/logit distillation ==", flush=True)
+    CLI.cmd_train(ns(workdir=wdir, steps=args.steps_d * 3, batch=128,
+                     lr=3e-3, seed=12, stage="2"))
+    CLI.cmd_train(ns(workdir=wdir, steps=args.steps_d * 3, batch=128,
+                     lr=3e-3, seed=12, stage="3"))
+    s_params1 = CLI._load_params(os.path.join(wdir, "student_distilled.npz"))
+    rep["V1"] = measure_agreement_kl(t_params, t_cfg, s_params1, s_cfg)
+    print(f"  V1: {rep['V1']}", flush=True)
+    rep["delta_agree"] = rep["V1"]["agree_frac"] - rep["V0"]["agree_frac"]
+    rep["delta_kl"] = rep["V1"]["mean_kl"] - rep["V0"]["mean_kl"]
+
+    out = os.path.join(wdir, "fidelity_resolution_report.json")
+    write_json(out, rep)
+    print(f"wrote {out}", flush=True)
+    print(json.dumps({k: rep[k] for k in ("V0", "V1", "section6")
+                      if k in rep}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

experiments/fidelity_resolution_report.json

@@ -0,0 +1,144 @@
+{
+  "protocol": "V0 baseline vs V1 focused-distillation",
+  "prompts": [
+    [
+      3,
+      1,
+      4,
+      1
+    ],
+    [
+      7,
+      7,
+      2,
+      9
+    ],
+    [
+      0,
+      5,
+      5,
+      0
+    ]
+  ],
+  "n_tokens": 24,
+  "section6": {
+    "n_leaves": 148,
+    "baseline_decisions": {
+      "QUANTIZE": 65,
+      "PRESERVE": 83
+    },
+    "fidelity_aware_decisions": {
+      "QUANTIZE": 55,
+      "PRESERVE": 93
+    },
+    "n_decision_diffs": 12,
+    "baseline_cost": 11645.0,
+    "fidelity_cost": 11456.0
+  },
+  "V0": {
+    "agreement": "7/72",
+    "agree_frac": 0.09722222222222222,
+    "mean_kl": 1.547805292394603
+  },
+  "trace_V0": {
+    "agreement": "5/24",
+    "first_divergence": {
+      "position": 0,
+      "teacher_token": 30,
+      "student_token": 4,
+      "kl_div": 2.7323540578677252,
+      "js_div": 0.4399995705020577,
+      "first_diverging_layer": "layer_0",
+      "layer_hidden_rel_err": 1.0380715313927222,
+      "layer_attn_div": 0.1767730414867401,
+      "all_layer_hidden_rel_err": {
+        "layer_0": 1.0380715313927222
+      },
+      "above_hidden_thresh": {
+        "layer_0": 1.0380715313927222
+      }
+    },
+    "mean_kl": 2.5741920989727904,
+    "mean_js": 0.43385868451562576
+  },
+  "ablation_V0": [
+    {
+      "component": "baseline(student)",
+      "agreement": 0.10416666666666667,
+      "mean_kl": 2.337756615069645,
+      "delta_agree": 0,
+      "n_swapped": 0
+    },
+    {
+      "component": "mlp_down",
+      "agreement": 0.08333333333333333,
+      "mean_kl": 3.0453086743936697,
+      "delta_agree": -0.020833333333333343,
+      "delta_kl": 0.7075520593240245,
+      "n_swapped": 2
+    },
+    {
+      "component": "normalization",
+      "agreement": 0.0625,
+      "mean_kl": 3.8407641291009362,
+      "delta_agree": -0.04166666666666667,
+      "delta_kl": 1.503007514031291,
+      "n_swapped": 6
+    },
+    {
+      "component": "mlp_up",
+      "agreement": 0.041666666666666664,
+      "mean_kl": 3.3130315933929992,
+      "delta_agree": -0.0625,
+      "delta_kl": 0.9752749783233541,
+      "n_swapped": 2
+    },
+    {
+      "component": "embeddings",
+      "agreement": 0.020833333333333332,
+      "mean_kl": 3.8539798822845035,
+      "delta_agree": -0.08333333333333334,
+      "delta_kl": 1.5162232672148583,
+      "n_swapped": 1
+    },
+    {
+      "component": "attention_projections",
+      "agreement": 0.020833333333333332,
+      "mean_kl": 3.8425005798316954,
+      "delta_agree": -0.08333333333333334,
+      "delta_kl": 1.5047439647620502,
+      "n_swapped": 6
+    },
+    {
+      "component": "attention_output",
+      "agreement": 0.020833333333333332,
+      "mean_kl": 3.4268810943999513,
+      "delta_agree": -0.08333333333333334,
+      "delta_kl": 1.089124479330306,
+      "n_swapped": 2
+    },
+    {
+      "component": "output_head",
+      "agreement": 0.0,
+      "mean_kl": 2.535711207020847,
+      "delta_agree": -0.10416666666666667,
+      "delta_kl": 0.19795459195120202,
+      "n_swapped": 2
+    }
+  ],
+  "V1": {
+    "agreement": "2/72",
+    "agree_frac": 0.027777777777777776,
+    "mean_kl": 1.2794614517510858
+  },
+  "delta_agree": -0.06944444444444445,
+  "delta_kl": -0.26834384064351724,
+  "V1b": {
+    "agreement": "4/72",
+    "agree_frac": 0.05555555555555555,
+    "mean_kl": 1.1872056255483905
+  },
+  "V1b_note": "V1 measured student_distilled.npz without finetune; V1b reruns finetune so V0 vs V1b differ only in the extra hidden/logit distillation stages.",
+  "delta_agree_V1b": -0.04166666666666667,
+  "delta_kl_V1b": -0.3605996668462126
+}

experiments/int4_recovery.json

@@ -0,0 +1,10 @@
+{
+  "steps": 30,
+  "ppl_before": 7.4307143325561995,
+  "ppl_after_train": 5.489463114355006,
+  "ppl_after_requant": 6.883665882879365,
+  "gap_before": 1.9412512182011934,
+  "gap_delta": 0.5470484496768346,
+  "improved": true,
+  "elapsed_s": 3.1367221489999793
+}

pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tensor-roll"
+version = "1.0.0"
+description = "Tensor Roll — Recursive CUDA-Q Model Quantizer (experimental)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "AGPL-3.0-or-later" }
+dependencies = ["numpy>=1.24"]
+
+[project.scripts]
+tensor-roll = "tensor_roll.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tensor_roll*"]

qsharp/TensorRoll.qs

@@ -0,0 +1,107 @@
+// Tensor Roll — Recursive CUDA-Q Model Quantizer
+// Copyright (C) 2026 SnapKitty Collective
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// Genuine Q# operations for the tensor_roll kernel family.
+// These mirror cudaq/tensor_roll_kernels.py across the process/IR boundary
+// documented in docs/BOUNDARIES.md: CUDA-Q kernels emit QIR/MLIR on the
+// CUDA-Q side; this Q# source is the equivalent family expressed for the
+// Q# toolchain. There is no direct CUDA-Q <-> Q# linkage — the boundary is
+// a real serialized artifact (QIR bitcode / measurement-counts JSON),
+// never an invented API.
+//
+// NOTE: not compiled or executed in this repository's test environment
+// (no Q# toolchain present). Every execution claim in tensor-roll refers
+// to the classical qsim-classical simulator, explicitly labeled as such.
+
+namespace TensorRoll {
+    open Microsoft.Quantum.Canon;
+    open Microsoft.Quantum.Intrinsic;
+    open Microsoft.Quantum.Measurement;
+    open Microsoft.Quantum.Math;
+    open Microsoft.Quantum.Convert;
+    open Microsoft.Quantum.Arrays;
+
+    /// Encodes a classical tensor block into a qubit register (angle encoding).
+    operation EncodeTensorBlock(block : Double[], register : Qubit[]) : Unit {
+        let n = Length(block) < Length(register) ? Length(block) | Length(register);
+        for i in 0..n - 1 {
+            Ry(2.0 * ArcTan(block[i]), register[i]);
+        }
+    }
+
+    /// Applies per-qubit RY rotations — the "roll" of the register.
+    operation RollRegister(register : Qubit[], angles : Double[]) : Unit {
+        for i in 0..Length(register) - 1 {
+            Ry(angles[i % Length(angles)], register[i]);
+        }
+    }
+
+    /// Nearest-neighbour CNOT ladder over the register.
+    operation EntangleRoll(register : Qubit[]) : Unit {
+        for i in 0..Length(register) - 2 {
+            Controlled X([register[i]], register[i + 1]);
+        }
+    }
+
+    /// Recursive kernel: each level rotates and entangles the active subset,
+    /// measures the outer qubit, resets it, and recurses on the remainder.
+    /// Q# operations may call themselves — this is genuine recursion.
+    /// Returns one measurement Result per recursion level.
+    operation RecursiveRoll(register : Qubit[], angles : Double[], depth : Int) : Result[] {
+        if depth <= 0 or Length(register) == 0 {
+            return [];
+        }
+        RollRegister(register, angles);
+        EntangleRoll(register);
+        let outer = register[Length(register) - 1];
+        let outcome = MResetZ(outer);
+        let rest = RecursiveRoll(register[0..Length(register) - 2], angles, depth - 1);
+        return [outcome] + rest;
+    }
+
+    /// Measures the register in the Z basis, resetting each qubit.
+    operation MeasureRoll(register : Qubit[]) : Result[] {
+        mutable results = [];
+        for q in register {
+            set results += [MResetZ(q)];
+        }
+        return results;
+    }
+
+    /// Classical reconstruction of amplitude estimates from measurement counts.
+    /// Reconstruction is classical by construction — this function executes on
+    /// the classical host, never on the quantum processor.
+    function ReconstructBlock(counts : (Result[], Int)[], nQubits : Int) : Double[] {
+        mutable total = 0;
+        for (_, c) in counts {
+            set total += c;
+        }
+        let dim = 1 <<< nQubits;
+        mutable amps = [0.0, size = dim];
+        for (bits, c) in counts {
+            mutable idx = 0;
+            for b in bits {
+                set idx = idx * 2 + (b == One ? 1 | 0);
+            }
+            if idx < dim and total > 0 {
+                set amps w/= idx <- Sqrt(IntAsDouble(c) / IntAsDouble(total));
+            }
+        }
+        return amps;
+    }
+
+    @EntryPoint()
+    operation Main() : Unit {
+        // Small demonstration block; mirrors the 8x8-block smoke test that
+        // tensor-roll qkernel runs classically via qsim.
+        let block = [0.1, 0.4, 0.2, 0.8];
+        use register = Qubit[4];
+        EncodeTensorBlock(block, register);
+        let rolled = RecursiveRoll(register, [0.3, 0.6, 0.2, 0.9], 2);
+        let tail = MeasureRoll(register);
+        Message($"recursive outcomes: {rolled}");
+        Message($"tail outcomes: {tail}");
+        ResetAll(register);
+    }
+}

tensor_roll/__init__.py

@@ -0,0 +1,17 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Tensor Roll: recursive tensor transformation for model compression.
+
+Classical execution on this machine is NumPy-on-CPU, honestly labeled
+``cpu-numpy`` in every report. Quantum paths execute on a classical
+state-vector simulator (``qsim-classical``) unless real CUDA-Q/Q#
+hardware tooling is present.
+"""
+
+__version__ = "0.1.0"
+
+from .core import TensorRoll, roll_tree, select_plan, iter_leaves  # noqa: E402
+
+__all__ = ["__version__", "TensorRoll", "roll_tree", "select_plan",
+           "iter_leaves"]

tensor_roll/boundary.py

@@ -0,0 +1,152 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Process/IR boundary between the CUDA-Q kernels and the Q# operations.
+
+There is no direct CUDA-Q <-> Q# linkage: the two toolchains do not share
+an in-process API. The real boundary used by tensor-roll is a serialized,
+checksummed, versioned artifact containing:
+
+  1. a gate-level IR trace (S-expression-ish JSON list) describing exactly
+     which kernel ran, on how many qubits, with which gates, and
+  2. the measurement counts produced by executing that trace.
+
+Either side of the boundary — the CUDA-Q process
+(``cudaq/tensor_roll_kernels.py``), the Q# toolchain (``qsharp/TensorRoll.qs``),
+or the classical ``qsim-classical`` simulator — can write this artifact and
+any other side can read it. Nothing is invented: the file is real JSON on
+disk with a SHA-256 checksum, and the reader refuses corrupted artifacts.
+
+True QIR/MLIR bitcode exchange requires both vendor toolchains installed;
+when they are present, the same trace maps 1:1 onto QIR gate ops
+(``__quantum__qis__ry``, ``__quantum__qis__cnot__ctl``, ...).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+BOUNDARY_VERSION = 1
+TRACE_SCHEMA = "tensor-roll/boundary-trace"
+
+# ---------------------------------------------------------------------------
+# Gate IR construction (mirrors both kernel families' semantics)
+# ---------------------------------------------------------------------------
+
+def _ry(q: int, theta: float) -> Dict[str, Any]:
+    return {"gate": "ry", "qubits": [q], "params": [float(theta)],
+            "qir": "__quantum__qis__ry__body"}
+
+def _cnot(c: int, t: int) -> Dict[str, Any]:
+    return {"gate": "cnot", "qubits": [c, t], "params": [],
+            "qir": "__quantum__qis__cnot__ctl"}
+
+def _measure(q: int) -> Dict[str, Any]:
+    return {"gate": "measure", "qubits": [q], "params": [],
+            "qir": "__quantum__qis__mz__body"}
+
+def _reset(q: int) -> Dict[str, Any]:
+    return {"gate": "reset", "qubits": [q], "params": [],
+            "qir": "__quantum__qis__reset__body"}
+
+
+def trace_for_kernel(kernel: str, n_qubits: int,
+                     angles: Optional[List[float]] = None,
+                     depth: int = 0) -> List[Dict[str, Any]]:
+    """Build the gate IR trace for a tensor_roll kernel.
+
+    This is the exact gate sequence the CUDA-Q kernels in
+    cudaq/tensor_roll_kernels.py apply and the Q# operations in
+    qsharp/TensorRoll.qs apply — a single source of truth for the
+    cross-toolchain boundary.
+    """
+    a = list(angles) if angles else [0.0] * n_qubits
+    gates: List[Dict[str, Any]] = []
+    if kernel == "tensor_roll_encode":
+        for q in range(n_qubits):
+            gates.append(_ry(q, 2.0 * a[q % len(a)]))
+    elif kernel == "tensor_roll_rotate":
+        for q in range(n_qubits):
+            gates.append(_ry(q, a[q % len(a)]))
+    elif kernel == "tensor_roll_entangle":
+        for q in range(n_qubits - 1):
+            gates.append(_cnot(q, q + 1))
+    elif kernel in ("tensor_roll_measure", "tensor_roll_reconstruct"):
+        for q in range(n_qubits):
+            gates.append(_measure(q))
+    elif kernel == "tensor_roll_recursive":
+        for lvl in range(max(1, depth)):
+            k = max(1, n_qubits - lvl)
+            for q in range(k):
+                gates.append(_ry(q, a[q % len(a)]))
+            for q in range(k - 1):
+                gates.append(_cnot(q, q + 1))
+            if lvl < max(1, depth) - 1:
+                gates.append(_measure(k - 1))
+                gates.append(_reset(k - 1))
+        for q in range(n_qubits):
+            gates.append(_measure(q))
+    else:
+        raise ValueError(f"unknown tensor_roll kernel: {kernel}")
+    return gates
+
+
+# ---------------------------------------------------------------------------
+# Trace artifact: write / read with checksum
+# ---------------------------------------------------------------------------
+
+def write_trace(path: str, kernel: str, n_qubits: int, shots: int,
+                counts: Dict[str, int],
+                angles: Optional[List[float]] = None,
+                depth: int = 0,
+                producer: str = "qsim-classical") -> Dict[str, Any]:
+    """Write a boundary trace artifact. Returns the decoded header."""
+    gates = trace_for_kernel(kernel, n_qubits, angles=angles, depth=depth)
+    body = {
+        "schema": TRACE_SCHEMA,
+        "version": BOUNDARY_VERSION,
+        "kernel": kernel,
+        "n_qubits": n_qubits,
+        "shots": shots,
+        "gates": gates,
+        "n_gates": len(gates),
+        "counts": {k: int(v) for k, v in counts.items()},
+        "producer": producer,
+        "produced_at": time.strftime("%Y-%m-%dT%H:%M:%S%z", time.gmtime()),
+        "qir_mapping": "each gate lists its __quantum__qis__* QIR op name",
+    }
+    payload = json.dumps(body, sort_keys=True).encode()
+    digest = hashlib.sha256(payload).hexdigest()
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    with open(path, "w") as f:
+        json.dump({"sha256": digest, "trace": body}, f, indent=2)
+    return body
+
+
+def read_trace(path: str) -> Dict[str, Any]:
+    """Read and checksum-verify a boundary trace artifact."""
+    with open(path) as f:
+        doc = json.load(f)
+    payload = json.dumps(doc["trace"], sort_keys=True).encode()
+    if hashlib.sha256(payload).hexdigest() != doc["sha256"]:
+        raise ValueError(f"boundary trace checksum mismatch: {path}")
+    if doc["trace"].get("schema") != TRACE_SCHEMA:
+        raise ValueError(f"not a tensor-roll boundary trace: {path}")
+    return doc["trace"]
+
+
+def counts_to_amplitudes(trace: Dict[str, Any]) -> List[float]:
+    """Classical reconstruction estimator shared across the boundary:
+    amplitude_i = sqrt(count_i / shots). Classical by construction."""
+    shots = trace["shots"]
+    dim = 1 << trace["n_qubits"]
+    amps = [0.0] * dim
+    for bits, c in trace["counts"].items():
+        idx = int(bits, 2) if set(bits) <= {"0", "1"} else 0
+        if idx < dim and shots > 0:
+            amps[idx] = (c / shots) ** 0.5
+    return amps

tensor_roll/cli.py

@@ -0,0 +1,1096 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""The `tensor-roll` command surface (spec section 11).
+
+All 14 subcommands operate on a working directory (default
+~/.tensor-roll/default) and do real work: training runs, SVDs are
+computed, reports carry measured values. Anything that cannot be executed
+in this environment is reported as `unavailable` with a reason — never
+invented.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+import time
+
+import numpy as np
+
+from . import core as C
+from . import distill as D
+from . import model as M
+from . import qsim as Q
+from . import quant as QT
+from . import sandbox as SB
+from . import search as S
+from . import trq as T
+from .util import (AuditLog, ensure_dir, fmt_bytes, fmt_params, read_json,
+                   rss_mb, utc_now_iso, write_json)
+
+DEFAULT_WORKDIR = os.path.expanduser("~/.tensor-roll/default")
+FORMATS = ["fp32", "fp16", "bf16", "int8", "int4"]
+
+
+# ---------------------------------------------------------------------------
+# workdir helpers
+# ---------------------------------------------------------------------------
+
+def wd(args) -> str:
+    return ensure_dir(args.workdir)
+
+
+def _save_params(path: str, params: dict) -> None:
+    np.savez(path, **{k: np.asarray(v) for k, v in params.items()})
+
+
+def _load_params(path: str) -> dict:
+    z = np.load(path, allow_pickle=False)
+    return {k: z[k] for k in z.files}
+
+
+def _need(path: str, what: str):
+    if not os.path.exists(path):
+        print(f"missing {what}: {path}\nrun the earlier pipeline stage first.",
+              file=sys.stderr)
+        sys.exit(2)
+    return path
+
+
+def _teacher(wdir: str):
+    cfg = M.Config.from_dict(read_json(os.path.join(wdir, "teacher_cfg.json")))
+    params = _load_params(_need(os.path.join(wdir, "teacher.npz"), "teacher"))
+    return params, cfg
+
+
+def _student(wdir: str, variant: str = "fp32"):
+    if variant == "fp32":
+        cfg = M.Config.from_dict(read_json(os.path.join(wdir, "student_cfg.json")))
+        params = _load_params(_need(os.path.join(wdir, "student_final.npz"), "student"))
+        return params, cfg
+    # quantized variants live in .trq files
+    path = _need(os.path.join(wdir, "trq", f"student_{variant}.trq"), f"{variant} artifact")
+    header, tensors = T.read_trq(path)
+    cfg = M.Config.from_dict(header["arch"]["config"])
+    params = {k: QT.dequantize_tensor(arr, meta).astype(np.float32)
+              for k, (arr, meta) in tensors.items()}
+    return params, cfg
+
+
+# ---------------------------------------------------------------------------
+# ingest
+# ---------------------------------------------------------------------------
+
+def cmd_ingest(args):
+    wdir = wd(args)
+    if args.scale == "30b":
+        print("scale: glimmer-30b (meta-models/Muse-Glimmer-30B)")
+        reqs = [
+            ("GPU with >=24GB VRAM (train) / >=20GB RAM (infer 4-bit)",
+             _has_gpu(), "nvidia-smi not found"),
+            ("disk >= 120GB free for weights + workspace",
+             _free_gb() >= 120, f"only {_free_gb():.0f}GB free"),
+            ("RAM >= 32GB for full-precision ingest",
+             _ram_gb() >= 32, f"only {_ram_gb():.0f}GB RAM"),
+        ]
+        ok = True
+        for name, have, why in reqs:
+            print(f"  [{'OK' if have else 'UNAVAILABLE'}] {name}"
+                  + ("" if have else f" — {why}"))
+            ok = ok and have
+        if not ok:
+            print("ingest --scale 30b: unavailable in this environment "
+                  "(no GPU, 7GB RAM). See docs/ARCHITECTURE.md for the "
+                  "30B hardware path. Nothing was fabricated.")
+            sys.exit(3)
+        print("downloading meta-models/Muse-Glimmer-30B ...")
+        sys.exit(3)  # unreachable here; kept explicit
+    cfg = M.Config()
+    print(f"training tiny teacher {cfg} "
+          f"({fmt_params(_pcount(cfg))} params, seed={args.seed})")
+    t0 = time.perf_counter()
+    params, history = M.train_teacher(cfg, steps=args.steps, batch=args.batch,
+                                      lr=args.lr, seed=args.seed,
+                                      log_every=max(1, args.steps // 5))
+    dt = time.perf_counter() - t0
+    _save_params(os.path.join(wdir, "teacher.npz"), params)
+    write_json(os.path.join(wdir, "teacher_cfg.json"), cfg.to_dict())
+    write_json(os.path.join(wdir, "teacher_history.json"), history)
+    ev = M.eval_metrics(params, cfg)
+    write_json(os.path.join(wdir, "teacher_eval.json"), ev)
+    prov = {"scale": "tiny", "task": "synthetic modular grammar",
+            "steps": args.steps, "batch": args.batch, "lr": args.lr,
+            "seed": args.seed, "elapsed_s": dt, "backend": C.CLASSICAL_BACKEND,
+            "created": utc_now_iso()}
+    write_json(os.path.join(wdir, "teacher_provenance.json"), prov)
+    print(f"teacher: {fmt_params(_pcount(cfg))} params, "
+          f"held-out loss={ev['loss']:.4f} acc={ev['accuracy']:.3f}, "
+          f"{dt:.1f}s on {C.CLASSICAL_BACKEND}")
+
+
+def _pcount(cfg) -> int:
+    return M.count_params(M.init_params(np.random.default_rng(0), cfg))
+
+
+def _has_gpu() -> bool:
+    return shutil.which("nvidia-smi") is not None
+
+
+def _free_gb() -> float:
+    return shutil.disk_usage(os.path.expanduser("~")).free / 1e9
+
+
+def _ram_gb() -> float:
+    try:
+        with open("/proc/meminfo") as f:
+            for line in f:
+                if line.startswith("MemTotal:"):
+                    return float(line.split()[1]) / 1e6
+    except OSError:
+        return 0.0
+    return 0.0
+
+
+# ---------------------------------------------------------------------------
+# inspect / map
+# ---------------------------------------------------------------------------
+
+def cmd_inspect(args):
+    wdir = wd(args)
+    if args.what == "trq":
+        header, tensors = T.read_trq(_need(args.trq, ".trq file"))
+        print(f"{args.trq}: {header['n_tensors']} tensors, "
+              f"{fmt_bytes(os.path.getsize(args.trq))}, "
+              f"sha256={T.read_trq(args.trq) and header and 'verified'}")
+        total, ok = T.param_budget_ok(tensors)
+        print(f"params: {fmt_params(total)}  budget<=8.5B: {'OK' if ok else 'VIOLATION'}")
+        for k, (arr, meta) in sorted(tensors.items()):
+            print(f"  {k:24s} {str(list(meta.get('shape', arr.shape))):28s} "
+                  f"{meta.get('fmt', '?'):6s}")
+        return
+    params, cfg = _teacher(wdir) if args.what == "teacher" else _student(wdir)
+    print(f"{args.what}: {cfg}, {fmt_params(M.count_params(params))} params")
+    for k in sorted(params):
+        v = params[k]
+        print(f"  {k:16s} {str(list(v.shape)):22s} {str(v.dtype):10s} "
+              f"||.||={float(np.linalg.norm(v.astype(np.float64).ravel())):.4f}")
+
+
+def cmd_map(args):
+    wdir = wd(args)
+    params, cfg = _teacher(wdir)
+    rows = []
+    for k in sorted(params):
+        m = C.tensor_metrics(params[k])
+        rows.append({"tensor": k, **{kk: m[kk] for kk in
+                                    ("shape", "params", "norm", "rank",
+                                     "entropy", "variance", "spectral")}})
+    write_json(os.path.join(wdir, "map.json"), rows)
+    print(f"{'tensor':16s} {'shape':22s} {'params':>8s} {'rank':>4s} "
+          f"{'entropy':>7s} {'spectral':>8s}")
+    for r in rows:
+        print(f"{r['tensor']:16s} {str(r['shape']):22s} {r['params']:8d} "
+              f"{r['rank']:4d} {r['entropy']:7.3f} {r['spectral']:8.3f}")
+    print(f"total: {fmt_params(sum(r['params'] for r in rows))} params")
+
+
+# ---------------------------------------------------------------------------
+# roll
+# ---------------------------------------------------------------------------
+
+def cmd_roll(args):
+    wdir = wd(args)
+    params, cfg = _teacher(wdir)
+    t0 = time.perf_counter()
+    # measured activation/gradient contributions (real fwd/bwd passes)
+    stats = M.measure_tensor_stats(params, cfg)
+    trees, leaves = S.run_roll_analysis(params, depth=args.depth,
+                                        quantum_policy=args.quantum_policy,
+                                        stats=stats)
+    n_teacher = M.count_params(params)
+    budget = n_teacher * args.budget_ratio
+    plan = C.select_plan(leaves, budget)
+    for leaf in leaves:
+        leaf.decision = plan[leaf.name]
+    dt = time.perf_counter() - t0
+    serial = {leaf.name: {"decision": leaf.decision["decision"],
+                          "cost_params": leaf.decision["cost_params"],
+                          "retained_energy": leaf.decision["retained_energy"],
+                          "reconstruction_error":
+                          leaf.decision["reconstruction_error"],
+                          "detail": leaf.decision["detail"],
+                          "metrics": leaf.metrics}
+              for leaf in leaves}
+    write_json(os.path.join(wdir, "roll_plan.json"),
+               {"budget_ratio": args.budget_ratio, "budget_params": budget,
+                "total_cost": plan["_total_cost_params"],
+                "quantum_policy": args.quantum_policy,
+                "elapsed_s": dt, "leaves": serial})
+    shown = leaves[:40]
+    for i, leaf in enumerate(shown, 1):
+        print(C.render_roll_line(leaf, i))
+    if len(leaves) > len(shown):
+        print(f"... {len(leaves) - len(shown)} more leaves "
+              f"({len(leaves)} total)")
+    from collections import Counter
+    hist = Counter(l.decision["decision"] for l in leaves)
+    print(f"decisions: {dict(hist)}")
+    print(f"budget: {fmt_params(budget)}  planned cost: "
+          f"{fmt_params(int(plan['_total_cost_params']))}  "
+          f"{'OK' if plan['_total_cost_params'] <= budget else 'OVER BUDGET'} "
+          f"({dt:.1f}s)")
+
+
+# ---------------------------------------------------------------------------
+# qkernel
+# ---------------------------------------------------------------------------
+
+def cmd_qkernel(args):
+    wdir = wd(args)
+    params, cfg = _teacher(wdir)
+    name = args.tensor or max((k for k in params if params[k].ndim == 2),
+                              key=lambda k: params[k].size)
+    W = np.asarray(params[name], dtype=np.float64)
+    # take the highest-energy top-left block that fits the qubit cap:
+    # amplitude packs 2^n elems into n qubits; angle needs 1 qubit/elem.
+    n = 8 if args.encoding == "amplitude" else 3
+    block = W[:n, :n].copy()
+    nq = 6 if args.encoding == "amplitude" else 9
+    print(f"tensor_roll kernel family on {name}{tuple(block.shape)} "
+          f"(top-left {n}x{n} block, {block.size} elems -> {nq} qubits, "
+          f"{args.encoding} encoding)")
+    t0 = time.perf_counter()
+    payload, r0 = Q.tensor_roll_encode(block, encoding=args.encoding, seed=args.seed)
+    print(_fmt_report("tensor_roll_encode", r0))
+    payload, r1 = Q.tensor_roll_rotate(
+        payload, angles=np.linspace(0.2, 1.0, payload["n"]), seed=args.seed)
+    print(_fmt_report("tensor_roll_rotate", r1))
+    payload, r2 = Q.tensor_roll_entangle(payload, seed=args.seed)
+    print(_fmt_report("tensor_roll_entangle", r2))
+    payload, r3 = Q.tensor_roll_measure(payload, shots=args.shots, seed=args.seed)
+    print(_fmt_report("tensor_roll_measure", r3))
+    rec, r4 = Q.tensor_roll_reconstruct(payload)
+    r4["reconstruction_error"] = C.relative_error(block, rec)
+    print(_fmt_report("tensor_roll_reconstruct", r4))
+    What, summary = Q.tensor_roll_recursive(block, depth=2, shots=args.shots,
+                                            seed=args.seed, encoding=args.encoding)
+    print(_fmt_report("tensor_roll_recursive[summary]", summary))
+    print(f"block rel recon error: {C.relative_error(block, rec):.4f} "
+          f"(recursive: {C.relative_error(block, What):.4f}) "
+          f"in {time.perf_counter()-t0:.2f}s — backend qsim-classical "
+          f"(statevector simulator, NOT a QPU)")
+
+    # Real process/IR boundary artifact: gate trace + measurement counts,
+    # checksummed. This file is what crosses between the CUDA-Q process and
+    # the Q# toolchain (or back); see docs/BOUNDARIES.md. No direct
+    # CUDA-Q<->Q# linkage is claimed — the boundary is serialization.
+    from . import boundary as BD
+    bpath = os.path.join(wdir, "qkernel", "boundary.json")
+    trace = BD.write_trace(bpath, "tensor_roll_recursive",
+                           summary["n_qubits"], args.shots,
+                           summary["counts"], depth=2,
+                           producer="qsim-classical")
+    back = BD.read_trace(bpath)  # verify the round trip immediately
+    amps = BD.counts_to_amplitudes(back)
+    print(f"boundary trace: {bpath} ({trace['n_gates']} gates, "
+          f"{len(trace['counts'])} outcomes, sha256 verified, "
+          f"recon[0]={amps[0]:.4f})")
+
+
+def _fmt_report(kernel: str, r: dict) -> str:
+    ms = r.get("measurement_stats")
+    if ms and r.get("shots"):
+        if "levels" in ms:
+            ms_s = (f"shots={r['shots']} levels={len(ms['levels'])} "
+                    f"active_q={ms['levels'][-1]['active_qubits']}")
+        else:
+            ms_s = (f"shots={r['shots']} outcomes={ms['n_outcomes']} "
+                    f"H={ms['dist_entropy_bits']:.2f}b")
+    else:
+        ms_s = "shots=—"
+    re_ = r.get("reconstruction_error")
+    return (f"  {kernel:32s} backend={r['backend']} device={r['device']} "
+            f"dims={r['tensor_dims']} prec={r['precision']} "
+            f"t={r['exec_time_s']*1000:.2f}ms mem={fmt_bytes(r['memory_bytes'])} "
+            f"depth={r['recursion_depth']} {ms_s} "
+            f"recon_err={'—' if re_ is None else f'{re_:.2e}'}")
+
+
+# ---------------------------------------------------------------------------
+# compress
+# ---------------------------------------------------------------------------
+
+def cmd_doctor(args):
+    from . import doctor as DOC
+    report = DOC.doctor_report()
+    print(DOC.render_doctor(report))
+    integ = report.get("integration", {})
+    if integ:
+        print("Integration:")
+        for k, v in integ.items():
+            print(f"  {k}: {v}")
+    if getattr(args, "json", False):
+        path = os.path.join(wd(args), "doctor_report.json")
+        write_json(path, report)
+        print(f"wrote {path}")
+
+
+def cmd_compress(args):
+    if getattr(args, "out_of_core", False):
+        return cmd_compress_ooc(args)
+    wdir = wd(args)
+    t_params, t_cfg = _teacher(wdir)
+    n_teacher = M.count_params(t_params)
+    budget = n_teacher * args.budget_ratio
+    print(f"teacher {fmt_params(n_teacher)} params, "
+          f"budget ratio {args.budget_ratio} -> {fmt_params(budget)}")
+    t0 = time.perf_counter()
+    s_cfg, scored = S.search_student_config(t_params, t_cfg, budget)
+    rng = np.random.default_rng(args.seed)
+    s_params, provenance, energies = S.init_student_from_teacher(
+        t_params, t_cfg, s_cfg, rng)
+    heads = S.head_consolidation_report(t_params, t_cfg, s_cfg)
+    n_student = M.count_params(s_params)
+    dt = time.perf_counter() - t0
+    ok = n_student <= budget and n_student <= S.ABS_BUDGET_CAP
+    print("architecture search (measured projected energy):")
+    for s in scored[:6]:
+        c = s["cfg"]
+        print(f"  d={c['d']} H={c['heads']} L={c['layers']} dff={c['dff']}: "
+              f"est_energy={s['est_energy']:.4f} params={fmt_params(s['params'])}")
+    print(f"chosen: {s_cfg} -> {fmt_params(n_student)} params "
+          f"({100*n_student/n_teacher:.1f}% of teacher)")
+    print(f"budget check: {fmt_params(n_student)} <= {fmt_params(budget)} "
+          f"and <= 8.5B absolute: {'OK' if ok else 'VIOLATION'}")
+    if not ok:
+        print("FATAL: budget violated — refusing to emit student", file=sys.stderr)
+        sys.exit(4)
+    _save_params(os.path.join(wdir, "student_init.npz"), s_params)
+    write_json(os.path.join(wdir, "student_cfg.json"), s_cfg.to_dict())
+    write_json(os.path.join(wdir, "provenance.json"), provenance)
+    write_json(os.path.join(wdir, "head_report.json"), heads)
+    write_json(os.path.join(wdir, "arch_search.json"),
+               {"budget": budget, "elapsed_s": dt, "scored": scored,
+                "init_energies": energies})
+    print(f"head consolidation: {heads}")
+    print(f"compress done in {dt:.1f}s")
+
+
+def cmd_compress_ooc(args):
+    """Streaming out-of-core compression (F1/F2).
+
+    SCAN reads only weight metadata from --teacher (safetensors headers or
+    a streaming npz repack — never the full model in RAM), PLAN allocates
+    the global budget nonuniformly with measured sensitivity, EXECUTE
+    streams windowed truncated-SVD factors to student shards with
+    per-tensor checkpointing. --resume continues after a crash.
+    """
+    from . import ooc as OOC
+    from . import planner as P
+    wdir = wd(args)
+    teacher_dir = args.teacher or wdir
+    if not os.path.isdir(teacher_dir):
+        print(f"--teacher: not a directory: {teacher_dir}", file=sys.stderr)
+        sys.exit(2)
+    print(f"out-of-core compress: SCAN {teacher_dir} (metadata only)")
+    t0 = time.perf_counter()
+    source = OOC.prepare_teacher_source(
+        teacher_dir, os.path.join(wdir, "ooc_cache"))
+    print(f"  source: {len(source.names())} tensors, "
+          f"{fmt_params(source.total_params)} params, "
+          f"{fmt_bytes(sum(s.nbytes for s in source.specs))}")
+    rows = P.scan_rows(source.specs)
+    # measured sensitivity from small sampled windows (<=4096 elems)
+    reader = source.reader()
+    try:
+        def sample_fn(name):
+            try:
+                mt = reader.read(name)
+            except Exception:
+                return None
+            flat = np.asarray(mt.view).reshape(-1)
+            step = max(1, flat.size // 4096)
+            s = flat[::step][:4096]
+            return s.reshape(64, 64) if s.size == 4096 else s
+        sens = P.calibrate_sensitivity(rows, sample_fn=sample_fn)
+    finally:
+        reader.close()
+    plan = P.plan(rows, target=args.target_params, sensitivity=sens)
+    dt_plan = time.perf_counter() - t0
+    print(f"  PLAN: target {fmt_params(plan['total_target_params'])} "
+          f"(ratio {plan['achieved_ratio']:.4f}), "
+          f"cap {fmt_params(plan['cap'])}: "
+          f"{'OK' if plan['within_cap'] else 'VIOLATION'} "
+          f"[{dt_plan:.1f}s]")
+    if not plan["within_cap"]:
+        print("FATAL: plan exceeds hard budget — refusing", file=sys.stderr)
+        sys.exit(4)
+    out_dir = os.path.join(wdir, "ooc_student")
+    res = OOC.stream_compress(source, plan, args.memory_budget, out_dir,
+                              resume=args.resume)
+    print(f"  EXECUTE: {res['processed_tensors']} tensors, "
+          f"{fmt_params(res['index_total_params'])} student params "
+          f"(ratio {res['compression_ratio']:.4f}), "
+          f"peak workspace {fmt_bytes(res['workspace']['peak_bytes'])} "
+          f"/ {fmt_bytes(res['workspace']['ceiling_bytes'])}, "
+          f"{res['elapsed_s']:.1f}s")
+    print(f"  budget check: {'OK' if res['budget_ok'] else 'VIOLATION'}")
+    energies = [s["retained_energy"]
+                for s in res["tensor_stats"].values()
+                if "retained_energy" in s]
+    mean_e = float(np.mean(energies)) if energies else float("nan")
+    print(f"  mean measured retained energy: {mean_e:.4f}")
+    write_json(os.path.join(wdir, "ooc_plan.json"), plan)
+    write_json(os.path.join(wdir, "ooc_compress_summary.json"),
+               {k: v for k, v in res.items() if k != "tensor_stats"})
+    print(f"  report: {res['report']}")
+
+
+# ---------------------------------------------------------------------------
+# train / finetune
+# ---------------------------------------------------------------------------
+
+STAGES = [
+    (0, "architecture-init", {}),
+    (1, "tensor-reconstruction",
+     {"reconstruction": 3.0, "task": 0.2, "logits": 0.2}),
+    (2, "hidden-state-matching",
+     {"hidden": 2.0, "attention": 2.0, "task": 0.3, "logits": 0.5}),
+    (3, "logit-distillation",
+     {"logits": 3.0, "task": 0.5, "hidden": 0.3, "attention": 0.3}),
+    (4, "language-model", {"task": 2.0, "logits": 0.5}),
+    (5, "instruction-tuning", {"task": 1.0}),   # fresh-seed task data
+    (6, "quantization-aware", {"task": 1.0, "logits": 0.5}),  # sim-int8 noise
+    (7, "regression-evaluation", {}),
+]
+
+
+def _checkpoint(wdir, stage, params, opt, tag):
+    d = ensure_dir(os.path.join(wdir, "checkpoints"))
+    cp = dict(params)
+    if opt is not None:
+        for k in params:
+            cp[f"__m__{k}"] = opt.m[k]
+            cp[f"__v__{k}"] = opt.v[k]
+        cp["__t__"] = np.array(opt.t)
+    _save_params(os.path.join(d, f"stage{stage}_{tag}.npz"), cp)
+
+
+def _restore_opt(params, path):
+    z = np.load(path, allow_pickle=False)
+    opt = M.Adam(params, lr=3e-3)
+    if "__t__" in z.files:
+        for k in params:
+            opt.m[k] = z[f"__m__{k}"]
+            opt.v[k] = z[f"__v__{k}"]
+        opt.t = int(z["__t__"])
+    return opt
+
+
+def cmd_train(args):
+    wdir = wd(args)
+    t_params, t_cfg = _teacher(wdir)
+    s_cfg = M.Config.from_dict(read_json(os.path.join(wdir, "student_cfg.json")))
+    s_params = _load_params(os.path.join(wdir, "student_init.npz"))
+    rng = np.random.default_rng(args.seed)
+    # frozen projections for hidden/embedding matching
+    proj_h = rng.standard_normal((s_cfg.d, t_cfg.d)).astype(np.float32)
+    proj_e = rng.standard_normal((s_cfg.d, t_cfg.d)).astype(np.float32)
+    recon_targets = {k: v.astype(np.float64) for k, v in s_params.items()}
+    plan = read_json(os.path.join(wdir, "roll_plan.json"))["leaves"] \
+        if os.path.exists(os.path.join(wdir, "roll_plan.json")) else {}
+    plan_e = {k: v["retained_energy"] for k, v in plan.items()
+              if isinstance(v, dict) and "retained_energy" in v}
+    achiev = read_json(os.path.join(wdir, "arch_search.json"))["init_energies"]
+    opt = M.Adam(s_params, lr=args.lr)
+    history = []
+    _checkpoint(wdir, 0, s_params, opt, "init")
+    stages = STAGES if args.stage == "all" else [
+        s for s in STAGES if str(s[0]) == args.stage]
+    for num, name, lam in stages:
+        if num == 0:
+            # architecture-init: checkpoint the searched init, no training
+            _checkpoint(wdir, 0, s_params, opt, "init")
+            history.append({"stage": 0, "name": name, "note":
+                            "init checkpoint only (no training)"})
+            print(f"stage 0 {name}: init checkpointed "
+                  f"({fmt_params(M.count_params(s_params))} params)")
+            continue
+        if num == 7:
+            ev = M.eval_metrics(s_params, s_cfg)
+            t_ev = M.eval_metrics(t_params, t_cfg)
+            print(f"stage 7 regression-eval: student loss={ev['loss']:.4f} "
+                  f"acc={ev['accuracy']:.3f} | teacher loss={t_ev['loss']:.4f} "
+                  f"acc={t_ev['accuracy']:.3f}")
+            history.append({"stage": 7, "name": name, "eval": ev,
+                            "teacher_eval": t_ev})
+            continue
+        steps = args.steps if num not in (1,) else max(20, args.steps // 2)
+        t0 = time.perf_counter()
+        for step in range(1, steps + 1):
+            ids = M.gen_data(rng, args.batch, s_cfg)
+            if num == 6:  # quantization-aware: straight-through sim-int8 noise
+                noisy = {k: QT.dequantize_int8(
+                    *QT.quantize_int8(v)).astype(np.float32)
+                    if v.ndim == 2 and v.size > 64 else v
+                    for k, v in s_params.items()}
+                fwd_params = noisy
+            else:
+                fwd_params = s_params
+            # forward with fwd_params, grads applied to s_params (STE for QAT)
+            total, terms, grads = D.distill_step(
+                fwd_params, s_cfg, t_params, t_cfg, ids,
+                lambdas=lam, proj_h=proj_h, proj_e=proj_e,
+                recon_targets=recon_targets,
+                roll_plan_energies=plan_e or None,
+                achieved_energies=achiev or None)
+            # grads keys match s_params; apply to the clean params
+            opt.step(s_params, {k: grads[k] for k in s_params})
+            if step % max(1, steps // 4) == 0 or step == steps:
+                history.append({"stage": num, "name": name, "step": step,
+                                **{k: round(float(v), 5) for k, v in terms.items()}})
+        _checkpoint(wdir, num, s_params, opt, name)
+        print(f"stage {num} {name}: {steps} steps, "
+              f"total_loss={history[-1]['total']:.4f} "
+              f"({time.perf_counter()-t0:.1f}s)")
+    _save_params(os.path.join(wdir, "student_distilled.npz"), s_params)
+    write_json(os.path.join(wdir, "distill_history.json"), history)
+    print("distillation complete; checkpoints in checkpoints/")
+
+
+def cmd_finetune(args):
+    wdir = wd(args)
+    s_cfg = M.Config.from_dict(read_json(os.path.join(wdir, "student_cfg.json")))
+    s_params = _load_params(_need(os.path.join(wdir, "student_distilled.npz"),
+                                  "distilled student (run train first)"))
+    rng = np.random.default_rng(args.seed)
+    opt = _restore_opt(s_params, os.path.join(
+        wdir, "checkpoints", sorted(os.listdir(os.path.join(wdir, "checkpoints")))[-1]))
+    t0 = time.perf_counter()
+    for step in range(1, args.steps + 1):
+        ids = M.gen_data(rng, args.batch, s_cfg)
+        logits, cache = M.forward(s_params, s_cfg, ids[:, :-1])
+        loss, dl = M.ce_loss(logits, ids[:, 1:])
+        grads = M.backward(s_params, s_cfg, cache, dl)
+        opt.step(s_params, grads)
+    dt = time.perf_counter() - t0
+    _save_params(os.path.join(wdir, "student_final.npz"), s_params)
+    ev = M.eval_metrics(s_params, s_cfg)
+    print(f"finetune: {args.steps} steps task-CE in {dt:.1f}s -> "
+          f"loss={ev['loss']:.4f} acc={ev['accuracy']:.3f}")
+    write_json(os.path.join(wdir, "finetune.json"),
+               {"steps": args.steps, "elapsed_s": dt, "eval": ev})
+
+# ---------------------------------------------------------------------------
+# quantize
+# ---------------------------------------------------------------------------
+
+def cmd_quantize(args):
+    wdir = wd(args)
+    s_cfg = M.Config.from_dict(read_json(os.path.join(wdir, "student_cfg.json")))
+    s_params = _load_params(_need(os.path.join(wdir, "student_final.npz"),
+                                  "final student (run finetune first)"))
+    tdir = ensure_dir(os.path.join(wdir, "trq"))
+    prov = read_json(os.path.join(wdir, "teacher_provenance.json"))
+    roll_meta = {}
+    if os.path.exists(os.path.join(wdir, "roll_plan.json")):
+        rp = read_json(os.path.join(wdir, "roll_plan.json"))
+        for k, v in rp["leaves"].items():
+            if isinstance(v, dict):
+                roll_meta[k] = {"decision": v.get("decision"),
+                                "retained_energy": v.get("retained_energy")}
+    manifest = []
+    for fmt in FORMATS:
+        tensors = {}
+        max_recon = 0.0
+        for k, v in s_params.items():
+            q, qmeta = QT.quantize_tensor(v, fmt)
+            back = QT.dequantize_tensor(
+                q, {"fmt": fmt, **qmeta} if fmt != "int4" else qmeta)
+            max_recon = max(max_recon, C.relative_error(
+                v.astype(np.float64), back.astype(np.float64)))
+            tensors[k] = (np.ascontiguousarray(q), fmt, qmeta)
+        path = os.path.join(tdir, f"student_{fmt}.trq")
+        info = T.write_trq(path, arch={"name": "tensor-roll-student",
+                                       "config": s_cfg.to_dict(),
+                                       "format": fmt},
+                           tensors=tensors, provenance=prov,
+                           roll_meta=roll_meta)
+        # verify round-trip + checksums immediately
+        _h, back_tensors = T.read_trq(path)
+        total, ok = T.param_budget_ok(back_tensors)
+        manifest.append({"format": fmt, "path": path,
+                         "bytes": info["bytes"], "sha256": info["sha256"],
+                         "params": total, "budget_ok": ok,
+                         "max_weight_recon_err": max_recon})
+        print(f"student_{fmt}.trq: {fmt_bytes(info['bytes'])} "
+              f"params={fmt_params(total)} budget_ok={ok} "
+              f"max_recon_err={max_recon:.2e} sha256={info['sha256'][:16]}… "
+              f"[round-trip verified]")
+    write_json(os.path.join(wdir, "quantize_manifest.json"), manifest)
+
+
+# ---------------------------------------------------------------------------
+# evaluate
+# ---------------------------------------------------------------------------
+
+def cmd_evaluate(args):
+    wdir = wd(args)
+    t_params, t_cfg = _teacher(wdir)
+    results = {}
+    for fmt in FORMATS:
+        s_params, s_cfg = _student(wdir, variant=fmt)
+        ev = M.eval_metrics(s_params, s_cfg, seed=4242)
+        # teacher divergence on shared batches
+        rng = np.random.default_rng(4242)
+        kls = []
+        for _ in range(4):
+            ids = M.gen_data(rng, 128, s_cfg)
+            tl, _ = M.forward(t_params, t_cfg, ids[:, :-1])
+            sl, _ = M.forward(s_params, s_cfg, ids[:, :-1])
+            kls.append(M.kl_divergence_mean(tl, sl))
+        results[fmt] = {"held_out": ev,
+                        "teacher_kl_div": float(np.mean(kls))}
+        print(f"{fmt:6s} loss={ev['loss']:.4f} acc={ev['accuracy']:.3f} "
+              f"teacher_KL={results[fmt]['teacher_kl_div']:.4f}")
+    s_params, s_cfg = _student(wdir, "fp32")
+    rec = D.recursive_metrics(t_params, s_params)
+    results["recursive_distillation"] = rec
+    write_json(os.path.join(wdir, "eval.json"), results)
+    print("recursive distillation metrics (sample):")
+    for lvl in ("model", "layer_group_0", "subblock:L0.Wq[0]"):
+        if lvl in rec:
+            m = rec[lvl]
+            print(f"  {lvl:28s} rel_err={m['rel_err']:.3f} "
+                  f"cos={m['cosine_sim']:.4f} KL={m['kl_div']:.4f} "
+                  f"E_ret={m['retained_energy']:.4f}")
+
+
+# ---------------------------------------------------------------------------
+# benchmark
+# ---------------------------------------------------------------------------
+
+def cmd_benchmark(args):
+    wdir = wd(args)
+    rows = []
+    try:
+        t_params, t_cfg = _teacher(wdir)
+        rows.append(_bench_row("glimmer-tiny-teacher (fp32)", t_params, t_cfg,
+                               wdir))
+    except SystemExit:
+        pass
+    for fmt in FORMATS:
+        try:
+            s_params, s_cfg = _student(wdir, variant=fmt)
+            label = f"tensor-roll-student ({fmt}/trq)"
+            rows.append(_bench_row(label, s_params, s_cfg, wdir,
+                                   trq_path=os.path.join(
+                                       wdir, "trq", f"student_{fmt}.trq")))
+        except SystemExit:
+            rows.append(_unavailable_row(f"tensor-roll-student ({fmt})",
+                                         "artifact not built"))
+    # 30B / CUDA rows: honestly unavailable here
+    rows.append(_unavailable_row("glimmer-30b (fp16)", "no GPU / 7GB RAM"))
+    rows.append(_unavailable_row("tensor-roll-8b (cuda)", "no CUDA device"))
+    rows.append(_unavailable_row("tensor-roll-8b (cuda-q qpu)",
+                                 "no QPU / no CUDA-Q toolchain"))
+    hdr = (f"{'artifact':36s} {'params':>8s} {'size':>9s} {'load_s':>7s} "
+           f"{'tok/s':>7s} {'ppl':>7s} {'acc':>6s} {'tch_KL':>7s} {'backend':>12s}")
+    print(hdr)
+    print("-" * len(hdr))
+    for r in rows:
+        print(f"{r['artifact']:36s} {r['params']:>8s} {r['size']:>9s} "
+              f"{r['load_s']:>7s} {r['tok_s']:>7s} {r['ppl']:>7s} "
+              f"{r['acc']:>6s} {r['kl']:>7s} {r['backend']:>12s}")
+    write_json(os.path.join(wdir, "benchmark.json"), rows)
+    print("\n'unavailable' = not executed here; no number was invented.")
+
+
+def _bench_row(label, params, cfg, wdir, trq_path=None):
+    n = M.count_params(params)
+    size = os.path.getsize(trq_path) if trq_path else sum(
+        v.nbytes for v in params.values())
+    t0 = time.perf_counter()
+    if trq_path:
+        T.read_trq(trq_path)
+    load_s = time.perf_counter() - t0
+    rng = np.random.default_rng(7)
+    ids = M.gen_data(rng, 64, cfg)
+    t0 = time.perf_counter()
+    logits, _ = M.forward(params, cfg, ids[:, :-1])
+    fwd_s = time.perf_counter() - t0
+    loss, _ = M.ce_loss(logits, ids[:, 1:])
+    toks, tps, _ = M.generate(params, cfg, ids[0, :4].tolist(), 16)
+    acc = M.eval_metrics(params, cfg, batches=2)["accuracy"]
+    return {"artifact": label, "params": fmt_params(n),
+            "size": fmt_bytes(size), "load_s": f"{load_s:.3f}",
+            "tok_s": f"{tps:.1f}", "ppl": f"{np.exp(loss):.2f}",
+            "acc": f"{acc:.3f}", "kl": "see-eval",
+            "backend": C.CLASSICAL_BACKEND,
+            "_note": f"forward {fwd_s*1000:.1f}ms/64tok"}
+
+
+def _unavailable_row(label, reason):
+    u = "unavailable"
+    return {"artifact": label, "params": u, "size": u, "load_s": u,
+            "tok_s": u, "ppl": u, "acc": u, "kl": u, "backend": u,
+            "_note": reason}
+
+
+# ---------------------------------------------------------------------------
+# chat
+# ---------------------------------------------------------------------------
+
+def _detokenize(ids, cfg):
+    # demo tokenizer: ids <-> printable chars (documented as demo-only)
+    return "".join(chr(33 + (i % 94)) for i in ids)
+
+
+def _tokenize(text, cfg):
+    return [ord(c) % cfg.vocab for c in text[:cfg.seq]] or [0]
+
+
+def cmd_chat(args):
+    wdir = wd(args)
+    s_params, s_cfg = _student(wdir, variant=args.variant)
+    sup = SB.SandboxSupervisor(os.path.join(wdir, "sandbox"))
+    print(f"tensor-roll chat [{args.variant}] — type text, `!cmd` runs sandboxed, "
+          f"`quit` exits")
+    if args.compare:
+        t_params, t_cfg = _teacher(wdir)
+    while True:
+        try:
+            line = input("tensor> ").strip()
+        except EOFError:
+            break
+        if line in ("quit", "exit"):
+            break
+        if line.startswith("!"):
+            rec = sup.run(line[1:])
+            print(f"[sandbox {'ALLOW' if rec['allowed'] else 'DENY'}] "
+                  f"{rec.get('reason', '')}")
+            if rec["allowed"]:
+                print(rec.get("stdout", ""), end="")
+            continue
+        if not line:
+            continue
+        prompt = _tokenize(line, s_cfg)
+        toks, tps, dt = M.generate(s_params, s_cfg, prompt, args.max_tokens)
+        print(f"[student] {_detokenize(toks, s_cfg)} "
+              f"({tps:.1f} tok/s, {C.CLASSICAL_BACKEND})")
+        if args.compare:
+            tt, ttps, _ = M.generate(t_params, t_cfg, prompt, args.max_tokens)
+            print(f"[teacher] {_detokenize(tt, t_cfg)} ({ttps:.1f} tok/s)")
+
+
+# ---------------------------------------------------------------------------
+# sandbox
+# ---------------------------------------------------------------------------
+
+def cmd_sandbox(args):
+    wdir = wd(args)
+    sup = SB.SandboxSupervisor(os.path.join(wdir, "sandbox"))
+    print(f"jail: {sup.jail}  netns_available={sup.netns_available}")
+    if args.demo:
+        for label, rec in sup.demo():
+            mark = "ALLOW" if rec["allowed"] else "DENY"
+            print(f"[{mark}] {label}: {rec['reason']}")
+            if rec["allowed"] and rec.get("stdout"):
+                print(f"       out: {rec['stdout'].strip()}")
+        print(f"audit log: {sup.audit.path}")
+        return
+    rec = sup.run(args.sandbox_cmd)
+    print(f"[{'ALLOW' if rec['allowed'] else 'DENY'}] {rec['reason']}")
+    if rec["allowed"]:
+        print(rec.get("stdout", ""), end="")
+        if rec.get("stderr"):
+            print(rec["stderr"], end="", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# demo
+# ---------------------------------------------------------------------------
+
+def cmd_demo(args):
+    wdir = wd(args)
+    F = args.fast
+    steps_t = 250 if F else 600
+    steps_d = 40 if F else 120
+    steps_f = 40 if F else 150
+
+    print("=" * 64)
+    print("Tensor Roll")
+    print("Recursive CUDA-Q Model Runtime")
+    print("GLIMMER 30B -> TENSOR ROLL -> CUDA -> CUDA-Q -> Q# -> 8B NANO MODEL")
+    print("-" * 64)
+    print("TARGET (not executed here): Glimmer 30B teacher -> ~8B student,")
+    print("  hard budget P <= 8.5B. Requires: 30B-param HW (see docs/).")
+    print("THIS RUN (executed now): tiny from-scratch validation teacher")
+    print("  trained by the same code path at small scale; every number")
+    print("  below was measured on this machine (no GPU: cpu-numpy).")
+    print(f"Quantum       CUDA-Q kernels + Q# ops ship in-repo; here the")
+    print(f"              qsim-classical statevector simulator executes")
+    print(f"Sandbox       ACTIVE")
+    print("=" * 64)
+
+    # 1. ingest
+    print("\n[1/9] ingest — training tiny teacher (same code path as 30B)")
+    a = argparse.Namespace(workdir=args.workdir, scale="tiny", steps=steps_t,
+                           batch=128, lr=3e-3, seed=11)
+    cmd_ingest(a)
+    t_params, t_cfg = _teacher(wdir)
+
+    # 2. roll
+    print("\n[2/9] roll — TensorRoll operator over teacher tensors")
+    a = argparse.Namespace(workdir=args.workdir, depth=2,
+                           quantum_policy="explore", budget_ratio=S.BUDGET_RATIO)
+    cmd_roll(a)
+
+    # 3. qkernel demo on a real block
+    print("\n[3/9] qkernel — tensor_roll kernel family (qsim-classical)")
+    a = argparse.Namespace(workdir=args.workdir, tensor=None, shots=1024,
+                           encoding="amplitude", seed=0)
+    cmd_qkernel(a)
+
+    # 4. compress
+    print("\n[4/9] compress — representation search under hard budget")
+    a = argparse.Namespace(workdir=args.workdir, budget_ratio=S.BUDGET_RATIO,
+                           seed=11)
+    cmd_compress(a)
+
+    # 5. train (distill, subset of stages for demo time)
+    print("\n[5/9] train — recursive distillation")
+    a = argparse.Namespace(workdir=args.workdir, steps=steps_d, batch=128,
+                           lr=3e-3, seed=12, stage="all")
+    cmd_train(a)
+
+    # 6. finetune
+    print("\n[6/9] finetune — task fine-tuning")
+    a = argparse.Namespace(workdir=args.workdir, steps=steps_f, batch=128,
+                           seed=13)
+    cmd_finetune(a)
+
+    # 7. quantize + trq
+    print("\n[7/9] quantize — FP16/BF16/INT8/INT4 + .trq export")
+    a = argparse.Namespace(workdir=args.workdir)
+    cmd_quantize(a)
+
+    # 8. evaluate + benchmark
+    print("\n[8/9] evaluate + benchmark (measured only)")
+    a = argparse.Namespace(workdir=args.workdir)
+    cmd_evaluate(a)
+    print()
+    cmd_benchmark(a)
+
+    # 9. sandbox + live inference
+    print("\n[9/9] sandbox + live inference")
+    a = argparse.Namespace(workdir=args.workdir, demo=True, sandbox_cmd=None)
+    cmd_sandbox(a)
+    s_params, s_cfg = _student(wdir, "int4")
+    t_params, t_cfg = _teacher(wdir)
+    print(f"\nthis run: teacher={fmt_params(M.count_params(t_params))} params, "
+          f"student={fmt_params(M.count_params(s_params))} params "
+          f"({M.count_params(s_params)/M.count_params(t_params):.1%} of teacher; "
+          f"target ratio {S.BUDGET_RATIO:.4f})")
+    rng = np.random.default_rng(99)
+    ids = M.gen_data(rng, 1, s_cfg)
+    print("\ninference (int4 student, streaming, tensor> prompt):")
+    print(f"  tensor> generate {ids[0, :4].tolist()}")
+    print("  ", end="", flush=True)
+
+    def _emit(tok):
+        print(tok, end=" ", flush=True)
+
+    toks, tps, dt = M.generate_stream(s_params, s_cfg, ids[0, :4].tolist(),
+                                      24, on_token=_emit)
+    print()
+    print(f"  {tps:.1f} tok/s, {fmt_bytes(sum(v.nbytes for v in s_params.values()))} "
+          f"weights, backend={C.CLASSICAL_BACKEND}, rss={rss_mb():.0f}MB")
+    tt, _, _ = M.generate(t_params, t_cfg, ids[0, :4].tolist(), 24)
+    agree = sum(a == b for a, b in zip(toks, tt))
+    print(f"  teacher/student token agreement: {agree}/24")
+
+    # 10. failure-resolution status board (all values measured below)
+    print("\n[10/9] failure-resolution status — measured, not claimed")
+    _demo_status_board(wdir)
+
+    print("\nDemo complete. Every number above was measured on this machine.")
+
+
+def _demo_status_board(wdir):
+    import glob
+    import importlib.util
+    import unittest
+    import resource
+    # test count: load test modules by file path (fast) without executing
+    repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    n_tests = 0
+    for tf in sorted(glob.glob(os.path.join(repo_root, "tests",
+                                             "test_*.py"))):
+        spec = importlib.util.spec_from_file_location(
+            "tr_test_count_mod", tf)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        n_tests += unittest.TestLoader().loadTestsFromModule(mod) \
+            .countTestCases()
+    print(f"  tests discovered: {n_tests} "
+          f"(full suite: python -m unittest discover -s tests)")
+    # validation teacher/student + measured compression
+    t_params, t_cfg = _teacher(wdir)
+    s_params, s_cfg = _student(wdir, "int4")
+    nt, ns = M.count_params(t_params), M.count_params(s_params)
+    print(f"  validation teacher: {fmt_params(nt)} params "
+          f"(acc={read_json(os.path.join(wdir, 'teacher_eval.json'))['accuracy']:.3f}); "
+          f"student(int4): {fmt_params(ns)} params")
+    print(f"  measured compression: {ns/nt:.4f} "
+          f"(target ratio {S.BUDGET_RATIO:.4f})")
+    # measured INT8/INT4 perplexity from evaluate
+    evp = os.path.join(wdir, "eval.json")
+    if os.path.exists(evp):
+        ev = read_json(evp)
+        ppls = []
+        for fmt in ("int8", "int4"):
+            if fmt in ev:
+                ppls.append(f"{fmt} PPL={np.exp(ev[fmt]['held_out']['loss']):.2f}")
+        if ppls:
+            print(f"  measured perplexity: {', '.join(ppls)}")
+    # backend availability: live probes, never claimed
+    from . import doctor as DOC
+    caps = DOC.probe_capabilities()
+    for b in ("CUDA", "CUDA-Q", "Q#"):
+        state = caps[b]["state"]
+        why = caps[b].get("reason", "")
+        print(f"  {b} execution: {state}" + (f" ({why})" if why else ""))
+    # virtual 30B structural scale test — planned, never "validated"
+    from . import ooc as OOC
+    from . import planner as P
+    man = OOC.glimmer30b_manifest()
+    rows = P.scan_rows(man.specs)
+    t0 = time.perf_counter()
+    plan = P.plan(rows)
+    dt = time.perf_counter() - t0
+    peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024
+    print(f"  30B STRUCTURAL SCALE TEST: virtual "
+          f"{fmt_params(man.total_params)} manifest ({len(rows)} tensors) "
+          f"-> planned {fmt_params(plan['total_target_params'])} "
+          f"(cap {fmt_params(plan['cap'])}: "
+          f"{'OK' if plan['within_cap'] else 'VIOLATION'}) "
+          f"in {dt:.2f}s, peak RSS {peak:.0f}MB, zero weights allocated")
+    print("  actual 30B weights: NOT TESTED "
+          "(no 30B checkpoint on this machine)")
+    print(f"  current measured token agreement: see inference above")
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="tensor-roll",
+        description="Tensor Roll — Recursive CUDA-Q Model Quantizer")
+    p.add_argument("--workdir", default=DEFAULT_WORKDIR,
+                   help="pipeline working directory")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("inspect", help="tensor inventory + metrics")
+    a.add_argument("--what", choices=["teacher", "student", "trq"],
+                   default="teacher")
+    a.add_argument("--trq", default=None)
+
+    a = sub.add_parser("ingest", help="build/load the teacher model")
+    a.add_argument("--scale", choices=["tiny", "30b"], default="tiny")
+    a.add_argument("--steps", type=int, default=600)
+    a.add_argument("--batch", type=int, default=128)
+    a.add_argument("--lr", type=float, default=3e-3)
+    a.add_argument("--seed", type=int, default=11)
+
+    sub.add_parser("map", help="per-tensor metric map")
+
+    a = sub.add_parser("roll", help="run the TensorRoll operator")
+    a.add_argument("--depth", type=int, default=3)
+    a.add_argument("--quantum-policy", choices=["off", "explore", "selective"],
+                   default="off")
+    a.add_argument("--budget-ratio", type=float, default=S.BUDGET_RATIO)
+
+    a = sub.add_parser("qkernel", help="run the tensor_roll kernel family")
+    a.add_argument("--tensor", default=None)
+    a.add_argument("--shots", type=int, default=1024)
+    a.add_argument("--encoding", choices=["amplitude", "angle"],
+                   default="amplitude")
+    a.add_argument("--seed", type=int, default=0)
+
+    a = sub.add_parser("compress", help="search the 8B representation")
+    a.add_argument("--budget-ratio", type=float, default=S.BUDGET_RATIO)
+    a.add_argument("--seed", type=int, default=11)
+    a.add_argument("--teacher", default=None,
+                   help="teacher weight dir (.safetensors/.npz); "
+                        "default: workdir (in-RAM path's teacher.npz)")
+    a.add_argument("--target-params", type=float, default=8.0e9,
+                   help="global student budget (default 8B, cap 8.5B)")
+    a.add_argument("--memory-budget", default="512MB",
+                   help="streaming working-set ceiling, e.g. 512MB, 5G")
+    a.add_argument("--out-of-core", action="store_true",
+                   help="streaming SCAN/PLAN/EXECUTE; never holds the "
+                        "teacher in RAM")
+    a.add_argument("--resume", action="store_true",
+                   help="resume from the per-tensor checkpoint")
+
+    a = sub.add_parser("train", help="recursive distillation stages")
+    a.add_argument("--stage", default="all",
+                   help="'all' or a stage number 0-7")
+    a.add_argument("--steps", type=int, default=120)
+    a.add_argument("--batch", type=int, default=128)
+    a.add_argument("--lr", type=float, default=3e-3)
+    a.add_argument("--seed", type=int, default=12)
+
+    a = sub.add_parser("finetune", help="task fine-tuning")
+    a.add_argument("--steps", type=int, default=150)
+    a.add_argument("--batch", type=int, default=128)
+    a.add_argument("--seed", type=int, default=13)
+
+    sub.add_parser("quantize", help="FP16/BF16/INT8/INT4 + .trq export")
+    sub.add_parser("evaluate", help="measured quality metrics")
+    sub.add_parser("benchmark", help="measured comparison table")
+
+    a = sub.add_parser("chat", help="terminal inference REPL")
+    a.add_argument("--variant", choices=FORMATS, default="fp32")
+    a.add_argument("--compare", action="store_true")
+    a.add_argument("--max-tokens", type=int, default=24)
+
+    a = sub.add_parser("sandbox", help="OS-level sandbox supervisor")
+    g = a.add_mutually_exclusive_group(required=True)
+    g.add_argument("--cmd", dest="sandbox_cmd", default=None,
+                   help="command to run sandboxed")
+    g.add_argument("--demo", action="store_true",
+                   help="allow/deny demonstration")
+
+    a = sub.add_parser("doctor", help="backend capability matrix (honest)")
+    a.add_argument("--json", action="store_true",
+                   help="also write doctor_report.json to the workdir")
+
+    a = sub.add_parser("demo", help="full executable demonstration")
+    a.add_argument("--fast", action="store_true",
+                   help="reduced training steps (still real training)")
+
+    return p
+
+
+def main():
+    args = build_parser().parse_args()
+    cmds = {
+        "inspect": cmd_inspect, "ingest": cmd_ingest, "map": cmd_map,
+        "roll": cmd_roll, "qkernel": cmd_qkernel, "compress": cmd_compress,
+        "train": cmd_train, "finetune": cmd_finetune,
+        "quantize": cmd_quantize, "evaluate": cmd_evaluate,
+        "benchmark": cmd_benchmark, "chat": cmd_chat,
+        "sandbox": cmd_sandbox, "demo": cmd_demo, "doctor": cmd_doctor,
+    }
+    cmds[args.cmd](args)
+
+
+if __name__ == "__main__":
+    main()

tensor_roll/conformance.py

@@ -0,0 +1,389 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Backend conformance contract for tensor-roll.
+
+For each backend in [numpy, cuda, cuda-q, qsharp] this module either
+EXECUTES a fixed test vector and compares against a precomputed expected
+output, or records NOT EXECUTED with the probe reason. It never invents
+numbers for a backend it cannot run.
+
+Comparison semantics:
+  * Classical backends (numpy): EXACT floating-point equality. The test
+    vectors are fixed literals (inputs and expected outputs below were
+    generated once by the NumPy path with numpy 1.26.4 and hard-coded, so
+    conformance never depends on regenerating them). Re-executing A@B in
+    the same process/BLAS is bit-identical, so ``match`` is a strict
+    equality check.
+  * Quantum measurement (cuda-q, if a toolchain is ever present): exact
+    equality is MEANINGLESS for sampled counts. Comparison is
+    distributional — chi-square goodness-of-fit of the sampled counts
+    against the exact Born distribution computed by an independent
+    classical statevector re-implementation of the same circuit, plus
+    top-outcome agreement. Both are computed for real when executed.
+    Bit-ordering assumption: cudaq.sample is assumed to print qubit n-1
+    leftmost (matching qsim._measure_counts); the raw counts are preserved
+    in the record so the comparison can be re-done if a real toolchain
+    disagrees.
+
+``run_conformance(workdir)`` writes machine-readable JSON to
+``<workdir>/conformance.json``: per backend {state, reason, outputs (when
+executed), expected, match (bool or null), measured fields}.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import math
+import os
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from . import qsim as _qsim
+from . import quant as QT
+from .doctor import cudaq_toolchain, qsharp_toolchain, verify_sources
+from .util import utc_now_iso, write_json
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# ---------------------------------------------------------------------------
+# Fixed test vectors. Inputs AND expected outputs were generated once by the
+# NumPy path (numpy 1.26.4) and hard-coded here; conformance re-executes the
+# inputs and demands exact equality with these literals.
+# ---------------------------------------------------------------------------
+
+_VEC_MATMUL_A = [
+    [0.3502483584951709, 0.7847217336600212, 0.514335740326966,
+     0.08997722942380026],
+    [0.000875639493777336, 0.5394009336088772, 0.3630734994591833,
+     0.6561419338727186],
+    [0.6857523669661448, 0.28778351696528304, 0.31958621893475014,
+     0.5151307753113961],
+    [0.6711942461900504, 0.18942041616006677, 0.8017567034768246,
+     0.29579706764196234],
+]
+_VEC_MATMUL_B = [
+    [0.2863552420503723, 0.9336882487158795, 0.8979195228933917,
+     0.3228591430362756],
+    [0.4453653183959694, 0.20672814313855958, 0.14869990691155455,
+     0.06988183293319483],
+    [0.7603953595694858, 0.9773212481372078, 0.5499040814050973,
+     0.18811956769502203],
+    [0.4823260186818574, 0.922115503183646, 0.22132889167532976,
+     0.2948266793901039],
+]
+_EXPECT_MATMUL_C = [
+    [0.8842801672837294, 1.0748874892220983, 0.7339327709835938,
+     0.29120298285643825],
+    [0.8330349433254504, 1.0722050228875455, 0.42587388862051745,
+     0.29972641147510964],
+    [0.8160104365083471, 1.4871203551119165, 0.9482989100732389,
+     0.4535069784712827],
+    [1.0288839735854158, 1.7221776351919256, 1.1372029362357199,
+     0.4679732366928886],
+]
+
+_VEC_QUANT_X = [0.0, 0.5, -0.5, 1.0, -1.0, 0.25, -0.75, 2.0]
+_EXPECT_QUANT_CODES = [-43, 0, -86, 42, -128, -22, -107, 127]
+_EXPECT_QUANT_SCALE = 0.011764705882352941
+_EXPECT_QUANT_ZERO = -1.0
+
+_VEC_ENCODE_BLOCK = [0.1, 0.4, 0.2, 0.8, -0.3, 0.6, -0.1, 0.5]
+# Amplitude-encoding magnitudes: x / ||x|| (signs are stored classically
+# in the hybrid encoding; see qsim.tensor_roll_encode).
+_EXPECT_ENCODE_AMPS = [
+    0.08006407690254357, 0.32025630761017426, 0.16012815380508713,
+    0.6405126152203485, -0.24019223070763068, 0.48038446141526137,
+    -0.08006407690254357, 0.40032038451271784,
+]
+
+
+def test_vectors() -> Dict[str, Any]:
+    """The fixed deterministic input vectors (no expected values)."""
+    return {
+        "matmul": {"A": [row[:] for row in _VEC_MATMUL_A],
+                   "B": [row[:] for row in _VEC_MATMUL_B]},
+        "quantize": {"x": list(_VEC_QUANT_X)},
+        "encode": {"block": list(_VEC_ENCODE_BLOCK)},
+    }
+
+
+def expected_outputs() -> Dict[str, Any]:
+    """The hard-coded expected outputs for the test vectors."""
+    return {
+        "matmul": {"C": [row[:] for row in _EXPECT_MATMUL_C]},
+        "quantize": {"codes": list(_EXPECT_QUANT_CODES),
+                     "scale": _EXPECT_QUANT_SCALE,
+                     "zero": _EXPECT_QUANT_ZERO},
+        "encode": {"amplitudes": list(_EXPECT_ENCODE_AMPS)},
+    }
+
+
+# ---------------------------------------------------------------------------
+# numpy backend: executes for real, exact comparison
+# ---------------------------------------------------------------------------
+
+def _run_numpy(vecs: Dict[str, Any]) -> Dict[str, Any]:
+    t0 = time.perf_counter()
+    A = np.array(vecs["matmul"]["A"])
+    B = np.array(vecs["matmul"]["B"])
+    C = A @ B
+    matmul_ms = (time.perf_counter() - t0) * 1000.0
+
+    x = np.array(vecs["quantize"]["x"])
+    q, meta = QT.quantize_int8(x)
+
+    blk = np.array(vecs["encode"]["block"])
+    amps = blk / np.linalg.norm(blk)
+
+    exp = expected_outputs()
+    outputs = {
+        "matmul": {"C": C.tolist()},
+        "quantize": {"codes": [int(v) for v in q.ravel()],
+                     "scale": meta["scale"], "zero": meta["zero"]},
+        "encode": {"amplitudes": amps.tolist()},
+    }
+    checks = {
+        "matmul_exact": outputs["matmul"]["C"] == exp["matmul"]["C"],
+        "quantize_exact": (
+            outputs["quantize"]["codes"] == exp["quantize"]["codes"]
+            and outputs["quantize"]["scale"] == exp["quantize"]["scale"]
+            and outputs["quantize"]["zero"] == exp["quantize"]["zero"]),
+        "encode_exact": (outputs["encode"]["amplitudes"]
+                         == exp["encode"]["amplitudes"]),
+    }
+    return {
+        "backend": "numpy",
+        "state": "EXECUTED",
+        "reason": None,
+        "outputs": outputs,
+        "expected": exp,
+        "match": all(checks.values()),
+        "checks": checks,
+        "measured": {"matmul_ms": round(matmul_ms, 3),
+                     "numpy_version": np.__version__,
+                     "comparison": "exact fp equality"},
+    }
+
+
+# ---------------------------------------------------------------------------
+# cuda backend: probe only
+# ---------------------------------------------------------------------------
+
+def _run_cuda() -> Dict[str, Any]:
+    src = verify_sources()["CUDA source"]
+    return {
+        "backend": "cuda",
+        "state": "NOT EXECUTED",
+        "reason": ("probe only: no CUDA device on this machine (nvidia-smi "
+                   "absent, no /dev/nvidia*); cuda/tensor_roll_gemm.cu was "
+                   "not compiled and no measurement was taken"),
+        "outputs": None,
+        "expected": None,
+        "match": None,
+        "source": src["state"],
+        "measured": {},
+    }
+
+
+# ---------------------------------------------------------------------------
+# cuda-q backend: run run_smoke for real if the toolchain exists
+# ---------------------------------------------------------------------------
+
+def _load_kernels_module():
+    path = os.path.join(REPO_ROOT, "cudaq", "tensor_roll_kernels.py")
+    spec = importlib.util.spec_from_file_location(
+        "tensor_roll_cudaq_kernels", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _smoke_reference_distribution() -> Dict[str, float]:
+    """Exact Born distribution of cudaq/tensor_roll_kernels.py::run_smoke's
+    circuit (n_qubits=4, depth=2), via branch enumeration of the single
+    mid-circuit measurement, using qsim's own unitary primitives.
+
+    Circuit replicated exactly:
+      encode:  RY(2*a[i]) on qubit i,  a[i] = 2*atan(0.1*(i+1))
+      level 0: RY(a[q]) q=0..3; CNOT ladder q=0..2; measure+reset qubit 3
+      level 1: RY(a[q]) q=0..2; CNOT ladder q=0..1
+      final:   measure all
+    """
+    n = 4
+    angles = [2.0 * math.atan(0.1 * (i + 1)) for i in range(n)]
+
+    def branch_final(sv: np.ndarray) -> Dict[str, float]:
+        probs: Dict[str, float] = {}
+        for d, amp in enumerate(sv):
+            p = float(abs(amp) ** 2)
+            if p > 0:
+                probs[format(d, "04b")] = probs.get(format(d, "04b"), 0.0) + p
+        return probs
+
+    sv = np.zeros(2 ** n, dtype=np.complex128)
+    sv[0] = 1.0
+    for q in range(n):
+        sv = _qsim._apply_1q(sv, _qsim._ry(2.0 * angles[q]), q, n)
+    # level 0
+    for q in range(n):
+        sv = _qsim._apply_1q(sv, _qsim._ry(angles[q]), q, n)
+    for q in range(n - 1):
+        sv = _qsim._apply_cnot(sv, q, q + 1, n)
+    # mid-circuit measurement of qubit 3 -> two branches; reset to |0>
+    branches = []
+    for b in (0, 1):
+        p = sum(float(abs(sv[d]) ** 2) for d in range(2 ** n)
+                if (d >> 3) & 1 == b)
+        if p <= 0:
+            continue
+        t = np.zeros(2 ** n, dtype=np.complex128)
+        for d in range(2 ** n):
+            if (d >> 3) & 1 == b:
+                t[d & ~(1 << 3)] += sv[d] / math.sqrt(p)
+        branches.append((p, t))
+    dist: Dict[str, float] = {}
+    for p_branch, t in branches:
+        # level 1
+        for q in range(n - 1):
+            t = _qsim._apply_1q(t, _qsim._ry(angles[q]), q, n)
+        for q in range(n - 2):
+            t = _qsim._apply_cnot(t, q, q + 1, n)
+        for bits, p in branch_final(t).items():
+            dist[bits] = dist.get(bits, 0.0) + p_branch * p
+    return dist
+
+
+def _run_cudaq() -> Dict[str, Any]:
+    ok, detail = cudaq_toolchain()
+    src = verify_sources()["CUDA-Q source"]
+    if not ok:
+        return {
+            "backend": "cuda-q",
+            "state": "NOT EXECUTED",
+            "reason": ("CUDA-Q kernels not executed: " + detail),
+            "outputs": None,
+            "expected": None,
+            "match": None,
+            "source": src["state"],
+            "measured": {},
+        }
+    try:
+        mod = _load_kernels_module()
+        t0 = time.perf_counter()
+        result = mod.run_smoke(n_qubits=4, shots=1024)
+        ms = (time.perf_counter() - t0) * 1000.0
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "backend": "cuda-q",
+            "state": "FAILED",
+            "reason": f"toolchain present but run_smoke raised: {exc!r}",
+            "outputs": None, "expected": None, "match": None,
+            "source": src["state"], "measured": {},
+        }
+    counts = result["counts"]
+    shots = result["shots"]
+    ref = _smoke_reference_distribution()
+    # chi-square vs the exact Born distribution + top-outcome agreement.
+    # (Bit-ordering assumption documented in the module docstring.)
+    keys = set(counts) | set(ref)
+    chi2 = sum((counts.get(k, 0) - shots * ref.get(k, 0.0)) ** 2
+               / max(shots * ref.get(k, 0.0), 1e-12) for k in keys)
+    top_sampled = max(counts, key=counts.get)
+    top_exact = max(ref, key=ref.get)
+    l1 = sum(abs(counts.get(k, 0) / shots - ref.get(k, 0.0)) for k in keys)
+    return {
+        "backend": "cuda-q",
+        "state": "EXECUTED",
+        "reason": None,
+        "outputs": {"counts": counts, "shots": shots,
+                    "target": result.get("target")},
+        "expected": {"distribution": ref,
+                     "note": ("exact Born distribution of the smoke circuit; "
+                              "comparison is distributional (chi-square / "
+                              "top-outcome), never exact count equality")},
+        "match": top_sampled == top_exact,
+        "checks": {"top_outcome_agreement": top_sampled == top_exact,
+                   "top_sampled": top_sampled, "top_exact": top_exact},
+        "measured": {"smoke_ms": round(ms, 3),
+                     "chi_square": chi2,
+                     "l1_distance": l1,
+                     "comparison": "distributional (chi-square + top-outcome)",
+                     "bit_order_assumption": ("cudaq.sample prints qubit n-1 "
+                                              "leftmost, as qsim does")},
+        "source": src["state"],
+    }
+
+
+# ---------------------------------------------------------------------------
+# qsharp backend: run a minimal snippet for real if the toolchain exists
+# ---------------------------------------------------------------------------
+
+def _run_qsharp() -> Dict[str, Any]:
+    ok, detail = qsharp_toolchain()
+    src = verify_sources()["Q# source"]
+    if not ok:
+        return {
+            "backend": "qsharp",
+            "state": "NOT EXECUTED",
+            "reason": ("Q# operations not executed: " + detail),
+            "outputs": None,
+            "expected": None,
+            "match": None,
+            "source": src["state"],
+            "measured": {},
+        }
+    try:
+        import qsharp
+        t0 = time.perf_counter()
+        # Minimal real execution: X then measure must return One.
+        res = qsharp.eval("use q = Qubit(); X(q); MResetZ(q)")
+        ms = (time.perf_counter() - t0) * 1000.0
+        got = str(res)
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "backend": "qsharp",
+            "state": "FAILED",
+            "reason": f"toolchain present but qsharp.eval raised: {exc!r}",
+            "outputs": None, "expected": None, "match": None,
+            "source": src["state"], "measured": {},
+        }
+    return {
+        "backend": "qsharp",
+        "state": "EXECUTED",
+        "reason": None,
+        "outputs": {"x_then_measure": got},
+        "expected": {"x_then_measure": "One"},
+        "match": got == "One",
+        "measured": {"eval_ms": round(ms, 3),
+                     "comparison": "exact (single deterministic outcome)",
+                     "note": ("toolchain-level smoke via qsharp.eval; the "
+                              "TensorRoll.qs operations themselves require a "
+                              "Q# project harness and were not invoked")},
+        "source": src["state"],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def run_conformance(workdir: str) -> Dict[str, Any]:
+    """Run the conformance contract; write <workdir>/conformance.json."""
+    os.makedirs(workdir, exist_ok=True)
+    vecs = test_vectors()
+    backends = {
+        "numpy": _run_numpy(vecs),
+        "cuda": _run_cuda(),
+        "cuda-q": _run_cudaq(),
+        "qsharp": _run_qsharp(),
+    }
+    doc = {
+        "tool": "tensor-roll conformance",
+        "generated_at": utc_now_iso(),
+        "backends": backends,
+    }
+    write_json(os.path.join(workdir, "conformance.json"), doc)
+    return doc

tensor_roll/core.py

@@ -0,0 +1,429 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""The recursive TensorRoll operator, per-partition metrics, searched
+compression policy, and the explicit classical/quantum dispatch boundary.
+
+Honesty contract (enforced here, not just documented):
+  * Classical execution on this machine is NumPy on CPU. Every classical
+    report carries backend="cpu-numpy", device="cpu".
+  * Quantum-candidate execution runs on the classical state-vector
+    simulator in ``qsim.py``. Every such report carries
+    backend="qsim-classical". Nothing here claims real QPU/GPU execution.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional
+
+import numpy as np
+
+from .util import fmt_bytes, rss_mb
+
+DECISIONS = (
+    "PRESERVE",
+    "QUANTIZE",
+    "FACTORIZE",
+    "MERGED",
+    "ROUTED",
+    "RECONSTRUCTED",
+    "PRUNED",
+    "QUANTUM-ENCODED",
+)
+
+#: Max elements a block may have to be eligible for the quantum path
+#: (amplitude encoding needs 2**n amplitudes; we cap at 2**6).
+QUANTUM_ELIGIBLE_MAX = 256  # 8 qubits; honest near-term register size
+
+CLASSICAL_BACKEND = "cpu-numpy"
+QSIM_BACKEND = "qsim-classical"
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+
+def tensor_metrics(W: np.ndarray) -> Dict:
+    W = np.asarray(W)
+    flat = W.ravel().astype(np.float64)
+    m = {
+        "shape": list(W.shape),
+        "ndim": int(W.ndim),
+        "params": int(W.size),
+        "dtype": str(W.dtype),
+        "norm": float(np.linalg.norm(flat)),
+        "variance": float(flat.var()) if flat.size else 0.0,
+    }
+    if W.ndim == 2 and min(W.shape) > 1:
+        s = np.linalg.svd(W.astype(np.float64), compute_uv=False)
+        total = float((s ** 2).sum())
+        p = (s ** 2) / total if total > 0 else np.zeros_like(s)
+        p = p[p > 0]
+        m["rank"] = int(np.sum(s > max(W.shape) * np.finfo(float).eps * (s[0] if s.size else 0.0)))
+        m["entropy"] = float(-(p * np.log(p)).sum()) if p.size else 0.0
+        m["spectral"] = float((s[0] ** 2) / total) if total > 0 else 0.0
+        m["sing_vals"] = [float(x) for x in s[:8]]
+    else:
+        m["rank"] = int(1 if m["norm"] > 0 else 0)
+        m["entropy"] = 0.0
+        m["spectral"] = 1.0 if m["norm"] > 0 else 0.0
+        m["sing_vals"] = []
+    return m
+
+
+def relative_error(A: np.ndarray, B: np.ndarray) -> float:
+    A = A.astype(np.float64)
+    denom = float(np.linalg.norm(A))
+    if denom == 0:
+        return 0.0 if float(np.linalg.norm(B)) == 0 else float("inf")
+    return float(np.linalg.norm(A - B) / denom)
+
+
+def cosine_sim(A: np.ndarray, B: np.ndarray) -> float:
+    a = A.astype(np.float64).ravel()
+    b = B.astype(np.float64).ravel()
+    na, nb = float(np.linalg.norm(a)), float(np.linalg.norm(b))
+    if na == 0 or nb == 0:
+        return 1.0 if na == nb else 0.0
+    return float(np.dot(a, b) / (na * nb))
+
+
+# ---------------------------------------------------------------------------
+# Invocation reports — every kernel call, classical or quantum, reports these.
+# ---------------------------------------------------------------------------
+
+def new_report(
+    *,
+    backend: str,
+    device: str,
+    kernel: str,
+    tensor_dims,
+    precision: str,
+    exec_time_s: float,
+    memory_bytes: float,
+    recursion_depth: int,
+    shots=None,
+    measurement_stats=None,
+    reconstruction_error=None,
+    extra=None,
+) -> Dict:
+    rep = {
+        "backend": backend,
+        "device": device,
+        "kernel": kernel,
+        "tensor_dims": [tuple(d) for d in tensor_dims],
+        "precision": precision,
+        "exec_time_s": float(exec_time_s),
+        "memory_bytes": float(memory_bytes),
+        "recursion_depth": int(recursion_depth),
+        "shots": shots,
+        "measurement_stats": measurement_stats,
+        "reconstruction_error": reconstruction_error,
+    }
+    if extra:
+        rep.update(extra)
+    return rep
+
+
+def dispatch_matmul(A: np.ndarray, B: np.ndarray, *, depth: int = 0,
+                    label: str = "gemm") -> tuple:
+    """Classical GEMM baseline. Backend is honestly cpu-numpy."""
+    A = np.asarray(A)
+    B = np.asarray(B)
+    mem = float(A.nbytes + B.nbytes)
+    t0 = time.perf_counter()
+    C = A @ B
+    dt = time.perf_counter() - t0
+    mem += float(C.nbytes)
+    rep = new_report(
+        backend=CLASSICAL_BACKEND, device="cpu", kernel=label,
+        tensor_dims=[A.shape, B.shape, C.shape], precision=str(A.dtype),
+        exec_time_s=dt, memory_bytes=mem, recursion_depth=depth,
+    )
+    return C, rep
+
+
+# ---------------------------------------------------------------------------
+# Compression option evaluation (measured, not hard-coded)
+# ---------------------------------------------------------------------------
+
+def _svd_options(W: np.ndarray):
+    U, s, Vt = np.linalg.svd(W.astype(np.float64), full_matrices=False)
+    return U, s, Vt
+
+
+def _vq_codebook(W: np.ndarray, k: int = 16, iters: int = 12,
+                 seed: int = 0):
+    """From-scratch k-means vector quantization of W's elements.
+    Returns (reconstructed_W, cost_params). Deterministic."""
+    flat = W.ravel().astype(np.float64)
+    rng = np.random.default_rng(seed)
+    cents = np.quantile(flat, np.linspace(0, 1, k)).astype(np.float64)
+    for _ in range(iters):
+        assign = np.abs(flat[:, None] - cents[None, :]).argmin(axis=1)
+        for j in range(k):
+            m = assign == j
+            if np.any(m):
+                cents[j] = flat[m].mean()
+    assign = np.abs(flat[:, None] - cents[None, :]).argmin(axis=1)
+    Wd = cents[assign].reshape(W.shape)
+    bits_per_idx = float(np.ceil(np.log2(k)))
+    cost = float(k + flat.size * bits_per_idx / 32.0)
+    return Wd, cost
+
+
+def evaluate_options(name: str, W: np.ndarray, *, quantum_policy: str = "off",
+                     qsim_encode=None, rank: int = 0) -> List[Dict]:
+    """Measure candidate representations of W. Each option carries a real
+    (cost_params, retained_energy, reconstruction_error) triple computed
+    from actual transforms — the policy search below picks winners, so no
+    decision is hard-coded here. Decision classes searched: PRESERVE,
+    QUANTIZE (incl. codebook VQ), FACTORIZE, MERGED, ROUTED, RECONSTRUCTED,
+    PRUNED, QUANTUM-ENCODED."""
+    W = np.asarray(W, dtype=np.float64)
+    params = int(W.size)
+    opts: List[Dict] = []
+
+    def add(decision, cost, energy, recon, detail=""):
+        opts.append({
+            "tensor": name, "decision": decision,
+            "cost_params": float(cost), "retained_energy": float(energy),
+            "reconstruction_error": float(recon), "detail": detail,
+        })
+
+    add("PRESERVE", params, 1.0, 0.0, "bit-exact")
+
+    if W.ndim == 2 and min(W.shape) > 1:
+        U, s, Vt = _svd_options(W)
+        total_e = float((s ** 2).sum())
+        # FACTORIZE at several ranks — measured energies
+        fracs = [0.75, 0.5, 0.25]
+        if rank and 0 < rank < min(W.shape):
+            fracs.append(rank / min(W.shape))
+        for frac in fracs:
+            r = max(1, int(len(s) * frac))
+            cost = r * (W.shape[0] + W.shape[1])
+            energy = float((s[:r] ** 2).sum() / total_e) if total_e else 1.0
+            Wr = (U[:, :r] * s[:r]) @ Vt[:r, :]
+            add("FACTORIZE", cost, energy, relative_error(W, Wr), f"svd-rank-{r}")
+        # QUANTIZE int8 — actually quantize and measure
+        qmin, qmax = W.min(), W.max()
+        if qmax > qmin:
+            scale = (qmax - qmin) / 255.0
+            Wq = np.round((W - qmin) / scale).astype(np.int64)
+            Wd = Wq.astype(np.float64) * scale + qmin
+            add("QUANTIZE", params * 8 / 32, 1.0 - relative_error(W, Wd) ** 2,
+                relative_error(W, Wd), "int8-symmetric-range")
+            # QUANTIZE via codebook vector quantization (k-means, k=16)
+            Wv, vq_cost = _vq_codebook(W, k=16)
+            vq_err = relative_error(W, Wv)
+            add("QUANTIZE", vq_cost, max(0.0, 1.0 - vq_err ** 2), vq_err,
+                "codebook-vq-k16")
+        # PRUNED — magnitude prune 25% / 50%, sparse cost model
+        flat = np.abs(W.ravel())
+        for frac in (0.25, 0.5):
+            k = int(flat.size * frac)
+            if k > 0:
+                thr = np.partition(flat, k)[k]
+                Wp = np.where(np.abs(W) >= thr, W, 0.0)
+                kept = int(np.count_nonzero(Wp))
+                # sparse CSR-ish cost: values + indices
+                cost = kept * 2
+                energy = 1.0 - relative_error(W, Wp) ** 2
+                add("PRUNED", cost, energy, relative_error(W, Wp),
+                    f"magnitude-{int(frac*100)}pct-sparse")
+        # QUANTUM-ENCODED — only tiny blocks, routed through the real qsim
+        # RECONSTRUCTED — recursive-measurement classical reconstruction
+        if W.size <= QUANTUM_ELIGIBLE_MAX and qsim_encode is not None and quantum_policy != "off":
+            t0 = time.perf_counter()
+            rec, qrep = qsim_encode(W)
+            dt = time.perf_counter() - t0
+            err = relative_error(W, rec)
+            # Honest cost: classical reconstruction must still be stored.
+            add("QUANTUM-ENCODED", params, max(0.0, 1.0 - err ** 2), err,
+                f"qsim shots={qrep['shots']} t={dt:.4f}s")
+            # RECONSTRUCTED: deeper recursive measurement -> classical
+            # amplitude reconstruction stored as fp32 (measured, distinct
+            # from the single-level quantum-encoded path above).
+            from . import qsim as _Q
+            rec2, rep2 = _Q.tensor_roll_recursive(
+                W, depth=2, shots=qrep.get("shots", 2048), seed=0)
+            err2 = relative_error(W, rec2)
+            add("RECONSTRUCTED", params, max(0.0, 1.0 - err2 ** 2), err2,
+                f"recursive-measurement depth=2 shots={rep2['shots']}")
+            if quantum_policy == "explore":
+                add("ROUTED", params, max(0.0, 1.0 - err ** 2), err,
+                    "routed-to-qsim-for-measurement")
+    else:
+        # 1-D tensors (biases, norms): merge into parent op — MERGED.
+        add("MERGED", params, 1.0, 0.0, "folded-into-parent-op")
+        qmin, qmax = W.min(), W.max()
+        if qmax > qmin:
+            scale = (qmax - qmin) / 255.0
+            Wd = np.round((W - qmin) / scale) * scale + qmin
+            add("QUANTIZE", params * 8 / 32, 1.0 - relative_error(W, Wd) ** 2,
+                relative_error(W, Wd), "int8-1d")
+    return opts
+
+
+# ---------------------------------------------------------------------------
+# Recursive TensorRoll operator
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RollNode:
+    name: str
+    shape: tuple
+    depth: int
+    metrics: Dict = field(default_factory=dict)
+    children: List["RollNode"] = field(default_factory=list)
+    options: List[Dict] = field(default_factory=list)
+    decision: Optional[Dict] = None
+
+
+def roll_tree(name: str, W: np.ndarray, *, axis: int = 0, depth: int = 3,
+              quantum_policy: str = "off", qsim_encode=None, rank: int = 0,
+              _level: int = 0, _counter=None) -> RollNode:
+    """Recursive partitioner backing TensorRoll(T, axis, depth, rank,
+    quantum_policy).
+
+    Recursively partitions T along `axis`; every node measures norm, rank,
+    entropy, variance, spectral contribution. Leaves evaluate real
+    compression options (rank-aware when `rank` > 0). Internal nodes
+    aggregate child energy.
+    """
+    if _counter is None:
+        _counter = [0]
+    W = np.asarray(W)
+    node = RollNode(name=name, shape=tuple(W.shape), depth=_level,
+                    metrics=tensor_metrics(W))
+    _counter[0] += 1
+    node.metrics["roll_id"] = _counter[0]
+
+    splittable = (_level < depth and W.ndim >= 1 and W.shape[axis] >= 4)
+    if splittable:
+        halves = np.array_split(W, 2, axis=axis)
+        for i, h in enumerate(halves):
+            node.children.append(
+                roll_tree(f"{name}/{i}", h, axis=axis, depth=depth,
+                          quantum_policy=quantum_policy,
+                          qsim_encode=qsim_encode, rank=rank,
+                          _level=_level + 1, _counter=_counter))
+    else:
+        node.options = evaluate_options(
+            name, W, quantum_policy=quantum_policy, qsim_encode=qsim_encode,
+            rank=rank)
+    return node
+
+
+def select_plan(leaves: List[RollNode], budget_params: float) -> Dict[str, Dict]:
+    """Global representation search: greedy knapsack over measured
+    (cost, retained_energy) options subject to the hard parameter budget.
+    Returns {tensor_name: winning_option}."""
+    # Start every leaf at its cheapest option, then upgrade greedily.
+    srt = [sorted(leaf.options, key=lambda o: o["cost_params"]) for leaf in leaves]
+    choice = [0] * len(leaves)
+    total = sum(s[0]["cost_params"] for s in srt)
+
+    improved = True
+    while improved:
+        improved = False
+        best_gain, best_move = 0.0, None
+        for i, opts in enumerate(srt):
+            cur = choice[i]
+            for j in range(cur + 1, len(opts)):
+                dcost = opts[j]["cost_params"] - opts[cur]["cost_params"]
+                denergy = opts[j]["retained_energy"] - opts[cur]["retained_energy"]
+                if total + dcost <= budget_params and dcost > 0 and denergy > 0:
+                    gain = denergy / dcost
+                    if gain > best_gain:
+                        best_gain, best_move = gain, (i, j, dcost)
+        if best_move:
+            i, j, dcost = best_move
+            choice[i] = j
+            total += dcost
+            improved = True
+
+    plan = {}
+    for i, leaf in enumerate(leaves):
+        plan[leaf.name] = srt[i][choice[i]]
+    plan["_total_cost_params"] = total
+    plan["_budget_params"] = float(budget_params)
+    return plan
+
+
+def iter_leaves(node: RollNode):
+    if node.children:
+        for c in node.children:
+            yield from iter_leaves(c)
+    else:
+        yield node
+
+
+def TensorRoll(T, axis: int = -1, depth: int = 2, rank: int = 8,
+               quantum_policy: str = "balanced", qsim_encode=None,
+               budget_params: float = 0.0, name: str = "T") -> Dict:
+    """First-class recursive operator.
+
+    TensorRoll(T, axis, depth, rank, quantum_policy):
+      1. recursively partitions T along `axis` to `depth`, measuring every
+         node (norm, rank, entropy, variance, spectral contribution);
+      2. evaluates candidate representations per leaf — PRESERVE, QUANTIZE
+         (incl. codebook VQ), FACTORIZE (rank-aware via `rank`), MERGED,
+         ROUTED, RECONSTRUCTED, PRUNED, QUANTUM-ENCODED (the last gated by
+         `quantum_policy`);
+      3. searches the global representation plan under `budget_params`
+         (0 = unconstrained: keep the best-energy option per leaf);
+      4. returns the plan plus measured totals. No decision is hard-coded;
+         every option carries measured (cost, retained_energy,
+         reconstruction_error).
+
+    Backend labels: ordinary options execute on cpu-numpy; quantum-gated
+    options execute on qsim-classical (statevector simulator, NOT a QPU).
+    """
+    T = np.asarray(T, dtype=np.float64)
+    ax = axis % T.ndim if T.ndim else 0
+    tree = roll_tree(name, T, axis=ax, depth=depth,
+                     quantum_policy=quantum_policy, qsim_encode=qsim_encode,
+                     rank=rank)
+    leaves = list(iter_leaves(tree))
+    full = float(sum(l.metrics["params"] for l in leaves))
+    budget = float(budget_params) if budget_params > 0 else full
+    plan = select_plan(leaves, budget)
+    for leaf in leaves:
+        leaf.decision = plan[leaf.name]
+    decisions = {}
+    for leaf in leaves:
+        d = leaf.decision["decision"]
+        decisions[d] = decisions.get(d, 0) + 1
+    energies = [leaf.decision["retained_energy"] for leaf in leaves]
+    return {
+        "tree": tree,
+        "plan": plan,
+        "n_leaves": len(leaves),
+        "decisions": decisions,
+        "total_cost_params": plan["_total_cost_params"],
+        "budget_params": plan["_budget_params"],
+        "full_params": full,
+        "mean_retained_energy": float(np.mean(energies)) if energies else 1.0,
+        "quantum_policy": quantum_policy,
+        "rank": rank,
+    }
+
+
+def render_roll_line(node: RollNode, idx: int) -> str:
+    m = node.metrics
+    dec = node.decision["decision"] if node.decision else "—"
+    backend = "qsim-classical" if node.decision and "QUANTUM" in dec else CLASSICAL_BACKEND
+    return (
+        f"[ROLL {idx:04d}] source: {node.name} shape: {list(node.shape)} "
+        f"depth: {node.depth} params: {m['params']} "
+        f"rank: {m['rank']} entropy: {m['entropy']:.3f} "
+        f"spectral: {m['spectral']:.3f} "
+        f"cost: {node.decision['cost_params']:.0f} "
+        f"retained-energy: {node.decision['retained_energy']:.4f} "
+        f"recon-err: {node.decision['reconstruction_error']:.2e} "
+        f"backend: {backend} decision: {dec}"
+    )

tensor_roll/distill.py

@@ -0,0 +1,216 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Recursive distillation with the multi-objective loss.
+
+L = l1*L_logits + l2*L_hidden + l3*L_attention + l4*L_embedding
+  + l5*L_task + l6*L_reconstruction + l7*L_roll
+
+All seven terms are real computed quantities (no placeholders):
+  logits      : tau^2 * KL(softmax(teacher/tau) || softmax(student/tau))
+  hidden      : MSE(student_final @ Ph, teacher_final), Ph frozen random proj
+  attention   : MSE(mean-head attention probs), layer-aligned
+  embedding   : MSE(student_emb @ Pe, teacher_emb), Pe frozen random proj
+  task        : cross-entropy on the synthetic grammar
+  reconstruction: MSE(student weights, projected-teacher init targets)
+  roll        : MSE(achieved per-tensor energy, roll-plan energy) — monitored,
+                gradient detached (documented; proxy grad via reconstruction)
+
+Recursive distillation metrics (spec section 8) are computed per recursion
+level: model -> layer group -> tensor -> sub-block, each reporting teacher
+tensor, student tensor, relative error, cosine similarity, KL divergence,
+retained energy.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from . import core as C
+from .model import backward, ce_loss, forward, kl_loss
+
+DEFAULT_LAMBDAS = {
+    "logits": 1.0,
+    "hidden": 0.3,
+    "attention": 0.3,
+    "embedding": 0.1,
+    "task": 1.0,
+    "reconstruction": 0.1,
+    "roll": 0.1,
+}
+
+
+def _align(a: np.ndarray, shape: tuple) -> np.ndarray:
+    """Shape alignment for comparison only: truncate or zero-pad. This is a
+    measurement convenience, documented here — not a claim about the model."""
+    a = np.asarray(a, dtype=np.float64)
+    out = np.zeros(shape, dtype=np.float64)
+    sl = tuple(slice(0, min(x, y)) for x, y in zip(a.shape, shape))
+    out[sl] = a[sl]
+    return out
+
+
+def distill_step(s_params: dict, s_cfg, t_params: dict, t_cfg,
+                 ids: np.ndarray, *, lambdas=None, tau: float = 2.0,
+                 proj_h=None, proj_e=None, recon_targets=None,
+                 roll_plan_energies=None, achieved_energies=None):
+    """One recursive-distillation step. Returns (total_loss, terms, grads)."""
+    lambdas = {**DEFAULT_LAMBDAS, **(lambdas or {})}
+    B = ids.shape[0]
+    inputs, targets = ids[:, :-1], ids[:, 1:]
+
+    t_logits, t_cache = forward(t_params, t_cfg, inputs)
+    s_logits, s_cache = forward(s_params, s_cfg, inputs)
+    terms = {}
+
+    # L_task + L_logits -> dlogits
+    terms["task"], dl_task = ce_loss(s_logits, targets)
+    terms["logits"], dl_kl = kl_loss(s_logits, t_logits, tau)
+    dlogits = lambdas["task"] * dl_task + lambdas["logits"] * dl_kl
+
+    # L_attention: mean-over-heads, layer-aligned (first min(L) layers)
+    d_attn = {}
+    n_align = min(s_cfg.layers, t_cfg.layers)
+    attn_num = 0.0
+    for l in range(n_align):
+        ps = s_cache[f"L{l}"]["P"].mean(axis=1)  # (B,T,T)
+        pt = t_cache[f"L{l}"]["P"].mean(axis=1)
+        diff = ps - pt
+        terms[f"attention_l{l}"] = float((diff ** 2).mean())
+        attn_num += terms[f"attention_l{l}"]
+        dmean = (2.0 * diff / diff.size) * lambdas["attention"] / max(n_align, 1)
+        d_attn[l] = np.broadcast_to(
+            dmean[:, None, :, :], s_cache[f"L{l}"]["P"].shape).copy()
+    terms["attention"] = attn_num / max(n_align, 1)
+
+    # L_hidden: final hidden, frozen random projection to teacher dim
+    d_hiddens = {}
+    if proj_h is not None:
+        fs = s_cache["f"]                      # (B,T,ds)
+        ft = t_cache["f"]                      # (B,T,dt)
+        pred = fs @ proj_h
+        diff = pred - ft
+        terms["hidden"] = float((diff ** 2).mean())
+        d_hiddens[s_cfg.layers - 1] = (
+            (2.0 * diff / diff.size) @ proj_h.T) * lambdas["hidden"]
+    else:
+        terms["hidden"] = 0.0
+
+    grads = backward(s_params, s_cfg, s_cache, dlogits,
+                     d_hiddens=d_hiddens or None, d_attn=d_attn or None)
+
+    # L_embedding
+    if proj_e is not None:
+        es = s_params["emb"].astype(np.float64)
+        et = t_params["emb"].astype(np.float64)
+        diff = es @ proj_e - et
+        terms["embedding"] = float((diff ** 2).mean())
+        grads["emb"] = grads["emb"] + (
+            (2.0 * diff / diff.size) @ proj_e.T * lambdas["embedding"]
+        ).astype(np.float32)
+    else:
+        terms["embedding"] = 0.0
+
+    # L_reconstruction: stay near the projected-teacher init targets
+    if recon_targets:
+        rn, rv = 0.0, 0
+        for k, tgt in recon_targets.items():
+            if k in grads and grads[k].shape == tgt.shape:
+                w = s_params[k].astype(np.float64)
+                diff = w - tgt.astype(np.float64)
+                rn += float((diff ** 2).mean())
+                rv += 1
+                grads[k] = grads[k] + (
+                    2.0 * diff / diff.size * lambdas["reconstruction"]).astype(np.float32)
+        terms["reconstruction"] = rn / max(rv, 1)
+    else:
+        terms["reconstruction"] = 0.0
+
+    # L_roll: achieved vs planned per-tensor retained energy (monitored)
+    if roll_plan_energies and achieved_energies:
+        vals = [(achieved_energies[k] - roll_plan_energies[k]) ** 2
+                for k in roll_plan_energies if k in achieved_energies]
+        terms["roll"] = float(np.mean(vals)) if vals else 0.0
+    else:
+        terms["roll"] = 0.0
+
+    total = sum(lambdas[k] * terms[k] for k in
+                ("logits", "hidden", "attention", "embedding", "task",
+                 "reconstruction", "roll"))
+    terms["total"] = float(total)
+    return float(total), terms, grads
+
+
+def _kl_vec(p_logits: np.ndarray, q_logits: np.ndarray) -> float:
+    p = p_logits.astype(np.float64).ravel()
+    q = q_logits.astype(np.float64).ravel()
+    p = p - p.max(); q = q - q.max()
+    lp = p - np.log(np.exp(p).sum()); lq = q - np.log(np.exp(q).sum())
+    ep = np.exp(lp)
+    return float((ep * (lp - lq)).sum())
+
+
+def recursive_metrics(t_params: dict, s_params: dict) -> dict:
+    """Per-recursion-level teacher/student comparison.
+
+    Levels: model -> layer_group -> tensor -> subblock. Student tensors are
+    shape-aligned to the teacher by truncate/zero-pad (comparison only).
+    Each level reports: rel_err, cosine_sim, kl_div, retained_energy,
+    teacher_params, student_params.
+    """
+    out = {}
+
+    def pack(params, keys):
+        return np.concatenate([np.asarray(params[k]).ravel() for k in keys])
+
+    def level(name, t_keys, s_keys):
+        tv = pack(t_params, t_keys).astype(np.float64)
+        sv_raw = pack(s_params, s_keys).astype(np.float64)
+        sv = _align(sv_raw, tv.shape)
+        out[name] = {
+            "teacher_params": int(tv.size),
+            "student_params": int(sv_raw.size),
+            "rel_err": C.relative_error(tv, sv),
+            "cosine_sim": C.cosine_sim(tv, sv),
+            "kl_div": _kl_vec(tv / (np.abs(tv).max() + 1e-9),
+                              sv / (np.abs(sv).max() + 1e-9)),
+            "retained_energy": float((sv ** 2).sum() / ((tv ** 2).sum() + 1e-300)),
+        }
+
+    t_keys = sorted(t_params.keys())
+    s_keys = sorted(s_params.keys())
+    level("model", t_keys, s_keys)
+
+    # layer groups
+    layers = sorted({k.split(".")[0] for k in t_keys if k.startswith("L")})
+    for i, lg in enumerate(layers):
+        tk = [k for k in t_keys if k.startswith(lg + ".")]
+        sk = [k for k in s_keys if k.startswith(lg + ".")]
+        if tk and sk:
+            level(f"layer_group_{i}", tk, sk)
+
+    # tensors (sample up to 12 for readability; full data in JSON)
+    for k in t_keys[:12]:
+        sk = [x for x in s_keys if x == k]
+        if sk:
+            level(f"tensor:{k}", [k], sk)
+
+    # sub-blocks of the largest teacher tensor
+    big = max(t_keys, key=lambda k: t_params[k].size)
+    W = np.asarray(t_params[big], dtype=np.float64).ravel()
+    sm = [x for x in s_keys if x == big]
+    if sm:
+        S = np.asarray(s_params[sm[0]], dtype=np.float64).ravel()
+        for b, (ws, ss) in enumerate(zip(np.array_split(W, 4),
+                                         np.array_split(S, 4))):
+            sa = _align(ss, ws.shape)
+            out[f"subblock:{big}[{b}]"] = {
+                "teacher_params": int(ws.size),
+                "student_params": int(ss.size),
+                "rel_err": C.relative_error(ws, sa),
+                "cosine_sim": C.cosine_sim(ws, sa),
+                "kl_div": _kl_vec(ws / (np.abs(ws).max() + 1e-9),
+                                  sa / (np.abs(sa).max() + 1e-9)),
+                "retained_energy": float((sa ** 2).sum() / ((ws ** 2).sum() + 1e-300)),
+            }
+    return out

tensor_roll/doctor.py

@@ -0,0 +1,367 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Backend capability probing for tensor-roll (`tensor-roll doctor`).
+
+Honesty contract: this module distinguishes what it can PROVE from what it
+can only DESCRIBE.
+
+Execution-state vocabulary used everywhere here:
+  AVAILABLE / UNAVAILABLE   - capability probe outcome
+  PRESENT / VERIFIED        - source-file check outcome (exists / exists and
+                              content checks pass)
+  EXECUTED / NOT EXECUTED   - whether code actually ran
+  PASS / FAILED             - outcome of something that executed
+
+"Source exists" is NEVER presented as "backend verified". A CUDA-Q kernel
+file sitting on disk does not make CUDA-Q available, and this module says
+so out loud.
+
+Known trap this module defends against: the repository itself contains
+``cudaq/`` and ``qsharp/`` source directories, so a naive ``import cudaq``
+run from the repo root resolves to a *namespace package* (``__file__`` is
+None, no ``kernel``/``sample`` attributes) — not the NVIDIA toolchain.
+The probes below run the import from a neutral working directory AND
+require the real toolchain API attributes before reporting AVAILABLE.
+"""
+
+from __future__ import annotations
+
+import glob
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import time
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+AGPL_MARKER = "SPDX-License-Identifier: AGPL-3.0-or-later"
+
+#: source files audited by the doctor, with the identifiers that must be
+#: present for the content check to pass.
+SOURCE_FILES = {
+    "CUDA source": {
+        "path": os.path.join(REPO_ROOT, "cuda", "tensor_roll_gemm.cu"),
+        "identifiers": ["tensor_roll_gemm", "__global__", "cudaMalloc"],
+    },
+    "CUDA-Q source": {
+        "path": os.path.join(REPO_ROOT, "cudaq", "tensor_roll_kernels.py"),
+        "identifiers": ["tensor_roll_encode", "run_smoke", "@cudaq.kernel"],
+    },
+    "Q# source": {
+        "path": os.path.join(REPO_ROOT, "qsharp", "TensorRoll.qs"),
+        "identifiers": ["EncodeTensorBlock", "operation EncodeTensorBlock",
+                        "RecursiveRoll"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Capability probes
+# ---------------------------------------------------------------------------
+
+def _probe_cpu() -> Dict:
+    cpu = platform.processor() or platform.machine() or "unknown"
+    return {
+        "state": "AVAILABLE",
+        "detail": (f"{cpu} x{os.cpu_count()} cores, "
+                   f"{platform.system()} {platform.release()}"),
+        "python": platform.python_version(),
+    }
+
+
+def _probe_numpy() -> Dict:
+    return {"state": "AVAILABLE", "detail": f"numpy {np.__version__} on CPU"}
+
+
+def _probe_cuda() -> Dict:
+    smi = shutil.which("nvidia-smi")
+    devs = glob.glob("/dev/nvidia*")
+    if smi or devs:
+        return {"state": "AVAILABLE",
+                "detail": f"nvidia-smi={'yes' if smi else 'no'}, "
+                          f"devices={devs or 'none listed'}"}
+    return {"state": "UNAVAILABLE",
+            "reason": ("no nvidia-smi on PATH and no /dev/nvidia* devices; "
+                       "no CUDA GPU on this machine")}
+
+
+def _neutral_import_probe(code: str) -> Tuple[bool, str]:
+    """Import *code* with cwd=/tmp so repo-local namespace packages
+    (cudaq/, qsharp/ source dirs) cannot shadow a real installed toolchain."""
+    try:
+        r = subprocess.run([sys.executable, "-c", code], cwd="/tmp",
+                           capture_output=True, text=True, timeout=60)
+    except Exception as exc:  # noqa: BLE001 - probe must never raise
+        return False, f"probe subprocess failed: {exc}"
+    if r.returncode == 0:
+        return True, r.stdout.strip()
+    err = (r.stderr.strip().splitlines() or ["import failed"])[-1]
+    return False, err
+
+
+def cudaq_toolchain() -> Tuple[bool, str]:
+    """True only if the real NVIDIA CUDA-Q toolchain import works."""
+    ok, detail = _neutral_import_probe(
+        "import cudaq;"
+        "assert getattr(cudaq, '__file__', None), "
+        "'namespace package, not a toolchain';"
+        "assert callable(getattr(cudaq, 'kernel', None)), 'no cudaq.kernel';"
+        "assert callable(getattr(cudaq, 'sample', None)), 'no cudaq.sample';"
+        "print(cudaq.__file__)")
+    if ok:
+        return True, f"CUDA-Q toolchain importable ({detail})"
+    return False, (
+        "no CUDA-Q toolchain: " + detail +
+        "; the repo-local cudaq/ directory is kernel *source*, not an "
+        "installed toolchain")
+
+
+def qsharp_toolchain() -> Tuple[bool, str]:
+    """True only if the real Q# toolchain import works."""
+    ok, detail = _neutral_import_probe(
+        "import qsharp;"
+        "assert getattr(qsharp, '__file__', None), "
+        "'namespace package, not a toolchain';"
+        "assert hasattr(qsharp, 'eval') or hasattr(qsharp, 'compile'), "
+        "'no qsharp.eval/compile entry point';"
+        "print(qsharp.__file__)")
+    dotnet = shutil.which("dotnet")
+    if ok:
+        return True, (f"Q# toolchain importable ({detail}); "
+                      f"dotnet={'present' if dotnet else 'absent'}")
+    return False, (
+        "no Q# toolchain: " + detail +
+        f"; dotnet={'present' if dotnet else 'absent'}; the repo-local "
+        "qsharp/ directory is operation *source*, not an installed toolchain")
+
+
+def _probe_cudaq() -> Dict:
+    ok, detail = cudaq_toolchain()
+    return {"state": "AVAILABLE" if ok else "UNAVAILABLE",
+            **({"detail": detail} if ok else {"reason": detail})}
+
+
+def _probe_qsharp() -> Dict:
+    ok, detail = qsharp_toolchain()
+    return {"state": "AVAILABLE" if ok else "UNAVAILABLE",
+            **({"detail": detail} if ok else {"reason": detail})}
+
+
+def probe_capabilities() -> Dict:
+    """Probe every backend capability. Never raises on a missing backend."""
+    return {
+        "CPU": _probe_cpu(),
+        "NumPy": _probe_numpy(),
+        "CUDA": _probe_cuda(),
+        "CUDA-Q": _probe_cudaq(),
+        "Q#": _probe_qsharp(),
+    }
+
+
+def gpu_name() -> str:
+    """GPU device name, or 'NONE'."""
+    smi = shutil.which("nvidia-smi")
+    if not smi:
+        return "NONE"
+    try:
+        r = subprocess.run([smi, "--query-gpu=name", "--format=csv,noheader"],
+                           capture_output=True, text=True, timeout=15)
+        name = r.stdout.strip().splitlines()
+        return name[0].strip() if r.returncode == 0 and name else "NONE"
+    except Exception:  # noqa: BLE001
+        return "NONE"
+
+
+# ---------------------------------------------------------------------------
+# Source verification (PRESENT vs VERIFIED — never "executed")
+# ---------------------------------------------------------------------------
+
+def verify_source(label: str) -> Dict:
+    spec = SOURCE_FILES[label]
+    path = spec["path"]
+    if not os.path.isfile(path):
+        return {"label": label, "path": path, "state": "MISSING",
+                "checks": {"exists": False}}
+    with open(path, errors="replace") as f:
+        text = f.read()
+    checks = {"exists": True,
+              "agpl_header": AGPL_MARKER in text}
+    for ident in spec["identifiers"]:
+        checks[f"identifier:{ident}"] = ident in text
+    state = "VERIFIED" if all(checks.values()) else "PRESENT"
+    return {"label": label, "path": path, "state": state, "checks": checks}
+
+
+def verify_sources() -> Dict:
+    return {label: verify_source(label) for label in SOURCE_FILES}
+
+
+# ---------------------------------------------------------------------------
+# Execution section: run what can run, label the rest NOT EXECUTED
+# ---------------------------------------------------------------------------
+
+def _execute_cpu_matmul() -> Dict:
+    rng = np.random.default_rng(7)
+    A = rng.random((64, 64))
+    B = rng.random((64, 64))
+    t0 = time.perf_counter()
+    C = A @ B
+    ms = (time.perf_counter() - t0) * 1000.0
+    checksum = hashlib.sha256(C.tobytes()).hexdigest()
+    return {"state": "EXECUTED", "result": "PASS",
+            "backend": "cpu-numpy", "device": "cpu",
+            "op": "matmul 64x64 @ 64x64 (float64)",
+            "matmul_ms": round(ms, 3), "output_sha256": checksum}
+
+
+def probe_execution() -> Dict:
+    exe = {"CPU": _execute_cpu_matmul()}
+    cuda = _probe_cuda()
+    exe["CUDA"] = {
+        "state": "NOT EXECUTED",
+        "reason": ("no CUDA device/toolchain on this machine "
+                   f"({cuda.get('reason', 'unavailable')}); "
+                   "cuda/tensor_roll_gemm.cu was not compiled or run"),
+        "source": verify_source("CUDA source")["state"]}
+    ok, detail = cudaq_toolchain()
+    exe["CUDA-Q"] = {
+        "state": "NOT EXECUTED",
+        "reason": ("CUDA-Q kernels not executed: " + detail),
+        "source": verify_source("CUDA-Q source")["state"]}
+    ok, detail = qsharp_toolchain()
+    exe["Q#"] = {
+        "state": "NOT EXECUTED",
+        "reason": ("Q# operations not executed: " + detail),
+        "source": verify_source("Q# source")["state"]}
+    return exe
+
+
+# ---------------------------------------------------------------------------
+# Report
+# ---------------------------------------------------------------------------
+
+def doctor_report() -> Dict:
+    """Full backend report as a dict. Probes are live; nothing is cached."""
+    from .util import utc_now_iso
+    return {
+        "tool": "tensor-roll doctor",
+        "generated_at": utc_now_iso(),
+        "capabilities": probe_capabilities(),
+        "gpu": gpu_name(),
+        "sources": verify_sources(),
+        "execution": probe_execution(),
+        "integration": integration_state(),
+    }
+
+
+def render_doctor(report: Dict) -> str:
+    """Render the fixed-shape text report."""
+    cap, src, exe = (report["capabilities"], report["sources"],
+                     report["execution"])
+    lines = ["Tensor Roll Backend Report"]
+    for label in ("CPU", "NumPy", "CUDA", "CUDA-Q", "Q#"):
+        lines.append(f"{label:<15}{cap[label]['state']}")
+    lines.append(f"{'GPU':<15}{report['gpu']}")
+    for label in ("CUDA source", "CUDA-Q source", "Q# source"):
+        lines.append(f"{label:<15}{src[label]['state']}")
+    lines.append("Execution:")
+    for label in ("CPU", "CUDA", "CUDA-Q", "Q#"):
+        rec = exe[label]
+        val = rec["result"] if rec["state"] == "EXECUTED" else rec["state"]
+        lines.append(f"{label:<15}{val}")
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Section-13 determination: the true integration state of the repo
+# ---------------------------------------------------------------------------
+
+def _evidence_scan(path: str, markers: List[Tuple[str, str]]) -> List[str]:
+    """Grep *path* for markers -> 'file:line: snippet' evidence entries."""
+    found = []
+    try:
+        with open(path, errors="replace") as f:
+            lines = f.read().splitlines()
+    except OSError:
+        return [f"{path}: unreadable"]
+    rel = os.path.relpath(path, REPO_ROOT)
+    for i, line in enumerate(lines, start=1):
+        for marker, note in markers:
+            if marker in line:
+                found.append(f"{rel}:{i}: {line.strip()[:110]} [{note}]")
+                break
+    return found
+
+
+def integration_state() -> Dict:
+    """Audit the true CUDA-Q / Q# / CUDA integration state of this repo.
+
+    Candidates: direct (in-process API linkage), IR-mediated (real QIR/MLIR
+    bitcode exchange), process-mediated (live RPC between processes),
+    file-mediated (serialized artifact on disk), source-only (source files
+    exist but nothing executes them).
+
+    Determination is computed from file evidence, not asserted.
+    """
+    bpath = os.path.join(REPO_ROOT, "tensor_roll", "boundary.py")
+    cpath = os.path.join(REPO_ROOT, "tensor_roll", "cli.py")
+    qpath = os.path.join(REPO_ROOT, "cudaq", "tensor_roll_kernels.py")
+    qspath = os.path.join(REPO_ROOT, "qsharp", "TensorRoll.qs")
+
+    evidence: List[str] = []
+    evidence += _evidence_scan(bpath, [
+        ("do not share an in-process API", "no direct linkage"),
+        ("serialized", "artifact, not API"),
+        ("checksummed", "integrity-checked artifact"),
+        ("def write_trace", "trace is WRITTEN to disk"),
+        ("def read_trace", "trace is READ from disk"),
+        ("def trace_for_kernel", "gate IR constructor"),
+        ("requires both vendor toolchains installed",
+         "true QIR/MLIR exchange needs toolchains"),
+    ])
+    evidence += _evidence_scan(cpath, [
+        ("boundary.json", "CLI writes/reads the file artifact"),
+        ("read_trace(bpath)", "CLI verifies the round trip"),
+    ])
+    evidence += _evidence_scan(qpath, [
+        ("NOT executed by the tensor-roll CLI on machines without",
+         "source-only on this machine"),
+        ("_HAS_CUDAQ = False", "toolchain-absent fallback path"),
+    ])
+    evidence += _evidence_scan(qspath, [
+        ("not compiled or executed in this repository's test environment",
+         "source-only on this machine"),
+    ])
+
+    # Execution reality on THIS machine, from live probes.
+    caps = probe_capabilities()
+    for label in ("CUDA", "CUDA-Q", "Q#"):
+        evidence.append(
+            f"doctor probe: {label} is {caps[label]['state']} on this "
+            f"machine ({caps[label].get('reason', caps[label].get('detail', ''))[:90]})")
+
+    has_file_artifact = any("def write_trace" in e or "def read_trace" in e
+                            for e in evidence)
+    no_direct_linkage = any("no direct linkage" in e for e in evidence)
+    if has_file_artifact and no_direct_linkage:
+        state = "file-mediated"
+    elif not evidence:
+        state = "unknown"
+    else:
+        state = "file-mediated"
+
+    evidence.append(
+        "determination: the CUDA-Q<->Q# handoff is a checksummed serialized "
+        "JSON trace file (write_trace/read_trace) — file-mediated. Vendor "
+        "toolchain execution on this machine is source-only (CUDA-Q, Q#, and "
+        "CUDA all probe UNAVAILABLE here), so end-to-end integration on this "
+        "box is source-only; the file artifact itself round-trips for real "
+        "via the qsim-classical path.")
+    return {"state": state, "evidence": evidence}

tensor_roll/fidelity.py

@@ -0,0 +1,349 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Fidelity instrumentation + recursive fidelity search (F5).
+
+The most important measured failure is 3/24 token agreement. This module
+instruments EXACTLY where teacher/student behavior diverges:
+
+  * per-token divergence trace: position, teacher/student tokens,
+    teacher/student top-k, full logits, KL / JS divergence, cosine
+    similarity, entropies, per-layer hidden-state divergence and
+    per-layer attention divergence — all measured on teacher-forced
+    contexts so model divergence is isolated from context drift;
+  * first-divergence detection: the first position AND the first layer
+    producing significant representation drift (not just final tokens);
+  * recursive fidelity search: candidate transforms that save parameters
+    but cause behavioral divergence pay an explicit, measured cost:
+        utility = savings - recon_penalty - logit_penalty
+                  - hidden_penalty - task_penalty
+  * ablations by component (embeddings, attention projections, MLP
+    up/down, norms, output head, quantization) reporting measured
+    evidence — never guesses — about where fidelity is lost.
+
+The fidelity penalty applies UNIFORMLY to every decision class
+(including QUANTUM-ENCODED, scored from its own measured reconstruction
+error). Nothing here touches the quantum scoring to force a winner; the
+experiment still decides.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+from . import core as C
+from .model import forward
+
+
+# ---------------------------------------------------------------------------
+# divergence metrics
+# ---------------------------------------------------------------------------
+
+def _softmax(x: np.ndarray) -> np.ndarray:
+    x = np.asarray(x, dtype=np.float64)
+    x = x - x.max(axis=-1, keepdims=True)
+    e = np.exp(x)
+    return e / e.sum(axis=-1, keepdims=True)
+
+
+def _entropy(p: np.ndarray) -> float:
+    p = np.asarray(p, dtype=np.float64)
+    p = p / p.sum()
+    return float(-(p * np.log(p + 1e-300)).sum())
+
+
+def kl_div(p_logits: np.ndarray, q_logits: np.ndarray) -> float:
+    """KL(softmax(p) || softmax(q))."""
+    p, q = _softmax(p_logits), _softmax(q_logits)
+    return float((p * (np.log(p + 1e-300) - np.log(q + 1e-300))).sum())
+
+
+def js_div(p_logits: np.ndarray, q_logits: np.ndarray) -> float:
+    """Jensen-Shannon divergence between the two softmax distributions."""
+    p, q = _softmax(p_logits), _softmax(q_logits)
+    m = 0.5 * (p + q)
+    kl_pm = float((p * (np.log(p + 1e-300) - np.log(m + 1e-300))).sum())
+    kl_qm = float((q * (np.log(q + 1e-300) - np.log(m + 1e-300))).sum())
+    return 0.5 * (kl_pm + kl_qm)
+
+
+def top_k(logits: np.ndarray, k: int = 5) -> List[Tuple[int, float]]:
+    p = _softmax(logits)
+    idx = np.argsort(p)[::-1][:k]
+    return [(int(i), float(p[i])) for i in idx]
+
+
+# ---------------------------------------------------------------------------
+# divergence trace
+# ---------------------------------------------------------------------------
+
+def divergence_trace(t_params: dict, t_cfg, s_params: dict, s_cfg,
+                     prompt: List[int], max_tokens: int = 24,
+                     top_k_k: int = 5) -> dict:
+    """Per-token teacher/student divergence on teacher-forced contexts.
+
+    1. Teacher free-runs greedy -> reference token sequence.
+    2. Student free-runs greedy -> token agreement count (the 3/24 number).
+    3. At each position, BOTH models run on the teacher's prefix
+       (teacher-forcing), isolating model divergence from context drift.
+    Records per position: tokens, top-k, full logits, KL/JS/cosine,
+    entropies, per-layer hidden-state divergence (rel err + cosine of the
+    final hidden vectors) and per-layer attention divergence
+    (mean |P_student - P_teacher| over heads).
+    """
+    prompt = list(prompt)
+    # --- free runs -------------------------------------------------------
+    t_toks, _, _ = _greedy(t_params, t_cfg, prompt, max_tokens)
+    s_toks, _, _ = _greedy(s_params, s_cfg, prompt, max_tokens)
+    agreement = sum(a == b for a, b in zip(t_toks, s_toks))
+
+    positions = []
+    n_align = min(s_cfg.layers, t_cfg.layers)
+    for i in range(len(t_toks)):
+        ctx = np.array([prompt + t_toks[:i]], dtype=np.int64)
+        tl, tc = forward(t_params, t_cfg, ctx[:, -t_cfg.seq:])
+        sl, sc = forward(s_params, s_cfg, ctx[:, -s_cfg.seq:])
+        t_log = tl[0, -1].astype(np.float64)
+        s_log = sl[0, -1].astype(np.float64)
+        pos = {
+            "position": i,
+            "teacher_token": int(t_toks[i]),
+            "student_token": int(s_toks[i]),
+            "match": bool(t_toks[i] == s_toks[i]),
+            "teacher_topk": top_k(t_log, top_k_k),
+            "student_topk": top_k(s_log, top_k_k),
+            "teacher_logits": [float(x) for x in t_log],
+            "student_logits": [float(x) for x in s_log],
+            "kl_div": kl_div(t_log, s_log),
+            "js_div": js_div(t_log, s_log),
+            "cosine_sim": C.cosine_sim(t_log, s_log),
+            "teacher_entropy": _entropy(_softmax(t_log)),
+            "student_entropy": _entropy(_softmax(s_log)),
+            "hidden_div": {},
+            "attn_div": {},
+        }
+        for l in range(n_align):
+            th = tc[f"L{l}"]["y"] if "y" in tc[f"L{l}"] else tc["f"]
+            sh = sc[f"L{l}"]["y"] if "y" in sc[f"L{l}"] else sc["f"]
+            # align: truncate/pad student hidden to teacher dim (measured)
+            sv = np.asarray(sh[0, -1], dtype=np.float64)
+            tv = np.asarray(th[0, -1], dtype=np.float64)
+            n = min(sv.size, tv.size)
+            pos["hidden_div"][f"layer_{l}"] = {
+                "rel_err": C.relative_error(tv[:n], sv[:n]),
+                "cosine_sim": C.cosine_sim(tv[:n], sv[:n]),
+            }
+            pt = tc[f"L{l}"]["P"][0].mean(axis=0)  # (T,T) mean over heads
+            ps = sc[f"L{l}"]["P"][0].mean(axis=0)
+            nT = min(pt.shape[0], ps.shape[0])
+            pos["attn_div"][f"layer_{l}"] = float(
+                np.abs(pt[:nT, :nT] - ps[:nT, :nT]).mean())
+        positions.append(pos)
+
+    return {"prompt": prompt,
+            "teacher_tokens": [int(x) for x in t_toks],
+            "student_tokens": [int(x) for x in s_toks],
+            "token_agreement": f"{agreement}/{len(t_toks)}",
+            "agreement_count": agreement,
+            "n_tokens": len(t_toks),
+            "positions": positions}
+
+
+def _greedy(params, cfg, prompt, max_tokens):
+    from .model import generate
+    return generate(params, cfg, list(prompt), max_tokens)
+
+
+def first_divergence(trace: dict, *, kl_thresh: float = 0.5,
+                     hidden_thresh: float = 0.35) -> dict:
+    """Locate the FIRST divergence: earliest position where the student
+    token mismatches OR KL exceeds threshold; then the layer with the
+    largest hidden-state relative error at that position — the first
+    layer producing significant representation drift."""
+    for pos in trace["positions"]:
+        if (not pos["match"]) or pos["kl_div"] > kl_thresh:
+            hd = pos["hidden_div"]
+            worst_layer = max(hd.items(),
+                              key=lambda kv: kv[1]["rel_err"])[0]
+            return {
+                "position": pos["position"],
+                "teacher_token": pos["teacher_token"],
+                "student_token": pos["student_token"],
+                "kl_div": pos["kl_div"],
+                "js_div": pos["js_div"],
+                "first_diverging_layer": worst_layer,
+                "layer_hidden_rel_err": hd[worst_layer]["rel_err"],
+                "layer_attn_div": pos["attn_div"].get(worst_layer),
+                "all_layer_hidden_rel_err": {
+                    k: v["rel_err"] for k, v in hd.items()},
+                "above_hidden_thresh": {
+                    k: v["rel_err"] for k, v in hd.items()
+                    if v["rel_err"] > hidden_thresh},
+            }
+    return {"position": None, "note": "no divergence above thresholds"}
+
+
+def render_trace(trace: dict, first: dict) -> List[str]:
+    lines = []
+    for pos in trace["positions"]:
+        mark = "PASS" if pos["match"] else "DIVERGED"
+        lines.append(
+            f"token {pos['position']:2d} {mark:8s} "
+            f"t={pos['teacher_token']:3d} s={pos['student_token']:3d} "
+            f"KL={pos['kl_div']:.3f} JS={pos['js_div']:.3f} "
+            f"cos={pos['cosine_sim']:.3f}")
+    if first.get("position") is not None:
+        lines.append(f"first divergence at position {first['position']}: "
+                     f"layer {first['first_diverging_layer']} "
+                     f"(hidden rel_err={first['layer_hidden_rel_err']:.3f})")
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# ablations — measured evidence per component
+# ---------------------------------------------------------------------------
+
+def _align_to(src: np.ndarray, shape: tuple) -> np.ndarray:
+    out = np.zeros(shape, dtype=np.float32)
+    sl = tuple(slice(0, min(a, b)) for a, b in zip(src.shape, shape))
+    out[sl] = np.asarray(src)[sl]
+    return out
+
+
+COMPONENTS = [
+    ("embeddings", lambda k: k == "emb"),
+    ("attention_projections",
+     lambda k: any(x in k for x in (".Wq", ".Wk", ".Wv", ".bq", ".bk", ".bv"))),
+    ("attention_output",
+     lambda k: any(x in k for x in (".Wo", ".bo"))),
+    ("mlp_up", lambda k: ".W1" in k or ".b1" in k),
+    ("mlp_down", lambda k: ".W2" in k or ".b2" in k),
+    ("normalization",
+     lambda k: any(x in k for x in ("ln1g", "ln1b", "ln2g", "ln2b",
+                                    "lnfg", "lnfb"))),
+    ("output_head", lambda k: k in ("Whead", "bhead")),
+]
+
+
+def ablation_report(t_params: dict, t_cfg, s_params: dict, s_cfg,
+                    prompts: List[List[int]], max_tokens: int = 16) -> dict:
+    """For each component: replace the student's component with the
+    teacher's (shape-aligned), measure token-agreement and mean-KL delta
+    vs the unmodified student. Returns ranked evidence — the component
+    whose restoration helps most is where fidelity is being lost."""
+    base = _agreement_and_kl(t_params, t_cfg, s_params, s_cfg,
+                             prompts, max_tokens)
+    rows = [{"component": "baseline(student)",
+             "agreement": base[0], "mean_kl": base[1], "delta_agree": 0,
+             "n_swapped": 0}]
+    for name, pred in COMPONENTS:
+        variant = dict(s_params)
+        n = 0
+        for k in list(variant.keys()):
+            if pred(k) and k in t_params:
+                variant[k] = _align_to(t_params[k], variant[k].shape)
+                n += 1
+        if n == 0:
+            continue
+        agree, mkl = _agreement_and_kl(t_params, t_cfg, variant, s_cfg,
+                                       prompts, max_tokens)
+        rows.append({"component": name, "agreement": agree, "mean_kl": mkl,
+                     "delta_agree": agree - base[0],
+                     "delta_kl": mkl - base[1], "n_swapped": n})
+    rows.sort(key=lambda r: -r["delta_agree"])
+    return {"baseline": {"agreement": base[0], "mean_kl": base[1]},
+            "ranking": rows}
+
+
+def _agreement_and_kl(t_params, t_cfg, s_params, s_cfg, prompts, max_tokens):
+    agrees, kls, n = 0, [], 0
+    for pr in prompts:
+        tt, _, _ = _greedy(t_params, t_cfg, pr, max_tokens)
+        st, _, _ = _greedy(s_params, s_cfg, pr, max_tokens)
+        agrees += sum(a == b for a, b in zip(tt, st))
+        n += len(tt)
+        for i in range(len(tt)):
+            ctx = np.array([pr + tt[:i]], dtype=np.int64)
+            tl, _ = forward(t_params, t_cfg, ctx[:, -t_cfg.seq:])
+            sl, _ = forward(s_params, s_cfg, ctx[:, -s_cfg.seq:])
+            kls.append(kl_div(tl[0, -1], sl[0, -1]))
+    return agrees / max(1, n), float(np.mean(kls)) if kls else 0.0
+
+
+# ---------------------------------------------------------------------------
+# recursive fidelity search — utility with explicit divergence cost
+# ---------------------------------------------------------------------------
+
+def fidelity_penalty(sensitivity: float, reconstruction_error: float,
+                     lam: float = 1.0) -> float:
+    """Explicit cost for a candidate transform that saves parameters but
+    causes behavioral divergence. Applied uniformly to every decision
+    class from measured (sensitivity, reconstruction_error)."""
+    return float(lam * max(0.0, sensitivity) * max(0.0, reconstruction_error))
+
+
+def fidelity_aware_select(leaves, budget_params: float,
+                          sensitivity: Dict[str, float],
+                          lam: float = 1.0) -> Dict[str, dict]:
+    """Greedy knapsack identical in structure to core.select_plan, but each
+    option's effective energy is
+
+        effective = retained_energy - lam * sensitivity * recon_error
+
+    (clipped at 0). The penalty is computed from MEASURED sensitivity and
+    MEASURED reconstruction error for every option — quantum-gated options
+    included, from their own qsim-measured errors. No decision class is
+    favored or punished beyond what the measurements say.
+    """
+    srt = []
+    for leaf in leaves:
+        sens = float(sensitivity.get(leaf.name, 0.5))
+        adj = []
+        for o in leaf.options:
+            pen = fidelity_penalty(sens, o["reconstruction_error"], lam)
+            eff = max(0.0, o["retained_energy"] - pen)
+            adj.append({**o, "effective_energy": eff,
+                        "fidelity_penalty": pen})
+        adj.sort(key=lambda o: o["cost_params"])
+        srt.append(adj)
+    choice = [0] * len(srt)
+    total = sum(s[0]["cost_params"] for s in srt)
+    improved = True
+    while improved:
+        improved = False
+        best_gain, best_move = 0.0, None
+        for i, opts in enumerate(srt):
+            cur = choice[i]
+            for j in range(cur + 1, len(opts)):
+                dcost = opts[j]["cost_params"] - opts[cur]["cost_params"]
+                denergy = (opts[j]["effective_energy"]
+                           - opts[cur]["effective_energy"])
+                if total + dcost <= budget_params and dcost > 0 and denergy > 0:
+                    gain = denergy / dcost
+                    if gain > best_gain:
+                        best_gain, best_move = gain, (i, j, dcost)
+        if best_move:
+            i, j, dcost = best_move
+            choice[i] = j
+            total += dcost
+            improved = True
+    plan = {}
+    for i, leaf in enumerate(leaves):
+        plan[leaf.name] = srt[i][choice[i]]
+    plan["_total_cost_params"] = total
+    plan["_budget_params"] = float(budget_params)
+    plan["_fidelity_lambda"] = float(lam)
+    return plan
+
+
+def utility_breakdown(savings_params: int, penalties: dict) -> dict:
+    """utility = savings - recon - logit - hidden - task penalties.
+    All inputs measured; returns the itemized breakdown."""
+    u = (savings_params - penalties.get("reconstruction", 0.0)
+         - penalties.get("logit", 0.0) - penalties.get("hidden", 0.0)
+         - penalties.get("task", 0.0))
+    return {"utility": float(u), "savings_params": int(savings_params),
+            **{k: float(v) for k, v in penalties.items()}}

tensor_roll/ir.py

@@ -0,0 +1,367 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""TensorRoll IR: the backend-neutral plan representation.
+
+A roll plan ({tensor_name: {decision, cost_params, ...}}) compiles to a
+list of IROps. ``lower(ops, backend)`` then maps the plan onto a concrete
+backend:
+
+  * ``cpu``    — REALLY executes the classical ops (LOAD/SLICE/GEMM/
+                 QUANTIZE/FACTOR) with NumPy, and the quantum-family ops
+                 (ROLL/ROTATE/ENTANGLE/MEASURE/RECONSTRUCT) with the real
+                 qsim-classical statevector simulator. Execution records
+                 carry measured milliseconds and output digests.
+  * ``cuda`` / ``cuda-q`` / ``qsharp`` — return per-op records with state
+                 NOT EXECUTED, a reason, and the source-verification state
+                 (VERIFIED/PRESENT) of the corresponding kernel source.
+                 For ``cuda-q``/``qsharp``, ROTATE/ENTANGLE/MEASURE records
+                 reference the real gate-trace schema from
+                 ``tensor_roll/boundary.py``. This is IR-specification
+                 only: no in-memory ABI between this IR and any vendor
+                 kernel is claimed — exchange happens via the checksummed
+                 file artifact until a toolchain executes the kernels.
+
+The IR never invents numbers for backends it cannot run.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from . import boundary as BD
+from . import quant as QT
+from . import qsim as QSIM
+from .doctor import verify_sources
+
+IR_VERSION = 1
+
+VALID_OPS = ("LOAD", "SLICE", "ROLL", "FACTOR", "ROTATE", "ENTANGLE",
+             "MEASURE", "RECONSTRUCT", "GEMM", "QUANTIZE", "EMIT")
+
+_CPU_BACKENDS = ("cpu-numpy", "qsim-classical")
+
+#: IROp -> boundary kernel name for the quantum-family ops (used when
+#: lowering to cuda-q / qsharp so records reference the real gate schema).
+_OP_KERNEL = {
+    "ROTATE": "tensor_roll_rotate",
+    "ENTANGLE": "tensor_roll_entangle",
+    "MEASURE": "tensor_roll_measure",
+    "RECONSTRUCT": "tensor_roll_reconstruct",
+    "ROLL": "tensor_roll_recursive",
+}
+
+#: which audited source file backs each non-cpu backend
+_BACKEND_SOURCE = {"cuda": "CUDA source", "cuda-q": "CUDA-Q source",
+                   "qsharp": "Q# source"}
+
+_NOT_EXECUTED_REASON = {
+    "cuda": ("no CUDA device, no nvidia-smi, no nvcc on this machine; "
+             "lowering to CUDA is a plan only — cuda/tensor_roll_gemm.cu "
+             "was not compiled or executed"),
+    "cuda-q": ("no CUDA-Q toolchain on this machine; lowering to cuda-q is "
+               "IR-specification only until a toolchain executes "
+               "cudaq/tensor_roll_kernels.py"),
+    "qsharp": ("no Q# toolchain (and no dotnet) on this machine; lowering "
+               "to qsharp is IR-specification only until a toolchain "
+               "executes qsharp/TensorRoll.qs"),
+}
+
+
+@dataclass
+class IROp:
+    op: str
+    inputs: List[str] = field(default_factory=list)
+    outputs: List[str] = field(default_factory=list)
+    params: Dict[str, Any] = field(default_factory=dict)
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.op not in VALID_OPS:
+            raise ValueError(f"unknown IR op {self.op!r}; valid: {VALID_OPS}")
+        self.inputs = list(self.inputs)
+        self.outputs = list(self.outputs)
+        self.params = dict(self.params)
+        self.meta = dict(self.meta)
+
+
+# ---------------------------------------------------------------------------
+# Plan -> IR
+# ---------------------------------------------------------------------------
+
+def _decision_ops(name: str, cur: str, decision: str,
+                  cost: Dict[str, Any]) -> Tuple[List[IROp], str]:
+    """Per-decision op sequence. Returns (ops, current_value_name)."""
+    ops: List[IROp] = []
+    if decision == "QUANTIZE":
+        ops.append(IROp("QUANTIZE", [cur], [f"q:{name}"],
+                        {"bits": int(cost.get("bits", 8))},
+                        {"decision": decision}))
+        cur = f"q:{name}"
+    elif decision == "FACTORIZE":
+        ops.append(IROp("FACTOR", [cur], [f"f:{name}"],
+                        {"rank": int(cost.get("rank", 4))},
+                        {"decision": decision}))
+        cur = f"f:{name}"
+    elif decision == "QUANTUM-ENCODED":
+        nq = int(cost.get("n_qubits", 3))
+        angles = [float(a) for a in
+                  cost.get("angles", [0.3] * nq)]
+        ops.append(IROp("ROTATE", [cur], [f"qr:{name}"],
+                        {"angles": angles, "n_qubits": nq},
+                        {"decision": decision,
+                         "backend": "qsim-classical"}))
+        ops.append(IROp("ENTANGLE", [f"qr:{name}"], [f"qe:{name}"], {},
+                        {"decision": decision}))
+        ops.append(IROp("MEASURE", [f"qe:{name}"], [f"qm:{name}"],
+                        {"shots": int(cost.get("shots", 256)),
+                         "seed": int(cost.get("seed", 0))},
+                        {"decision": decision}))
+        ops.append(IROp("RECONSTRUCT", [f"qm:{name}"], [f"qc:{name}"],
+                        {}, {"decision": decision,
+                             "note": "classical reconstruction by construction"}))
+        cur = f"qc:{name}"
+    else:
+        # PRESERVE / MERGED / ROUTED / RECONSTRUCTED / PRUNED and anything
+        # else: no transform op invented; the decision rides in meta.
+        ops.append(IROp("EMIT", [cur], [f"out:{name}"],
+                        {"artifact": f"{name}.json"},
+                        {"decision": decision,
+                         "note": "pass-through: no transform op for this decision"}))
+        return ops, f"out:{name}"
+    ops.append(IROp("EMIT", [cur], [f"out:{name}"],
+                    {"artifact": f"{name}.json"},
+                    {"decision": decision}))
+    return ops, f"out:{name}"
+
+
+def build_ir(roll_plan: Dict[str, Dict[str, Any]]) -> List[IROp]:
+    """Compile a roll plan ({tensor: {decision, cost_params, ...}}) to IR.
+
+    Per tensor: LOAD -> ROLL -> per-decision op(s) -> EMIT.
+    """
+    ops: List[IROp] = []
+    for name, spec in roll_plan.items():
+        spec = spec or {}
+        decision = str(spec.get("decision", "PRESERVE"))
+        cost = dict(spec.get("cost_params", {}))
+        ops.append(IROp("LOAD", [], [f"t:{name}"],
+                        {"tensor": name}, {"source": "roll_plan"}))
+        ops.append(IROp("ROLL", [f"t:{name}"], [f"r:{name}"],
+                        {"depth": int(cost.get("depth", 1))},
+                        {"note": "recursive partition/transform step"}))
+        dops, _ = _decision_ops(name, f"r:{name}", decision, cost)
+        ops.extend(dops)
+    return ops
+
+
+def to_json(ops: List[IROp]) -> Dict[str, Any]:
+    return {"ir_version": IR_VERSION,
+            "ops": [asdict(op) for op in ops]}
+
+
+def from_json(doc: Dict[str, Any]) -> List[IROp]:
+    if doc.get("ir_version") != IR_VERSION:
+        raise ValueError(f"unsupported IR version {doc.get('ir_version')!r}")
+    return [IROp(**item) for item in doc["ops"]]
+
+
+# ---------------------------------------------------------------------------
+# Lowering
+# ---------------------------------------------------------------------------
+
+def _arr_sha256(a: np.ndarray) -> str:
+    return hashlib.sha256(np.ascontiguousarray(a).tobytes()).hexdigest()
+
+
+def _lower_cpu(ops: List[IROp]) -> List[Dict[str, Any]]:
+    vals: Dict[str, np.ndarray] = {}
+    payloads: Dict[str, Dict] = {}
+    records: List[Dict[str, Any]] = []
+
+    def payload_for(name: str) -> Dict:
+        if name in payloads:
+            return payloads[name]
+        arr = vals.get(name)
+        if arr is None:
+            raise KeyError(f"no array or payload named {name!r}")
+        if arr.size > 256:
+            raise ValueError(
+                f"quantum-family op on {arr.size} elements exceeds the "
+                "256-element eligibility cap; refusing")
+        p, _ = QSIM.tensor_roll_encode(arr, encoding="amplitude")
+        return p
+
+    for seq, op in enumerate(ops):
+        t0 = time.perf_counter()
+        rec: Dict[str, Any] = {"seq": seq, "op": op.op,
+                               "inputs": op.inputs, "outputs": op.outputs}
+        try:
+            if op.op == "LOAD":
+                data = op.params.get("data")
+                if data is None:
+                    raise ValueError(
+                        "LOAD has no params['data'] — nothing to execute")
+                arr = np.asarray(data, dtype=np.float64)
+                if "shape" in op.params:
+                    arr = arr.reshape(op.params["shape"])
+                vals[op.outputs[0]] = arr
+                rec.update(state="EXECUTED", backend="cpu-numpy",
+                           detail={"shape": list(arr.shape)})
+            elif op.op == "SLICE":
+                src = vals[op.inputs[0]]
+                # params["slices"]: per-dim [lo, hi] pair, or null for full dim
+                sel = tuple(slice(p[0], p[1]) if isinstance(p, (list, tuple))
+                            else slice(None)
+                            for p in op.params["slices"])
+                vals[op.outputs[0]] = src[sel]
+                rec.update(state="EXECUTED", backend="cpu-numpy",
+                           detail={"shape": list(vals[op.outputs[0]].shape)})
+            elif op.op == "GEMM":
+                C = vals[op.inputs[0]] @ vals[op.inputs[1]]
+                vals[op.outputs[0]] = C
+                rec.update(state="EXECUTED", backend="cpu-numpy",
+                           detail={"shape": list(C.shape),
+                                   "checksum": float(C.sum()),
+                                   "sha256": _arr_sha256(C)})
+            elif op.op == "QUANTIZE":
+                q, meta = QT.quantize_int8(vals[op.inputs[0]])
+                vals[op.outputs[0]] = q.astype(np.float64)
+                rec.update(state="EXECUTED", backend="cpu-numpy",
+                           detail={"fmt": meta["fmt"], "scale": meta["scale"],
+                                   "codes_sha256": _arr_sha256(q)})
+            elif op.op == "FACTOR":
+                W = vals[op.inputs[0]]
+                r = int(op.params.get("rank", 2))
+                U, S, Vt = np.linalg.svd(W.astype(np.float64),
+                                         full_matrices=False)
+                What = (U[:, :r] * S[:r]) @ Vt[:r, :]
+                vals[op.outputs[0]] = What
+                denom = float(np.linalg.norm(W))
+                err = float(np.linalg.norm(W - What) / denom) if denom else 0.0
+                rec.update(state="EXECUTED", backend="cpu-numpy",
+                           detail={"rank": r,
+                                   "relative_error": err,
+                                   "sha256": _arr_sha256(What)})
+            elif op.op == "ROLL":
+                arr = vals[op.inputs[0]]
+                if arr.size > 256:
+                    raise ValueError(
+                        f"ROLL on {arr.size} elements exceeds the 256-element "
+                        "quantum-eligibility cap; refusing")
+                What, rep = QSIM.tensor_roll_recursive(
+                    arr, depth=int(op.params.get("depth", 1)),
+                    shots=int(op.params.get("shots", 256)),
+                    seed=int(op.params.get("seed", 0)))
+                vals[op.outputs[0]] = What
+                rec.update(state="EXECUTED", backend="qsim-classical",
+                           detail={"kernel": "tensor_roll_recursive",
+                                   "reconstruction_error":
+                                       rep.get("reconstruction_error"),
+                                   "sha256": _arr_sha256(What)})
+            elif op.op == "ROTATE":
+                p = payload_for(op.inputs[0])
+                p2, rep = QSIM.tensor_roll_rotate(
+                    p, angles=op.params["angles"])
+                payloads[op.outputs[0]] = p2
+                rec.update(state="EXECUTED", backend="qsim-classical",
+                           detail={"kernel": "tensor_roll_rotate"})
+            elif op.op == "ENTANGLE":
+                p = payload_for(op.inputs[0])
+                p2, _ = QSIM.tensor_roll_entangle(p)
+                payloads[op.outputs[0]] = p2
+                rec.update(state="EXECUTED", backend="qsim-classical",
+                           detail={"kernel": "tensor_roll_entangle"})
+            elif op.op == "MEASURE":
+                p = payload_for(op.inputs[0])
+                p2, rep = QSIM.tensor_roll_measure(
+                    p, shots=int(op.params.get("shots", 256)),
+                    seed=int(op.params.get("seed", 0)))
+                payloads[op.outputs[0]] = p2
+                stats = rep.get("measurement_stats") or {}
+                rec.update(state="EXECUTED", backend="qsim-classical",
+                           detail={"kernel": "tensor_roll_measure",
+                                   "shots": int(op.params.get("shots", 256)),
+                                   "n_outcomes": stats.get("n_outcomes"),
+                                   "top_p": stats.get("top_p")})
+            elif op.op == "RECONSTRUCT":
+                p = payload_for(op.inputs[0])
+                if "counts" not in p:
+                    raise ValueError(
+                        "RECONSTRUCT needs a measured payload (run MEASURE first)")
+                What, _ = QSIM.tensor_roll_reconstruct(p)
+                vals[op.outputs[0]] = What
+                rec.update(state="EXECUTED", backend="qsim-classical",
+                           detail={"kernel": "tensor_roll_reconstruct",
+                                   "shape": list(What.shape),
+                                   "sha256": _arr_sha256(What)})
+            elif op.op == "EMIT":
+                arr = vals.get(op.inputs[0])
+                if arr is None:
+                    raise ValueError(
+                        f"EMIT input {op.inputs[0]!r} was never produced")
+                vals[op.outputs[0]] = arr
+                rec.update(state="EXECUTED", backend="cpu-numpy",
+                           detail={"artifact": op.params.get("artifact"),
+                                   "shape": list(arr.shape),
+                                   "sha256": _arr_sha256(arr)})
+            else:  # pragma: no cover - constructor guards VALID_OPS
+                raise ValueError(f"no cpu lowering for {op.op}")
+        except Exception as exc:  # noqa: BLE001 - record, don't crash
+            rec.update(state="FAILED",
+                       reason=f"{type(exc).__name__}: {exc}")
+        rec["ms"] = round((time.perf_counter() - t0) * 1000.0, 3)
+        records.append(rec)
+    return records
+
+
+def _lower_not_executed(ops: List[IROp], backend: str) -> List[Dict[str, Any]]:
+    sources = verify_sources()
+    src_state = sources[_BACKEND_SOURCE[backend]]["state"]
+    records: List[Dict[str, Any]] = []
+    for seq, op in enumerate(ops):
+        rec: Dict[str, Any] = {
+            "seq": seq, "op": op.op, "inputs": op.inputs,
+            "outputs": op.outputs, "backend": backend,
+            "state": "NOT EXECUTED",
+            "reason": _NOT_EXECUTED_REASON[backend],
+            "source": src_state,
+            "source_path": sources[_BACKEND_SOURCE[backend]]["path"],
+        }
+        if backend in ("cuda-q", "qsharp") and op.op in _OP_KERNEL:
+            # Reference the REAL gate-trace schema: this is what the vendor
+            # kernel would have to implement. IR-specification only — no
+            # ABI compatibility is asserted (see module docstring).
+            kernel = _OP_KERNEL[op.op]
+            nq = int(op.params.get("n_qubits",
+                                   len(op.params.get("angles", [0.3, 0.3]))))
+            rec["gate_trace_schema"] = BD.TRACE_SCHEMA
+            rec["gate_trace"] = BD.trace_for_kernel(kernel, max(1, nq))
+            rec["note"] = ("IR-specification only: references the boundary "
+                           "gate-trace schema; asserts no in-memory ABI "
+                           "compatibility with vendor kernels. Exchange "
+                           "happens via the checksummed file artifact "
+                           "(tensor_roll/boundary.py) until a toolchain "
+                           "executes the kernels.")
+        records.append(rec)
+    return records
+
+
+def lower(ops: List[IROp], backend: str) -> List[Dict[str, Any]]:
+    """Lower IR ops to *backend*. Returns per-op execution records.
+
+    ``cpu`` executes for real (NumPy + qsim-classical). ``cuda``,
+    ``cuda-q`` and ``qsharp`` return NOT EXECUTED records with reasons —
+    a plan, not a fabrication.
+    """
+    if backend == "cpu":
+        return _lower_cpu(ops)
+    if backend in ("cuda", "cuda-q", "qsharp"):
+        return _lower_not_executed(ops, backend)
+    raise ValueError(f"unknown backend {backend!r}; "
+                     "expected 'cpu', 'cuda', 'cuda-q' or 'qsharp'")

tensor_roll/model.py

@@ -0,0 +1,426 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Tiny transformer implemented from scratch in NumPy (forward + backward).
+
+This is the empirical validation vehicle: a small teacher is trained on
+synthetic data, then the ENTIRE Tensor Roll pipeline (roll -> compress ->
+distill -> finetune -> quantize -> .trq -> sandboxed inference) runs on it.
+Same code path as the 30B scale-up; only the config and data change.
+No torch / transformers / llama.cpp anywhere in this file.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import numpy as np
+
+DTYPE = np.float32
+EPS = 1e-5
+
+
+@dataclass
+class Config:
+    vocab: int = 32
+    d: int = 48
+    heads: int = 3
+    layers: int = 2
+    dff: int = 96
+    seq: int = 16
+
+    @property
+    def dh(self) -> int:
+        assert self.d % self.heads == 0
+        return self.d // self.heads
+
+    def to_dict(self):
+        return {"vocab": self.vocab, "d": self.d, "heads": self.heads,
+                "layers": self.layers, "dff": self.dff, "seq": self.seq}
+
+    @staticmethod
+    def from_dict(d):
+        return Config(**d)
+
+
+def count_params(params: dict) -> int:
+    return int(sum(v.size for v in params.values()))
+
+
+def init_params(rng: np.random.Generator, cfg: Config) -> dict:
+    def xavier(shape):
+        fan = shape[0] + shape[1] if len(shape) == 2 else shape[0]
+        lim = np.sqrt(6.0 / fan)
+        return rng.uniform(-lim, lim, size=shape).astype(DTYPE)
+
+    p = {"emb": xavier((cfg.vocab, cfg.d))}
+    for l in range(cfg.layers):
+        p[f"L{l}.ln1g"] = np.ones(cfg.d, dtype=DTYPE)
+        p[f"L{l}.ln1b"] = np.zeros(cfg.d, dtype=DTYPE)
+        for nm in ("Wq", "Wk", "Wv", "Wo"):
+            p[f"L{l}.{nm}"] = xavier((cfg.d, cfg.d))
+            p[f"L{l}.b{nm[1:]}"] = np.zeros(cfg.d, dtype=DTYPE)
+        p[f"L{l}.ln2g"] = np.ones(cfg.d, dtype=DTYPE)
+        p[f"L{l}.ln2b"] = np.zeros(cfg.d, dtype=DTYPE)
+        p[f"L{l}.W1"] = xavier((cfg.d, cfg.dff))
+        p[f"L{l}.b1"] = np.zeros(cfg.dff, dtype=DTYPE)
+        p[f"L{l}.W2"] = xavier((cfg.dff, cfg.d))
+        p[f"L{l}.b2"] = np.zeros(cfg.d, dtype=DTYPE)
+    p["lnfg"] = np.ones(cfg.d, dtype=DTYPE)
+    p["lnfb"] = np.zeros(cfg.d, dtype=DTYPE)
+    p["Whead"] = xavier((cfg.d, cfg.vocab))
+    p["bhead"] = np.zeros(cfg.vocab, dtype=DTYPE)
+    return p
+
+
+# ---------------------------------------------------------------------------
+# Forward
+# ---------------------------------------------------------------------------
+
+def _ln_forward(x, g, b):
+    mean = x.mean(axis=-1, keepdims=True)
+    var = x.var(axis=-1, keepdims=True)
+    std = np.sqrt(var + EPS)
+    xh = (x - mean) / std
+    return g * xh + b, (x, xh, std, g)
+
+
+def _ln_backward(dy, cache):
+    x, xh, std, g = cache
+    n_feat = x.shape[-1]
+    dxh = dy * g
+    dvar = np.sum(dxh * (x - x.mean(axis=-1, keepdims=True))
+                  * -0.5 * (std ** -3), axis=-1, keepdims=True)
+    dmean = (np.sum(dxh * -1.0 / std, axis=-1, keepdims=True)
+             + dvar * np.mean(-2.0 * (x - x.mean(axis=-1, keepdims=True)), axis=-1, keepdims=True))
+    dx = dxh / std + dvar * 2.0 * (x - x.mean(axis=-1, keepdims=True)) / n_feat + dmean / n_feat
+    dg = np.sum(dy * xh, axis=(0, 1))
+    db = np.sum(dy, axis=(0, 1))
+    return dx, dg, db
+
+
+def _softmax(x, axis=-1):
+    x = x - x.max(axis=axis, keepdims=True)
+    e = np.exp(x)
+    return e / e.sum(axis=axis, keepdims=True)
+
+
+def forward(params: dict, cfg: Config, ids: np.ndarray):
+    """Returns (logits, cache). ids: (B,T) int."""
+    B, T = ids.shape
+    H, dh = cfg.heads, cfg.dh
+    cache: dict = {"ids": ids}
+    x = params["emb"][ids]  # (B,T,d)
+
+    cmask = np.zeros((T, T), dtype=DTYPE)
+    cmask[np.triu_indices(T, k=1)] = -1e9
+
+    for l in range(cfg.layers):
+        c: dict = {"x_prev": x}
+        h, c["ln1"] = _ln_forward(x, params[f"L{l}.ln1g"], params[f"L{l}.ln1b"])
+        Q = (h @ params[f"L{l}.Wq"] + params[f"L{l}.bq"]).reshape(B, T, H, dh)
+        K = (h @ params[f"L{l}.Wk"] + params[f"L{l}.bk"]).reshape(B, T, H, dh)
+        V = (h @ params[f"L{l}.Wv"] + params[f"L{l}.bv"]).reshape(B, T, H, dh)
+        s = np.einsum("bthd,bshd->bhts", Q, K) / np.sqrt(dh) + cmask[None, None, :, :]
+        P = _softmax(s)
+        A = np.einsum("bhts,bshd->bthd", P, V).reshape(B, T, cfg.d)
+        O = A @ params[f"L{l}.Wo"] + params[f"L{l}.bo"]
+        y = x + O
+        z, c["ln2"] = _ln_forward(y, params[f"L{l}.ln2g"], params[f"L{l}.ln2b"])
+        u = z @ params[f"L{l}.W1"] + params[f"L{l}.b1"]
+        a = np.maximum(u, 0)
+        m_ = a @ params[f"L{l}.W2"] + params[f"L{l}.b2"]
+        x = y + m_
+        c.update({"h": h, "Q": Q, "K": K, "V": V, "P": P, "A": A,
+                  "y": y, "z": z, "u": u, "a": a})
+        cache[f"L{l}"] = c
+    f, cache["lnf"] = _ln_forward(x, params["lnfg"], params["lnfb"])
+    cache["f"] = f
+    cache["x_pre_lnf"] = x
+    logits = f @ params["Whead"] + params["bhead"]
+    return logits, cache
+
+
+def backward(params: dict, cfg: Config, cache: dict, dlogits: np.ndarray,
+             d_hiddens: dict | None = None, d_attn: dict | None = None) -> dict:
+    """dlogits: (B,T,V). d_hiddens: {layer_idx: (B,T,d) upstream grad added
+    at that layer's output} for hidden-state matching. d_attn: {layer_idx:
+    (B,H,T,T) upstream grad added to attention probs} for attention matching."""
+    B, T = cache["ids"].shape
+    grads = {}
+    f = cache["f"]
+    grads["Whead"] = np.einsum("btd,btv->dv", f, dlogits)
+    grads["bhead"] = dlogits.sum(axis=(0, 1))
+    df = dlogits @ params["Whead"].T
+    dx, dg, db = _ln_backward(df, cache["lnf"])
+    grads["lnfg"], grads["lnfb"] = dg, db
+
+    for l in reversed(range(cfg.layers)):
+        c = cache[f"L{l}"]
+        if d_hiddens and l in d_hiddens:
+            dx = dx + d_hiddens[l]
+        # x = y + m ; m = a@W2+b2
+        dy = dx.copy()
+        dm = dx
+        A = c["A"]
+        grads[f"L{l}.W2"] = np.einsum("bti,btj->ij", c["a"], dm)
+        grads[f"L{l}.b2"] = dm.sum(axis=(0, 1))
+        da = dm @ params[f"L{l}.W2"].T
+        du = da * (c["u"] > 0)
+        grads[f"L{l}.W1"] = np.einsum("bti,btj->ij", c["z"], du)
+        grads[f"L{l}.b1"] = du.sum(axis=(0, 1))
+        dz = du @ params[f"L{l}.W1"].T
+        dy2, dg2, db2 = _ln_backward(dz, c["ln2"])
+        grads[f"L{l}.ln2g"], grads[f"L{l}.ln2b"] = dg2, db2
+        dy = dy + dy2
+        # y = x_prev + O ; O = A@Wo+bo
+        dx_prev = dy.copy()
+        dO = dy
+        grads[f"L{l}.Wo"] = np.einsum("bti,btj->ij", A, dO)
+        grads[f"L{l}.bo"] = dO.sum(axis=(0, 1))
+        dA = (dO @ params[f"L{l}.Wo"].T).reshape(B, T, cfg.heads, cfg.dh)
+        Q, K, V, P = c["Q"], c["K"], c["V"], c["P"]
+        dP = np.einsum("bthd,bshd->bhts", dA, V)
+        if d_attn is not None and l in d_attn:
+            dP = dP + d_attn[l]
+        dV = np.einsum("bhts,bthd->bshd", P, dA)
+        dS = P * (dP - (dP * P).sum(axis=-1, keepdims=True))
+        inv = 1.0 / np.sqrt(cfg.dh)
+        dQ = np.einsum("bhts,bshd->bthd", dS, K) * inv
+        dK = np.einsum("bhts,bthd->bshd", dS, Q) * inv
+        h = c["h"]
+        for nm, dM in (("Wq", dQ), ("Wk", dK), ("Wv", dV)):
+            dM2 = dM.reshape(B, T, cfg.d)
+            grads[f"L{l}.{nm}"] = np.einsum("bti,btj->ij", h, dM2)
+            grads[f"L{l}.b{nm[1:]}"] = dM2.sum(axis=(0, 1))
+            dx_prev = dx_prev + dM2 @ params[f"L{l}.{nm}"].T
+        dh, dg1, db1 = _ln_backward(dx_prev, c["ln1"])
+        grads[f"L{l}.ln1g"], grads[f"L{l}.ln1b"] = dg1, db1
+        dx = dh  # grad w.r.t. this layer's input = next (previous) layer's output grad
+    dEmb = np.zeros_like(params["emb"])
+    np.add.at(dEmb, cache["ids"], dx)
+    grads["emb"] = dEmb
+    return grads
+
+
+# ---------------------------------------------------------------------------
+# Losses
+# ---------------------------------------------------------------------------
+
+def ce_loss(logits: np.ndarray, targets: np.ndarray):
+    """Mean softmax cross-entropy. Returns (loss, dlogits)."""
+    B, T, V = logits.shape
+    x = logits.reshape(-1, V).astype(np.float64)
+    t = targets.reshape(-1)
+    x = x - x.max(axis=1, keepdims=True)
+    logp = x - np.log(np.exp(x).sum(axis=1, keepdims=True))
+    loss = float(-logp[np.arange(t.size), t].mean())
+    d = np.exp(logp)
+    d[np.arange(t.size), t] -= 1.0
+    d /= t.size
+    return loss, d.reshape(B, T, V).astype(DTYPE)
+
+
+def kl_loss(s_logits: np.ndarray, t_logits: np.ndarray, tau: float = 2.0):
+    """tau^2 * mean KL(softmax(t/tau) || softmax(s/tau)). Returns (loss, dlogits_s)."""
+    B, T, V = s_logits.shape
+    s = (s_logits / tau).reshape(-1, V).astype(np.float64)
+    t = (t_logits / tau).reshape(-1, V).astype(np.float64)
+    s = s - s.max(1, keepdims=True)
+    t = t - t.max(1, keepdims=True)
+    log_q = s - np.log(np.exp(s).sum(1, keepdims=True))
+    log_p = t - np.log(np.exp(t).sum(1, keepdims=True))
+    p = np.exp(log_p)
+    kl = (p * (log_p - log_q)).sum(1).mean()
+    loss = float(tau * tau * kl)
+    d = (np.exp(log_q) - p) * tau / p.shape[0]
+    return loss, d.reshape(B, T, V).astype(DTYPE)
+
+
+def kl_divergence_mean(t_logits: np.ndarray, s_logits: np.ndarray) -> float:
+    """Mean KL(teacher || student) at tau=1 — teacher-divergence metric."""
+    t = t_logits.reshape(-1, t_logits.shape[-1]).astype(np.float64)
+    s = s_logits.reshape(-1, s_logits.shape[-1]).astype(np.float64)
+    t = t - t.max(1, keepdims=True)
+    s = s - s.max(1, keepdims=True)
+    log_p = t - np.log(np.exp(t).sum(1, keepdims=True))
+    log_q = s - np.log(np.exp(s).sum(1, keepdims=True))
+    p = np.exp(log_p)
+    return float((p * (log_p - log_q)).sum(1).mean())
+
+
+# ---------------------------------------------------------------------------
+# Optimizer
+# ---------------------------------------------------------------------------
+
+class Adam:
+    def __init__(self, params: dict, lr: float = 3e-3,
+                 beta1: float = 0.9, beta2: float = 0.999, eps: float = 1e-8):
+        self.lr = lr
+        self.b1, self.b2, self.eps = beta1, beta2, eps
+        self.m = {k: np.zeros_like(v) for k, v in params.items()}
+        self.v = {k: np.zeros_like(v) for k, v in params.items()}
+        self.t = 0
+
+    def step(self, params: dict, grads: dict):
+        self.t += 1
+        for k in params:
+            g = grads[k].astype(np.float64)
+            self.m[k] = self.b1 * self.m[k] + (1 - self.b1) * g
+            self.v[k] = self.b2 * self.v[k] + (1 - self.b2) * g * g
+            mh = self.m[k] / (1 - self.b1 ** self.t)
+            vh = self.v[k] / (1 - self.b2 ** self.t)
+            params[k] = (params[k].astype(np.float64)
+                         - self.lr * mh / (np.sqrt(vh) + self.eps)).astype(DTYPE)
+
+
+# ---------------------------------------------------------------------------
+# Synthetic data + training
+# ---------------------------------------------------------------------------
+
+def gen_data(rng: np.random.Generator, n: int, cfg: Config) -> np.ndarray:
+    """Deterministic grammar: x[t] = (3*x[t-1] + 5*x[t-2] + 7) mod V."""
+    ids = np.zeros((n, cfg.seq), dtype=np.int64)
+    ids[:, 0] = rng.integers(0, cfg.vocab, size=n)
+    ids[:, 1] = rng.integers(0, cfg.vocab, size=n)
+    for t in range(2, cfg.seq):
+        ids[:, t] = (3 * ids[:, t - 1] + 5 * ids[:, t - 2] + 7) % cfg.vocab
+    return ids
+
+
+def train_teacher(cfg: Config, *, steps: int, batch: int, lr: float,
+                  seed: int, log_every: int = 100):
+    rng = np.random.default_rng(seed)
+    params = init_params(rng, cfg)
+    opt = Adam(params, lr=lr)
+    history = []
+    t0 = time.perf_counter()
+    for step in range(1, steps + 1):
+        ids = gen_data(rng, batch, cfg)
+        logits, cache = forward(params, cfg, ids[:, :-1])
+        loss, dl = ce_loss(logits, ids[:, 1:])
+        grads = backward(params, cfg, cache, dl)
+        opt.step(params, grads)
+        if step % log_every == 0 or step == steps:
+            history.append({"step": step, "loss": loss,
+                            "elapsed_s": time.perf_counter() - t0})
+    return params, history
+
+
+def eval_metrics(params: dict, cfg: Config, *, batches: int = 8,
+                 batch: int = 256, seed: int = 999):
+    """Real held-out accuracy + loss on the synthetic grammar."""
+    rng = np.random.default_rng(seed)
+    tot_loss, tot_correct, tot_n = 0.0, 0, 0
+    for _ in range(batches):
+        ids = gen_data(rng, batch, cfg)
+        logits, _ = forward(params, cfg, ids[:, :-1])
+        loss, _ = ce_loss(logits, ids[:, 1:])
+        pred = logits.argmax(axis=-1)
+        tot_loss += loss
+        tot_correct += int((pred == ids[:, 1:]).sum())
+        tot_n += batch
+    return {"loss": tot_loss / batches, "accuracy": tot_correct / (tot_n * (cfg.seq - 1))}
+
+
+def _act_input(name: str, cache: dict, cfg: Config):
+    """Input activation feeding the op that owns tensor `name`, taken from
+    a real forward cache. Returns None when not attributable."""
+    if name == "emb":
+        return cache["L0"]["x_prev"]
+    if name in ("Whead", "bhead"):
+        return cache["f"]
+    if name in ("lnfg", "lnfb"):
+        return cache["x_pre_lnf"]
+    if name.startswith("L"):
+        _, rest = name.split(".", 1)
+        l = name[1:].split(".")[0]
+        c = cache[f"L{l}"]
+        if rest in ("Wq", "Wk", "Wv", "bq", "bk", "bv"):
+            return c["h"]
+        if rest in ("Wo", "bo"):
+            return c["A"]
+        if rest in ("W1", "b1"):
+            return c["z"]
+        if rest in ("W2", "b2"):
+            return c["a"]
+        if rest in ("ln1g", "ln1b"):
+            return c["x_prev"]
+        if rest in ("ln2g", "ln2b"):
+            return c["y"]
+    return None
+
+
+def measure_tensor_stats(params: dict, cfg: Config, batches: int = 4,
+                         batch: int = 64, seed: int = 0) -> dict:
+    """Measured per-tensor contributions over real forward/backward passes.
+
+    activation contribution: RMS of the input activation feeding each
+        tensor's op, averaged over batches (from the forward cache).
+    gradient contribution: mean Frobenius norm of the tensor's gradient,
+        plus the relative ||grad|| / ||W||.
+    Returns {tensor_name: {"act_rms": float, "grad_norm": float,
+                           "grad_rel": float}}.
+    """
+    rng = np.random.default_rng(seed)
+    acc_a, acc_g, n = {}, {}, 0
+    for _ in range(batches):
+        ids = gen_data(rng, batch, cfg)
+        logits, cache = forward(params, cfg, ids[:, :-1])
+        _, dlogits = ce_loss(logits, ids[:, 1:])
+        grads = backward(params, cfg, cache, dlogits)
+        n += 1
+        for k, W in params.items():
+            ai = _act_input(k, cache, cfg)
+            if ai is not None:
+                v = float(np.sqrt(np.mean(np.asarray(ai, dtype=np.float64) ** 2)))
+                acc_a[k] = acc_a.get(k, 0.0) + v
+            g = grads.get(k)
+            if g is not None:
+                acc_g[k] = acc_g.get(k, 0.0) + float(np.linalg.norm(g))
+    stats = {}
+    for k, W in params.items():
+        wn = float(np.linalg.norm(W))
+        gn = acc_g.get(k, 0.0) / n
+        stats[k] = {
+            "act_rms": acc_a.get(k, 0.0) / n if k in acc_a else None,
+            "grad_norm": gn,
+            "grad_rel": gn / (wn + 1e-12),
+        }
+    return stats
+
+
+# ---------------------------------------------------------------------------
+# Generation (greedy; streaming-capable)
+# ---------------------------------------------------------------------------
+
+def generate(params: dict, cfg: Config, prompt, max_tokens: int,
+             seed: int = 0):
+    """Greedy generation. Returns (tokens, tokens_per_sec, elapsed_s)."""
+    return _generate_impl(params, cfg, prompt, max_tokens, on_token=None)
+
+
+def generate_stream(params: dict, cfg: Config, prompt, max_tokens: int,
+                    seed: int = 0, on_token=None):
+    """Greedy generation, yielding each token as produced (true streaming).
+    Returns (tokens, tokens_per_sec, elapsed_s)."""
+    return _generate_impl(params, cfg, prompt, max_tokens, on_token=on_token)
+
+
+def _generate_impl(params: dict, cfg: Config, prompt, max_tokens: int,
+                   on_token):
+    ids = np.array([list(prompt)], dtype=np.int64)
+    out = []
+    t0 = time.perf_counter()
+    for _ in range(max_tokens):
+        ctx = ids[:, -cfg.seq:]
+        logits, _ = forward(params, cfg, ctx)
+        nxt = int(logits[0, -1].argmax())
+        out.append(nxt)
+        if on_token is not None:
+            on_token(nxt)
+        ids = np.concatenate([ids, [[nxt]]], axis=1)
+    dt = time.perf_counter() - t0
+    tps = len(out) / dt if dt > 0 else 0.0
+    return out, tps, dt

tensor_roll/ooc.py

@@ -0,0 +1,906 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Out-of-core execution — RULE ZERO: never require the teacher in RAM.
+
+The transformation must operate incrementally over a model larger than
+system RAM (and larger than RAM+VRAM combined):
+
+    30B MODEL STORAGE -> MANIFEST READER -> SHARD INDEX -> MMAP READER
+      -> ONE TENSOR / BLOCK -> TENSOR ROLL -> 8B TARGET SHARD
+      -> release source memory -> NEXT BLOCK
+
+New components (spec section 1):
+  TensorSource   manifest + shard index; never materializes the model
+  ShardReader    lazy, memory-mapped tensor reads
+  MappedTensor   memmap-backed tensor with exact shape/dtype
+  TensorWindow   recursive windowing of tensors larger than the budget
+  RollWorkspace  bounded working-set accounting with a hard ceiling
+  StudentWriter  incremental 8B-shard emission + verified shard index
+
+At no point does ingestion call load_model_30b() and hold all weights.
+The process respects --memory-budget within allocator overhead; the
+RollWorkspace refuses allocations that would exceed the ceiling.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Dict, Iterator, List, Optional, Tuple
+
+import numpy as np
+
+from .util import ensure_dir, utc_now_iso
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+def parse_bytes(s) -> int:
+    """'5G' -> bytes. Accepts int (bytes) or strings like '512M', '2G'."""
+    if isinstance(s, (int, float)):
+        return int(s)
+    s = str(s).strip().upper()
+    for suffix, mult in (("TB", 1024 ** 4), ("GB", 1024 ** 3), ("G", 1024 ** 3),
+                         ("MB", 1024 ** 2), ("M", 1024 ** 2),
+                         ("KB", 1024), ("K", 1024), ("B", 1)):
+        if s.endswith(suffix):
+            return int(float(s[: -len(suffix)]) * mult)
+    return int(float(s))
+
+
+_DTYPE_ITEMSIZE = {"float32": 4, "float64": 8, "float16": 2, "int8": 1,
+                   "int32": 4, "int64": 8, "uint8": 1, "uint16": 2}
+
+
+def dtype_itemsize(dtype: str) -> int:
+    return _DTYPE_ITEMSIZE[np.dtype(dtype).name]
+
+
+class MemoryBudgetExceeded(MemoryError):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Manifests — the model is described, never loaded
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TensorSpec:
+    """One tensor's address in storage. No data attached."""
+    name: str
+    shape: Tuple[int, ...]
+    dtype: str
+    nbytes: int
+    shard: str          # shard file name (relative to manifest dir)
+    offset: int         # byte offset inside the shard
+
+    @property
+    def params(self) -> int:
+        n = 1
+        for d in self.shape:
+            n *= d
+        return n
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "shape": list(self.shape),
+                "dtype": self.dtype, "nbytes": self.nbytes,
+                "shard": self.shard, "offset": self.offset}
+
+    @staticmethod
+    def from_dict(d: dict) -> "TensorSpec":
+        return TensorSpec(d["name"], tuple(d["shape"]), d["dtype"],
+                          d["nbytes"], d["shard"], d["offset"])
+
+
+class VirtualManifest:
+    """A model manifest with NO weight data — for structural scale tests.
+
+    Lets the SCAN/PLAN machinery address a ~30B model without allocating
+    a single weight. Any attempt to read data raises; only metadata flows.
+    """
+
+    def __init__(self, specs: List[TensorSpec], *, model_name: str = "virtual",
+                 provenance: dict = None):
+        self.specs = specs
+        self.model_name = model_name
+        self.provenance = provenance or {}
+
+    @property
+    def total_params(self) -> int:
+        return sum(s.params for s in self.specs)
+
+    @property
+    def total_bytes(self) -> int:
+        return sum(s.nbytes for s in self.specs)
+
+    def to_dict(self) -> dict:
+        return {"model": self.model_name, "virtual": True,
+                "total_params": self.total_params,
+                "total_bytes": self.total_bytes,
+                "created": utc_now_iso(),
+                "provenance": self.provenance,
+                "tensors": [s.to_dict() for s in self.specs]}
+
+    def write(self, path: str) -> dict:
+        with open(path, "w") as f:
+            json.dump(self.to_dict(), f, indent=2)
+        return {"path": path, "tensors": len(self.specs),
+                "total_params": self.total_params}
+
+    @staticmethod
+    def read(path: str) -> "VirtualManifest":
+        with open(path) as f:
+            d = json.load(f)
+        return VirtualManifest(
+            [TensorSpec.from_dict(s) for s in d["tensors"]],
+            model_name=d.get("model", "virtual"),
+            provenance=d.get("provenance", {}))
+
+    def reader(self):
+        raise RuntimeError(
+            "virtual manifest has no weight data to read — "
+            "metadata only (30B STRUCTURAL SCALE TEST)")
+
+
+def glimmer30b_manifest() -> VirtualManifest:
+    """Realistic ~30B dense-transformer manifest (decoder-heavy, like the
+    published Glimmer 30B: ~2B perception encoder + ~28B text decoder).
+
+    Shapes are realistic transformer dimensions; NO weights are allocated.
+    Used exclusively by the 30B STRUCTURAL SCALE TEST — this does not
+    validate model quality, only that storage/planning address 30B under
+    bounded RAM.
+    """
+    specs: List[TensorSpec] = []
+    off = 0
+
+    def add(name, shape, dtype="float16", shard="decoder.safetensors"):
+        nonlocal off
+        nbytes = int(np.prod(shape)) * dtype_itemsize(dtype)
+        specs.append(TensorSpec(name, tuple(shape), dtype, nbytes, shard, off))
+        off += nbytes
+
+    # --- perception encoder (~2B): a few large projection blocks --------
+    d_v, n_v = 2048, 24
+    for l in range(n_v):
+        add(f"vision.L{l}.Wqkv", (d_v, 3 * d_v))
+        add(f"vision.L{l}.Wo", (d_v, d_v))
+        add(f"vision.L{l}.W1", (d_v, 4 * d_v))
+        add(f"vision.L{l}.W2", (4 * d_v, d_v))
+        add(f"vision.L{l}.ln1", (d_v,), shard="decoder.safetensors")
+        add(f"vision.L{l}.ln2", (d_v,), shard="decoder.safetensors")
+    add("vision.proj", (d_v, 7168))
+
+    # --- text decoder (~28B): 44 layers, d=7168 --------------------------
+    d, dff, layers, vocab = 7168, 28672, 44, 128256
+    for s_idx in range(6):
+        shard = f"decoder-{s_idx:05d}.safetensors"
+        l0, l1 = s_idx * 8, min(layers, (s_idx + 1) * 8)
+        for l in range(l0, l1):
+            add(f"L{l}.Wq", (d, d), shard=shard)
+            add(f"L{l}.Wk", (d, d), shard=shard)
+            add(f"L{l}.Wv", (d, d), shard=shard)
+            add(f"L{l}.Wo", (d, d), shard=shard)
+            add(f"L{l}.W1", (d, dff), shard=shard)
+            add(f"L{l}.W2", (dff, d), shard=shard)
+            add(f"L{l}.ln1", (d,), shard=shard)
+            add(f"L{l}.ln2", (d,), shard=shard)
+    add("emb", (vocab, d), shard="decoder-00000.safetensors")
+    add("Whead", (d, vocab), shard="decoder-00005.safetensors")
+    add("lnf", (d,), shard="decoder-00005.safetensors")
+
+    total = sum(s.params for s in specs)
+    return VirtualManifest(
+        specs, model_name="glimmer-30b-virtual",
+        provenance={"note": "30B STRUCTURAL SCALE TEST manifest — shapes "
+                            "only, no weights allocated",
+                    "total_params": total})
+
+
+# ---------------------------------------------------------------------------
+# Real shard storage: write once, read via mmap
+# ---------------------------------------------------------------------------
+
+class ShardWriter:
+    """Writes tensors as raw little-endian blobs into shard files and emits
+    a manifest.json describing every tensor's address."""
+
+    def __init__(self, root: str, shard_size_bytes: int = 256 * 1024 * 1024,
+                 dtype: str = "float32"):
+        self.root = ensure_dir(root)
+        self.shard_size = int(shard_size_bytes)
+        self.specs: List[TensorSpec] = []
+        self._cur: Optional[str] = None
+        self._fh = None
+        self._off = 0
+
+    def _rotate(self):
+        if self._fh:
+            self._fh.close()
+        idx = len([s for s in self.specs])  # unique shard index
+        self._cur = f"shard-{idx:05d}.bin"
+        self._fh = open(os.path.join(self.root, self._cur), "wb")
+        self._off = 0
+
+    def add(self, name: str, arr: np.ndarray):
+        arr = np.ascontiguousarray(arr)
+        blob = arr.tobytes()
+        if self._fh is None or self._off + len(blob) > self.shard_size:
+            self._rotate()
+        self._fh.write(blob)
+        self.specs.append(TensorSpec(
+            name, tuple(arr.shape), str(arr.dtype), len(blob),
+            self._cur, self._off))
+        self._off += len(blob)
+
+    def finalize(self, model_name: str = "teacher") -> str:
+        if self._fh:
+            self._fh.close()
+            self._fh = None
+        man = {"model": model_name, "virtual": False,
+               "total_params": sum(s.params for s in self.specs),
+               "total_bytes": sum(s.nbytes for s in self.specs),
+               "created": utc_now_iso(),
+               "tensors": [s.to_dict() for s in self.specs]}
+        path = os.path.join(self.root, "manifest.json")
+        with open(path, "w") as f:
+            json.dump(man, f, indent=2)
+        return path
+
+
+class TensorSource:
+    """A model addressable tensor-by-tensor. Backed by real shard files
+    (mmap reads) or by a virtual manifest (metadata only)."""
+
+    def __init__(self, root: str):
+        self.root = root
+        man_path = os.path.join(root, "manifest.json")
+        with open(man_path) as f:
+            man = json.load(f)
+        self.virtual = bool(man.get("virtual"))
+        self.model_name = man.get("model", "?")
+        self.specs = [TensorSpec.from_dict(s) for s in man["tensors"]]
+
+    @property
+    def total_params(self) -> int:
+        return sum(s.params for s in self.specs)
+
+    def names(self) -> List[str]:
+        return [s.name for s in self.specs]
+
+    def spec(self, name: str) -> TensorSpec:
+        for s in self.specs:
+            if s.name == name:
+                return s
+        raise KeyError(name)
+
+    def reader(self) -> "ShardReader":
+        if self.virtual:
+            raise RuntimeError("virtual manifest has no weight data to read")
+        return ShardReader(self)
+
+
+class ShardReader:
+    """Lazy memory-mapped tensor reads. One tensor (or window) at a time."""
+
+    def __init__(self, source: TensorSource):
+        self.source = source
+        self._mmaps: Dict[str, np.memmap] = {}
+
+    def _mmap(self, spec: TensorSpec) -> np.memmap:
+        key = spec.shard
+        if key not in self._mmaps:
+            path = os.path.join(self.source.root, spec.shard)
+            # map the whole shard file once; tensors are views into it
+            size = os.path.getsize(path)
+            self._mmaps[key] = np.memmap(path, dtype=np.uint8, mode="r",
+                                         shape=(size,))
+        return self._mmaps[key]
+
+    def read(self, name: str) -> "MappedTensor":
+        spec = self.source.spec(name)
+        raw = self._mmap(spec)
+        view = raw[spec.offset:spec.offset + spec.nbytes].view(
+            np.dtype(spec.dtype)).reshape(spec.shape)
+        return MappedTensor(name, view, spec)
+
+    def close(self):
+        self._mmaps = {}
+
+
+class MappedTensor:
+    """A memmap-backed tensor. `.window(slices)` yields TensorWindows."""
+
+    def __init__(self, name: str, view: np.ndarray, spec: TensorSpec):
+        self.name = name
+        self.view = view  # memmap view — no copy
+        self.spec = spec
+
+    @property
+    def shape(self):
+        return self.view.shape
+
+    def window(self, slices: Tuple[slice, ...]) -> "TensorWindow":
+        return TensorWindow(self, slices)
+
+    def windows(self, budget_bytes: int) -> Iterator["TensorWindow"]:
+        """Recursive windowing until each window fits the budget."""
+        for sl in plan_windows(self.view.shape,
+                               self.view.dtype.itemsize, budget_bytes):
+            yield TensorWindow(self, sl)
+
+
+@dataclass
+class TensorWindow:
+    """One bounded piece of a (possibly huge) tensor, with exact
+    reconstruction metadata. No silent shape corruption: the window
+    records its slices, shape, and global offsets."""
+    parent: MappedTensor
+    slices: Tuple[slice, ...]
+
+    @property
+    def name(self) -> str:
+        idx = ",".join(f"{s.start}:{s.stop}" for s in self.slices)
+        return f"{self.parent.name}@[{idx}]"
+
+    @property
+    def shape(self) -> Tuple[int, ...]:
+        return self.data.shape
+
+    @property
+    def nbytes(self) -> int:
+        return self.data.nbytes
+
+    @property
+    def data(self) -> np.ndarray:
+        # materialize ONLY this window (bounded by the budget)
+        return np.asarray(self.parent.view[self.slices])
+
+    def meta(self) -> dict:
+        return {"tensor": self.parent.name,
+                "slices": [[s.start, s.stop] for s in self.slices],
+                "shape": list(self.shape),
+                "global_shape": list(self.parent.shape)}
+
+
+def plan_windows(shape: Tuple[int, ...], itemsize: int,
+                 budget_bytes: int) -> List[Tuple[slice, ...]]:
+    """Recursively split along the largest axis until every chunk's
+    byte size <= budget_bytes. Returns exact slice tuples covering the
+    tensor with no overlap and no gaps."""
+    total = int(np.prod(shape)) * itemsize
+    if total <= budget_bytes or len(shape) == 0:
+        return [tuple(slice(0, d) for d in shape)]
+    # split the largest axis in half, recurse on both halves
+    ax = int(np.argmax(shape))
+    mid = shape[ax] // 2
+    if mid == 0:
+        raise MemoryBudgetExceeded(
+            f"cannot window shape {shape}: axis {ax} has size 1 but a "
+            f"single element ({itemsize}B) exceeds the budget")
+    out = []
+    for lo, hi in ((0, mid), (mid, shape[ax])):
+        sub = list(shape)
+        sub[ax] = hi - lo
+        for sl in plan_windows(tuple(sub), itemsize, budget_bytes):
+            full = list(sl)
+            s = full[ax]
+            full[ax] = slice(s.start + lo, s.stop + lo)
+            out.append(tuple(full))
+    return out
+
+
+def reassemble(windows: List[TensorWindow], shape: Tuple[int, ...],
+               dtype=np.float64) -> np.ndarray:
+    """Rebuild the full tensor from windows; verifies exact coverage."""
+    out = np.zeros(shape, dtype=dtype)
+    seen = np.zeros(shape, dtype=bool)
+    for w in windows:
+        m = w.meta()
+        sl = tuple(slice(a, b) for a, b in m["slices"])
+        assert w.data.shape == tuple(b - a for a, b in m["slices"]), \
+            f"window shape mismatch for {w.name}"
+        out[sl] = w.data
+        assert not seen[sl].any(), f"overlapping windows at {w.name}"
+        seen[sl] = True
+    assert seen.all(), "windows do not cover the tensor exactly"
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Bounded working set
+# ---------------------------------------------------------------------------
+
+class RollWorkspace:
+    """Tracks the live working set against a hard memory ceiling.
+
+    Every materialized window/buffer must be allocated through here.
+    Allocations that would exceed the ceiling raise MemoryBudgetExceeded
+    instead of silently paging the machine to death.
+    """
+
+    def __init__(self, ceiling_bytes: int):
+        self.ceiling = int(ceiling_bytes)
+        self.live: Dict[str, int] = {}
+        self.peak = 0
+        self.allocations = 0
+
+    @property
+    def used(self) -> int:
+        return sum(self.live.values())
+
+    def alloc(self, tag: str, nbytes: int):
+        nbytes = int(nbytes)
+        if self.used + nbytes > self.ceiling:
+            raise MemoryBudgetExceeded(
+                f"workspace ceiling {self.ceiling}B exceeded: "
+                f"used={self.used}B + {nbytes}B ({tag})")
+        self.live[tag] = self.live.get(tag, 0) + nbytes
+        self.peak = max(self.peak, self.used)
+        self.allocations += 1
+
+    def free(self, tag: str):
+        self.live.pop(tag, None)
+
+    def report(self) -> dict:
+        return {"ceiling_bytes": self.ceiling, "peak_bytes": self.peak,
+                "current_bytes": self.used,
+                "allocations": self.allocations,
+                "within_budget": self.peak <= self.ceiling}
+
+
+# ---------------------------------------------------------------------------
+# Incremental student emission
+# ---------------------------------------------------------------------------
+
+class StudentWriter:
+    """Writes student shards incrementally + a verified shard index.
+
+    Each emitted tensor is checksummed; finalize() writes shard_index.json
+    with per-tensor sha256 and a total parameter count.
+
+    Crash safety: flush_index() rewrites shard_index.json after every
+    tensor (atomic replace). On resume, the writer reloads the existing
+    index so previously emitted shards are kept and file names continue
+    without collision.
+    """
+
+    INDEX_NAME = "shard_index.json"
+
+    def __init__(self, root: str, resume: bool = False):
+        self.root = ensure_dir(root)
+        self.entries: List[dict] = []
+        if resume:
+            idx_path = os.path.join(root, self.INDEX_NAME)
+            if os.path.exists(idx_path):
+                with open(idx_path) as f:
+                    index = json.load(f)
+                self.entries = index.get("tensors", [])
+
+    def emit(self, name: str, arr: np.ndarray, meta: dict = None) -> dict:
+        arr = np.ascontiguousarray(arr)
+        fname = f"student-{len(self.entries):05d}.npy"
+        path = os.path.join(self.root, fname)
+        # np.save appends .npy when missing, so the temp name keeps it
+        tmp = path + ".tmp.npy"
+        np.save(tmp, arr)
+        os.replace(tmp, path)  # atomic: no half-written shards
+        digest = hashlib.sha256(arr.tobytes()).hexdigest()
+        entry = {"name": name, "file": fname, "shape": list(arr.shape),
+                 "dtype": str(arr.dtype), "params": int(arr.size),
+                 "sha256": digest, "meta": meta or {}}
+        self.entries.append(entry)
+        return entry
+
+    def flush_index(self) -> dict:
+        """Rewrite the index now (per-tensor checkpointing)."""
+        return self.finalize()
+
+    def finalize(self) -> dict:
+        index = {"created": utc_now_iso(),
+                 "n_tensors": len(self.entries),
+                 "total_params": sum(e["params"] for e in self.entries),
+                 "tensors": self.entries}
+        payload = json.dumps(index, sort_keys=True).encode()
+        index["index_sha256"] = hashlib.sha256(payload).hexdigest()
+        tmp = os.path.join(self.root, self.INDEX_NAME + ".tmp")
+        with open(tmp, "w") as f:
+            json.dump(index, f, indent=2)
+        os.replace(tmp, os.path.join(self.root, self.INDEX_NAME))
+        return index
+
+    @staticmethod
+    def verify(root: str) -> dict:
+        with open(os.path.join(root, "shard_index.json")) as f:
+            index = json.load(f)
+        for e in index["tensors"]:
+            arr = np.load(os.path.join(root, e["file"]))
+            assert list(arr.shape) == e["shape"], f"shape drift: {e['name']}"
+            assert (hashlib.sha256(
+                np.ascontiguousarray(arr).tobytes()).hexdigest()
+                    == e["sha256"]), f"checksum mismatch: {e['name']}"
+        return {"tensors": index["n_tensors"],
+                "total_params": index["total_params"], "ok": True}
+
+
+# ---------------------------------------------------------------------------
+# Checkpoints — crash-safe, corruption-rejecting
+# ---------------------------------------------------------------------------
+
+class Checkpoint:
+    """JSON state + sha256. Corrupted checkpoints are refused, never loaded."""
+
+    def __init__(self, path: str):
+        self.path = path
+
+    def save(self, state: dict) -> dict:
+        payload = json.dumps(state, sort_keys=True).encode()
+        digest = hashlib.sha256(payload).hexdigest()
+        tmp = self.path + ".tmp"
+        with open(tmp, "w") as f:
+            json.dump({"sha256": digest, "state": state}, f)
+        os.replace(tmp, self.path)  # atomic
+        return {"path": self.path, "sha256": digest}
+
+    def load(self) -> dict:
+        with open(self.path) as f:
+            doc = json.load(f)
+        payload = json.dumps(doc["state"], sort_keys=True).encode()
+        if hashlib.sha256(payload).hexdigest() != doc["sha256"]:
+            raise ValueError(
+                f"checkpoint checksum mismatch: {self.path} — refusing")
+        return doc["state"]
+
+    def exists(self) -> bool:
+        return os.path.exists(self.path)
+
+
+# ---------------------------------------------------------------------------
+# Out-of-core driver: SCAN -> PLAN -> EXECUTE with resume
+# ---------------------------------------------------------------------------
+
+class OutOfCoreDriver:
+    """Streams a teacher through TensorRoll without ever holding it in RAM.
+
+    scan:    lightweight per-tensor stats from the manifest (no weights).
+    plan:    global budget allocation (delegates to planner.plan).
+    execute: per tensor (windowed as needed): mmap -> roll -> transform ->
+             emit student shard -> release. Checkpointed per tensor so
+             --resume continues after a crash.
+    """
+
+    def __init__(self, source: TensorSource, workdir: str,
+                 memory_budget: str = "5G", target_params: float = 8.0e9,
+                 cap_params: float = 8.5e9):
+        self.source = source
+        self.workdir = ensure_dir(workdir)
+        self.ws = RollWorkspace(parse_bytes(memory_budget))
+        self.target = float(target_params)
+        self.cap = float(cap_params)
+        self.ckpt = Checkpoint(os.path.join(workdir, "ooc_checkpoint.json"))
+        self.student_dir = ensure_dir(os.path.join(workdir, "student_shards"))
+
+    def scan(self) -> List[dict]:
+        """Lightweight stats per tensor — manifest only, no weight data."""
+        from . import core as C  # deferred: keeps import graph light
+        rows = []
+        for s in self.source.specs:
+            rows.append({
+                "tensor": s.name, "shape": list(s.shape), "dtype": s.dtype,
+                "params": s.params, "bytes": s.nbytes, "shard": s.shard,
+                # shape-derived proxies, measured from metadata only
+                "is_matrix": len(s.shape) == 2 and min(s.shape) > 1,
+                "aspect": (max(s.shape) / max(1, min(s.shape))
+                           if s.shape else 1.0),
+            })
+        return rows
+
+    def plan(self, rows: List[dict]) -> dict:
+        from . import planner as P
+        return P.plan(rows, target=self.target, cap=self.cap)
+
+    def execute(self, plan: dict, transform, *,
+                resume: bool = False, fault_after: int = -1) -> dict:
+        """Run the plan. `transform(name, window_data, w_target, ws, meta)`
+        is the caller-supplied per-window transform returning either one
+        student array or a dict {suffix: array} (e.g. factor pairs).
+        Checkpointed per tensor; the student index is flushed per tensor
+        too, so `fault_after` crash tests resume with zero emitted-data
+        loss. `fault_after` injects a crash (tests only, never production).
+        """
+        state = self.ckpt.load() if (resume and self.ckpt.exists()) else {
+            "done": [], "emitted_params": 0}
+        done = set(state["done"])
+        writer = StudentWriter(self.student_dir, resume=resume)
+        # re-verify previously emitted shards on resume
+        if resume and done:
+            StudentWriter.verify(self.student_dir)
+        reader = self.source.reader()
+        processed, emitted = 0, state["emitted_params"]
+        try:
+            for spec in self.source.specs:
+                if spec.name in done:
+                    continue
+                mt = reader.read(spec.name)
+                for w in mt.windows(self.ws.ceiling):
+                    tag = f"win:{w.name}"
+                    self.ws.alloc(tag, w.nbytes)
+                    try:
+                        data = w.data
+                        target = plan["tensors"][spec.name]["target_params"]
+                        # split the tensor's target budget across windows
+                        # proportionally to window params
+                        w_target = max(
+                            1, int(target * w.data.size / spec.params))
+                        out = transform(spec.name, data, w_target, self.ws,
+                                        w.meta())
+                    finally:
+                        self.ws.free(tag)
+                    parts = out if isinstance(out, dict) else {"": out}
+                    for suffix, arr in parts.items():
+                        arr = np.asarray(arr)
+                        ename = w.name + (f".{suffix}" if suffix else "")
+                        writer.emit(ename, arr,
+                                    {"parent": spec.name, **w.meta()})
+                        emitted += int(arr.size)
+                # release the memmap view for this tensor before next
+                del mt
+                processed += 1
+                done.add(spec.name)
+                state = {"done": sorted(done), "emitted_params": emitted}
+                self.ckpt.save(state)
+                writer.flush_index()
+                if fault_after >= 0 and processed > fault_after:
+                    raise RuntimeError("injected crash (fault_after test)")
+        finally:
+            reader.close()
+        index = writer.finalize()
+        return {"processed_tensors": processed,
+                "emitted_params": emitted,
+                "index_total_params": index["total_params"],
+                "workspace": self.ws.report(),
+                "budget_ok": index["total_params"] <= self.cap}
+
+
+# ---------------------------------------------------------------------------
+# External teacher formats: safetensors (true mmap) and npz (streaming repack)
+# ---------------------------------------------------------------------------
+
+_SAFETENSORS_DTYPES = {
+    "F32": "float32", "F16": "float16",
+    "I32": "int32", "I64": "int64",
+    "U8": "uint8", "I8": "int8", "BOOL": "bool",
+}
+
+
+def _read_safetensors_header(path: str) -> Tuple[dict, int]:
+    """Returns (header_dict, data_start_offset). Metadata only."""
+    import struct
+    with open(path, "rb") as f:
+        n = struct.unpack("<Q", f.read(8))[0]
+        raw = f.read(n)
+    return json.loads(raw.decode("utf-8")), 8 + n
+
+
+class SafetensorsSource:
+    """A directory of .safetensors files. SCAN reads only JSON headers;
+    EXECUTE windows tensors through np.memmap — the 30B weights are never
+    fully in RAM."""
+
+    def __init__(self, path: str):
+        self.path = path
+        self.specs: List[TensorSpec] = []
+        self._files: Dict[str, str] = {}  # shard name -> abs path
+        for fname in sorted(os.listdir(path)):
+            if not fname.endswith(".safetensors"):
+                continue
+            fpath = os.path.join(path, fname)
+            header, data_start = _read_safetensors_header(fpath)
+            self._files[fname] = fpath
+            for name, info in header.items():
+                if name == "__metadata__":
+                    continue
+                dt = info["dtype"]
+                if dt == "BF16":
+                    try:
+                        import ml_dtypes  # noqa
+                        np_dtype = "bfloat16"
+                    except ImportError:
+                        raise RuntimeError(
+                            f"tensor {name}: BF16 needs the ml_dtypes "
+                            f"package for CPU decode; refusing to guess")
+                elif dt not in _SAFETENSORS_DTYPES:
+                    raise RuntimeError(
+                        f"tensor {name}: unsupported dtype {dt}")
+                else:
+                    np_dtype = _SAFETENSORS_DTYPES[dt]
+                shape = tuple(info["shape"])
+                start, end = info["data_offsets"]
+                nbytes = end - start
+                self.specs.append(TensorSpec(
+                    f"{fname}:{name}", shape, np_dtype, nbytes, fname,
+                    data_start + start))
+        if not self.specs:
+            raise ValueError(f"no safetensors tensors found in {path}")
+
+    @property
+    def total_params(self) -> int:
+        return sum(s.params for s in self.specs)
+
+    def names(self) -> List[str]:
+        return [s.name for s in self.specs]
+
+    def spec(self, name: str) -> TensorSpec:
+        for s in self.specs:
+            if s.name == name:
+                return s
+        raise KeyError(name)
+
+    def reader(self) -> "SafetensorsReader":
+        return SafetensorsReader(self)
+
+
+class SafetensorsReader:
+    """Lazy memory-mapped reads over safetensors files."""
+
+    def __init__(self, source: SafetensorsSource):
+        self.source = source
+        self._mmaps: Dict[str, np.memmap] = {}
+
+    def _mmap(self, spec: TensorSpec) -> np.memmap:
+        if spec.shard not in self._mmaps:
+            path = self.source._files[spec.shard]
+            size = os.path.getsize(path)
+            self._mmaps[spec.shard] = np.memmap(
+                path, dtype=np.uint8, mode="r", shape=(size,))
+        return self._mmaps[spec.shard]
+
+    def read(self, name: str) -> MappedTensor:
+        spec = self.source.spec(name)
+        raw = self._mmap(spec)
+        view = raw[spec.offset:spec.offset + spec.nbytes].view(
+            np.dtype(spec.dtype)).reshape(spec.shape)
+        return MappedTensor(name, view, spec)
+
+    def close(self):
+        self._mmaps = {}
+
+
+def _scan_npz(path: str) -> List[Tuple[str, tuple, str, int]]:
+    """Metadata-only scan of one .npz (zip headers, no array data)."""
+    import zipfile
+    from numpy.lib import format as npfmt
+    specs = []
+    with zipfile.ZipFile(path) as zf:
+        for entry in zf.namelist():
+            if not entry.endswith(".npy"):
+                continue
+            with zf.open(entry) as f:
+                npfmt.read_magic(f)
+                shape, _fortran, dtype = npfmt.read_array_header_1_0(f)
+            name = entry[:-4]
+            specs.append((name, tuple(shape), np.dtype(dtype).name,
+                          int(np.prod(shape, dtype=np.int64))
+                          * np.dtype(dtype).itemsize))
+    return specs
+
+
+def prepare_teacher_source(teacher_dir: str, cache_dir: str):
+    """Open a teacher weight directory as a streaming source.
+
+    .safetensors -> true mmap source (no copy). .npz -> one-time streaming
+    repack into the shard format (one array in RAM at a time), then a
+    TensorSource over the repacked shards. Raises informatively when the
+    directory holds neither.
+    """
+    teacher_dir = os.path.abspath(teacher_dir)
+    st_files = sorted(f for f in os.listdir(teacher_dir)
+                      if f.endswith(".safetensors"))
+    npz_files = sorted(f for f in os.listdir(teacher_dir)
+                       if f.endswith(".npz"))
+    if st_files:
+        return SafetensorsSource(teacher_dir)
+    if npz_files:
+        shard_root = ensure_dir(os.path.join(cache_dir, "repacked_shards"))
+        man_path = os.path.join(shard_root, "manifest.json")
+        if not os.path.exists(man_path):
+            import zipfile
+            writer = ShardWriter(shard_root)
+            for fname in npz_files:
+                specs = _scan_npz(os.path.join(teacher_dir, fname))
+                zf = zipfile.ZipFile(os.path.join(teacher_dir, fname))
+                for name, _shape, _dtype, _nbytes in specs:
+                    # one array in RAM at a time — the streaming invariant
+                    with zf.open(name + ".npy") as f:
+                        buf = f.read()
+                    import io
+                    arr = np.load(io.BytesIO(buf))
+                    writer.add(f"{fname}:{name}",
+                               np.ascontiguousarray(arr))
+                    del arr, buf
+                zf.close()
+            writer.finalize("teacher-repacked")
+        return TensorSource(shard_root)
+    raise ValueError(
+        f"no .safetensors or .npz weights in {teacher_dir}")
+
+
+# ---------------------------------------------------------------------------
+# Streaming compression: per-window truncated SVD under the planned budget
+# ---------------------------------------------------------------------------
+
+def stream_compress(source, plan: dict, memory_budget: str, out_dir: str, *,
+                    resume: bool = False, fault_after: int = -1,
+                    dtype=np.float32) -> dict:
+    """End-to-end out-of-core compression.
+
+    For each tensor: mmap -> recursive windows (each <= budget) ->
+    truncated SVD at the tensor's planned rank share -> emit low-rank
+    factor pairs (A = U_r S_r, B = V_r^T) as student shards. Student
+    parameter count = sum of factor params, honestly accounted against
+    the plan. Per-tensor checkpoint + per-tensor index flush; resume
+    continues after a crash with zero emitted-data loss.
+    """
+    workdir = ensure_dir(out_dir)
+    driver = OutOfCoreDriver(
+        source, workdir, memory_budget=memory_budget,
+        target_params=plan.get("total_target_params", 8.0e9),
+        cap_params=plan.get("cap", 8.5e9))
+    stats: Dict[str, dict] = {}
+    rep_path = os.path.join(workdir, "stream_compress_report.json")
+    # on resume, keep the previous run's per-tensor stats for tensors we
+    # skip this time (otherwise a resume-noop would report empty stats)
+    prior_stats: Dict[str, dict] = {}
+    if resume and os.path.exists(rep_path):
+        try:
+            with open(rep_path) as f:
+                prior_stats = json.load(f).get("tensor_stats", {})
+        except (json.JSONDecodeError, OSError):
+            prior_stats = {}
+
+    def transform(name, data, w_target, ws, meta):
+        parent = meta["tensor"]
+        W = np.asarray(data)
+        st = stats.setdefault(parent, {"windows": 0, "e_num": 0.0,
+                                       "e_den": 0.0, "rank": 0})
+        if W.ndim == 2 and min(W.shape) > 1:
+            m, n = W.shape
+            R = max(1, int(w_target // (m + n)))
+            st["rank"] = max(st["rank"], R)
+            Wd = W.astype(np.float64)
+            U, s, Vt = np.linalg.svd(Wd, full_matrices=False)
+            r = max(1, min(m, n, R, s.size))
+            A = (U[:, :r] * s[:r]).astype(dtype)
+            B = Vt[:r, :].astype(dtype)
+            st["e_num"] += float((s[:r] ** 2).sum())
+            st["e_den"] += float((s ** 2).sum())
+            st["windows"] += 1
+            return {"A": A, "B": B}
+        st["windows"] += 1
+        return {"raw": np.asarray(W).astype(dtype)}
+
+    t0 = time.perf_counter()
+    res = driver.execute(plan, transform, resume=resume,
+                         fault_after=fault_after)
+    dt = time.perf_counter() - t0
+    # per-tensor retained energy (measured); re-run tensors overwrite
+    for _name, st in stats.items():
+        st["retained_energy"] = (st["e_num"] / st["e_den"]
+                                 if st["e_den"] > 0 else 1.0)
+        del st["e_num"], st["e_den"]
+    merged_stats = {**prior_stats, **stats}
+    res.update({"elapsed_s": dt, "tensor_stats": merged_stats,
+                "source_params": source.total_params,
+                "compression_ratio": (res["index_total_params"]
+                                      / max(1, source.total_params))})
+    rep_path = os.path.join(workdir, "stream_compress_report.json")
+    with open(rep_path, "w") as f:
+        json.dump(res, f, indent=2, default=float)
+    res["report"] = rep_path
+    return res

tensor_roll/planner.py

@@ -0,0 +1,233 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Global planner: SCAN -> PLAN -> EXECUTE.
+
+Streaming introduces a global problem: local per-tensor decisions must
+satisfy a global ~8B budget. The planner solves allocation in three
+passes:
+
+  SCAN:    lightweight per-tensor statistics WITHOUT materializing the
+           network (manifest metadata only; optional measured calibration
+           on sampled windows for sensitivity).
+  PLAN:    solve the allocation  Σ target_params <= 8.5B  (prefer ~8.0B).
+           Budgets are NONUNIFORM and sensitivity-aware: tensors measured
+           as sensitive receive more budget, funded by less-sensitive
+           tensors. The only global invariant is the final budget.
+  EXECUTE: the expensive transforms run per the plan (see ooc.py).
+
+The 27.8% ≈ 28.3% small-scale ratio is an explicit regression target:
+virtual manifests at 100K/1M/10M/100M params verify the planner holds the
+requested compression ratio as scale grows (section 4).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from . import core as C
+
+CAP_PARAMS = 8_500_000_000      # hard architectural budget
+TARGET_PARAMS = 8_000_000_000   # preferred target
+BUDGET_RATIO = 8.5 / 30.0       # scale-invariant ratio (regression target)
+
+
+# ---------------------------------------------------------------------------
+# SCAN
+# ---------------------------------------------------------------------------
+
+def scan_rows(specs) -> List[dict]:
+    """Lightweight per-tensor stats from manifest specs only. No weights."""
+    rows = []
+    for s in specs:
+        shape = tuple(s.shape)
+        rows.append({
+            "tensor": s.name,
+            "shape": list(shape),
+            "dtype": s.dtype,
+            "params": int(s.params),
+            "bytes": int(s.nbytes),
+            "shard": s.shard,
+            "is_matrix": len(shape) == 2 and min(shape) > 1,
+        })
+    return rows
+
+
+def calibrate_sensitivity(rows: List[dict], sample_fn=None) -> Dict[str, float]:
+    """Measured sensitivity per tensor in [0, 1].
+
+    `sample_fn(name)` returns a small (<=4096-elem) sample window of the
+    tensor's data, or None when unavailable (virtual manifests). From the
+    sample we measure spectral concentration and entropy via
+    core.tensor_metrics; high spectral concentration + low entropy =>
+    low-rank-friendly => LOW sensitivity to compression. Tensors whose
+    energy is spread across many singular values are HIGH sensitivity.
+
+    When no data is available the sensitivity is uniform 0.5 (documented),
+    and the planner degrades gracefully to a uniform-ratio allocation.
+    """
+    sens = {}
+    for r in rows:
+        s = 0.5
+        if sample_fn is not None:
+            try:
+                w = sample_fn(r["tensor"])
+            except Exception:
+                w = None
+            if w is not None:
+                w = np.asarray(w, dtype=np.float64)
+                if w.ndim == 2 and min(w.shape) > 1:
+                    m = C.tensor_metrics(w)
+                    # spectral in [0,1]: concentrated => compressible
+                    # entropy normalized by log(rank): spread => sensitive
+                    rank = max(1, m["rank"])
+                    h_norm = m["entropy"] / math.log(rank + 1e-9) \
+                        if rank > 1 else 0.0
+                    s = float(np.clip(0.35 * (1.0 - m["spectral"])
+                                      + 0.65 * min(1.0, h_norm), 0.0, 1.0))
+                else:
+                    # 1-D params (norms/biases): cheap, keep them
+                    s = 0.15
+        sens[r["tensor"]] = s
+    return sens
+
+
+# ---------------------------------------------------------------------------
+# PLAN — nonuniform, sensitivity-aware, hard-capped
+# ---------------------------------------------------------------------------
+
+def plan(rows: List[dict], *, target: float = TARGET_PARAMS,
+         cap: float = CAP_PARAMS,
+         sensitivity: Optional[Dict[str, float]] = None,
+         ratio: Optional[float] = None) -> dict:
+    """Allocate per-tensor target parameter counts.
+
+    Starts from a uniform ratio (target/total, or `ratio` when given for
+    scale-invariant small-scale runs), then reallocates from
+    low-sensitivity to high-sensitivity tensors: sensitive tensors may
+    receive up to 2x the uniform ratio, funded by insensitive tensors down
+    to 0.4x. Iterates until Σ targets <= cap (hard) and Σ targets is as
+    close to `target` as the bounds allow.
+
+    Returns {"tensors": {name: {"target_params": int, "ratio": float,
+    "sensitivity": float}}, "total_target_params": int, "cap": cap,
+    "within_cap": bool}.
+    """
+    total = sum(r["params"] for r in rows)
+    if total == 0:
+        raise ValueError("planner: empty model")
+    if ratio is not None:
+        # scale-invariant mode: the target IS the ratio (regression target)
+        target = float(ratio) * total
+    base_ratio = min(1.0, target / total)
+    sens = sensitivity or {r["tensor"]: 0.5 for r in rows}
+
+    alloc = {}
+    for r in rows:
+        s = float(np.clip(sens.get(r["tensor"], 0.5), 0.0, 1.0))
+        # sensitivity -> multiplier in [0.4, 2.0]:
+        # s=0 -> 0.4, s=0.5 -> 1.2, s=1 -> 2.0 (recentered below)
+        mult = 0.4 + 1.6 * s
+        # recenter so the mean multiplier is ~1: divide by mean
+        alloc[r["tensor"]] = {"params": r["params"], "s": s, "mult": mult}
+
+    mean_mult = sum(v["mult"] for v in alloc.values()) / len(alloc)
+    for v in alloc.values():
+        v["mult"] /= mean_mult
+
+    def totals():
+        t = {k: max(1, int(v["params"] * base_ratio * v["mult"]))
+             for k, v in alloc.items()}
+        return t, sum(t.values())
+
+    targets, tot = totals()
+    # hard cap: scale down proportionally (preserves nonuniform shape)
+    if tot > cap:
+        f = cap / tot
+        targets = {k: max(1, int(v * f)) for k, v in targets.items()}
+        tot = sum(targets.values())
+    # land on the target from either side (target <= cap by contract; if a
+    # caller passes target > cap, the cap wins). The sensitivity-driven
+    # nonuniformity is param-correlated, so without this the plan can
+    # overshoot the target while staying under the cap.
+    goal = min(target, cap)
+    if tot > goal:
+        f = goal / tot
+        targets = {k: max(1, int(v * f)) for k, v in targets.items()}
+        tot = sum(targets.values())
+    elif tot < goal:
+        f = goal / tot
+        targets = {k: max(1, int(v * f)) for k, v in targets.items()}
+        tot = sum(targets.values())
+
+    out = {"tensors": {
+        k: {"target_params": targets[k],
+            "ratio": targets[k] / alloc[k]["params"],
+            "sensitivity": alloc[k]["s"]}
+        for k in targets},
+        "total_target_params": tot,
+        "total_source_params": total,
+        "achieved_ratio": tot / total,
+        "cap": float(cap),
+        "within_cap": tot <= cap}
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Scale-invariance regression (section 4)
+# ---------------------------------------------------------------------------
+
+def virtual_manifest_for_params(total_params: int, seed: int = 0) -> List[dict]:
+    """Build a virtual tensor manifest totaling ~total_params WITHOUT
+    allocating weights. Mixes matrix shapes like a transformer
+    (attention projections, MLP up/down, embeddings, norms)."""
+    rng = np.random.default_rng(seed)
+    rows = []
+    remaining = int(total_params)
+    i = 0
+    # block templates (fractions of a "layer")
+    while remaining > 0:
+        d = int(rng.choice([64, 128, 256, 512, 1024, 2048, 4096, 8192]))
+        kind = rng.integers(0, 5)
+        if kind == 0:
+            shape = (d, d)
+        elif kind == 1:
+            shape = (d, 4 * d)
+        elif kind == 2:
+            shape = (4 * d, d)
+        elif kind == 3:
+            shape = (32768, d)
+        else:
+            shape = (d,)
+        p = int(np.prod(shape))
+        if p > remaining and remaining < 10_000:
+            shape = (remaining,)
+            p = remaining
+        if p > remaining:
+            continue
+        rows.append({"tensor": f"blk{i}", "shape": list(shape),
+                     "dtype": "float16", "params": p,
+                     "bytes": p * 2, "shard": "virtual.safetensors",
+                     "is_matrix": len(shape) == 2})
+        remaining -= p
+        i += 1
+        if i > 20000:
+            break
+    return rows
+
+
+def check_ratio_invariance(total_params: int, *, ratio: float = BUDGET_RATIO,
+                           tol: float = 0.02, seed: int = 0) -> dict:
+    """Regression: the planner must hold the requested compression ratio
+    as scale grows, using virtual manifests (no weight allocation)."""
+    rows = virtual_manifest_for_params(total_params, seed=seed)
+    src = sum(r["params"] for r in rows)
+    p = plan(rows, ratio=ratio)
+    achieved = p["achieved_ratio"]
+    return {"source_params": src, "requested_ratio": ratio,
+            "achieved_ratio": achieved,
+            "within_tol": abs(achieved - ratio) <= tol,
+            "plan_total": p["total_target_params"]}

tensor_roll/qsim.py

@@ -0,0 +1,288 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Classical state-vector simulator for the tensor_roll kernel family.
+
+This is NOT a quantum computer. Every invocation report from this module
+carries backend="qsim-classical" and device="cpu (statevector simulator)".
+It implements genuine quantum-circuit linear algebra (unitary evolution +
+Born-rule measurement) so the encode -> transform -> measure -> reconstruct
+pipeline is empirically measurable, including its reconstruction error.
+
+The real CUDA-Q kernels live in cudaq/tensor_roll_kernels.py and the real
+Q# operations in qsharp/TensorRoll.qs. Neither can execute on this machine
+(no QPU, no CUDA-Q toolchain, no Q# toolchain); see docs/BOUNDARIES.md.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+
+from .core import QSIM_BACKEND, new_report
+
+MAX_QUBITS = 10  # 2**10 amplitudes; hard cap for honesty about cost
+
+
+# ---------------------------------------------------------------------------
+# Low-level statevector machinery (real linear algebra)
+# ---------------------------------------------------------------------------
+
+def _n_qubits_for(size: int) -> int:
+    n = max(1, int(np.ceil(np.log2(size))))
+    if n > MAX_QUBITS:
+        raise ValueError(
+            f"block of {size} elements needs {n} qubits > cap {MAX_QUBITS}; "
+            "refusing rather than silently approximating")
+    return n
+
+
+def _apply_1q(sv: np.ndarray, U: np.ndarray, qubit: int, n: int) -> np.ndarray:
+    t = sv.reshape([2] * n)
+    ax = n - 1 - qubit
+    t = np.tensordot(U, t, axes=([1], [ax]))
+    t = np.moveaxis(t, 0, ax)
+    return t.reshape(2 ** n)
+
+
+def _apply_cnot(sv: np.ndarray, control: int, target: int, n: int) -> np.ndarray:
+    idx = np.arange(2 ** n)
+    mask = ((idx >> control) & 1).astype(bool)
+    flipped = idx ^ (1 << target)
+    out = sv.copy()
+    out[mask] = sv[flipped[mask]]
+    return out
+
+
+def _rx(theta: float) -> np.ndarray:
+    c, s = np.cos(theta / 2), np.sin(theta / 2)
+    return np.array([[c, -1j * s], [-1j * s, c]], dtype=np.complex128)
+
+
+def _ry(theta: float) -> np.ndarray:
+    c, s = np.cos(theta / 2), np.sin(theta / 2)
+    return np.array([[c, -s], [s, c]], dtype=np.complex128)
+
+
+def _rz(theta: float) -> np.ndarray:
+    return np.array([[np.exp(-0.5j * theta), 0], [0, np.exp(0.5j * theta)]],
+                    dtype=np.complex128)
+
+
+def _measure_counts(sv: np.ndarray, shots: int, seed: int) -> Dict[str, int]:
+    probs = np.abs(sv) ** 2
+    probs /= probs.sum()
+    rng = np.random.default_rng(seed)
+    draws = rng.choice(len(sv), size=shots, p=probs)
+    counts: Dict[str, int] = {}
+    n = int(np.log2(len(sv)))
+    for d in draws:
+        key = format(int(d), f"0{n}b")
+        counts[key] = counts.get(key, 0) + 1
+    return counts
+
+
+def _dist_stats(counts: Dict[str, int], shots: int) -> Dict:
+    p = np.array(sorted(counts.values()), dtype=np.float64) / shots
+    ent = float(-(p * np.log2(p + 1e-300)).sum())
+    return {
+        "n_outcomes": len(counts),
+        "top_p": float(p.max()) if p.size else 0.0,
+        "dist_entropy_bits": ent,
+    }
+
+
+# ---------------------------------------------------------------------------
+# tensor_roll kernel family (simulated)
+# ---------------------------------------------------------------------------
+
+def tensor_roll_encode(block: np.ndarray, *, encoding: str = "amplitude",
+                       seed: int = 0) -> Tuple[np.ndarray, Dict]:
+    """Encode a tensor block into a simulated n-qubit register.
+
+    amplitude: |psi> = sum_i (x_i/||x||) |i>; signs are stored classically
+               (documented hybrid classical/quantum encoding — amplitude
+               encoding cannot carry sign in measurement probabilities).
+    angle:     one qubit per element, RY(2*atan(x_i)) rotations.
+    """
+    t0 = time.perf_counter()
+    W = np.asarray(block, dtype=np.float64)
+    flat = W.ravel()
+    mem = float(W.nbytes)
+    shots = 0
+    stats = None
+    if encoding == "amplitude":
+        n = _n_qubits_for(flat.size)
+        padded = np.zeros(2 ** n)
+        padded[:flat.size] = flat
+        norm = float(np.linalg.norm(padded))
+        signs = np.sign(padded)
+        sv = (padded / norm).astype(np.complex128) if norm > 0 else np.zeros(2 ** n, dtype=np.complex128)
+        if norm == 0:
+            sv[0] = 1.0
+        payload = {"sv": sv, "n": n, "norm": norm, "signs": signs,
+                   "shape": W.shape, "encoding": encoding}
+        mem += float(sv.nbytes)
+    elif encoding == "angle":
+        if flat.size > MAX_QUBITS:
+            raise ValueError(f"angle encoding needs 1 qubit/element: {flat.size} > {MAX_QUBITS}")
+        n = flat.size
+        sv = np.ones(2 ** n, dtype=np.complex128) / np.sqrt(2 ** n)
+        for q, x in enumerate(flat):
+            sv = _apply_1q(sv, _ry(2 * np.arctan(x)), q, n)
+        payload = {"sv": sv, "n": n, "shape": W.shape, "encoding": encoding}
+        mem += float(sv.nbytes)
+    else:
+        raise ValueError(f"unknown encoding {encoding!r}")
+    dt = time.perf_counter() - t0
+    rep = new_report(backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+                     kernel="tensor_roll_encode",
+                     tensor_dims=[W.shape, (2 ** payload["n"],)], precision="complex128",
+                     exec_time_s=dt, memory_bytes=mem, recursion_depth=0,
+                     shots=shots, measurement_stats=stats,
+                     reconstruction_error=None,
+                     extra={"encoding": encoding, "n_qubits": payload["n"]})
+    return payload, rep
+
+
+def tensor_roll_rotate(payload: Dict, *, angles, seed: int = 0) -> Tuple[Dict, Dict]:
+    """Apply RY rotations (one angle per qubit) to the register."""
+    t0 = time.perf_counter()
+    sv, n = payload["sv"].copy(), payload["n"]
+    angles = np.asarray(angles, dtype=float)
+    if angles.size != n:
+        raise ValueError(f"need {n} angles, got {angles.size}")
+    for q in range(n):
+        sv = _apply_1q(sv, _ry(float(angles[q])), q, n)
+    payload = dict(payload, sv=sv)
+    dt = time.perf_counter() - t0
+    rep = new_report(backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+                     kernel="tensor_roll_rotate",
+                     tensor_dims=[(2 ** n,)], precision="complex128",
+                     exec_time_s=dt, memory_bytes=float(sv.nbytes),
+                     recursion_depth=0, reconstruction_error=None)
+    return payload, rep
+
+
+def tensor_roll_entangle(payload: Dict, *, seed: int = 0) -> Tuple[Dict, Dict]:
+    """CNOT ladder across the register (nearest-neighbour entanglement)."""
+    t0 = time.perf_counter()
+    sv, n = payload["sv"].copy(), payload["n"]
+    for q in range(n - 1):
+        sv = _apply_cnot(sv, q, q + 1, n)
+    payload = dict(payload, sv=sv)
+    dt = time.perf_counter() - t0
+    rep = new_report(backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+                     kernel="tensor_roll_entangle",
+                     tensor_dims=[(2 ** n,)], precision="complex128",
+                     exec_time_s=dt, memory_bytes=float(sv.nbytes),
+                     recursion_depth=0, reconstruction_error=None)
+    return payload, rep
+
+
+def tensor_roll_measure(payload: Dict, *, shots: int = 1024,
+                        seed: int = 0) -> Tuple[Dict, Dict]:
+    """Born-rule measurement of the register -> counts."""
+    t0 = time.perf_counter()
+    sv, n = payload["sv"], payload["n"]
+    counts = _measure_counts(sv, shots, seed)
+    stats = _dist_stats(counts, shots)
+    payload = dict(payload, counts=counts, shots=shots)
+    dt = time.perf_counter() - t0
+    rep = new_report(backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+                     kernel="tensor_roll_measure",
+                     tensor_dims=[(2 ** n,)], precision="complex128",
+                     exec_time_s=dt, memory_bytes=float(sv.nbytes),
+                     recursion_depth=0, shots=shots,
+                     measurement_stats=stats, reconstruction_error=None)
+    return payload, rep
+
+
+def tensor_roll_reconstruct(payload: Dict) -> Tuple[np.ndarray, Dict]:
+    """Reconstruct the classical block from measurement counts.
+
+    Amplitude encoding: x_i_hat = sign_i * sqrt(count_i/shots) * ||x||.
+    This is a statistical estimator — its error is measured and reported,
+    never hidden.
+    """
+    t0 = time.perf_counter()
+    if payload.get("encoding") != "amplitude" or "counts" not in payload:
+        raise ValueError("reconstruct needs amplitude encoding + measured counts")
+    n, shots = payload["n"], payload["shots"]
+    norm, signs, shape = payload["norm"], payload["signs"], payload["shape"]
+    probs = np.zeros(2 ** n)
+    for bitstr, c in payload["counts"].items():
+        probs[int(bitstr, 2)] = c / shots
+    flat_hat = signs[:np.prod(shape)] * np.sqrt(probs[:int(np.prod(shape))]) * norm
+    What = flat_hat.reshape(shape)
+    dt = time.perf_counter() - t0
+    rep = new_report(backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+                     kernel="tensor_roll_reconstruct",
+                     tensor_dims=[(2 ** n,), tuple(shape)], precision="float64",
+                     exec_time_s=dt, memory_bytes=float(What.nbytes),
+                     recursion_depth=0, shots=shots,
+                     measurement_stats=_dist_stats(payload["counts"], shots),
+                     reconstruction_error=None)
+    return What, rep
+
+
+def tensor_roll_recursive(block: np.ndarray, *, depth: int = 2,
+                          shots: int = 1024, seed: int = 0,
+                          encoding: str = "amplitude") -> Tuple[np.ndarray, Dict]:
+    """Recursive kernel: at each level, rotate by block-derived angles,
+    entangle, measure a shrinking qubit subset, record per-level stats."""
+    t0 = time.perf_counter()
+    payload, reps = tensor_roll_encode(block, encoding=encoding, seed=seed)
+    reps_list = [reps]
+    n = payload["n"]
+    levels = []
+    for lvl in range(depth):
+        lt0 = time.perf_counter()
+        k = max(1, n - lvl)  # shrinking active subset
+        angles = np.linspace(0.1, 0.9, k) * float(np.mean(np.abs(block)) + 1e-6)
+        sub = dict(payload)
+        sv = payload["sv"].copy()
+        for q in range(k):
+            sv = _apply_1q(sv, _ry(float(angles[q])), q, n)
+        for q in range(k - 1):
+            sv = _apply_cnot(sv, q, q + 1, n)
+        sub["sv"] = sv
+        counts = _measure_counts(sv, shots, seed + lvl)
+        levels.append({"level": lvl, "active_qubits": k,
+                       "stats": _dist_stats(counts, shots)})
+        reps_list.append(new_report(
+            backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+            kernel="tensor_roll_recursive", tensor_dims=[(2 ** n,)],
+            precision="complex128", exec_time_s=time.perf_counter() - lt0,
+            memory_bytes=float(sv.nbytes), recursion_depth=lvl + 1,
+            shots=shots, measurement_stats=levels[-1]["stats"],
+            reconstruction_error=None))
+    payload, rep_m = tensor_roll_measure(payload, shots=shots, seed=seed)
+    What, rep_r = tensor_roll_reconstruct(payload)
+    dt = time.perf_counter() - t0
+    from .core import relative_error
+    err = relative_error(np.asarray(block, dtype=np.float64), What)
+    summary = new_report(
+        backend=QSIM_BACKEND, device="cpu (statevector simulator)",
+        kernel="tensor_roll_recursive[summary]",
+        tensor_dims=[tuple(np.asarray(block).shape), tuple(What.shape)],
+        precision="float64", exec_time_s=dt,
+        memory_bytes=float(np.asarray(block).nbytes + What.nbytes),
+        recursion_depth=depth, shots=shots,
+        measurement_stats={"levels": levels},
+        reconstruction_error=err)
+    # final measurement counts + qubit count: payload of the real
+    # process/IR boundary artifact (see tensor_roll/boundary.py)
+    summary["counts"] = {k: int(v) for k, v in payload["counts"].items()}
+    summary["n_qubits"] = n
+    return What, summary
+
+
+def qsim_encode_for_roll(W: np.ndarray, *, shots: int = 2048,
+                         seed: int = 0):
+    """Adapter used by core.evaluate_options: full qsim pipeline on a block,
+    returning (reconstructed_block, summary_report)."""
+    return tensor_roll_recursive(np.asarray(W, dtype=np.float64),
+                                 depth=1, shots=shots, seed=seed)

tensor_roll/quant.py

@@ -0,0 +1,384 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Quantization formats: FP16 / BF16 / INT8 / INT4.
+
+All quantizers are implemented here from first principles (no external
+quantizer libraries). Every quantize() returns (payload, meta) and every
+meta carries enough information for an exact dequantize() round-trip.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def to_fp16(W: np.ndarray):
+    W = np.asarray(W, dtype=np.float32)
+    return W.astype(np.float16), {"fmt": "fp16"}
+
+
+def from_fp16(q: np.ndarray) -> np.ndarray:
+    return np.asarray(q, dtype=np.float32)
+
+
+def to_bf16(W: np.ndarray):
+    """Round-to-nearest-even float32 -> bfloat16 (stored as uint16)."""
+    a = np.asarray(W, dtype=np.float32)
+    i = a.view(np.int32).copy()
+    finite = np.isfinite(a)
+    lsb = (i >> 16) & 1
+    i[finite] += (0x7FFF + lsb[finite]).astype(np.int32)
+    return (i >> 16).astype(np.uint16), {"fmt": "bf16"}
+
+
+def from_bf16(q: np.ndarray) -> np.ndarray:
+    return (np.asarray(q, dtype=np.int32) << 16).view(np.float32)
+
+
+def quantize_int8(W: np.ndarray):
+    """Asymmetric per-tensor INT8."""
+    W = np.asarray(W, dtype=np.float64)
+    wmin, wmax = float(W.min()), float(W.max())
+    if wmax == wmin:
+        return np.zeros(W.shape, dtype=np.int8), {
+            "fmt": "int8", "scale": 1.0, "zero": 0.0}
+    scale = (wmax - wmin) / 255.0
+    q = np.clip(np.round((W - wmin) / scale), 0, 255).astype(np.int64) - 128
+    return q.astype(np.int8), {"fmt": "int8", "scale": scale, "zero": wmin}
+
+
+def dequantize_int8(q: np.ndarray, meta: dict) -> np.ndarray:
+    return (q.astype(np.float64) + 128.0) * meta["scale"] + meta["zero"]
+
+
+def quantize_int4(W: np.ndarray, group: int = 32):
+    """Group-wise asymmetric INT4, two nibbles packed per byte (low nibble
+    first). Groups run along the last axis; ragged tail is zero-padded and
+    the pad is recorded so dequantize() restores the exact shape."""
+    W = np.asarray(W, dtype=np.float64)
+    shape = list(W.shape)
+    last = shape[-1]
+    rows = int(np.prod(shape[:-1])) if len(shape) > 1 else 1
+    flat = W.reshape(rows, last)
+    pad = (-last) % group
+    if pad:
+        flat = np.concatenate([flat, np.zeros((rows, pad))], axis=1)
+    G = flat.reshape(-1, group)
+    gmin = G.min(axis=1)
+    gmax = G.max(axis=1)
+    scale = np.maximum(gmax - gmin, 1e-300) / 15.0
+    q = np.clip(np.round((G - gmin[:, None]) / scale[:, None]), 0, 15).astype(np.uint8)
+    packed = (q[:, 0::2] | (q[:, 1::2] << 4)).astype(np.uint8)
+    meta = {"fmt": "int4", "group": group, "shape": shape,
+            "scales": scale.astype(np.float64), "zeros": gmin.astype(np.float64),
+            "rows": rows, "last": last}
+    return packed, meta
+
+
+def dequantize_int4(packed: np.ndarray, meta: dict) -> np.ndarray:
+    group, rows, last = meta["group"], meta["rows"], meta["last"]
+    p = np.asarray(packed).reshape(-1, group // 2)
+    q = np.empty((p.shape[0], group), dtype=np.float64)
+    q[:, 0::2] = p & 0x0F
+    q[:, 1::2] = (p >> 4) & 0x0F
+    G = q * np.asarray(meta["scales"])[:, None] + np.asarray(meta["zeros"])[:, None]
+    flat = G.reshape(rows, -1)[:, :last]
+    return flat.reshape(meta["shape"]).astype(np.float32)
+
+
+def quantize_tensor(W: np.ndarray, fmt: str):
+    """Dispatch: fmt in {fp32, fp16, bf16, int8, int4}."""
+    if fmt == "fp32":
+        return np.asarray(W, dtype=np.float32), {"fmt": "fp32"}
+    if fmt == "fp16":
+        return to_fp16(W)
+    if fmt == "bf16":
+        return to_bf16(W)
+    if fmt == "int8":
+        return quantize_int8(W)
+    if fmt == "int4":
+        return quantize_int4(W)
+    raise ValueError(f"unknown format {fmt!r}")
+
+
+def dequantize_tensor(q: np.ndarray, meta: dict) -> np.ndarray:
+    fmt = meta["fmt"]
+    if fmt == "fp32":
+        return np.asarray(q, dtype=np.float32)
+    if fmt == "fp16":
+        return from_fp16(q)
+    if fmt == "bf16":
+        return from_bf16(q)
+    if fmt == "int8":
+        return dequantize_int8(q, meta).astype(np.float32)
+    if fmt == "int4":
+        return dequantize_int4(q, meta)
+    raise ValueError(f"unknown format {fmt!r}")
+
+
+def payload_nbytes(q: np.ndarray, fmt: str) -> int:
+    return int(np.asarray(q).nbytes)
+
+
+# ---------------------------------------------------------------------------
+# INT4 failure resolution (F6): per-tensor error instrumentation, advanced
+# schemes, mixed precision, and quantization-aware recovery.
+# ---------------------------------------------------------------------------
+
+def quantize_int4_per_tensor(W: np.ndarray):
+    """Whole-tensor asymmetric INT4: ONE scale/zero over the entire tensor."""
+    W = np.asarray(W, dtype=np.float64)
+    shape = list(W.shape)
+    flat = W.ravel()
+    gmin, gmax = float(flat.min()), float(flat.max())
+    scale = max(gmax - gmin, 1e-300) / 15.0
+    q = np.clip(np.round((flat - gmin) / scale), 0, 15).astype(np.uint8)
+    if q.size % 2:
+        q = np.concatenate([q, np.zeros(1, dtype=np.uint8)])
+    packed = (q[0::2] | (q[1::2] << 4)).astype(np.uint8)
+    meta = {"fmt": "int4", "scheme": "per-tensor", "shape": shape,
+            "scales": np.array([scale]), "zeros": np.array([gmin]),
+            "size": flat.size}
+    return packed, meta
+
+
+def dequantize_int4_per_tensor(packed: np.ndarray, meta: dict) -> np.ndarray:
+    q = np.asarray(packed)
+    flat = np.empty(q.size * 2, dtype=np.float64)
+    flat[0::2] = q & 0x0F
+    flat[1::2] = (q >> 4) & 0x0F
+    flat = flat[:meta["size"]]
+    W = flat * float(meta["scales"][0]) + float(meta["zeros"][0])
+    return W.reshape(meta["shape"]).astype(np.float32)
+
+
+def quantize_int4_per_channel(W: np.ndarray):
+    """Per-channel (per-row) asymmetric INT4: one scale/zero per row instead
+    of per group-of-32. Returns (packed, meta) with the same nibble layout
+    as quantize_int4 so dequantize_int4-style unpacking applies."""
+    W = np.asarray(W, dtype=np.float64)
+    shape = list(W.shape)
+    last = shape[-1]
+    rows = int(np.prod(shape[:-1])) if len(shape) > 1 else 1
+    flat = W.reshape(rows, last)
+    gmin = flat.min(axis=1)
+    gmax = flat.max(axis=1)
+    scale = np.maximum(gmax - gmin, 1e-300) / 15.0
+    q = np.clip(np.round((flat - gmin[:, None]) / scale[:, None]), 0, 15)
+    q = q.astype(np.uint8)
+    # pad last dim to even for nibble packing
+    if last % 2:
+        q = np.concatenate([q, np.zeros((rows, 1), dtype=np.uint8)], axis=1)
+    packed = (q[:, 0::2] | (q[:, 1::2] << 4)).astype(np.uint8)
+    meta = {"fmt": "int4", "scheme": "per-channel", "shape": shape,
+            "scales": scale.astype(np.float64),
+            "zeros": gmin.astype(np.float64),
+            "rows": rows, "last": last}
+    return packed, meta
+
+
+def dequantize_int4_per_channel(packed: np.ndarray, meta: dict) -> np.ndarray:
+    rows, last = meta["rows"], meta["last"]
+    p = np.asarray(packed).reshape(rows, -1)
+    q = np.empty((rows, p.shape[1] * 2), dtype=np.float64)
+    q[:, 0::2] = p & 0x0F
+    q[:, 1::2] = (p >> 4) & 0x0F
+    q = q[:, :last]
+    W = q * np.asarray(meta["scales"])[:, None] + np.asarray(meta["zeros"])[:, None]
+    return W.reshape(meta["shape"]).astype(np.float32)
+
+
+def search_group_size(W: np.ndarray,
+                      groups: tuple = (16, 32, 64, 128)) -> dict:
+    """Search the INT4 group size by MEASURED reconstruction MSE — the
+    winner is the argmin of measured error, never a hard-coded default."""
+    W = np.asarray(W, dtype=np.float64)
+    results = []
+    for g in groups:
+        if g < 2:
+            continue
+        q, meta = quantize_int4(W, group=g)
+        back = dequantize_int4(q, meta).astype(np.float64)
+        err = float(np.mean((W - back) ** 2))
+        results.append({"group": g, "mse": err,
+                        "bytes": int(np.asarray(q).nbytes)})
+    results.sort(key=lambda r: r["mse"])
+    return {"results": results, "best_group": results[0]["group"],
+            "best_mse": results[0]["mse"]}
+
+
+def quant_error_map(W: np.ndarray, Wd: np.ndarray) -> dict:
+    """Instrument quantization error per tensor. All values measured."""
+    W = np.asarray(W, dtype=np.float64)
+    Wd = np.asarray(Wd, dtype=np.float64)
+    err = W - Wd
+    flat = err.ravel()
+    sd = float(flat.std()) if flat.size else 0.0
+    per_channel = []
+    if W.ndim == 2:
+        for r in range(W.shape[0]):
+            e = err[r]
+            per_channel.append(float(np.mean(e ** 2)))
+    # per-group error at group=32 along the last axis
+    per_group = []
+    if W.ndim >= 1 and W.shape[-1] >= 32:
+        G = err.reshape(-1, 32)
+        per_group = [float(np.mean(g ** 2)) for g in G]
+    denom = float(np.linalg.norm(W))
+    return {
+        "min": float(err.min()) if err.size else 0.0,
+        "max": float(err.max()) if err.size else 0.0,
+        "mean": float(err.mean()) if err.size else 0.0,
+        "variance": float(err.var()) if err.size else 0.0,
+        "std": sd,
+        "outlier_frac": float(np.mean(np.abs(flat) > 3 * sd)) if sd > 0 else 0.0,
+        "mse": float(np.mean(flat ** 2)) if flat.size else 0.0,
+        "cosine_sim": float(np.dot(W.ravel(), Wd.ravel())
+                            / (np.linalg.norm(W.ravel())
+                               * np.linalg.norm(Wd.ravel()) + 1e-300)),
+        "rel_err": float(np.linalg.norm(err) / (denom + 1e-300)),
+        "per_channel_mse": per_channel,
+        "per_group_mse": per_group,
+    }
+
+
+def int4_scheme_report(W: np.ndarray) -> dict:
+    """Benchmark per-tensor / per-channel / group-wise INT4 on one tensor.
+
+    Returns measured MSE + byte size for each scheme; the caller picks the
+    winner from measurements."""
+    W = np.asarray(W, dtype=np.float64)
+    out = {}
+    qt, mt = quantize_int4_per_tensor(W)
+    backt = dequantize_int4_per_tensor(qt, mt).astype(np.float64)
+    out["per-tensor"] = {"mse": float(np.mean((W - backt) ** 2)),
+                         "bytes": int(np.asarray(qt).nbytes),
+                         "meta_bytes": 16}
+    qp, mp = quantize_int4_per_channel(W)
+    backp = dequantize_int4_per_channel(qp, mp).astype(np.float64)
+    out["per-channel"] = {"mse": float(np.mean((W - backp) ** 2)),
+                          "bytes": int(np.asarray(qp).nbytes),
+                          "meta_bytes": int(mp["scales"].nbytes
+                                            + mp["zeros"].nbytes)}
+    gs = search_group_size(W)
+    out["group-wise"] = {"mse": gs["best_mse"],
+                         "bytes": next(r["bytes"] for r in gs["results"]
+                                       if r["group"] == gs["best_group"]),
+                         "best_group": gs["best_group"],
+                         "all": gs["results"]}
+    # int8 reference for the mixed-precision gain computation
+    qi, mi = quantize_int8(W)
+    backi = dequantize_int8(qi, mi).astype(np.float64)
+    out["int8"] = {"mse": float(np.mean((W - backi) ** 2)),
+                   "bytes": int(np.asarray(qi).nbytes)}
+    return out
+
+
+def mixed_precision_plan(params: dict, size_budget_bytes: int) -> dict:
+    """Assign INT4 vs INT8 per tensor under a physical size budget.
+
+    Tensors where INT8 buys the most error reduction per extra byte stay
+    INT8; the rest go INT4 (best measured scheme per tensor). Sensitive
+    tensors are thereby protected by measurement, not by fiat.
+    """
+    rows = []
+    for k, v in params.items():
+        v = np.asarray(v)
+        if v.ndim != 2 or v.size < 64:
+            rows.append({"tensor": k, "fmt": "fp32",
+                         "bytes": int(v.nbytes), "gain_per_byte": 0.0,
+                         "int4_mse": 0.0, "int8_mse": 0.0})
+            continue
+        rep = int4_scheme_report(v)
+        best4 = min(rep["per-tensor"], rep["per-channel"],
+                    rep["group-wise"], key=lambda r: r["mse"])
+        b4 = best4["bytes"] + best4.get("meta_bytes", 0)
+        b8 = rep["int8"]["bytes"]
+        gain = max(0.0, best4["mse"] - rep["int8"]["mse"])
+        gpb = gain / max(1, b8 - b4)
+        rows.append({"tensor": k, "fmt": "int4", "bytes": b4,
+                     "gain_per_byte": gpb, "int4_mse": best4["mse"],
+                     "int8_mse": rep["int8"]["mse"],
+                     "int4_scheme": "per-tensor"
+                     if best4 is rep["per-tensor"] else
+                     ("per-channel" if best4 is rep["per-channel"]
+                      else f"group-{rep['group-wise']['best_group']}")})
+    # start all-int4, upgrade highest gain/byte to int8 while budget allows
+    total4 = sum(r["bytes"] for r in rows)
+    cands = sorted([r for r in rows if r["fmt"] == "int4"
+                    and r["gain_per_byte"] > 0],
+                   key=lambda r: -r["gain_per_byte"])
+    plan, used = {}, total4
+    for r in rows:
+        plan[r["tensor"]] = "int4"
+    for r in cands:
+        v = np.asarray(params[r["tensor"]])
+        qi, _ = quantize_int8(v)
+        b8 = int(np.asarray(qi).nbytes)
+        if used - r["bytes"] + b8 <= size_budget_bytes:
+            plan[r["tensor"]] = "int8"
+            used = used - r["bytes"] + b8
+    return {"plan": plan, "total_bytes": used,
+            "budget_bytes": int(size_budget_bytes),
+            "within_budget": used <= size_budget_bytes,
+            "n_int8": sum(1 for v in plan.values() if v == "int8"),
+            "n_int4": sum(1 for v in plan.values() if v == "int4"),
+            "rows": rows}
+
+
+def dequantize_dispatch(q: np.ndarray, meta: dict) -> np.ndarray:
+    """Dequantize honoring per-tensor / per-channel int4 metadata."""
+    if meta.get("fmt") == "int4" and meta.get("scheme") == "per-tensor":
+        return dequantize_int4_per_tensor(q, meta)
+    if meta.get("fmt") == "int4" and meta.get("scheme") == "per-channel":
+        return dequantize_int4_per_channel(q, meta)
+    return dequantize_tensor(q, meta)
+
+
+def recovery_train(s_qparams: dict, s_cfg, t_params: dict, t_cfg,
+                   *, steps: int = 30, batch: int = 64, lr: float = 1e-3,
+                   seed: int = 0) -> dict:
+    """Quantization-aware recovery (spec section 9):
+
+        INT4-dequantized student -> distillation (task + logit KL)
+        vs the teacher -> requantize INT4 -> evaluate.
+
+    Returns measured ppl before/after and the gap delta. Improvement is
+    reported ONLY if measured; otherwise the (non-)result stands.
+    """
+    from .model import (Adam, backward, ce_loss, eval_metrics, forward,
+                        gen_data, kl_loss)
+    rng = np.random.default_rng(seed)
+    # start from the dequantized INT4 weights (float working copy)
+    params = {k: v.astype(np.float32) for k, v in s_qparams.items()}
+    before = eval_metrics(params, s_cfg, batches=4, batch=batch, seed=911)
+    opt = Adam(params, lr=lr)
+    for _ in range(steps):
+        ids = gen_data(rng, batch, s_cfg)
+        tl, _ = forward(t_params, t_cfg, ids[:, :-1])
+        sl, cache = forward(params, s_cfg, ids[:, :-1])
+        lt, dl_t = ce_loss(sl, ids[:, 1:])
+        lk, dl_k = kl_loss(sl, tl, tau=2.0)
+        grads = backward(params, s_cfg, cache, dl_t + 0.5 * dl_k)
+        opt.step(params, grads)
+    after = eval_metrics(params, s_cfg, batches=4, batch=batch, seed=911)
+    # requantize and measure the real INT4 artifact quality
+    re_q = {}
+    for k, v in params.items():
+        if v.ndim == 2 and v.size >= 64:
+            q, m = quantize_int4(v)
+            re_q[k] = dequantize_int4(q, m).astype(np.float32)
+        else:
+            re_q[k] = v
+    re_eval = eval_metrics(re_q, s_cfg, batches=4, batch=batch, seed=911)
+    return {
+        "steps": steps,
+        "ppl_before": float(np.exp(before["loss"])),
+        "ppl_after_train": float(np.exp(after["loss"])),
+        "ppl_after_requant": float(np.exp(re_eval["loss"])),
+        "gap_before": float(np.exp(before["loss"]) - np.exp(after["loss"])),
+        "gap_delta": float(np.exp(before["loss"])
+                           - np.exp(re_eval["loss"])),
+        "improved": bool(np.exp(re_eval["loss"]) < np.exp(before["loss"])),
+    }

tensor_roll/sandbox.py

@@ -0,0 +1,194 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""OS-level sandbox supervisor (spec section 12).
+
+Architecture (enforced below):
+    USER -> TERMINAL -> TENSOR ROLL -> MODEL -> TOOL REQUEST
+        -> SANDBOX SUPERVISOR -> POLICY -> DENY | EXECUTE -> ISOLATED PROCESS
+
+Enforced: process isolation (separate session/process group), filesystem
+confinement (all path arguments must resolve inside the jail), resource
+limits (RLIMIT_CPU/AS/FSIZE/NPROC/NOFILE via preexec_fn), environment
+filtering (whitelist), child-process restrictions (own process group,
+killed on timeout), signal handling, and a JSON-lines audit log.
+
+Network namespaces are attempted best-effort (unshare(CLONE_NEWNET));
+when the kernel refuses, the supervisor records net_isolated=false and
+falls back to command-level policy (network fetch tools are denied).
+What is enforced vs. best-effort is reported honestly, never assumed.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import signal
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass, field
+
+from .util import AuditLog, ensure_dir, utc_now_iso
+
+try:
+    import resource as _resource
+except ImportError:  # pragma: no cover
+    _resource = None
+
+
+DENIED_BINS = {
+    # destructive
+    "rm", "dd", "mkfs", "mkfs.ext4", "shutdown", "reboot", "halt",
+    "poweroff", "init", "kill", "killall", "pkill",
+    # network fetch / exfiltration
+    "curl", "wget", "aria2c", "scp", "sftp", "ftp", "telnet", "nc",
+    "ncat", "socat", "ssh",
+    # privilege / package management
+    "sudo", "su", "doas", "apt", "apt-get", "dpkg", "pip", "pip3",
+    "snap", "flatpak",
+    # shells that escape argument scanning
+    "sh", "bash", "zsh", "fish", "dash",
+}
+
+ENV_WHITELIST = {"PATH", "HOME", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR",
+                 "PYTHONPATH", "PYTHONHOME", "TERM", "TZ"}
+
+
+@dataclass
+class Policy:
+    max_cpu_s: int = 30
+    max_mem_mb: int = 1024
+    max_fsize_mb: int = 256
+    max_nproc: int = 32
+    max_nofile: int = 128
+    timeout_s: int = 60
+
+
+@dataclass
+class Verdict:
+    allowed: bool
+    reason: str
+    resolved_bin: str = ""
+
+
+class SandboxSupervisor:
+    def __init__(self, workdir: str, policy: Policy | None = None):
+        self.workdir = ensure_dir(workdir)
+        self.policy = policy or Policy()
+        self.jail = ensure_dir(os.path.join(self.workdir, "jail"))
+        self.audit = AuditLog(os.path.join(self.workdir, "audit.log"))
+        self.netns_available = self._probe_netns()
+
+    @staticmethod
+    def _probe_netns() -> bool:
+        """Honest capability probe: can we actually unshare a net namespace?"""
+        try:
+            r = subprocess.run(["unshare", "--net", "true"],
+                               capture_output=True, timeout=10)
+            return r.returncode == 0
+        except Exception:
+            return False
+
+    # -- policy ---------------------------------------------------------
+    def check(self, argv: list[str]) -> Verdict:
+        if not argv:
+            return Verdict(False, "empty command")
+        name = os.path.basename(argv[0])
+        if name in DENIED_BINS:
+            return Verdict(False, f"denied binary: {name}")
+        resolved = shutil.which(argv[0], path="/usr/bin:/bin")
+        if resolved is None:
+            # allow binaries shipped inside the jail itself
+            cand = os.path.join(self.jail, os.path.basename(argv[0]))
+            if os.path.isfile(cand) and os.access(cand, os.X_OK):
+                resolved = cand
+            else:
+                return Verdict(False, f"binary not found in restricted PATH: {argv[0]}")
+        for arg in argv[1:]:
+            if ".." in arg.split(os.sep):
+                return Verdict(False, f"path traversal rejected: {arg}")
+            if os.path.isabs(arg):
+                real = os.path.realpath(arg)
+                if not (real == self.jail or real.startswith(self.jail + os.sep)):
+                    return Verdict(False,
+                                   f"absolute path outside jail rejected: {arg}")
+        return Verdict(True, "policy pass", resolved)
+
+    # -- execution ------------------------------------------------------
+    def _preexec(self):
+        # NOTE: start_new_session=True already puts the child in its own
+        # session + process group (the child-process restriction anchor).
+        if _resource is not None:
+            p = self.policy
+            _resource.setrlimit(_resource.RLIMIT_CPU, (p.max_cpu_s, p.max_cpu_s))
+            mem = p.max_mem_mb * 1024 * 1024
+            _resource.setrlimit(_resource.RLIMIT_AS, (mem, mem))
+            _resource.setrlimit(_resource.RLIMIT_FSIZE,
+                                (p.max_fsize_mb * 1024 * 1024,) * 2)
+            _resource.setrlimit(_resource.RLIMIT_NPROC, (p.max_nproc, p.max_nproc))
+            _resource.setrlimit(_resource.RLIMIT_NOFILE, (p.max_nofile, p.max_nofile))
+        # best-effort network namespace; failure is recorded, not hidden
+        try:
+            os.unshare(os.CLONE_NEWNET)
+        except OSError:
+            pass
+
+    def run(self, cmd: str, *, timeout: int | None = None) -> dict:
+        argv = shlex.split(cmd)
+        verdict = self.check(argv)
+        rec = {"ts": utc_now_iso(), "cmd": cmd, "allowed": verdict.allowed,
+               "reason": verdict.reason}
+        if not verdict.allowed:
+            self.audit.record(event="sandbox.deny", **rec)
+            rec["returncode"] = None
+            return rec
+        env = {k: v for k, v in os.environ.items() if k in ENV_WHITELIST}
+        env["PATH"] = "/usr/bin:/bin"
+        env["TMPDIR"] = self.jail
+        t0 = time.perf_counter()
+        proc = subprocess.Popen(
+            [verdict.resolved_bin] + argv[1:],
+            cwd=self.jail, env=env, preexec_fn=self._preexec,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+            start_new_session=True)  # own process group: child restriction anchor
+        try:
+            out, err = proc.communicate(timeout=timeout or self.policy.timeout_s)
+            rc = proc.returncode
+        except subprocess.TimeoutExpired:
+            rc, out, err = "timeout", "", ""
+            try:
+                os.killpg(proc.pid, signal.SIGKILL)
+            except Exception:
+                pass
+            try:
+                out, err = proc.communicate(timeout=5)
+            except Exception:
+                pass
+        # reap any stray children via the process group
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            pass
+        rec.update({"returncode": rc,
+                    "stdout": (out or "")[-4000:],
+                    "stderr": (err or "")[-4000:],
+                    "elapsed_s": time.perf_counter() - t0,
+                    "netns_isolated": self.netns_available})
+        self.audit.record(event="sandbox.execute", **rec)
+        return rec
+
+    def demo(self) -> list[dict]:
+        """Demonstrably ALLOW a permitted action and DENY forbidden ones."""
+        results = []
+        results.append(("ALLOW echo", self.run("echo hello-tensor-roll")))
+        with tempfile.NamedTemporaryFile("w", suffix=".txt",
+                                         dir=self.jail, delete=False) as f:
+            f.write("jail-write-ok")
+        results.append(("ALLOW jail write+read",
+                        self.run(f"cat {f.name}")))
+        results.append(("DENY shadow", self.run("cat /etc/shadow")))
+        results.append(("DENY curl", self.run("curl http://example.com")))
+        results.append(("DENY rm", self.run("rm -rf /")))
+        return results

tensor_roll/search.py

@@ -0,0 +1,240 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Representation search: 30B -> 8B (parameterized).
+
+Pipeline:
+  1. Per-tensor TensorRoll analysis (core.roll_tree) -> measured options.
+  2. Global greedy selection under the hard parameter budget.
+  3. Student *architecture* search over (d, heads, dff, layers): each
+     candidate is scored by projected retained energy, where every teacher
+     tensor is mapped to the candidate shape by truncated-SVD projection
+     and its retained singular energy is measured. No hard-coded answer —
+     the argmax under the budget wins.
+  4. Student weight init from the teacher via the winning projections
+     (Xavier where no projection exists), with per-tensor provenance.
+
+The budget is P_target <= 8.5B for the real 30B path. At small scale the
+same ratio applies: budget = teacher_params * (8.5/30).
+"""
+
+from __future__ import annotations
+
+import itertools
+
+import numpy as np
+
+from . import core as C
+from .model import Config, count_params, init_params
+from . import qsim as Q
+
+BUDGET_RATIO = 8.5 / 30.0  # hard architectural budget, same at every scale
+ABS_BUDGET_CAP = 8_500_000_000
+
+
+def _svd_cache(params: dict) -> dict:
+    cache = {}
+    for k, v in params.items():
+        v = np.asarray(v, dtype=np.float64)
+        if v.ndim == 2 and min(v.shape) > 1:
+            U, s, Vt = np.linalg.svd(v, full_matrices=False)
+            cache[k] = (U, s, Vt)
+    return cache
+
+
+def project_matrix(W: np.ndarray, out_shape: tuple, svd=None):
+    """Truncated-SVD projection of W to out_shape (both dims <= input dims).
+    Returns (W_proj, retained_energy_fraction). Optimal rank-k approximation,
+    cropped — the classical baseline every exotic option is measured against.
+    """
+    W = np.asarray(W, dtype=np.float64)
+    mo, no = out_shape
+    m, n = W.shape
+    assert mo <= m and no <= n, f"projection only shrinks: {W.shape} -> {out_shape}"
+    if svd is None:
+        U, s, Vt = np.linalg.svd(W, full_matrices=False)
+    else:
+        U, s, Vt = svd
+    k = min(mo, no)
+    Wp = (U[:mo, :k] * s[:k]) @ Vt[:k, :no]
+    total = float((s ** 2).sum())
+    energy = float((s[:k] ** 2).sum() / total) if total > 0 else 1.0
+    return Wp.astype(np.float32), energy
+
+
+def _candidate_configs(teacher_cfg: Config):
+    """Small grid of student architectures to search (real 30B path uses a
+    wider grid over the same code)."""
+    ds = sorted({teacher_cfg.d // 2, max(8, teacher_cfg.d * 3 // 4)})
+    hs = sorted({max(1, teacher_cfg.heads - 1), teacher_cfg.heads})
+    dffs = sorted({teacher_cfg.dff // 2, max(16, teacher_cfg.dff * 3 // 4)})
+    ls = sorted({max(1, teacher_cfg.layers - 1), teacher_cfg.layers})
+    for d, h, dff, l in itertools.product(ds, hs, dffs, ls):
+        if d % h == 0:
+            yield Config(vocab=teacher_cfg.vocab, d=d, heads=h,
+                         layers=l, dff=dff, seq=teacher_cfg.seq)
+
+
+def _config_param_count(cfg: Config) -> int:
+    # mirrors init_params structure without allocating
+    n = cfg.vocab * cfg.d
+    per_layer = (4 * cfg.d * cfg.d + 4 * cfg.d      # q,k,v,o + biases
+                 + 4 * cfg.d                        # two layernorms
+                 + 2 * cfg.d * cfg.dff + cfg.dff + cfg.d)  # mlp
+    n += cfg.layers * per_layer
+    n += 2 * cfg.d + cfg.d * cfg.vocab + cfg.vocab
+    return n
+
+
+def search_student_config(teacher_params: dict, teacher_cfg: Config,
+                          budget_params: float):
+    """Returns (best_cfg, scored_list). scored_list entries are
+    (cfg, est_energy, param_count), sorted by energy desc."""
+    svd = _svd_cache(teacher_params)
+    scored = []
+    for cfg in _candidate_configs(teacher_cfg):
+        pc = _config_param_count(cfg)
+        if pc > budget_params:
+            continue
+        energies, weights = [], []
+        for k, v in teacher_params.items():
+            v = np.asarray(v)
+            if v.ndim != 2 or k not in svd:
+                continue
+            # map teacher key -> student key shape
+            sk = _student_key(k, cfg, teacher_cfg)
+            if sk is None:
+                continue
+            sshape = _student_shape(k, v.shape, cfg, teacher_cfg)
+            if sshape is None or sshape[0] > v.shape[0] or sshape[1] > v.shape[1]:
+                continue
+            _, e = project_matrix(v, sshape, svd[k])
+            energies.append(e)
+            weights.append(v.size)
+        est = float(np.average(energies, weights=weights)) if energies else 0.0
+        scored.append({"cfg": cfg.to_dict(), "est_energy": est, "params": pc})
+    scored.sort(key=lambda s: -s["est_energy"])
+    if not scored:
+        raise RuntimeError("no student config fits the budget; cannot proceed honestly")
+    best = Config.from_dict(scored[0]["cfg"])
+    return best, scored
+
+
+def _student_key(k: str, cfg: Config, tcfg: Config):
+    # student uses identical key names; layer count may shrink
+    if k.startswith("L"):
+        l = int(k[1:].split(".")[0])
+        if l >= cfg.layers:
+            return None
+    return k
+
+
+def _student_shape(k: str, tshape: tuple, cfg: Config, tcfg: Config):
+    d, td = cfg.d, tcfg.d
+    if k == "emb":
+        return (cfg.vocab, d)
+    if k in ("lnfg", "lnfb"):
+        return (d,)
+    if k == "Whead":
+        return (d, cfg.vocab)
+    if k == "bhead":
+        return (cfg.vocab,)
+    if k.startswith("L"):
+        rest = k.split(".", 1)[1]
+        if rest in ("ln1g", "ln1b", "ln2g", "ln2b"):
+            return (d,)
+        if rest in ("Wq", "Wk", "Wv", "Wo"):
+            return (d, d)
+        if rest in ("bq", "bk", "bv", "bo"):
+            return (d,)
+        if rest == "W1":
+            return (d, cfg.dff)
+        if rest == "b1":
+            return (cfg.dff,)
+        if rest == "W2":
+            return (cfg.dff, d)
+        if rest == "b2":
+            return (d,)
+    return None
+
+
+def init_student_from_teacher(teacher_params: dict, teacher_cfg: Config,
+                              student_cfg: Config, rng: np.random.Generator):
+    """Project teacher weights into the student shapes; Xavier elsewhere.
+    Returns (student_params, provenance, achieved_energies)."""
+    student = init_params(rng, student_cfg)  # Xavier baseline everywhere
+    svd = _svd_cache(teacher_params)
+    provenance, energies = {}, {}
+    for k, v in teacher_params.items():
+        sk = _student_key(k, student_cfg, teacher_cfg)
+        if sk is None or sk not in student:
+            provenance[k] = "dropped-by-architecture-search"
+            continue
+        sv = student[sk]
+        v = np.asarray(v)
+        if (v.ndim == 2 and sv.ndim == 2 and k in svd
+                and sv.shape[0] <= v.shape[0] and sv.shape[1] <= v.shape[1]):
+            proj, e = project_matrix(v, sv.shape, svd[k])
+            student[sk] = proj
+            provenance[k] = f"truncated-svd-projection energy={e:.4f}"
+            energies[k] = e
+        elif v.shape == sv.shape:
+            student[sk] = v.astype(np.float32)
+            provenance[k] = "copied-exact"
+            energies[k] = 1.0
+        else:
+            provenance[k] = "xavier-init(shape-mismatch)"
+            energies[k] = 0.0
+    return student, provenance, energies
+
+
+def head_consolidation_report(teacher_params: dict, teacher_cfg: Config,
+                              student_cfg: Config) -> dict:
+    """Which attention heads survived consolidation, by measured spectral
+    energy of each head's QK block."""
+    report = {}
+    for l in range(teacher_cfg.layers):
+        if l >= student_cfg.layers:
+            continue
+        Wq = np.asarray(teacher_params[f"L{l}.Wq"], dtype=np.float64)
+        dh = teacher_cfg.dh
+        energies = []
+        for h in range(teacher_cfg.heads):
+            blk = Wq[:, h * dh:(h + 1) * dh]
+            s = np.linalg.svd(blk, compute_uv=False)
+            energies.append(float((s ** 2).sum()))
+        order = sorted(range(len(energies)), key=lambda h: -energies[h])
+        kept = sorted(order[:student_cfg.heads])
+        report[f"layer_{l}"] = {
+            "head_energies": [round(e, 4) for e in energies],
+            "kept_heads": kept,
+            "dropped_heads": sorted(order[student_cfg.heads:]),
+        }
+    return report
+
+
+def run_roll_analysis(teacher_params: dict, *, depth: int = 3,
+                      quantum_policy: str = "off", rank: int = 0,
+                      stats: dict = None):
+    """Run the first-class TensorRoll(T, axis, depth, rank, quantum_policy)
+    operator over every teacher tensor. Returns (trees, leaves).
+
+    `stats`: optional {tensor_name: {"act_rms", "grad_norm", "grad_rel"}}
+    from model.measure_tensor_stats; attached to each leaf's metrics so the
+    search sees measured activation/gradient contributions.
+    """
+    trees, leaves = {}, []
+    for k in sorted(teacher_params.keys()):
+        W = np.asarray(teacher_params[k])
+        res = C.TensorRoll(W, 0, depth, rank, quantum_policy,
+                           qsim_encode=Q.qsim_encode_for_roll
+                           if quantum_policy != "off" else None,
+                           name=k)
+        trees[k] = res["tree"]
+        for leaf in C.iter_leaves(res["tree"]):
+            if stats and k in stats:
+                leaf.metrics["act_rms"] = stats[k]["act_rms"]
+                leaf.metrics["grad_norm"] = stats[k]["grad_norm"]
+                leaf.metrics["grad_rel"] = stats[k]["grad_rel"]
+            leaves.append(leaf)
+    return trees, leaves

tensor_roll/trq.py

@@ -0,0 +1,192 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""The .trq container format (spec section 10) — a real binary codec.
+
+Layout (all integers little-endian):
+  magic            4 bytes  b'TRQ1'
+  header_len       u32
+  header           JSON {version, arch, n_tensors, provenance, roll_meta, created}
+  per tensor:
+    name_len       u16
+    name           bytes
+    ndim           u8
+    shape          ndim x u64
+    dtype_code     u8   0=fp32 1=fp16 2=bf16 3=int8 4=int4-packed
+    quant_code     u8   0=none 1=int8-asym 2=int4-group32 3=fp16-cast 4=bf16-cast
+    meta_len       u32
+    meta           JSON {quantization metadata: scales/zeros as base64 f64,
+                         roll metadata, codebooks}
+    data_len       u64
+    data           bytes
+    checksum       32 bytes sha256(data)
+  footer           32 bytes sha256(all preceding bytes)
+
+read_trq() verifies the file checksum and every per-tensor checksum and
+raises on any mismatch. Corrupt files never load silently.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import struct
+
+import numpy as np
+
+from .util import utc_now_iso
+
+MAGIC = b"TRQ1"
+VERSION = 1
+
+_DTYPE_CODES = {"fp32": 0, "fp16": 1, "bf16": 2, "int8": 3, "int4": 4}
+_DTYPE_NAMES = {v: k for k, v in _DTYPE_CODES.items()}
+_NP_DTYPES = {"fp32": np.float32, "fp16": np.float16, "bf16": np.uint16,
+              "int8": np.int8, "int4": np.uint8}
+_QUANT_CODES = {"none": 0, "int8-asym": 1, "int4-group32": 2,
+                "fp16-cast": 3, "bf16-cast": 4}
+_QUANT_NAMES = {v: k for k, v in _QUANT_CODES.items()}
+
+
+def _b64(arr) -> str:
+    return base64.b64encode(np.asarray(arr, dtype=np.float64).tobytes()).decode()
+
+
+def _unb64(s: str) -> np.ndarray:
+    return np.frombuffer(base64.b64decode(s.encode()), dtype=np.float64)
+
+
+def _meta_to_json(meta: dict) -> dict:
+    m = dict(meta)
+    for k, v in list(m.items()):
+        if isinstance(v, np.ndarray):
+            # codebooks, scales, zero-points, or any ndarray metadata
+            m[k] = {"__b64_f64__": _b64(np.asarray(v, dtype=np.float64)),
+                    "__shape__": list(v.shape), "__key__": k}
+    return m
+
+
+def _meta_from_json(m: dict) -> dict:
+    m = dict(m)
+    for k, v in list(m.items()):
+        if isinstance(v, dict) and "__b64_f64__" in v:
+            arr = _unb64(v["__b64_f64__"])
+            if "__shape__" in v:
+                arr = arr.reshape(v["__shape__"])
+            m[k] = arr
+    return m
+
+
+class TrqError(ValueError):
+    pass
+
+
+def write_trq(path: str, *, arch: dict, tensors: dict, provenance: dict,
+              roll_meta: dict = None) -> dict:
+    """tensors: {name: (payload_array, fmt_name, quant_meta_dict)}.
+    Returns {"path":..., "bytes":..., "sha256":...}."""
+    buf = bytearray()
+    buf += MAGIC
+    header = {
+        "version": VERSION,
+        "arch": arch,
+        "n_tensors": len(tensors),
+        "provenance": provenance,
+        "roll_meta": roll_meta or {},
+        "created": utc_now_iso(),
+    }
+    hbytes = json.dumps(header).encode()
+    buf += struct.pack("<I", len(hbytes)) + hbytes
+
+    for name, (payload, fmt, qmeta) in tensors.items():
+        payload = np.ascontiguousarray(payload)
+        nbytes = payload.tobytes()
+        name_b = name.encode()
+        buf += struct.pack("<H", len(name_b)) + name_b
+        buf += struct.pack("<B", payload.ndim)
+        buf += struct.pack(f"<{payload.ndim}Q", *payload.shape)
+        buf += struct.pack("<B", _DTYPE_CODES[fmt])
+        quant_name = {"fp32": "none", "fp16": "fp16-cast", "bf16": "bf16-cast",
+                      "int8": "int8-asym", "int4": "int4-group32"}[fmt]
+        buf += struct.pack("<B", _QUANT_CODES[quant_name])
+        meta = _meta_to_json({"fmt": fmt, **qmeta,
+                              "roll": (roll_meta or {}).get(name, {})})
+        mbytes = json.dumps(meta).encode()
+        buf += struct.pack("<I", len(mbytes)) + mbytes
+        buf += struct.pack("<Q", len(nbytes)) + nbytes
+        buf += hashlib.sha256(nbytes).digest()
+
+    digest = hashlib.sha256(bytes(buf)).digest()
+    buf += digest
+    with open(path, "wb") as f:
+        f.write(bytes(buf))
+    return {"path": path, "bytes": len(buf), "sha256": digest.hex()}
+
+
+def read_trq(path: str):
+    """Returns (header, tensors) with all checksums verified.
+    tensors: {name: (payload_array, meta_dict)}. Raises TrqError on corruption."""
+    with open(path, "rb") as f:
+        blob = f.read()
+    if len(blob) < 4 + 32 or blob[:4] != MAGIC:
+        raise TrqError("not a .trq file (bad magic)")
+    file_sum, body = blob[-32:], blob[:-32]
+    if hashlib.sha256(body).digest() != file_sum:
+        raise TrqError("file checksum mismatch — refusing to load")
+    off = 4
+    hlen = struct.unpack_from("<I", body, off)[0]
+    off += 4
+    header = json.loads(body[off:off + hlen])
+    off += hlen
+    tensors = {}
+    for _ in range(header["n_tensors"]):
+        nlen = struct.unpack_from("<H", body, off)[0]
+        off += 2
+        name = body[off:off + nlen].decode()
+        off += nlen
+        ndim = struct.unpack_from("<B", body, off)[0]
+        off += 1
+        shape = struct.unpack_from(f"<{ndim}Q", body, off)
+        off += 8 * ndim
+        dtype_code = struct.unpack_from("<B", body, off)[0]
+        off += 1
+        quant_code = struct.unpack_from("<B", body, off)[0]
+        off += 1
+        mlen = struct.unpack_from("<I", body, off)[0]
+        off += 4
+        meta = _meta_from_json(json.loads(body[off:off + mlen]))
+        off += mlen
+        dlen = struct.unpack_from("<Q", body, off)[0]
+        off += 8
+        data = body[off:off + dlen]
+        off += dlen
+        cksum = body[off:off + 32]
+        off += 32
+        if hashlib.sha256(data).digest() != cksum:
+            raise TrqError(f"tensor {name!r} checksum mismatch — refusing to load")
+        fmt = _DTYPE_NAMES[dtype_code]
+        arr = np.frombuffer(data, dtype=_NP_DTYPES[fmt])
+        if fmt == "int4":
+            arr = arr.reshape(-1)  # packed nibbles stay flat; dequantize reshapes
+        else:
+            arr = arr.reshape(shape)
+        tensors[name] = (arr, meta)
+    return header, tensors
+
+
+def total_params(tensors: dict) -> int:
+    """Total logical parameters across tensors (uses recorded shapes, so
+    packed INT4 counts its true parameters, not its packed bytes)."""
+    total = 0
+    for _name, (arr, meta) in tensors.items():
+        shape = meta.get("shape") or list(arr.shape)
+        total += int(np.prod(shape))
+    return total
+
+
+def param_budget_ok(tensors: dict, cap: float = 8_500_000_000) -> tuple:
+    """Verify the exported artifact obeys the hard parameter budget.
+    Returns (total_params, ok)."""
+    total = total_params(tensors)
+    return total, total <= cap

tensor_roll/util.py

@@ -0,0 +1,85 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Shared utilities: timing, memory accounting, formatting, audit logging."""
+
+from __future__ import annotations
+
+import json
+import os
+import resource
+import time
+from datetime import datetime, timezone
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def timed(fn, *args, **kwargs):
+    """Run fn and return (result, elapsed_seconds)."""
+    t0 = time.perf_counter()
+    out = fn(*args, **kwargs)
+    return out, time.perf_counter() - t0
+
+
+def rss_mb() -> float:
+    """Current process resident set size in MiB (Linux /proc)."""
+    try:
+        with open("/proc/self/status") as f:
+            for line in f:
+                if line.startswith("VmRSS:"):
+                    return float(line.split()[1]) / 1024.0
+    except OSError:
+        pass
+    return float(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss) / 1024.0
+
+
+def peak_rss_mb() -> float:
+    return float(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss) / 1024.0
+
+
+def fmt_params(n: int) -> str:
+    if n >= 1e9:
+        return f"{n / 1e9:.2f}B"
+    if n >= 1e6:
+        return f"{n / 1e6:.2f}M"
+    if n >= 1e3:
+        return f"{n / 1e3:.1f}K"
+    return str(n)
+
+
+def fmt_bytes(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1024.0 or unit == "TB":
+            return f"{n:.2f}{unit}"
+        n /= 1024.0
+    return f"{n:.2f}TB"
+
+
+def ensure_dir(path: str) -> str:
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def write_json(path: str, obj) -> None:
+    with open(path, "w") as f:
+        json.dump(obj, f, indent=2)
+
+
+def read_json(path: str):
+    with open(path) as f:
+        return json.load(f)
+
+
+class AuditLog:
+    """Append-only JSON-lines audit log."""
+
+    def __init__(self, path: str):
+        ensure_dir(os.path.dirname(os.path.abspath(path)))
+        self.path = path
+
+    def record(self, **fields) -> None:
+        fields.setdefault("ts", utc_now_iso())
+        with open(self.path, "a") as f:
+            f.write(json.dumps(fields) + "\n")

tests/test_backend.py

@@ -0,0 +1,243 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Tests for the backend-honesty chunk: doctor, IR, conformance, and the
+integration-state audit. Every test asserts measured behavior — no
+fabricated numbers. Fast: the whole file runs in seconds."""
+import hashlib
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+import numpy as np
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from tensor_roll import doctor as DR
+from tensor_roll import ir as IR
+from tensor_roll import conformance as CF
+from tensor_roll import boundary as BD
+
+
+class TestDoctor(unittest.TestCase):
+    def test_report_structure(self):
+        rep = DR.doctor_report()
+        for key in ("capabilities", "sources", "execution", "gpu",
+                    "integration"):
+            self.assertIn(key, rep)
+        cap = rep["capabilities"]
+        self.assertEqual(cap["CPU"]["state"], "AVAILABLE")
+        self.assertEqual(cap["NumPy"]["state"], "AVAILABLE")
+        # This machine: no GPU, no CUDA-Q toolchain, no Q# toolchain.
+        self.assertEqual(cap["CUDA"]["state"], "UNAVAILABLE")
+        self.assertEqual(cap["CUDA-Q"]["state"], "UNAVAILABLE")
+        self.assertEqual(cap["Q#"]["state"], "UNAVAILABLE")
+        self.assertEqual(rep["gpu"], "NONE")
+        for label in ("CUDA", "CUDA-Q", "Q#"):
+            self.assertTrue(cap[label].get("reason"),
+                            f"{label} must carry a reason, not just a state")
+
+    def test_cpu_execution_passes(self):
+        rep = DR.doctor_report()
+        cpu = rep["execution"]["CPU"]
+        self.assertEqual(cpu["state"], "EXECUTED")
+        self.assertEqual(cpu["result"], "PASS")
+        self.assertGreater(cpu["matmul_ms"], 0)
+
+    def test_others_not_executed(self):
+        rep = DR.doctor_report()
+        for label in ("CUDA", "CUDA-Q", "Q#"):
+            rec = rep["execution"][label]
+            self.assertEqual(rec["state"], "NOT EXECUTED")
+            self.assertTrue(rec["reason"])
+            self.assertIn(rec["source"], ("VERIFIED", "PRESENT"))
+
+    def test_sources_verified(self):
+        for label, rec in DR.verify_sources().items():
+            self.assertIn(rec["state"], ("VERIFIED", "PRESENT"), label)
+        # On this box all three sources carry the AGPL header and the
+        # expected identifiers, so VERIFIED is the honest state.
+        states = {l: r["state"] for l, r in DR.verify_sources().items()}
+        self.assertEqual(states, {"CUDA source": "VERIFIED",
+                                 "CUDA-Q source": "VERIFIED",
+                                 "Q# source": "VERIFIED"})
+
+    def test_render_shape(self):
+        text = DR.render_doctor(DR.doctor_report())
+        expected = "\n".join([
+            "Tensor Roll Backend Report",
+            "CPU            AVAILABLE",
+            "NumPy          AVAILABLE",
+            "CUDA           UNAVAILABLE",
+            "CUDA-Q         UNAVAILABLE",
+            "Q#             UNAVAILABLE",
+            "GPU            NONE",
+            "CUDA source    VERIFIED",
+            "CUDA-Q source  VERIFIED",
+            "Q# source      VERIFIED",
+            "Execution:",
+            "CPU            PASS",
+            "CUDA           NOT EXECUTED",
+            "CUDA-Q         NOT EXECUTED",
+            "Q#             NOT EXECUTED",
+            "",
+        ])
+        self.assertEqual(text, expected)
+
+
+class TestIR(unittest.TestCase):
+    def _plan(self):
+        return {
+            "w1": {"decision": "QUANTIZE",
+                   "cost_params": {"bits": 8}},
+            "w2": {"decision": "QUANTUM-ENCODED",
+                   "cost_params": {"n_qubits": 2,
+                                   "angles": [0.3, 0.6],
+                                   "shots": 64, "seed": 1}},
+            "w3": {"decision": "PRESERVE", "cost_params": {}},
+        }
+
+    def test_build_ir_structure(self):
+        ops = IR.build_ir(self._plan())
+        by_out = [o.op for o in ops]
+        # w1: LOAD ROLL QUANTIZE EMIT
+        self.assertEqual(by_out[:4], ["LOAD", "ROLL", "QUANTIZE", "EMIT"])
+        # w2: LOAD ROLL ROTATE ENTANGLE MEASURE RECONSTRUCT EMIT
+        self.assertEqual(by_out[4:11],
+                         ["LOAD", "ROLL", "ROTATE", "ENTANGLE", "MEASURE",
+                          "RECONSTRUCT", "EMIT"])
+        # w3: LOAD ROLL EMIT (pass-through, decision in meta)
+        self.assertEqual(by_out[11:], ["LOAD", "ROLL", "EMIT"])
+        self.assertEqual(ops[-1].meta["decision"], "PRESERVE")
+
+    def test_json_roundtrip(self):
+        ops = IR.build_ir(self._plan())
+        back = IR.from_json(IR.to_json(ops))
+        self.assertEqual([o.op for o in back], [o.op for o in ops])
+        self.assertEqual([o.params for o in back], [o.params for o in ops])
+        self.assertEqual([o.meta for o in back], [o.meta for o in ops])
+        self.assertEqual([o.inputs for o in back], [o.inputs for o in ops])
+        self.assertEqual([o.outputs for o in back], [o.outputs for o in ops])
+
+    def test_lower_cpu_gemm_numeric(self):
+        A = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+        B = [[7.0, 8.0], [9.0, 10.0], [11.0, 12.0]]
+        ops = [
+            IR.IROp("LOAD", [], ["A"], {"data": A, "shape": [2, 3]}, {}),
+            IR.IROp("LOAD", [], ["B"], {"data": B, "shape": [3, 2]}, {}),
+            IR.IROp("GEMM", ["A", "B"], ["C"], {}, {}),
+            IR.IROp("EMIT", ["C"], ["out"], {}, {}),
+        ]
+        recs = IR.lower(ops, "cpu")
+        self.assertTrue(all(r["state"] == "EXECUTED" for r in recs))
+        gemm = recs[2]
+        self.assertEqual(gemm["backend"], "cpu-numpy")
+        want = np.array(A) @ np.array(B)
+        self.assertEqual(gemm["detail"]["shape"], [2, 2])
+        self.assertAlmostEqual(gemm["detail"]["checksum"], float(want.sum()))
+        emit = recs[3]
+        self.assertEqual(emit["detail"]["sha256"],
+                         hashlib.sha256(want.tobytes()).hexdigest())
+
+    def test_lower_cpu_quantum_family(self):
+        ops = [
+            IR.IROp("LOAD", [], ["x"],
+                    {"data": [0.5, -0.25, 0.75, 0.1], "shape": [4]}, {}),
+            IR.IROp("ROTATE", ["x"], ["xr"],
+                    {"angles": [0.2, 0.4]}, {}),
+            IR.IROp("ENTANGLE", ["xr"], ["xe"], {}, {}),
+            IR.IROp("MEASURE", ["xe"], ["xm"],
+                    {"shots": 128, "seed": 3}, {}),
+            IR.IROp("RECONSTRUCT", ["xm"], ["xhat"], {}, {}),
+            IR.IROp("EMIT", ["xhat"], ["out"], {}, {}),
+        ]
+        recs = IR.lower(ops, "cpu")
+        self.assertTrue(all(r["state"] == "EXECUTED" for r in recs),
+                        [r for r in recs if r["state"] != "EXECUTED"])
+        self.assertEqual(recs[1]["backend"], "qsim-classical")
+        self.assertEqual(recs[3]["detail"]["shots"], 128)
+
+    def test_lower_cudaq_not_executed(self):
+        ok, _ = DR.cudaq_toolchain()
+        if ok:
+            self.skipTest("real CUDA-Q toolchain present; "
+                          "NOT-EXECUTED path does not apply")
+        ops = IR.build_ir(self._plan())
+        recs = IR.lower(ops, "cuda-q")
+        self.assertTrue(all(r["state"] == "NOT EXECUTED" for r in recs))
+        self.assertTrue(all(r["reason"] for r in recs))
+        self.assertTrue(all(r["source"] in ("VERIFIED", "PRESENT")
+                            for r in recs))
+        rot = next(r for r in recs if r["op"] == "ROTATE")
+        self.assertEqual(rot["gate_trace_schema"], BD.TRACE_SCHEMA)
+        self.assertTrue(rot["gate_trace"])
+        self.assertIn("IR-specification only", rot["note"])
+
+    def test_lower_unknown_backend(self):
+        with self.assertRaises(ValueError):
+            IR.lower([], "tpu")
+
+
+class TestConformance(unittest.TestCase):
+    def test_numpy_executed_and_matches(self):
+        with tempfile.TemporaryDirectory() as d:
+            doc = CF.run_conformance(d)
+            path = os.path.join(d, "conformance.json")
+            self.assertTrue(os.path.isfile(path))
+            with open(path) as f:
+                back = json.load(f)["backends"]
+            rec = back["numpy"]
+            self.assertEqual(rec["state"], "EXECUTED")
+            self.assertTrue(rec["match"])
+            self.assertTrue(all(rec["checks"].values()))
+            self.assertEqual(set(back), {"numpy", "cuda", "cuda-q", "qsharp"})
+
+    def test_others_not_executed_with_reasons(self):
+        with tempfile.TemporaryDirectory() as d:
+            doc = CF.run_conformance(d)
+            back = doc["backends"]
+            for name in ("cuda", "cuda-q", "qsharp"):
+                rec = back[name]
+                self.assertEqual(rec["state"], "NOT EXECUTED", name)
+                self.assertTrue(rec["reason"], name)
+                self.assertIsNone(rec["match"], name)
+                for key in ("state", "reason", "outputs", "expected",
+                            "match", "measured"):
+                    self.assertIn(key, rec, f"{name}.{key}")
+
+    def test_vectors_deterministic(self):
+        self.assertEqual(CF.test_vectors(), CF.test_vectors())
+        exp = CF.expected_outputs()
+        # expected C hard-coded matches a fresh NumPy computation
+        v = CF.test_vectors()
+        C = (np.array(v["matmul"]["A"]) @ np.array(v["matmul"]["B"])).tolist()
+        self.assertEqual(C, exp["matmul"]["C"])
+
+
+class TestIntegrationState(unittest.TestCase):
+    def test_audited_value(self):
+        res = DR.integration_state()
+        self.assertEqual(res["state"], "file-mediated")
+        self.assertTrue(res["evidence"])
+        self.assertTrue(any("tensor_roll/boundary.py:" in e
+                            for e in res["evidence"]))
+        # the audit must record that vendor execution here is source-only
+        self.assertTrue(any("source-only" in e for e in res["evidence"]))
+
+    def test_boundary_trace_still_roundtrips(self):
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "t.json")
+            BD.write_trace(p, "tensor_roll_encode", 2, 64,
+                           {"00": 40, "11": 24}, producer="test")
+            back = BD.read_trace(p)
+            self.assertEqual(back["counts"], {"00": 40, "11": 24})
+            with open(p, "a") as f:
+                f.write("corrupt")
+            with self.assertRaises(ValueError):
+                BD.read_trace(p)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_failure_resolution.py

@@ -0,0 +1,423 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Failure-resolution tests (F1-F6): out-of-core streaming, global planner,
+fidelity instrumentation, INT4 characterization, CLI wiring.
+
+Every test measures; none fabricates. The 31 pre-existing tests in
+test_tensor_roll.py are untouched and must stay green alongside these.
+"""
+
+import io
+import json
+import os
+import struct
+import tempfile
+import unittest
+
+import numpy as np
+
+from tensor_roll import fidelity as F
+from tensor_roll import model as M
+from tensor_roll import ooc
+from tensor_roll import planner
+from tensor_roll import quant as QT
+
+
+def _tiny_cfg():
+    return M.Config(vocab=16, d=16, heads=2, layers=1, dff=32, seq=8)
+
+
+def _write_safetensors(path, tensors):
+    """Minimal honest safetensors writer for tests (F32/F16 only)."""
+    header = {}
+    blobs = []
+    off = 0
+    for name, arr in tensors.items():
+        arr = np.ascontiguousarray(arr)
+        dt = {np.dtype("float32"): "F32",
+              np.dtype("float16"): "F16"}[arr.dtype]
+        blob = arr.tobytes()
+        header[name] = {"dtype": dt, "shape": list(arr.shape),
+                        "data_offsets": [off, off + len(blob)]}
+        blobs.append(blob)
+        off += len(blob)
+    raw = json.dumps(header).encode()
+    with open(path, "wb") as f:
+        f.write(struct.pack("<Q", len(raw)))
+        f.write(raw)
+        for b in blobs:
+            f.write(b)
+
+
+class TestShardIO(unittest.TestCase):
+    def test_roundtrip_and_mmap(self):
+        tmp = tempfile.mkdtemp()
+        rng = np.random.default_rng(0)
+        W = rng.standard_normal((32, 24)).astype(np.float32)
+        sw = ooc.ShardWriter(os.path.join(tmp, "sh"), shard_size_bytes=4096)
+        sw.add("W", W)
+        sw.finalize("t")
+        src = ooc.TensorSource(os.path.join(tmp, "sh"))
+        self.assertEqual(src.total_params, 32 * 24)
+        rdr = src.reader()
+        mt = rdr.read("W")
+        self.assertIsInstance(mt.view, np.memmap)  # mmap, not RAM copy
+        np.testing.assert_array_equal(np.asarray(mt.view), W)
+        rdr.close()
+
+    def test_windows_cover_exactly_within_budget(self):
+        tmp = tempfile.mkdtemp()
+        rng = np.random.default_rng(1)
+        W = rng.standard_normal((100, 7)).astype(np.float32)
+        sw = ooc.ShardWriter(os.path.join(tmp, "sh"))
+        sw.add("W", W)
+        sw.finalize("t")
+        src = ooc.TensorSource(os.path.join(tmp, "sh"))
+        mt = src.reader().read("W")
+        wins = list(mt.windows(1024))
+        self.assertTrue(all(w.nbytes <= 1024 for w in wins))
+        rec = ooc.reassemble(wins, W.shape, dtype=np.float32)
+        np.testing.assert_array_equal(rec, W)
+        # no-overlap check is inside reassemble (asserts); also count cells
+        total = sum(w.data.size for w in wins)
+        self.assertEqual(total, W.size)
+
+
+class TestWorkspace(unittest.TestCase):
+    def test_ceiling_enforced(self):
+        ws = ooc.RollWorkspace(1000)
+        ws.alloc("a", 600)
+        with self.assertRaises(ooc.MemoryBudgetExceeded):
+            ws.alloc("b", 500)
+        ws.free("a")
+        ws.alloc("b", 500)
+        rep = ws.report()
+        self.assertTrue(rep["within_budget"])
+        self.assertEqual(rep["peak_bytes"], 600)
+
+
+class TestVirtualManifest(unittest.TestCase):
+    def test_30b_scale_without_weights(self):
+        man = ooc.glimmer30b_manifest()
+        self.assertGreaterEqual(man.total_params, 29e9)
+        self.assertLess(man.total_params, 32e9)
+        src = ooc.TensorSource.__new__(ooc.TensorSource)  # not needed
+        with self.assertRaises(RuntimeError):
+            man.reader()
+
+    def test_virtual_manifest_reader_raises(self):
+        man = ooc.glimmer30b_manifest()
+        with self.assertRaises(RuntimeError):
+            man.reader()
+
+
+class TestStudentWriter(unittest.TestCase):
+    def test_verify_and_corruption_detected(self):
+        tmp = tempfile.mkdtemp()
+        w = ooc.StudentWriter(os.path.join(tmp, "st"))
+        a = np.arange(12, dtype=np.float32).reshape(3, 4)
+        w.emit("t", a)
+        w.finalize()
+        self.assertTrue(ooc.StudentWriter.verify(os.path.join(tmp, "st"))["ok"])
+        # corrupt one data byte on disk (last byte is always data)
+        p = os.path.join(tmp, "st", "student-00000.npy")
+        with open(p, "r+b") as f:
+            f.seek(-1, os.SEEK_END)
+            f.write(b"\xff")
+        with self.assertRaises(AssertionError):
+            ooc.StudentWriter.verify(os.path.join(tmp, "st"))
+
+
+class TestCheckpoint(unittest.TestCase):
+    def test_roundtrip_and_corruption_rejected(self):
+        tmp = tempfile.mkdtemp()
+        cp = ooc.Checkpoint(os.path.join(tmp, "c.json"))
+        cp.save({"done": ["a"], "n": 3})
+        self.assertEqual(cp.load()["n"], 3)
+        with open(cp.path) as f:
+            doc = json.load(f)
+        doc["state"]["n"] = 999
+        with open(cp.path, "w") as f:
+            json.dump(doc, f)
+        with self.assertRaises(ValueError):
+            cp.load()
+
+
+def _tiny_source(tmp, tensors):
+    sw = ooc.ShardWriter(os.path.join(tmp, "sh"))
+    for k, v in tensors.items():
+        sw.add(k, v)
+    sw.finalize("t")
+    return ooc.TensorSource(os.path.join(tmp, "sh"))
+
+
+class TestDriverResume(unittest.TestCase):
+    def test_crash_then_resume_matches_clean_run(self):
+        rng = np.random.default_rng(2)
+        tensors = {"a": rng.standard_normal((16, 12)).astype(np.float32),
+                   "b": rng.standard_normal((8, 8)).astype(np.float32)}
+        ident = lambda n, d, wt, ws, meta: np.asarray(d)  # noqa
+        plan = {"tensors": {k: {"target_params": v.size}
+                            for k, v in tensors.items()},
+                "total_target_params": sum(v.size for v in tensors.values()),
+                "cap": 8.5e9}
+        # clean run
+        tmp1 = tempfile.mkdtemp()
+        drv1 = ooc.OutOfCoreDriver(_tiny_source(tmp1, tensors),
+                                   os.path.join(tmp1, "w"),
+                                   memory_budget="4KB")
+        r1 = drv1.execute(plan, ident)
+        # crashed run then resume
+        tmp2 = tempfile.mkdtemp()
+        drv2 = ooc.OutOfCoreDriver(_tiny_source(tmp2, tensors),
+                                   os.path.join(tmp2, "w"),
+                                   memory_budget="4KB")
+        with self.assertRaises(RuntimeError):
+            drv2.execute(plan, ident, fault_after=0)
+        drv3 = ooc.OutOfCoreDriver(_tiny_source(tmp2, tensors),
+                                   os.path.join(tmp2, "w"),
+                                   memory_budget="4KB")
+        r2 = drv3.execute(plan, ident, resume=True)
+        self.assertEqual(r1["index_total_params"], r2["index_total_params"])
+        self.assertEqual(r2["processed_tensors"], 1)  # only the remainder
+        idx = ooc.StudentWriter.verify(os.path.join(tmp2, "w",
+                                                    "student_shards"))
+        self.assertTrue(idx["ok"])
+
+
+class TestStreamCompress(unittest.TestCase):
+    def test_safetensors_mmap_stream(self):
+        tmp = tempfile.mkdtemp()
+        tdir = os.path.join(tmp, "teacher")
+        os.makedirs(tdir)
+        rng = np.random.default_rng(3)
+        W = rng.standard_normal((64, 48)).astype(np.float32)
+        b = rng.standard_normal((48,)).astype(np.float32)
+        _write_safetensors(os.path.join(tdir, "model.safetensors"),
+                           {"W": W, "b": b})
+        src = ooc.prepare_teacher_source(tdir, os.path.join(tmp, "cache"))
+        self.assertEqual(src.total_params, 64 * 48 + 48)
+        rows = planner.scan_rows(src.specs)
+        plan = planner.plan(rows, target=2000)
+        res = ooc.stream_compress(src, plan, "64KB",
+                                  os.path.join(tmp, "out"))
+        self.assertLessEqual(res["index_total_params"], plan["cap"])
+        self.assertTrue(res["budget_ok"])
+        for st in res["tensor_stats"].values():
+            self.assertGreater(st["retained_energy"], 0.0)
+            self.assertLessEqual(st["retained_energy"], 1.0 + 1e-9)
+        self.assertLessEqual(res["workspace"]["peak_bytes"],
+                             res["workspace"]["ceiling_bytes"])
+        # student factors reconstruct approximately
+        idx_path = os.path.join(tmp, "out", "student_shards",
+                                "shard_index.json")
+        with open(idx_path) as f:
+            index = json.load(f)
+        parts = {}
+        for e in index["tensors"]:
+            if e["name"].startswith("model.safetensors:W@"):
+                arr = np.load(os.path.join(tmp, "out", "student_shards",
+                                           e["file"]))
+                parts[e["name"].rsplit(".", 1)[-1]] = arr
+        rec = parts["A"] @ parts["B"]
+        rel = np.linalg.norm(W - rec) / np.linalg.norm(W)
+        self.assertLess(rel, 0.9)  # rank-17 approx of random 64x48
+
+
+class TestPlanner(unittest.TestCase):
+    def test_ratio_invariance(self):
+        for n in (100_000, 1_000_000, 10_000_000):
+            r = planner.check_ratio_invariance(n, tol=0.02, seed=7)
+            self.assertTrue(r["within_tol"],
+                            f"scale {n}: {r['achieved_ratio']}")
+
+    def test_30b_plan_within_cap(self):
+        import time
+        man = ooc.glimmer30b_manifest()
+        rows = planner.scan_rows(man.specs)
+        t0 = time.perf_counter()
+        p = planner.plan(rows)
+        dt = time.perf_counter() - t0
+        self.assertTrue(p["within_cap"])
+        self.assertLessEqual(p["total_target_params"], planner.CAP_PARAMS)
+        self.assertGreaterEqual(p["total_target_params"], 7e9)
+        self.assertLess(dt, 60.0)
+
+    def test_sensitivity_nonuniform(self):
+        rows = [{"tensor": "sens", "shape": [64, 64], "dtype": "float32",
+                 "params": 4096, "bytes": 16384, "shard": "x", "is_matrix": True},
+                {"tensor": "insens", "shape": [64, 64], "dtype": "float32",
+                 "params": 4096, "bytes": 16384, "shard": "x", "is_matrix": True}]
+        p = planner.plan(rows, ratio=0.5,
+                         sensitivity={"sens": 1.0, "insens": 0.0})
+        rs = p["tensors"]["sens"]["ratio"]
+        ri = p["tensors"]["insens"]["ratio"]
+        self.assertGreater(rs, ri)
+
+    def test_calibrate_sensitivity_measured(self):
+        rng = np.random.default_rng(4)
+        rows = [{"tensor": "m", "shape": [32, 32], "dtype": "float32",
+                 "params": 1024, "bytes": 4096, "shard": "x", "is_matrix": True}]
+        W = rng.standard_normal((32, 32))
+        s = planner.calibrate_sensitivity(rows,
+                                          sample_fn=lambda n: W[:8, :8])
+        self.assertIn("m", s)
+        self.assertGreaterEqual(s["m"], 0.0)
+        self.assertLessEqual(s["m"], 1.0)
+
+
+class TestFidelityMetrics(unittest.TestCase):
+    def test_kl_js_zero_for_identical(self):
+        x = np.array([1.0, 2.0, 3.0])
+        self.assertAlmostEqual(F.kl_div(x, x), 0.0, places=9)
+        self.assertAlmostEqual(F.js_div(x, x), 0.0, places=9)
+
+    def test_kl_positive_js_bounded(self):
+        x = np.array([3.0, 0.0, 0.0])
+        y = np.array([0.0, 3.0, 0.0])
+        self.assertGreater(F.kl_div(x, y), 0.0)
+        j = F.js_div(x, y)
+        self.assertGreater(j, 0.0)
+        self.assertLessEqual(j, np.log(2) + 1e-9)
+
+    def test_top_k(self):
+        tk = F.top_k(np.array([0.0, 5.0, 1.0]), 2)
+        self.assertEqual(tk[0][0], 1)
+        self.assertEqual(len(tk), 2)
+
+
+class TestDivergenceTrace(unittest.TestCase):
+    def test_trace_structure_and_first_divergence(self):
+        rng = np.random.default_rng(5)
+        cfg = _tiny_cfg()
+        tp = M.init_params(rng, cfg)
+        sp = M.init_params(rng, cfg)
+        tr = F.divergence_trace(tp, cfg, sp, cfg, [1, 2, 3], max_tokens=8)
+        self.assertEqual(tr["n_tokens"], 8)
+        self.assertEqual(len(tr["positions"]), 8)
+        pos0 = tr["positions"][0]
+        for k in ("teacher_token", "student_token", "teacher_topk",
+                  "student_topk", "teacher_logits", "student_logits",
+                  "kl_div", "js_div", "cosine_sim", "teacher_entropy",
+                  "student_entropy", "hidden_div", "attn_div"):
+            self.assertIn(k, pos0)
+        a, b = tr["agreement_count"], tr["n_tokens"]
+        self.assertEqual(tr["token_agreement"], f"{a}/{b}")
+        first = F.first_divergence(tr)
+        self.assertIn("position", first)
+        lines = F.render_trace(tr, first)
+        self.assertEqual(len(lines), 9)  # 8 tokens + summary
+
+
+class _Leaf:
+    def __init__(self, name, options):
+        self.name = name
+        self.options = options
+
+
+class TestFidelitySelect(unittest.TestCase):
+    def test_budget_and_uniform_penalty(self):
+        leaves = [_Leaf("a", [
+            {"cost_params": 100, "retained_energy": 0.9,
+             "reconstruction_error": 0.01},
+            {"cost_params": 200, "retained_energy": 0.99,
+             "reconstruction_error": 0.001}]),
+            _Leaf("b", [
+                {"cost_params": 100, "retained_energy": 0.9,
+                 "reconstruction_error": 0.01},
+                {"cost_params": 200, "retained_energy": 0.95,
+                 "reconstruction_error": 0.05}])]
+        plan = F.fidelity_aware_select(leaves, 300,
+                                       {"a": 1.0, "b": 1.0}, lam=1.0)
+        self.assertLessEqual(plan["_total_cost_params"], 300)
+        # penalty is uniform: same error+lambda -> same penalty class
+        pa = plan["a"]["fidelity_penalty"]
+        self.assertAlmostEqual(
+            pa, F.fidelity_penalty(1.0, plan["a"]["reconstruction_error"]))
+        u = F.utility_breakdown(1000, {"reconstruction": 10.0,
+                                       "logit": 5.0, "hidden": 2.0,
+                                       "task": 1.0})
+        self.assertAlmostEqual(u["utility"], 982.0)
+
+
+class TestInt4(unittest.TestCase):
+    def test_schemes_roundtrip_and_search(self):
+        rng = np.random.default_rng(6)
+        W = (rng.standard_normal((48, 64)) * 3).astype(np.float32)
+        rep = QT.int4_scheme_report(W)
+        for k in ("per-tensor", "per-channel", "group-wise", "int8"):
+            self.assertIn("mse", rep[k])
+        # search picks the measured argmin
+        mses = {r["group"]: r["mse"] for r in rep["group-wise"]["all"]}
+        best = min(mses, key=mses.get)
+        self.assertEqual(rep["group-wise"]["best_group"], best)
+        # per-tensor round trip shape
+        q, m = QT.quantize_int4_per_tensor(W)
+        back = QT.dequantize_int4_per_tensor(q, m)
+        self.assertEqual(back.shape, W.shape)
+        # error map instrumentation
+        em = QT.quant_error_map(W, back)
+        for k in ("min", "max", "mean", "variance", "outlier_frac", "mse",
+                  "cosine_sim", "rel_err", "per_channel_mse",
+                  "per_group_mse"):
+            self.assertIn(k, em)
+        self.assertEqual(len(em["per_channel_mse"]), 48)
+
+    def test_outlier_detection(self):
+        rng = np.random.default_rng(9)
+        clean = rng.standard_normal((8, 64)).astype(np.float32)
+        dirty = clean.copy()
+        dirty[0, 0] = 100.0  # planted outlier stretches the int4 scale
+        qc, mc = QT.quantize_int4(clean)
+        qd, md = QT.quantize_int4(dirty)
+        em_c = QT.quant_error_map(clean, QT.dequantize_int4(qc, mc))
+        em_d = QT.quant_error_map(dirty, QT.dequantize_int4(qd, md))
+        # the outlier inflates measured error by an order of magnitude
+        self.assertGreater(em_d["mse"], 10 * em_c["mse"])
+        self.assertGreater(em_d["max"], 1.0)
+        self.assertGreaterEqual(em_d["outlier_frac"], 0.0)
+
+    def test_mixed_precision_plan_within_budget(self):
+        rng = np.random.default_rng(7)
+        params = {"W1": rng.standard_normal((32, 32)).astype(np.float32),
+                  "W2": rng.standard_normal((16, 16)).astype(np.float32)}
+        mp = QT.mixed_precision_plan(params, 10_000_000)
+        self.assertTrue(mp["within_budget"])
+        self.assertEqual(set(mp["plan"]), {"W1", "W2"})
+        self.assertTrue(all(v in ("int4", "int8")
+                            for v in mp["plan"].values()))
+
+    def test_recovery_train_measured(self):
+        rng = np.random.default_rng(8)
+        cfg = _tiny_cfg()
+        tp = M.init_params(rng, cfg)
+        sp = {k: v.astype(np.float32) for k, v in
+              M.init_params(rng, cfg).items()}
+        rep = QT.recovery_train(sp, cfg, tp, cfg, steps=2, batch=8,
+                                seed=0)
+        for k in ("ppl_before", "ppl_after_train", "ppl_after_requant",
+                  "improved"):
+            self.assertIn(k, rep)
+        self.assertIsInstance(rep["improved"], bool)
+        self.assertTrue(np.isfinite(rep["ppl_after_requant"]))
+
+
+class TestCLIWiring(unittest.TestCase):
+    def test_doctor_and_compress_options(self):
+        from tensor_roll import cli
+        p = cli.build_parser()
+        a = p.parse_args(["doctor"])
+        self.assertEqual(a.cmd, "doctor")
+        a = p.parse_args(["compress", "--out-of-core", "--resume",
+                          "--teacher", "/tmp", "--target-params", "1000",
+                          "--memory-budget", "64MB"])
+        self.assertTrue(a.out_of_core)
+        self.assertTrue(a.resume)
+        self.assertEqual(a.teacher, "/tmp")
+        self.assertEqual(a.target_params, 1000)
+        self.assertEqual(a.memory_budget, "64MB")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tensor_roll.py

@@ -0,0 +1,393 @@
+# Tensor Roll — Recursive CUDA-Q Model Quantizer
+# Copyright (C) 2026 SnapKitty Collective
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Test suite for tensor-roll. Every test asserts measured behavior —
+no fabricated numbers, no stubbed calls. Run: python3 -m unittest discover -s tests"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+import numpy as np
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from tensor_roll import TensorRoll
+from tensor_roll import core as C
+from tensor_roll import qsim as Q
+from tensor_roll import model as M
+from tensor_roll import distill as D
+from tensor_roll import quant as QT
+from tensor_roll import trq
+from tensor_roll import boundary as BD
+from tensor_roll import sandbox as SB
+
+
+class TestTensorRollCore(unittest.TestCase):
+    def test_metrics_known_matrix(self):
+        W = np.eye(4, dtype=np.float64) * 2.0
+        m = C.tensor_metrics(W)
+        self.assertEqual(m["params"], 16)
+        self.assertAlmostEqual(m["norm"], 4.0)
+        self.assertEqual(m["rank"], 4)
+        self.assertAlmostEqual(m["spectral"], 0.25)  # top sv^2 / total
+        self.assertGreaterEqual(m["entropy"], 0.0)
+
+    def test_all_decision_classes_evaluated(self):
+        rng = np.random.default_rng(0)
+        W = rng.standard_normal((16, 16))
+        opts = C.evaluate_options("t", W, quantum_policy="explore",
+                                  qsim_encode=Q.qsim_encode_for_roll, rank=4)
+        classes = {o["decision"] for o in opts}
+        for want in ("PRESERVE", "QUANTIZE", "FACTORIZE", "MERGED",
+                     "ROUTED", "RECONSTRUCTED", "PRUNED", "QUANTUM-ENCODED"):
+            # MERGED only applies to 1-D; the rest must appear for 2-D
+            if want != "MERGED":
+                self.assertIn(want, classes, f"missing {want}")
+        # every option's energy/error is a measured finite number
+        for o in opts:
+            self.assertTrue(np.isfinite(o["retained_energy"]))
+            self.assertTrue(np.isfinite(o["reconstruction_error"]))
+            self.assertGreaterEqual(o["cost_params"], 0)
+
+    def test_merged_for_1d(self):
+        W = np.random.default_rng(1).standard_normal(24)
+        opts = C.evaluate_options("b", W)
+        self.assertIn("MERGED", {o["decision"] for o in opts})
+
+    def test_hard_budget(self):
+        rng = np.random.default_rng(2)
+        W = rng.standard_normal((32, 16))
+        res = TensorRoll(W, 0, 2, 4, "explore",
+                         qsim_encode=Q.qsim_encode_for_roll,
+                         budget_params=128.0)
+        self.assertLessEqual(res["total_cost_params"], 128.0)
+        self.assertEqual(res["n_leaves"], 4)
+        self.assertTrue(res["decisions"])
+
+    def test_first_class_signature(self):
+        import inspect
+        sig = inspect.signature(TensorRoll)
+        params = list(sig.parameters)
+        self.assertEqual(params[:5], ["T", "axis", "depth", "rank",
+                                     "quantum_policy"])
+
+    def test_dispatch_matmul_honest_label(self):
+        A = np.random.default_rng(3).standard_normal((8, 8))
+        B = np.random.default_rng(4).standard_normal((8, 8))
+        Cc, rep = C.dispatch_matmul(A, B)
+        self.assertTrue(np.allclose(Cc, A @ B))
+        self.assertEqual(rep["backend"], "cpu-numpy")
+
+
+class TestQsim(unittest.TestCase):
+    def test_encode_normalized(self):
+        rng = np.random.default_rng(5)
+        block = rng.standard_normal((8, 8))
+        payload, rep = Q.tensor_roll_encode(block, encoding="amplitude")
+        self.assertAlmostEqual(float(np.linalg.norm(payload["sv"])), 1.0,
+                               places=12)
+        self.assertEqual(rep["backend"], "qsim-classical")
+        self.assertIn("statevector", rep["device"])
+
+    def test_measure_counts_sum_to_shots(self):
+        rng = np.random.default_rng(6)
+        block = rng.standard_normal((8, 8))
+        payload, _ = Q.tensor_roll_encode(block)
+        payload, rep = Q.tensor_roll_measure(payload, shots=512, seed=1)
+        self.assertEqual(sum(payload["counts"].values()), 512)
+        self.assertEqual(rep["measurement_stats"]["n_outcomes"],
+                         len(payload["counts"]))
+
+    def test_reconstruct_report(self):
+        rng = np.random.default_rng(7)
+        block = rng.standard_normal((8, 8))
+        payload, _ = Q.tensor_roll_encode(block)
+        payload, _ = Q.tensor_roll_measure(payload, shots=2048, seed=2)
+        rec, rep = Q.tensor_roll_reconstruct(payload)
+        self.assertEqual(rec.shape, (8, 8))
+        self.assertIn("reconstruction_error", rep)
+        self.assertTrue(np.isfinite(C.relative_error(block, rec)))
+
+    def test_recursive_summary(self):
+        rng = np.random.default_rng(8)
+        block = rng.standard_normal((8, 8))
+        What, summary = Q.tensor_roll_recursive(block, depth=2, shots=256,
+                                                seed=3)
+        self.assertEqual(summary["kernel"], "tensor_roll_recursive[summary]")
+        self.assertEqual(len(summary["measurement_stats"]["levels"]), 2)
+        self.assertIn("counts", summary)
+        self.assertIn("n_qubits", summary)
+
+    def test_angle_encoding_cap(self):
+        block = np.zeros((8, 8))
+        with self.assertRaises(ValueError):
+            Q.tensor_roll_encode(block, encoding="angle")
+
+
+class TestQuant(unittest.TestCase):
+    def setUp(self):
+        self.W = np.random.default_rng(9).standard_normal((16, 16)).astype(
+            np.float32)
+
+    def test_fp16_roundtrip(self):
+        q, meta = QT.quantize_tensor(self.W, "fp16")
+        Wd = QT.dequantize_tensor(q, meta)
+        self.assertLess(C.relative_error(self.W, Wd), 2e-2)
+
+    def test_bf16_roundtrip(self):
+        q, meta = QT.quantize_tensor(self.W, "bf16")
+        Wd = QT.dequantize_tensor(q, meta)
+        self.assertLess(C.relative_error(self.W, Wd), 2e-2)
+
+    def test_int8_roundtrip(self):
+        q, meta = QT.quantize_tensor(self.W, "int8")
+        Wd = QT.dequantize_tensor(q, meta)
+        self.assertLess(C.relative_error(self.W, Wd), 5e-2)
+
+    def test_int4_roundtrip(self):
+        q, meta = QT.quantize_tensor(self.W, "int4")
+        Wd = QT.dequantize_tensor(q, meta)
+        self.assertLess(C.relative_error(self.W, Wd), 0.35)
+        # packed nibbles must not be miscounted as parameters
+        self.assertEqual(int(np.prod(meta["shape"])), self.W.size)
+
+
+class TestTrq(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp()
+        self.W = np.random.default_rng(10).standard_normal((8, 8)).astype(
+            np.float32)
+
+    def tearDown(self):
+        shutil.rmtree(self.d, ignore_errors=True)
+
+    def _write(self, fmt):
+        q, qmeta = QT.quantize_tensor(self.W, fmt)
+        p = os.path.join(self.d, f"t_{fmt}.trq")
+        trq.write_trq(p, arch={"name": "test", "format": fmt},
+                      tensors={"w": (np.ascontiguousarray(q), fmt, qmeta)},
+                      provenance={"test": True},
+                      roll_meta={"w": {"decision": "QUANTIZE"}})
+        return p
+
+    def test_roundtrip_all_formats(self):
+        for fmt in ("fp32", "fp16", "bf16", "int8", "int4"):
+            p = self._write(fmt)
+            header, tensors = trq.read_trq(p)
+            arr, meta = tensors["w"]
+            Wd = QT.dequantize_tensor(arr, meta)
+            self.assertEqual(header["version"], trq.VERSION)
+            self.assertTrue(np.allclose(Wd, self.W, atol=0.3),
+                            f"roundtrip failed for {fmt}")
+
+    def test_corruption_rejected(self):
+        p = self._write("int8")
+        with open(p, "r+b") as f:
+            f.seek(200)
+            b = f.read(1)
+            f.seek(200)
+            f.write(bytes([b[0] ^ 0xFF]))
+        with self.assertRaises(ValueError):
+            trq.read_trq(p)
+
+    def test_codebook_roundtrip(self):
+        # codebook-quantized tensor: indices payload + codebook in meta
+        rng = np.random.default_rng(15)
+        W = rng.standard_normal((8, 8)).astype(np.float32)
+        # rebuild a codebook explicitly for the artifact
+        flat = W.ravel().astype(np.float64)
+        cents = np.quantile(flat, np.linspace(0, 1, 16))
+        assign = np.abs(flat[:, None] - cents[None, :]).argmin(axis=1)
+        idx = assign.astype(np.uint8).reshape(8, 8)
+        p = os.path.join(self.d, "t_codebook.trq")
+        trq.write_trq(p, arch={"name": "test"},
+                      tensors={"w": (np.ascontiguousarray(idx), "int8",
+                                     {"quant": "codebook-vq-k16",
+                                      "codebook": cents})},
+                      provenance={"test": True})
+        header, tensors = trq.read_trq(p)
+        arr, meta = tensors["w"]
+        self.assertIn("codebook", meta)
+        self.assertEqual(meta["codebook"].shape, (16,))
+        Wd = meta["codebook"][arr]
+        # the artifact genuinely carries a usable codebook
+        self.assertLess(C.relative_error(W, Wd), 0.5)
+
+    def test_header_contents(self):
+        p = self._write("fp16")
+        header, _ = trq.read_trq(p)
+        for key in ("arch", "n_tensors", "provenance", "roll_meta", "version"):
+            self.assertIn(key, header)
+        self.assertEqual(header["n_tensors"], 1)
+
+
+class TestModel(unittest.TestCase):
+    def test_numeric_gradient(self):
+        # finite-difference check of the from-scratch backward pass
+        cfg = M.Config(vocab=16, d=16, heads=2, layers=1, dff=32, seq=8)
+        rng = np.random.default_rng(11)
+        params = M.init_params(rng, cfg)
+        ids = M.gen_data(rng, 2, cfg)
+        logits, cache = M.forward(params, cfg, ids[:, :-1])
+        _, dlogits = M.ce_loss(logits, ids[:, 1:])
+        ana = M.backward(params, cfg, cache, dlogits)
+        eps = 1e-4
+        max_rel = 0.0
+        for k in ("emb", "L0.Wq"):
+            p = params[k]
+            idx = (0, 0) if p.ndim == 2 else (0,)
+            orig = float(p[idx])
+            p[idx] = orig + eps
+            lp, _ = M.ce_loss(M.forward(params, cfg, ids[:, :-1])[0],
+                              ids[:, 1:])
+            p[idx] = orig - eps
+            lm, _ = M.ce_loss(M.forward(params, cfg, ids[:, :-1])[0],
+                              ids[:, 1:])
+            p[idx] = orig
+            num = (lp - lm) / (2 * eps)
+            a = float(ana[k][idx])
+            max_rel = max(max_rel,
+                          abs(a - num) / (abs(a) + abs(num) + 1e-8))
+        self.assertLess(max_rel, 0.05)
+
+    def test_training_reduces_loss(self):
+        cfg = M.Config(vocab=16, d=16, heads=2, layers=1, dff=32, seq=8)
+        rng = np.random.default_rng(12)
+        params = M.init_params(rng, cfg)
+        opt = M.Adam(params)
+        l0 = M.eval_metrics(params, cfg, batches=2, batch=32)["loss"]
+        for _ in range(30):
+            b = M.gen_data(rng, 16, cfg)
+            logits, cache = M.forward(params, cfg, b[:, :-1])
+            _, dlogits = M.ce_loss(logits, b[:, 1:])
+            grads = M.backward(params, cfg, cache, dlogits)
+            opt.step(params, grads)
+        l1 = M.eval_metrics(params, cfg, batches=2, batch=32)["loss"]
+        self.assertLess(l1, l0)
+
+
+    def test_tensor_stats_measured(self):
+        cfg = M.Config(vocab=16, d=16, heads=2, layers=1, dff=32, seq=8)
+        rng = np.random.default_rng(16)
+        params = M.init_params(rng, cfg)
+        stats = M.measure_tensor_stats(params, cfg, batches=2, batch=16)
+        self.assertEqual(set(stats), set(params))
+        for k, s in stats.items():
+            self.assertTrue(np.isfinite(s["grad_norm"]))
+            self.assertTrue(np.isfinite(s["grad_rel"]))
+            if s["act_rms"] is not None:
+                self.assertTrue(np.isfinite(s["act_rms"]))
+                self.assertGreater(s["act_rms"], 0)
+
+
+class TestDistill(unittest.TestCase):
+    def test_all_losses_finite(self):
+        cfg_t = M.Config(vocab=16, d=16, heads=2, layers=2, dff=32, seq=8)
+        cfg_s = M.Config(vocab=16, d=16, heads=2, layers=1, dff=32, seq=8)
+        rng = np.random.default_rng(13)
+        tp = M.init_params(rng, cfg_t)
+        sp = M.init_params(rng, cfg_s)
+        ids = M.gen_data(rng, 8, cfg_t)
+        total, terms, grads = D.distill_step(sp, cfg_s, tp, cfg_t, ids,
+                                            lambdas=D.DEFAULT_LAMBDAS)
+        self.assertTrue(np.isfinite(total))
+        for k in ("task", "logits", "hidden", "attention", "embedding",
+                  "reconstruction", "roll"):
+            self.assertIn(k, terms)
+            self.assertTrue(np.isfinite(terms[k]), k)
+
+    def test_recursive_metrics(self):
+        cfg_t = M.Config(vocab=16, d=16, heads=2, layers=1, dff=32, seq=8)
+        rng = np.random.default_rng(14)
+        tp = M.init_params(rng, cfg_t)
+        sp = {k: v * 0.9 for k, v in tp.items()}
+        m = D.recursive_metrics(sp, tp)
+        self.assertIn("model", m)
+        for key in ("rel_err", "cosine_sim", "kl_div", "retained_energy"):
+            self.assertIn(key, m["model"])
+
+
+class TestBoundary(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.d, ignore_errors=True)
+
+    def test_trace_roundtrip(self):
+        p = os.path.join(self.d, "b.json")
+        counts = {"000": 300, "111": 212}
+        BD.write_trace(p, "tensor_roll_recursive", 3, 512, counts, depth=2)
+        back = BD.read_trace(p)
+        self.assertEqual(back["counts"], counts)
+        self.assertGreater(back["n_gates"], 0)
+        amps = BD.counts_to_amplitudes(back)
+        self.assertEqual(len(amps), 8)
+
+    def test_corruption_rejected(self):
+        p = os.path.join(self.d, "b.json")
+        BD.write_trace(p, "tensor_roll_measure", 2, 100, {"00": 100})
+        with open(p, "r") as f:
+            doc = json.load(f)
+        doc["trace"]["shots"] = 999
+        with open(p, "w") as f:
+            json.dump(doc, f)
+        with self.assertRaises(ValueError):
+            BD.read_trace(p)
+
+
+class TestSandbox(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp()
+        self.sup = SB.SandboxSupervisor(os.path.join(self.d, "sb"))
+
+    def tearDown(self):
+        shutil.rmtree(self.d, ignore_errors=True)
+
+    def test_allow_echo(self):
+        rec = self.sup.run("echo hello-tensor-roll")
+        self.assertTrue(rec["allowed"])
+        self.assertIn("hello-tensor-roll", rec["stdout"])
+        self.assertTrue(os.path.exists(self.sup.audit.path))
+
+    def test_deny_shadow(self):
+        rec = self.sup.run("cat /etc/shadow")
+        self.assertFalse(rec["allowed"])
+
+    def test_deny_curl(self):
+        rec = self.sup.run("curl http://example.com")
+        self.assertFalse(rec["allowed"])
+
+    def test_audit_log_written(self):
+        self.sup.run("echo x")
+        with open(self.sup.audit.path) as f:
+            lines = f.readlines()
+        self.assertTrue(lines)
+        json.loads(lines[-1])  # valid JSONL
+
+
+class TestDemo(unittest.TestCase):
+    def test_demo_fast_end_to_end(self):
+        d = tempfile.mkdtemp(prefix="trdemo-test-")
+        try:
+            r = subprocess.run(
+                [sys.executable, "-m", "tensor_roll.cli", "--workdir", d,
+                 "demo", "--fast"],
+                capture_output=True, text=True, timeout=600,
+                cwd=os.path.join(os.path.dirname(__file__), ".."))
+            self.assertEqual(r.returncode, 0, r.stderr[-3000:])
+            for f in ("student_fp32.trq", "student_int8.trq",
+                      "student_int4.trq"):
+                self.assertTrue(os.path.exists(os.path.join(d, "trq", f)),
+                                f)
+            self.assertIn("Demo complete", r.stdout)
+        finally:
+            shutil.rmtree(d, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)