cscs-constraint-engine 2026.10.2__tar.gz

cscs_constraint_engine-2026.10.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cscs_constraint_engine-2026.10.2/NOTICE

@@ -0,0 +1,10 @@
+CSCS Constraint Physics Engine
+Copyright 2024-2026 Lazaro M. Echenique-Diaz, Ph.D.
+
+This product includes software developed by Lazaro M. Echenique-Diaz, Ph.D.
+(Yamagata University) as part of the CSCS Constraint State Physics research project.
+
+ATTRIBUTION NOTICE (Apache License 2.0, Section 4d):
+Any derivative work, distribution, or commercial integration of this software
+must retain attribution to the original author (Lazaro M. Echenique-Diaz, Ph.D.)
+and cite the project repository as specified in CITATION.cff.

cscs_constraint_engine-2026.10.2/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: cscs-constraint-engine
+Version: 2026.10.2
+Summary: CSCS Constraint Physics Engine: Zero-GPU Spectral Manifold & Contractive Telemetry Middleware for Small Language Models (SLMs)
+Author-email: "Lazaro M. Echenique-Diaz, Ph.D." <lazincip@gmail.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/lazincip/cscs-constraint-engine
+Keywords: SLM,LLM,guardrails,manifold,SVD,Banach-contraction,edge-AI,Ollama
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.22.0
+Dynamic: license-file
+
+# CSCS Constraint Physics Engine (`v2026.10.2`)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
+[![Zero GPU Overhead](https://img.shields.io/badge/GPU_Overhead-0_MB_(Pure_CPU)-brightgreen.svg)](#quickstart)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23750262-blue.svg)](https://doi.org/10.5281/zenodo.23750262)
+
+**A zero-GPU governor for Small Language Models.** It sits in front of a local SLM (Llama-3.2, Qwen-2.5, Phi-4, Gemma-2), scores prompts *before* they burn inference, tracks multi-turn drift, and audits outputs for confabulation — on one CPU thread, with **numpy only** and **0 MB VRAM**. Latency is environment-dependent; on the reference VM (Linux, Python 3.12.3, numpy 1.26.4) the v2026.10.2 gate measures **2.6 ms median / 3.4 ms P95 per turn across 300-turn sessions** (see [Operating Envelope](#operating-envelope) — earlier releases measured lower on other hardware; no cross-machine latency claim is made).
+
+*Created by **Lazaro M. Echenique-Diaz, Ph.D.*** · Concepts descend from evolutionary biology — see [Ecological Models & Origins](docs/ECOLOGICAL_MODELS_AND_ORIGINS.md).
+
+> **Note on nomenclature:** **CSCS** stands for **Constraint Space Coordinate System** — an independent open-source edge-AI middleware project created at Yamagata University, unrelated to the Swiss National Supercomputing Centre (CSCS, Lugano).
+
+---
+
+## Why
+
+Neural guardrails (LlamaGuard, NeMo) need a **second neural network** in VRAM — 1.5–4 GB a small edge device can't spare. Quantized SLMs also drift over long chats and invent citations, dates, and percentages when uncertain. This engine replaces the second model with linear algebra: a spectral manifold, a contraction mirror, and a friction field.
+
+The engine's first-stage discipline is **trajectory discipline**: a prompt is judged not only by what it contains, but by where the session has been — whether it continues the anchored trajectory of the conversation or breaks from it. Cross-model audit (2026-11) confirmed empirically that this history-relative signal (resonance collapse against the session anchors), not lexical content alone, is the engine's load-bearing discriminator; v2026.10.2 rebuilds the gate around that finding.
+
+## Intended Use & Non-Goals
+
+**Intended use:** Trajectory governance, drift telemetry, and confabulation auditing for a **known, deliberately seeded domain** on operator-controlled hardware — e.g. a university lab SLM answering questions about an enrolled research corpus, an offline field assistant constrained to an enrolled manual set, or a long-running local agent whose session must stay anchored to an operator-defined topic manifold.
+
+**Non-goals:** This engine is **not** a general-purpose chat filter, content-moderation system, or safety boundary for arbitrary open-domain conversation. A deployment whose domain is everything has no manifold to anchor to, and the gate's scores carry no meaning there. Operators enroll a seed corpus, choose the learning policy, and remain responsible for the deployment's content policy.
+
+## How it flows
+
+```mermaid
+flowchart LR
+    P[Prompt] --> Q{Quality gate<br/>score &ge; 0.30?}
+    Q -- No --> B[BLOCKED<br/>compute saved]
+    Q -- Yes --> M[SpectralManifold<br/>centered SVD residual &isin; &#91;0, 1&#93;]
+    M --> C[BanachContractionMirror<br/>anchor-weighted resonance &middot; Lyapunov &lambda;]
+    C --> S[RBFConstraintScout<br/>friction field]
+    S --> W{Wall?<br/>adaptive: friction &gt; 1/&phi; &asymp; 0.618<br/>calibrated: friction &gt; &tau;&#8329;&#8325;}
+    W -- Yes, not dreaming --> B
+    W -- No / dreaming --> SLM[SLM inference<br/>Ollama &middot; llama.cpp &middot; MLX]
+    SLM --> V[DriftVerifier]
+    V --> VS[VERIFIED]
+    V --> VD[SANCTIONED_DREAM]
+    V --> VR[SPORADIC_RISK]
+    M -.-> T[T3LB seed<br/>93 bytes &middot; 13-D state]
+```
+
+**State policy (v2026.10.2).** Blocked prompts mutate nothing. In the calibrated state, an allowed prompt commits state (mirror, scout, manifold) only if it lies in the **core attractor zone** — its anchor-only friction is at most $1/\Phi$; prompts in the tolerated band ($\Phi^{-1} < F \le \tau_{95}$) execute but change nothing, so long sessions cannot drift the judging state. Enrollment anchors the contraction mirror from the first cycle, and the engine **graduates automatically** from its adaptive policy (fixed $1/\Phi$ wall) to the calibrated policy (session-specific $\tau_{95}$, the leave-one-out 95th-percentile anchor friction) as soon as that wall is estimable from the anchored mirror vectors.
+
+## Quickstart
+
+```bash
+git clone https://github.com/lazincip/cscs-constraint-engine.git
+cd cscs-constraint-engine
+pip install -e .
+
+python -m unittest discover -s tests -v      # 6 invariant + regression tests
+python examples/slm_ollama_middleware.py     # simulation demo, no server needed
+python examples/slm_ollama_middleware.py --live --model qwen2.5:3b   # live Ollama
+python benchmarks/run_track_a.py             # committed Track A control battery
+```
+
+What the demo shows (verified run, v2026.10.2):
+
+```text
+[Turn 1] Summarize the divergence timeline of Solenodon cubanus...
+  Pre-Inference Gate : ALLOWED | Resonance 0.526
+  Post-Inference     : VERIFIED (sporadic_risk = 0.295)
+[Turn 4] buy cheap crypto tokens instant 100x pump free airdrop...
+  Pre-Inference Gate : BLOCKED (Compute Saved) | Resonance 0.239
+```
+
+> The Turn-1 verified risk changed from 0.195 (v2026.10.1) to 0.295 in v2026.10.2 — the verifier now counts plain integers and integer percentages as specifics and discounts hedged citations. The full change record is in [CHANGELOG.md](CHANGELOG.md).
+
+## Architectural Profile
+
+| Property | CSCS Constraint Engine |
+| :--- | :--- |
+| VRAM / GPU footprint | **0 MB (pure CPU / numpy)** |
+| Dependencies | numpy only |
+| Per-turn gate latency | environment-dependent — see Operating Envelope |
+| Domain signal | centered SVD residual $\in [0, 1]$ + anchor-weighted resonance |
+| Multi-turn drift metric | Banach contraction + Lyapunov exponent ($\lambda < 0$) + bounded state-commit budget |
+| Creativity vs. confabulation | **SANCTIONED_DREAM** vs. **SPORADIC_RISK** vs. **VERIFIED** |
+| Cross-session state | **93-byte T3LB seed** (lossless at 2-decimal precision) |
+
+Latency figures sometimes quoted for neural guardrails (80–450 ms) are published numbers for that model class, not measurements taken by this project, and are not used as a comparison baseline here. Full measurements, environment manifests, and the committed control-battery results: [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
+
+## Operating Envelope
+
+- **Latency (measured, this release):** 300 distinct-prompt turns, reference VM (Linux, Python 3.12.3, numpy 1.26.4): **median 2.6 ms, P95 3.4 ms**. v2026.10.1 measured 0.45–1.07 ms medians on other hardware with a lighter per-turn path; v2026.10.2 performs additional anchor passes per turn. Treat any single-machine figure as an envelope for that machine, not a guarantee. Very long prompts cost more (hashing is linear in length; ~2,000-word prompts reach ~10 ms class on commodity cores).
+- **Embedding cache:** repeated or near-repeated prompts (retries, loops, templated queries) hit the 1,024-entry embedding LRU and run **~2.6× faster** than distinct-prompt traffic. Quoted latencies are for *distinct* prompts — the conservative case.
+- **Language scope:** the quality gate tokenizes on whitespace. Unspaced scripts (e.g. Japanese, Chinese) score as single-token prompts and are blocked by the quality gate; CJK support requires a tokenizer and is out of scope for this release (documented in [docs/LIMITATIONS.md](docs/LIMITATIONS.md)).
+
+## Go deeper
+
+- **[Architecture & mathematics](docs/ARCHITECTURE.md)** — the five modules, the Dual-Gram SVD, the friction field, the graduation policy.
+- **[Benchmarks & evaluation protocol](docs/BENCHMARKS.md)** — Track A / Track B control tests and the verified baseline numbers.
+- **[Known limitations](docs/LIMITATIONS.md)** — friction-scale compression, cold-start geometry, CJK scope. Published, not hidden.
+- **[Ecological models & origins](docs/ECOLOGICAL_MODELS_AND_ORIGINS.md)** — coral, bushfire, and phoenix models behind the design.
+- **[Contributing](CONTRIBUTING.md)** — benchmark tracks and how to submit results.
+
+## License & citation
+
+Copyright © 2024–2026 **Lazaro M. Echenique-Diaz, Ph.D.**
+Licensed under the **Apache License, Version 2.0** (see [LICENSE](LICENSE) and [NOTICE](NOTICE)). If you use this in research or software, please cite it via [CITATION.cff](CITATION.cff) (concept DOI: [10.5281/zenodo.23750262](https://doi.org/10.5281/zenodo.23750262)).

cscs_constraint_engine-2026.10.2/README.md

@@ -0,0 +1,105 @@
+# CSCS Constraint Physics Engine (`v2026.10.2`)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
+[![Zero GPU Overhead](https://img.shields.io/badge/GPU_Overhead-0_MB_(Pure_CPU)-brightgreen.svg)](#quickstart)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23750262-blue.svg)](https://doi.org/10.5281/zenodo.23750262)
+
+**A zero-GPU governor for Small Language Models.** It sits in front of a local SLM (Llama-3.2, Qwen-2.5, Phi-4, Gemma-2), scores prompts *before* they burn inference, tracks multi-turn drift, and audits outputs for confabulation — on one CPU thread, with **numpy only** and **0 MB VRAM**. Latency is environment-dependent; on the reference VM (Linux, Python 3.12.3, numpy 1.26.4) the v2026.10.2 gate measures **2.6 ms median / 3.4 ms P95 per turn across 300-turn sessions** (see [Operating Envelope](#operating-envelope) — earlier releases measured lower on other hardware; no cross-machine latency claim is made).
+
+*Created by **Lazaro M. Echenique-Diaz, Ph.D.*** · Concepts descend from evolutionary biology — see [Ecological Models & Origins](docs/ECOLOGICAL_MODELS_AND_ORIGINS.md).
+
+> **Note on nomenclature:** **CSCS** stands for **Constraint Space Coordinate System** — an independent open-source edge-AI middleware project created at Yamagata University, unrelated to the Swiss National Supercomputing Centre (CSCS, Lugano).
+
+---
+
+## Why
+
+Neural guardrails (LlamaGuard, NeMo) need a **second neural network** in VRAM — 1.5–4 GB a small edge device can't spare. Quantized SLMs also drift over long chats and invent citations, dates, and percentages when uncertain. This engine replaces the second model with linear algebra: a spectral manifold, a contraction mirror, and a friction field.
+
+The engine's first-stage discipline is **trajectory discipline**: a prompt is judged not only by what it contains, but by where the session has been — whether it continues the anchored trajectory of the conversation or breaks from it. Cross-model audit (2026-11) confirmed empirically that this history-relative signal (resonance collapse against the session anchors), not lexical content alone, is the engine's load-bearing discriminator; v2026.10.2 rebuilds the gate around that finding.
+
+## Intended Use & Non-Goals
+
+**Intended use:** Trajectory governance, drift telemetry, and confabulation auditing for a **known, deliberately seeded domain** on operator-controlled hardware — e.g. a university lab SLM answering questions about an enrolled research corpus, an offline field assistant constrained to an enrolled manual set, or a long-running local agent whose session must stay anchored to an operator-defined topic manifold.
+
+**Non-goals:** This engine is **not** a general-purpose chat filter, content-moderation system, or safety boundary for arbitrary open-domain conversation. A deployment whose domain is everything has no manifold to anchor to, and the gate's scores carry no meaning there. Operators enroll a seed corpus, choose the learning policy, and remain responsible for the deployment's content policy.
+
+## How it flows
+
+```mermaid
+flowchart LR
+    P[Prompt] --> Q{Quality gate<br/>score &ge; 0.30?}
+    Q -- No --> B[BLOCKED<br/>compute saved]
+    Q -- Yes --> M[SpectralManifold<br/>centered SVD residual &isin; &#91;0, 1&#93;]
+    M --> C[BanachContractionMirror<br/>anchor-weighted resonance &middot; Lyapunov &lambda;]
+    C --> S[RBFConstraintScout<br/>friction field]
+    S --> W{Wall?<br/>adaptive: friction &gt; 1/&phi; &asymp; 0.618<br/>calibrated: friction &gt; &tau;&#8329;&#8325;}
+    W -- Yes, not dreaming --> B
+    W -- No / dreaming --> SLM[SLM inference<br/>Ollama &middot; llama.cpp &middot; MLX]
+    SLM --> V[DriftVerifier]
+    V --> VS[VERIFIED]
+    V --> VD[SANCTIONED_DREAM]
+    V --> VR[SPORADIC_RISK]
+    M -.-> T[T3LB seed<br/>93 bytes &middot; 13-D state]
+```
+
+**State policy (v2026.10.2).** Blocked prompts mutate nothing. In the calibrated state, an allowed prompt commits state (mirror, scout, manifold) only if it lies in the **core attractor zone** — its anchor-only friction is at most $1/\Phi$; prompts in the tolerated band ($\Phi^{-1} < F \le \tau_{95}$) execute but change nothing, so long sessions cannot drift the judging state. Enrollment anchors the contraction mirror from the first cycle, and the engine **graduates automatically** from its adaptive policy (fixed $1/\Phi$ wall) to the calibrated policy (session-specific $\tau_{95}$, the leave-one-out 95th-percentile anchor friction) as soon as that wall is estimable from the anchored mirror vectors.
+
+## Quickstart
+
+```bash
+git clone https://github.com/lazincip/cscs-constraint-engine.git
+cd cscs-constraint-engine
+pip install -e .
+
+python -m unittest discover -s tests -v      # 6 invariant + regression tests
+python examples/slm_ollama_middleware.py     # simulation demo, no server needed
+python examples/slm_ollama_middleware.py --live --model qwen2.5:3b   # live Ollama
+python benchmarks/run_track_a.py             # committed Track A control battery
+```
+
+What the demo shows (verified run, v2026.10.2):
+
+```text
+[Turn 1] Summarize the divergence timeline of Solenodon cubanus...
+  Pre-Inference Gate : ALLOWED | Resonance 0.526
+  Post-Inference     : VERIFIED (sporadic_risk = 0.295)
+[Turn 4] buy cheap crypto tokens instant 100x pump free airdrop...
+  Pre-Inference Gate : BLOCKED (Compute Saved) | Resonance 0.239
+```
+
+> The Turn-1 verified risk changed from 0.195 (v2026.10.1) to 0.295 in v2026.10.2 — the verifier now counts plain integers and integer percentages as specifics and discounts hedged citations. The full change record is in [CHANGELOG.md](CHANGELOG.md).
+
+## Architectural Profile
+
+| Property | CSCS Constraint Engine |
+| :--- | :--- |
+| VRAM / GPU footprint | **0 MB (pure CPU / numpy)** |
+| Dependencies | numpy only |
+| Per-turn gate latency | environment-dependent — see Operating Envelope |
+| Domain signal | centered SVD residual $\in [0, 1]$ + anchor-weighted resonance |
+| Multi-turn drift metric | Banach contraction + Lyapunov exponent ($\lambda < 0$) + bounded state-commit budget |
+| Creativity vs. confabulation | **SANCTIONED_DREAM** vs. **SPORADIC_RISK** vs. **VERIFIED** |
+| Cross-session state | **93-byte T3LB seed** (lossless at 2-decimal precision) |
+
+Latency figures sometimes quoted for neural guardrails (80–450 ms) are published numbers for that model class, not measurements taken by this project, and are not used as a comparison baseline here. Full measurements, environment manifests, and the committed control-battery results: [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
+
+## Operating Envelope
+
+- **Latency (measured, this release):** 300 distinct-prompt turns, reference VM (Linux, Python 3.12.3, numpy 1.26.4): **median 2.6 ms, P95 3.4 ms**. v2026.10.1 measured 0.45–1.07 ms medians on other hardware with a lighter per-turn path; v2026.10.2 performs additional anchor passes per turn. Treat any single-machine figure as an envelope for that machine, not a guarantee. Very long prompts cost more (hashing is linear in length; ~2,000-word prompts reach ~10 ms class on commodity cores).
+- **Embedding cache:** repeated or near-repeated prompts (retries, loops, templated queries) hit the 1,024-entry embedding LRU and run **~2.6× faster** than distinct-prompt traffic. Quoted latencies are for *distinct* prompts — the conservative case.
+- **Language scope:** the quality gate tokenizes on whitespace. Unspaced scripts (e.g. Japanese, Chinese) score as single-token prompts and are blocked by the quality gate; CJK support requires a tokenizer and is out of scope for this release (documented in [docs/LIMITATIONS.md](docs/LIMITATIONS.md)).
+
+## Go deeper
+
+- **[Architecture & mathematics](docs/ARCHITECTURE.md)** — the five modules, the Dual-Gram SVD, the friction field, the graduation policy.
+- **[Benchmarks & evaluation protocol](docs/BENCHMARKS.md)** — Track A / Track B control tests and the verified baseline numbers.
+- **[Known limitations](docs/LIMITATIONS.md)** — friction-scale compression, cold-start geometry, CJK scope. Published, not hidden.
+- **[Ecological models & origins](docs/ECOLOGICAL_MODELS_AND_ORIGINS.md)** — coral, bushfire, and phoenix models behind the design.
+- **[Contributing](CONTRIBUTING.md)** — benchmark tracks and how to submit results.
+
+## License & citation
+
+Copyright © 2024–2026 **Lazaro M. Echenique-Diaz, Ph.D.**
+Licensed under the **Apache License, Version 2.0** (see [LICENSE](LICENSE) and [NOTICE](NOTICE)). If you use this in research or software, please cite it via [CITATION.cff](CITATION.cff) (concept DOI: [10.5281/zenodo.23750262](https://doi.org/10.5281/zenodo.23750262)).

cscs_constraint_engine-2026.10.2/cscs/__init__.py

@@ -0,0 +1,24 @@
+"""
+CSCS Constraint Physics Engine: Zero-GPU Spectral Manifold & Contractive
+Telemetry Middleware for Small Language Models (SLMs) (v2026.10.2)
+Principal Investigator & Author: Lazaro M. Echenique-Diaz, Ph.D.
+"""
+
+from .manifold import SpectralManifold
+from .contraction import BanachContractionMirror
+from .scout import RBFConstraintScout
+from .compression import MDLCompressionRouter
+from .verifier import DriftVerifier
+from .codec import T3LBStateCodec
+from .engine import CSCSMiddlewareEngine
+
+__all__ = [
+    "SpectralManifold",
+    "BanachContractionMirror",
+    "RBFConstraintScout",
+    "MDLCompressionRouter",
+    "DriftVerifier",
+    "T3LBStateCodec",
+    "CSCSMiddlewareEngine"
+]
+__version__ = "2026.10.2"

cscs_constraint_engine-2026.10.2/cscs/codec.py

@@ -0,0 +1,82 @@
+"""
+T3LBStateCodec: 13-dimensional telemetry summary serializer for stateless SLM
+context handoffs across edge devices (93 bytes per state seed, lossless
+at 2-decimal fixed precision for the 13 summary scalars).
+"""
+
+import math as m
+import re
+import numpy as np
+from typing import Dict, Any
+
+
+class T3LBStateCodec:
+    """
+    Computes and serializes all 13 Constraint Space Coordinate System (CSCS)
+    dimensions into a compact 93-byte T3LB telemetry seed string:
+    X (Gap/Novelty Tolerance), Y (Quality Relay Gain), Z (Manifold Persistence),
+    W (Constraint Density), P (Compression Efficiency), T (Window Horizon Saturation),
+    R (Reflexivity / Inverse Friction), S (Kernel Density Coupling), V (Veto Strength),
+    N (Contraction Convergence), E (Effective Rank Ratio),
+    B (Bleaching/Block Recovery), Q (State Coherence).
+    """
+
+    DIMENSIONS = ["X", "Y", "Z", "W", "P", "T", "R", "S", "V", "N", "E", "B", "Q"]
+
+    def __init__(self):
+        self.dims: Dict[str, float] = {
+            "X": 0.88, "Y": 1.25, "Z": 0.94, "W": 1.08,
+            "P": 0.87, "T": 0.79, "R": 0.74, "S": 0.92,
+            "V": 0.78, "N": 0.74, "E": 0.88, "B": 0.79, "Q": 0.65
+        }
+
+    def update_from_cycle(self, resonance: float, field_friction: float,
+                          in_manifold: float, quality: float, blocked: bool,
+                          compression_ratio: float = 0.85, kernel_density: float = 0.50,
+                          effective_rank: float = 3.0, iterations: int = 4,
+                          cycles: int = 1):
+        self.dims["T"] = round(min(1.50, 0.50 + 0.50 * min(1.0, cycles / 64.0)), 3)
+
+        if blocked:
+            self.dims["B"] = min(1.50, round(self.dims["B"] + 0.02, 3))
+            self.dims["V"] = min(1.20, round(self.dims["V"] + 0.03, 3))
+            self.dims["X"] = max(0.40, round(self.dims["X"] - 0.02, 3))
+            return
+
+        self.dims["X"] = round(0.60 + 0.40 * (1.0 - field_friction), 3)
+        self.dims["Y"] = round(0.75 + 0.50 * quality, 3)
+        self.dims["Z"] = round(0.75 + 0.24 * in_manifold, 3)
+        self.dims["W"] = round(0.80 + 0.40 * (0.5 * resonance + 0.5 * in_manifold), 3)
+        self.dims["P"] = round(0.50 + 0.50 * max(0.0, min(1.0, 1.0 - compression_ratio * 0.5)), 3)
+        self.dims["R"] = round(0.60 + 0.35 * (1.0 - field_friction), 3)
+        self.dims["S"] = round(0.50 + 0.50 * max(0.0, min(1.0, kernel_density)), 3)
+        self.dims["N"] = round(0.50 + 0.50 * max(0.0, 1.0 - (iterations / 10.0)), 3)
+        self.dims["E"] = round(0.50 + 0.50 * min(1.0, effective_rank / 8.0), 3)
+        self.dims["Q"] = round(0.50 + 0.45 * (quality * resonance), 3)
+
+    def magnitude(self) -> float:
+        vec = np.array([self.dims[k] for k in self.DIMENSIONS], dtype=np.float64)
+        return round(float(np.linalg.norm(vec) * m.sqrt(len(self.DIMENSIONS)) / 2.8), 2)
+
+    def encode_seed(self, version: str = "v2026.10") -> str:
+        mag = self.magnitude()
+        body = "".join(f"{k}{self.dims[k]:.2f}" for k in self.DIMENSIONS)
+        return f"T3LB:{version}|M{mag:.2f}|{body}|SecLock"
+
+    @classmethod
+    def decode_seed(cls, seed_str: str) -> Dict[str, Any]:
+        parts = seed_str.strip().split("|")
+        if len(parts) < 3 or not parts[0].startswith("T3LB:"):
+            raise ValueError("Invalid T3LB seed format")
+        version = parts[0].split(":", 1)[1]
+        mag = float(parts[1][1:])
+        matches = re.findall(r"([A-Z])(\d+\.\d+)", parts[2])
+        dims = {k: float(v) for k, v in matches}
+        return {"version": version, "magnitude": mag, "dimensions": dims}
+
+    def load_seed(self, seed_str: str) -> Dict[str, Any]:
+        parsed = self.decode_seed(seed_str)
+        for k, v in parsed["dimensions"].items():
+            if k in self.dims:
+                self.dims[k] = float(v)
+        return parsed

cscs_constraint_engine-2026.10.2/cscs/compression.py

@@ -0,0 +1,94 @@
+"""
+MDLCompressionRouter: Information-Theoretic Minimum Description Length (MDL)
+and delta redundancy telemetry for context-constrained edge models.
+"""
+
+import hashlib as h
+import zlib
+import numpy as np
+from collections import OrderedDict
+from typing import Dict, List, Any
+from .manifold import SpectralManifold
+from .scout import INV_PHI
+
+
+class MDLCompressionRouter:
+    """
+    Measures real byte-level Minimum Description Length (MDL) across:
+    1. DEFLATE/LZ77 entropy coding of the state/prompt payload.
+    2. Entangled Delta Coding against the nearest neighbor in memory.
+    3. Spectral Coordinate Sparse Projection (structural summary).
+
+    Caches embedding vectors and compressed reference lengths in a bounded
+    registry (max 64 entries) for sub-0.2ms execution.
+    """
+
+    def __init__(self, manifold: SpectralManifold, max_registry: int = 64):
+        self.manifold = manifold
+        self.max_registry = max_registry
+        self.archive: OrderedDict[str, bytes] = OrderedDict()
+        self.raw_registry: OrderedDict[str, bytes] = OrderedDict()
+        self.vector_registry: OrderedDict[str, np.ndarray] = OrderedDict()
+
+    def compress(self, text: str, coords: List[float], mutate: bool = True) -> Dict[str, Any]:
+        raw_bytes = text.encode("utf-8")
+        raw_len = max(1, len(raw_bytes))
+        key = h.blake2b(raw_bytes, digest_size=6).hexdigest()
+
+        zlib_bytes = zlib.compress(raw_bytes, level=1)
+        lz_ratio = len(zlib_bytes) / raw_len
+
+        v = self.manifold.embed(text)
+        best_sim = 0.0
+        best_key = None
+
+        for k, pv in self.vector_registry.items():
+            sim = float(np.dot(v, pv))
+            if sim > best_sim:
+                best_sim = sim
+                best_key = k
+
+        if best_sim > INV_PHI and best_key is not None:
+            ref_bytes = self.raw_registry[best_key]
+            ref_compressed_len = len(self.archive[best_key])
+            joint_compressed = len(zlib.compress(ref_bytes + b"||" + raw_bytes, level=1))
+            marginal_bytes = max(4, joint_compressed - ref_compressed_len)
+            delta_ratio = marginal_bytes / raw_len
+        else:
+            delta_ratio = 1.0
+
+        if coords:
+            active = sum(1 for c in coords if abs(c) > 0.05)
+            spectral_ratio = (active * 4) / raw_len
+        else:
+            spectral_ratio = 1.0
+
+        if mutate:
+            self.archive[key] = zlib_bytes
+            self.raw_registry[key] = raw_bytes
+            self.vector_registry[key] = v
+            if len(self.vector_registry) > self.max_registry:
+                self.archive.popitem(last=False)
+                self.raw_registry.popitem(last=False)
+                self.vector_registry.popitem(last=False)
+
+        candidates = [
+            ("lz77_entropy", lz_ratio),
+            ("entangled_delta", delta_ratio),
+            ("spectral_sparse", spectral_ratio)
+        ]
+        best_method, best_ratio = min(candidates, key=lambda x: x[1])
+
+        return {
+            "key": key,
+            "best_method": best_method,
+            "best_ratio": round(float(best_ratio), 4),
+            "raw_bytes": raw_len,
+            "lz77_bytes": len(zlib_bytes),
+            "nearest_entanglement_sim": round(best_sim, 4),
+            "ratios": {
+                "lz77_entropy": round(float(lz_ratio), 4),
+                "entangled_delta": round(float(delta_ratio), 4),
+                "spectral_sparse": round(float(spectral_ratio), 4)
+            }
+        }