Update app.py

app.py

@@ -1,5 +1,5 @@
 # app.py — Hugging Face Gradio Space
-# Deterministic Governance Mechanism - Unified Interface
+# Deterministic Governance Mechanism - Interactive Verification
 
 import json
 import math
@@ -142,7 +142,11 @@ def run_engine(
 # ============================================================================
 
 class MockEmbedder:
-    """Deterministic 2D embeddings for demo purposes."""
+    """Deterministic 2D embeddings for demo purposes.
+    
+    Note: Cache is a memoization optimization (process-local), not part of the
+    determinism invariant. Same text always produces same embedding via SHA-256.
+    """
     def __init__(self):
         self.cache = {}
         
@@ -384,6 +388,7 @@ def run_llm_guardrail(substrate_text, candidates_text, show_full_trace):
             })
             
             # Selection rule: highest alignment (distance is recorded but not used for selection)
+            # This is a modeling choice—alignment determines substrate pairing, distance affects stress.
             if alignment > best_alignment:
                 best_alignment = alignment
                 best_distance = dist
@@ -498,24 +503,38 @@ def run_llm_guardrail(substrate_text, candidates_text, show_full_trace):
 # Gradio Interface
 # ============================================================================
 
-with gr.Blocks(title="Material-Field Engine GUI") as demo:
-    gr.Markdown("# Material-Field Engine GUI")
+with gr.Blocks(title="Deterministic Governance Mechanism") as demo:
+    gr.Markdown(
+        """
+        # Deterministic Governance Mechanism
+        
+        **Interactive verification of the core invariant:** Same inputs → Same outputs (bit-identical)
+        
+        Probabilistic systems cannot be audited. If a decision changes between runs with identical inputs,
+        post-hoc explanation is speculation, not verification.
+        
+        This interface demonstrates mechanical exclusion: decisions produced by hard thresholds, not sampling.
+        
+        **Repository:** [github.com/Rymley/Deterministic-Governance-Mechanism](https://github.com/Rymley/Deterministic-Governance-Mechanism)
+        """
+    )
     
     with gr.Tabs():
         # ====================================================================
         # TAB 1: Mechanism Demo
         # ====================================================================
-        with gr.Tab("Mechanism Demo"):
+        with gr.Tab("Verify Invariant"):
             gr.Markdown(
                 """
-                ## Deterministic Governance Mechanism
+                ## Interactive Proof of Determinism
                 
-                Visualizes stress accumulation across three phases (nucleation, quenching, crystallization).
-                Shows how candidates fracture when stress exceeds yield threshold.
+                Adjust parameters and run the engine. The SHA-256 hash is computed from canonical JSON
+                containing all inputs, configuration, and outputs.
                 
-                **Purpose:** Understand the mechanical process behind deterministic exclusion.
+                **Test the invariant:** Run with identical settings multiple times. Hash should be identical.
+                **Try to break it:** Change any parameter. Hash should change.
                 
-                Repository: [github.com/Rymley/Deterministic-Governance-Mechanism](https://github.com/Rymley/Deterministic-Governance-Mechanism)
+                This is not a demonstration—it's a falsifiable experiment.
                 """
             )
             
@@ -574,22 +593,24 @@ with gr.Blocks(title="Material-Field Engine GUI") as demo:
         # ====================================================================
         # TAB 2: LLM Guardrail
         # ====================================================================
-        with gr.Tab("LLM Guardrail"):
+        with gr.Tab("Applied: LLM Filter"):
             gr.Markdown(
                 """
-                ## Deterministic LLM Filter
+                ## Mechanical Exclusion Applied to AI Outputs
                 
-                Evaluates LLM candidate outputs against verified substrate (ground truth).
-                Same deterministic exclusion engine, applied to practical filtering.
+                The same deterministic engine, applied to filter AI-generated candidates against verified substrate.
                 
-                **Purpose:** See how the mechanism works for real-world LLM output verification.
+                Candidates are evaluated mechanically—no probability, no sampling, just threshold comparison.
+                If stress exceeds yield threshold, the candidate is excluded.
+                
+                **This shows:** How the invariant applies to practical AI governance.
                 """
             )
             
             with gr.Row():
                 with gr.Column():
                     gr.Markdown("### 1. Verified Substrate")
-                    gr.Markdown("Approved facts (Ground Truth). One per line.")
+                    gr.Markdown("Ground truth. One per line.")
                     llm_substrate = gr.Textbox(
                         value="The sky is blue\nWater is wet\nParis is capital of France",
                         lines=8,
@@ -597,8 +618,8 @@ with gr.Blocks(title="Material-Field Engine GUI") as demo:
                     )
                 
                 with gr.Column():
-                    gr.Markdown("### 2. LLM Candidates")
-                    gr.Markdown("Generated responses (including hallucinations). One per line.")
+                    gr.Markdown("### 2. AI Candidates")
+                    gr.Markdown("Generated outputs to filter. One per line.")
                     llm_candidates = gr.Textbox(
                         value="The sky is blue\nThe sky is green\nThe sky is made of cheese",
                         lines=8,
@@ -611,10 +632,10 @@ with gr.Blocks(title="Material-Field Engine GUI") as demo:
                 info="Disable for faster UI with large candidate sets"
             )
             
-            llm_run_btn = gr.Button("Run Guardrail Filter", variant="primary")
+            llm_run_btn = gr.Button("Run Filter", variant="primary")
             
             llm_out_summary = gr.Markdown(label="Result")
-            llm_out_trace = gr.Markdown(visible=False)  # Hidden for LLM tab
+            llm_out_trace = gr.Markdown(visible=False)
             llm_out_plot = gr.Plot(label="Material Field Projection")
             
             with gr.Accordion("Metrics JSON", open=False):
@@ -633,15 +654,19 @@ with gr.Blocks(title="Material-Field Engine GUI") as demo:
         """
         ---
         
-        ### About Determinism
+        ### Core Invariant
+        
+        ```
+        Same input + same configuration + same substrate → same output (bit-identical)
+        ```
         
-        The SHA-256 hash in the Mechanism Demo is computed from canonical JSON containing all inputs, configuration, and outputs.
-        Identical settings produce identical hashes, proving mechanical determinism.
+        If two executions produce different outputs, something upstream changed.
+        The system makes divergence visible rather than masking it behind probability.
         
-        The LLM Guardrail applies the same engine to filter AI outputs against verified facts.
+        **Try to break the invariant.** If you do, file an issue on GitHub.
         
-        **Development GUI** | [Deterministic Governance Mechanism](https://github.com/Rymley/Deterministic-Governance-Mechanism)
+        [Deterministic Governance Mechanism](https://github.com/Rymley/Deterministic-Governance-Mechanism)
         """
     )
 
-demo.launch()
+demo.launch()