fluidlayer 2.0.0__tar.gz → 2.2.0__tar.gz

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fluidlayer
-Version: 2.0.0
-Summary: A research memory layer for language models using cellular-sheaf diffusion
+Version: 2.2.0
+Summary: A research memory layer for language models with optional GPT-2 and Qwen2 adapters
 Author: Kapil Dhinwa
 License: MIT
 Project-URL: Homepage, https://github.com/kapildhinwa2010-dev/fluidtech
@@ -216,14 +216,17 @@ Details: [`docs/TEN-MILLION.md`](docs/TEN-MILLION.md)
 ## The negative results
 
 This is the part that makes the rest believable.
-Eleven results came out negative or against expectation, and all eleven are measured, reproducible, and published.
+Eleven negative or unexpected findings are documented. Most have checked-in
+result files; the archived transformer and real-GPT-2 outputs are now
+checked in. Their original model/script environments are not fully included,
+so those historical runs cannot be independently repeated as-is.
 
 | What we expected | What happened |
 |---|---|
 | The **topological** selection criterion picks the right facts | It does **not** — `0.000` precision vs `0.970` for plain geometric affinity. |
 | `‖L·1‖∞` detects the frozen state | It does **not** — the frustration index does; the old claim is now a test case. |
 | `λ₂` predicts long-context quality | Barely — Pearson `0.20`. |
-| A transformer loses at some scale | It **wins** at every scale we could train. |
+| A transformer loses at some scale | The archived run says it **wins**; see `results/train_results.json`. |
 | A domain prior beats a frequency table | It helps (`−0.006 nats`) but a **unigram table wins 6× more**. |
 | The diffusion tier is neutral on a frozen model | It **degrades** the model by **`+0.81 nats`** (fixed → `+0.0000`, but no upside either). |
 | Training the layer helps | It **hurts** — the training-free identity map is better (`0.800 vs 0.650`). |
@@ -235,16 +238,18 @@ Read it: [`docs/NEGATIVE-RESULTS.md`](docs/NEGATIVE-RESULTS.md)
 ## The repository
 
 ```text
-fluidlayer/            the package (pure NumPy; torch only in torch_graft.py)
+fluidlayer/            the package (NumPy core; optional PyTorch adapters)
   graft.py             the attachable memory layer
   memory.py            the frozen register (20 B per fact, bit-exact)
   torch_graft.py       the same layer in PyTorch, for a real LLM
   gpt2_model.py        a GPT-2 forward pass in PyTorch (no transformers needed)
   gpt2_tokenizer.py    the GPT-2 byte-level BPE, in pure Python
+  qwen2_model.py       an optional PyTorch Qwen2 forward pass
   sheaf.py topology.py diffusion.py blocks.py autodiff.py ...
 
 experiments/           every measurement; each writes a JSON into results/
   e14_real_gpt2.py     the graft on a REAL pretrained GPT-2 (124M)
+  e15_scale_model.py   the graft on Qwen2.5-0.5B
   e13_knn_baseline.py  the layer vs. the closest prior art (kNN-LM)
 
 tools/                 the artifact checker, bundler, checkpoint downloader,
@@ -253,7 +258,7 @@ fluidlayer/bpe.py      the byte-level BPE tokenizer
 
 tests/                 the unit tests (pytest, or run them without it)
 
-examples/              quickstart.py, graft_demo.py, gate_demo.py
+examples/              quickstart.py, graft_demo.py, gate_demo.py, appkit/
 
 docs/                  the design docs, the API, the limits, the theory report
 
@@ -273,28 +278,20 @@ and [limitations](docs/LIMITATION.md).
 
 ---
 
-## Status — and it now includes a REAL pretrained LLM
+## Real-model experiment status
 
-GPT-2 (124M parameters, the real 50,257-token BPE tokenizer), run on CPU with the memory layer attached:
+The E14 GPT-2 experiment script, forward implementation, tokenizer, and
+archived `results/e14_real_gpt2.json` are included. The checkpoint is not;
+rerun E14 to independently reproduce the recorded measurements. See
+[the reproduction guide](docs/REPRODUCING.md) for download and run commands.
 
-| Test | Result |
-|---|---|
-| Attaching the layer | The logits are **bit-identical** (max diff `0.000e+00`). |
-| A fact planted **2,947 tokens** before the query | The base GPT-2 predicts `464`; **the layer predicts the fact**. |
-| The base model’s perplexity | `4.0289` (`ppl 56.20`) → **`4.0019` (`ppl 54.70`)** with the layer. |
-
-And one result that narrows the claim honestly:
-
-On the real model, the classic kNN-LM interpolation beats the gated override by **8×** on perplexity — the opposite of the 131k-parameter model, where the gate won by **7.4×**.
-The gate wins where the base model is weak; interpolation wins where it is strong.
-The capability works on both.
-
-The checkpoint, the forward pass and the tokenizer are all in this repository:
-
-- [`fluidlayer/gpt2_model.py`](fluidlayer/gpt2_model.py)
-- [`fluidlayer/gpt2_tokenizer.py`](fluidlayer/gpt2_tokenizer.py)
-
-No `transformers` dependency, and the generation is verified coherent.
+E15 adds a from-scratch Qwen2.5-0.5B forward implementation and app-kit
+integration. Its archived run records bit-identical attachment, exact recall
+of a planted fact 1,411 tokens back, and a best gated loss improvement of
+`0.041` nats; the kNN-LM baseline improves loss by `0.274` nats, so this run
+does not show the gate outperforming that baseline. The checkpoint is not
+bundled. Reproduction requires the optional GPU dependencies and local model
+weights; see [E15 instructions](docs/REPRODUCING.md#qwen2-scale-experiment-e15).
 
 The Torch twin is now tested against the NumPy reference in [`tests/test_torch_parity.py`](tests/test_torch_parity.py): the two implementations must agree on the router, the store and the gated override.
 
@@ -314,7 +311,9 @@ claim or validate production-scale operation.
 
 ## A research prototype, honestly labelled
 
-Everything above was measured on CPU, at small scale, on a character-level or 512-token subword corpus, with a **131,392-parameter model**.
+The core research experiments use small CPU models and character-level or
+512-token subword corpora. E14 and E15 are separate pretrained-model
+experiments; their checkpoints are not included.
 
 The subword repeat is the closest thing to a realistic tokenizer in this repository.
 The GPU run, [`experiments/gpu_graft.py`](experiments/gpu_graft.py), is written and has not been executed here.
@@ -370,7 +369,7 @@ A research memory layer with an operator-level stability bound, a bounded in-mem
 ## Origin and acknowledgments
 
 The project began with the author's idea of flowing information through a
-topological structure. The implementation and repository organization were
-developed with AI assistance. The measurements, limitations, and research
-decisions are documented alongside the code so the work can be evaluated and
-reproduced.
+topological structure. The author describes it as a school project and
+credits AI assistance for implementation and repository organization. The
+research decisions, measurements, and limitations are documented alongside
+the code so the work can be evaluated and reproduced.

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/README.md

@@ -179,14 +179,17 @@ Details: [`docs/TEN-MILLION.md`](docs/TEN-MILLION.md)
 ## The negative results
 
 This is the part that makes the rest believable.
-Eleven results came out negative or against expectation, and all eleven are measured, reproducible, and published.
+Eleven negative or unexpected findings are documented. Most have checked-in
+result files; the archived transformer and real-GPT-2 outputs are now
+checked in. Their original model/script environments are not fully included,
+so those historical runs cannot be independently repeated as-is.
 
 | What we expected | What happened |
 |---|---|
 | The **topological** selection criterion picks the right facts | It does **not** — `0.000` precision vs `0.970` for plain geometric affinity. |
 | `‖L·1‖∞` detects the frozen state | It does **not** — the frustration index does; the old claim is now a test case. |
 | `λ₂` predicts long-context quality | Barely — Pearson `0.20`. |
-| A transformer loses at some scale | It **wins** at every scale we could train. |
+| A transformer loses at some scale | The archived run says it **wins**; see `results/train_results.json`. |
 | A domain prior beats a frequency table | It helps (`−0.006 nats`) but a **unigram table wins 6× more**. |
 | The diffusion tier is neutral on a frozen model | It **degrades** the model by **`+0.81 nats`** (fixed → `+0.0000`, but no upside either). |
 | Training the layer helps | It **hurts** — the training-free identity map is better (`0.800 vs 0.650`). |
@@ -198,16 +201,18 @@ Read it: [`docs/NEGATIVE-RESULTS.md`](docs/NEGATIVE-RESULTS.md)
 ## The repository
 
 ```text
-fluidlayer/            the package (pure NumPy; torch only in torch_graft.py)
+fluidlayer/            the package (NumPy core; optional PyTorch adapters)
   graft.py             the attachable memory layer
   memory.py            the frozen register (20 B per fact, bit-exact)
   torch_graft.py       the same layer in PyTorch, for a real LLM
   gpt2_model.py        a GPT-2 forward pass in PyTorch (no transformers needed)
   gpt2_tokenizer.py    the GPT-2 byte-level BPE, in pure Python
+  qwen2_model.py       an optional PyTorch Qwen2 forward pass
   sheaf.py topology.py diffusion.py blocks.py autodiff.py ...
 
 experiments/           every measurement; each writes a JSON into results/
   e14_real_gpt2.py     the graft on a REAL pretrained GPT-2 (124M)
+  e15_scale_model.py   the graft on Qwen2.5-0.5B
   e13_knn_baseline.py  the layer vs. the closest prior art (kNN-LM)
 
 tools/                 the artifact checker, bundler, checkpoint downloader,
@@ -216,7 +221,7 @@ fluidlayer/bpe.py      the byte-level BPE tokenizer
 
 tests/                 the unit tests (pytest, or run them without it)
 
-examples/              quickstart.py, graft_demo.py, gate_demo.py
+examples/              quickstart.py, graft_demo.py, gate_demo.py, appkit/
 
 docs/                  the design docs, the API, the limits, the theory report
 
@@ -236,28 +241,20 @@ and [limitations](docs/LIMITATION.md).
 
 ---
 
-## Status — and it now includes a REAL pretrained LLM
+## Real-model experiment status
 
-GPT-2 (124M parameters, the real 50,257-token BPE tokenizer), run on CPU with the memory layer attached:
+The E14 GPT-2 experiment script, forward implementation, tokenizer, and
+archived `results/e14_real_gpt2.json` are included. The checkpoint is not;
+rerun E14 to independently reproduce the recorded measurements. See
+[the reproduction guide](docs/REPRODUCING.md) for download and run commands.
 
-| Test | Result |
-|---|---|
-| Attaching the layer | The logits are **bit-identical** (max diff `0.000e+00`). |
-| A fact planted **2,947 tokens** before the query | The base GPT-2 predicts `464`; **the layer predicts the fact**. |
-| The base model’s perplexity | `4.0289` (`ppl 56.20`) → **`4.0019` (`ppl 54.70`)** with the layer. |
-
-And one result that narrows the claim honestly:
-
-On the real model, the classic kNN-LM interpolation beats the gated override by **8×** on perplexity — the opposite of the 131k-parameter model, where the gate won by **7.4×**.
-The gate wins where the base model is weak; interpolation wins where it is strong.
-The capability works on both.
-
-The checkpoint, the forward pass and the tokenizer are all in this repository:
-
-- [`fluidlayer/gpt2_model.py`](fluidlayer/gpt2_model.py)
-- [`fluidlayer/gpt2_tokenizer.py`](fluidlayer/gpt2_tokenizer.py)
-
-No `transformers` dependency, and the generation is verified coherent.
+E15 adds a from-scratch Qwen2.5-0.5B forward implementation and app-kit
+integration. Its archived run records bit-identical attachment, exact recall
+of a planted fact 1,411 tokens back, and a best gated loss improvement of
+`0.041` nats; the kNN-LM baseline improves loss by `0.274` nats, so this run
+does not show the gate outperforming that baseline. The checkpoint is not
+bundled. Reproduction requires the optional GPU dependencies and local model
+weights; see [E15 instructions](docs/REPRODUCING.md#qwen2-scale-experiment-e15).
 
 The Torch twin is now tested against the NumPy reference in [`tests/test_torch_parity.py`](tests/test_torch_parity.py): the two implementations must agree on the router, the store and the gated override.
 
@@ -277,7 +274,9 @@ claim or validate production-scale operation.
 
 ## A research prototype, honestly labelled
 
-Everything above was measured on CPU, at small scale, on a character-level or 512-token subword corpus, with a **131,392-parameter model**.
+The core research experiments use small CPU models and character-level or
+512-token subword corpora. E14 and E15 are separate pretrained-model
+experiments; their checkpoints are not included.
 
 The subword repeat is the closest thing to a realistic tokenizer in this repository.
 The GPU run, [`experiments/gpu_graft.py`](experiments/gpu_graft.py), is written and has not been executed here.
@@ -333,7 +332,7 @@ A research memory layer with an operator-level stability bound, a bounded in-mem
 ## Origin and acknowledgments
 
 The project began with the author's idea of flowing information through a
-topological structure. The implementation and repository organization were
-developed with AI assistance. The measurements, limitations, and research
-decisions are documented alongside the code so the work can be evaluated and
-reproduced.
+topological structure. The author describes it as a school project and
+credits AI assistance for implementation and repository organization. The
+research decisions, measurements, and limitations are documented alongside
+the code so the work can be evaluated and reproduced.

fluidlayer-2.2.0/deployment/__init__.py

@@ -0,0 +1 @@
+"""Optional deployment helpers for applications embedding FluidLayer."""

fluidlayer-2.2.0/deployment/session_registry.py

@@ -0,0 +1,178 @@
+"""Bounded, process-local isolation for stateful per-session memory branches.
+
+This helper is an application integration aid, not an authentication system
+or a cross-process session store. Applications must derive identifiers from
+their authenticated identity layer and must not expose branch objects beyond
+the lease that owns them.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Callable, Generic, Protocol, TypeVar
+
+
+class Resettable(Protocol):
+    """The minimum interface required from a stateful branch."""
+
+    def reset(self) -> None:
+        """Clear all state associated with the branch."""
+
+
+BranchT = TypeVar("BranchT", bound=Resettable)
+
+
+class SessionRegistryError(RuntimeError):
+    """Base exception for session-registry lifecycle errors."""
+
+
+class SessionCapacityError(SessionRegistryError):
+    """Raised when the registry is full of unexpired sessions."""
+
+
+class SessionBusyError(SessionRegistryError):
+    """Raised when a caller tries to reset or close an active session."""
+
+
+@dataclass
+class _Session(Generic[BranchT]):
+    branch: BranchT
+    last_used: float
+    active_leases: int = 0
+    lock: threading.RLock = field(default_factory=threading.RLock)
+
+
+class SessionRegistry(Generic[BranchT]):
+    """Manage separate stateful branches for `(tenant_id, session_id)` keys.
+
+    Each lease holds a per-session lock for its whole duration. This prevents
+    concurrent requests from interleaving writes to one branch while allowing
+    independent sessions to proceed concurrently. Expired idle sessions are
+    removed when the registry is next accessed. Capacity is a hard bound:
+    active or unexpired sessions are never silently evicted.
+
+    The registry is process-local and volatile. For multiple workers, use
+    worker affinity or an application-owned session service; do not serialize
+    live branch objects and assume they are safe to restore.
+    """
+
+    def __init__(
+        self,
+        branch_factory: Callable[[], BranchT],
+        *,
+        max_sessions: int = 1024,
+        ttl_seconds: float = 1800.0,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if not callable(branch_factory):
+            raise TypeError("branch_factory must be callable")
+        if isinstance(max_sessions, bool) or not isinstance(max_sessions, int):
+            raise TypeError("max_sessions must be an integer")
+        if max_sessions <= 0:
+            raise ValueError("max_sessions must be greater than zero")
+        if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, (int, float)):
+            raise TypeError("ttl_seconds must be a finite positive number")
+        if not math.isfinite(ttl_seconds) or ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be a finite positive number")
+        if not callable(clock):
+            raise TypeError("clock must be callable")
+
+        self._branch_factory = branch_factory
+        self._max_sessions = max_sessions
+        self._ttl_seconds = float(ttl_seconds)
+        self._clock = clock
+        self._sessions: dict[tuple[str, str], _Session[BranchT]] = {}
+        self._lock = threading.RLock()
+
+    @staticmethod
+    def _validate_id(value: str, name: str) -> str:
+        if not isinstance(value, str):
+            raise TypeError(f"{name} must be a string")
+        if not value.strip():
+            raise ValueError(f"{name} must not be empty")
+        return value
+
+    def _expire_idle_sessions(self, now: float) -> None:
+        expired = [
+            key
+            for key, session in self._sessions.items()
+            if session.active_leases == 0
+            and now - session.last_used >= self._ttl_seconds
+        ]
+        for key in expired:
+            del self._sessions[key]
+
+    @contextmanager
+    def lease(self, tenant_id: str, session_id: str) -> Iterator[BranchT]:
+        """Yield the branch for one identity pair, serialized per session."""
+        tenant = self._validate_id(tenant_id, "tenant_id")
+        session_name = self._validate_id(session_id, "session_id")
+        key = (tenant, session_name)
+        now = self._clock()
+
+        with self._lock:
+            self._expire_idle_sessions(now)
+            session = self._sessions.get(key)
+            if session is None:
+                if len(self._sessions) >= self._max_sessions:
+                    raise SessionCapacityError(
+                        f"session registry is at capacity "
+                        f"({self._max_sessions}); retry after sessions expire "
+                        "or close an idle session"
+                    )
+                session = _Session(self._branch_factory(), last_used=now)
+                self._sessions[key] = session
+            session.active_leases += 1
+            session.last_used = now
+
+        try:
+            with session.lock:
+                yield session.branch
+        finally:
+            with self._lock:
+                session.active_leases -= 1
+                session.last_used = self._clock()
+
+    def reset_session(self, tenant_id: str, session_id: str) -> bool:
+        """Reset an idle session; return False if it does not exist."""
+        key = (
+            self._validate_id(tenant_id, "tenant_id"),
+            self._validate_id(session_id, "session_id"),
+        )
+        with self._lock:
+            self._expire_idle_sessions(self._clock())
+            session = self._sessions.get(key)
+            if session is None:
+                return False
+            if session.active_leases:
+                raise SessionBusyError("cannot reset a session with an active lease")
+            session.branch.reset()
+            session.last_used = self._clock()
+            return True
+
+    def close_session(self, tenant_id: str, session_id: str) -> bool:
+        """Remove an idle session; return False if it does not exist."""
+        key = (
+            self._validate_id(tenant_id, "tenant_id"),
+            self._validate_id(session_id, "session_id"),
+        )
+        with self._lock:
+            session = self._sessions.get(key)
+            if session is None:
+                return False
+            if session.active_leases:
+                raise SessionBusyError("cannot close a session with an active lease")
+            del self._sessions[key]
+            return True
+
+    @property
+    def session_count(self) -> int:
+        """Return the number of registered sessions after expiring idle entries."""
+        with self._lock:
+            self._expire_idle_sessions(self._clock())
+            return len(self._sessions)

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/docs/BLOG.md

@@ -85,10 +85,9 @@ suite.
 λ₂ does not predict quality (pearson 0.20). The certificate is true
 about the operator; it says nothing about the task. The claim was
 weakened, not the data massaged.
-A transformer beats the fluid at every scale I could train
-(2.6331 vs 2.7397 nats). The fluid only wins against fixed-receptive-field
-aggregators (97.3 % vs 65.6 % / 71.0 %) — and it loses to full attention,
-which is the honest summary of the entire architecture.
+Archived results record a transformer beating the fluid (2.6331 vs 2.7397
+nats) and a 97.3 % mechanism result. The historical source scripts are not
+included, so see N4 in `docs/NEGATIVE-RESULTS.md` for the reproduction caveat.
 Grafted onto a frozen model, my own diffusion tier made the model
 worse — +0.81 nats (ppl 13.3 -> 29.9) on real English. The cause is
 structural: the persistent state sits outside the autodiff graph, so the

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/docs/CHANGELOG.md

@@ -6,6 +6,26 @@ uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-11-03
+
+### Added
+
+- Include the optional deployment session-isolation companion in the
+  published wheel and source distribution.
+
+### Changed
+
+- Add clean-install CI verification for the deployment package.
+
+## [2.1.0] - 2026-11-03
+
+### Added
+
+- Added the optional PyTorch Qwen2 adapter, E15 scale-model experiment,
+  archived measurements, and a runnable app-kit example.
+- Categorized the new project-process, app-kit, experiment, and result files
+  into `docs/`, `examples/`, `experiments/`, and `results/`.
+
 ### Changed
 
 - Improved the Markdown documentation structure, added a documentation

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/docs/COMPARISON.md

@@ -205,7 +205,7 @@ what makes per-user persistent memory economically possible at all.
 | ---|---|---|---|---|---|---|---|---|---|
 | exact needle at a position|✅|✅ recent|✅|❌|❌|❌|❌|✅|✅ pinned / L3|
 | exact  specific  fact|✅|✅ recent|✅|❌|❌|❌|❌|✅|✅ pinned (20 B)|
-| global gist / aggregate|✅|❌|✅|✅|✅|✅|❌|❌|✅ 97.3 % meas.|
+| global gist / aggregate|✅|❌|✅|✅|✅|✅|❌|❌|✅ archived 97.3 % result (`results/mechanism.json`)|
 | positional recall ( "3rd paragraph ")|✅|✅|✅|✅|❌|❌|❌|❌|❌|
 | infinite stream / never re-encode|❌|✅|❌|❌|✅|✅|n/a|✅|✅|
 | no  "lost in the middle "|❌|❌|❌|❌|~ (no positions)|~|n/a|~|✅ (no positional decay)|
@@ -266,12 +266,12 @@ the measured semantic/local-geometric policy performed better.
 KV bytes/token, KV @ctx, sessions that fit in VRAM, prefill FLOPs, crossover point
 fluid read cost 16 KB = 0.009 µs; fluid compute = 384 flops/token/layer
 our `selftest.py` → 50/50
-mechanism test: fluid 97.3 % sign acc vs local R=4 65.6 %, R=8 71.0 %
-LM A/B: transformer wins — 2.6331 vs 2.7397 final val (fewer params on our side)
+mechanism test: archived result records 97.3 % sign accuracy; original source unavailable
+LM A/B: archived result records transformer 2.6331 vs FluidLayer 2.7397; original training source unavailable
 param-matched FLOPs: 1.10× cheaper @8K → 2.54× @128K
 ⚠️ PROJECTED — needs E1/E5 to become fact
 that the 16 KB fluid carries long-range information at usable quality
-that a real LLM actually routes to the fluid (the 97.3 % was a synthetic task)
+that a real LLM actually routes to the fluid (the archived 97.3 % synthetic-task result does not establish real-model routing)
 that topology picks the right facts to freeze
 that pinned facts survive a real model's distribution shift
 Every table above is a CONDITIONAL: "IF the fluid is usable, THEN this".

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/docs/DESIGN_pinned_memory.md

@@ -45,10 +45,9 @@ This is the entire design in one move:
 FluidLayer stops being a memory. It becomes an index.
 The memory moves to a write-once register; the fluid answers where, and
 the register answers what.
-And the reason this is not a retreat: the 97.3 % mechanism result was always a
-routing result. In the mechanism test the fluid predicted the right global
-aggregate to 97.3 % sign accuracy. It was already an excellent addresser.
-We just gave it an exact value to point at.
+The archived `results/mechanism.json` records a 97.3 % global-aggregation
+result. Its original experiment source is not present, so the historical run
+cannot be independently regenerated (see N4 in `docs/NEGATIVE-RESULTS.md`).
 
 ## 1. The impossibility, stated precisely
 
@@ -89,7 +88,7 @@ keep.
          └──────────────────────────────────────────────────┘
 Slot layout (20 B, as implemented):`key uint64 | val int32 | sig uint32 | anchor uint16 | meta uint16`.
 The read path is three clean steps, each with a guarantee:
-query h  ──▶  L2 routes h → anchor a   (approx: 97.3 % measured)
+query h  ──▶  L2 routes h → anchor a   (approximate; archived score in results/mechanism.json)
               anchor a → slot id s       (exact: 1 byte)
               L1[s] = (key, token_id)    (exact: 4 bytes)
               verify key matches h's context hash   (fail-loud)
@@ -174,12 +173,12 @@ This is a testable prediction, and it is falsifiable.
 Which tokens to freeze? The longest bars = the structural landmarks =
 the tokens that carry the document's skeleton. Freeze those and you get
 exact extraction of the load-bearing facts, not random trivia.
-Why the fluid wins global aggregation (explains the 97.3 %). The
+The theory suggests why diffusion can carry global aggregation: the
 harmonic branch of `L` (its kernel) is the globally dominant H₀ mode —
-and the global mean is the longest bar. The fluid preserves the kernel
-component exactly; that is precisely why it beat local aggregators
-(65.6 % / 71.0 %) on the global-mean task and lost on position-sensitive
-tasks. The v0.1 theory report and the mechanism experiment now have one
+and the global mean is the longest bar. The archived mechanism output records
+a 97.3 % score, beating local aggregators (65.6 % / 71.0 %); its original
+source is unavailable, so the run cannot be independently regenerated. The
+v0.1 theory report and the mechanism experiment now have one
 unified explanation. That is a real, publishable narrative.
 
 ## 5. Budget: the 3-D trade-off
@@ -366,8 +365,8 @@ P4 needs one GPU for a few hours.
 
 Attention remembers by position. We remember by geometry. But geometry alone
 smears: diffusion destroys exactness by construction. So we split the
-memory. A 16 KB sheaf routes — 97.3 % accurate at picking the right
-landmark — and an append-only frozen register stores the exact token id
+memory. A 16 KB sheaf routes to an approximate landmark (the archived
+mechanism result records 97.3 % sign accuracy) — and an append-only frozen register stores the exact token id
 at 14 bytes per fact, 196,234× cheaper than a KV cache. Topology decides
 which landmarks get exact storage, using the document's own persistence
 diagram, at zero per-token cost. The model can promote a fact or recall one

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/docs/FRAMEWORK.md

@@ -3,6 +3,10 @@
 > **Historical design note:** this is not a current implementation contract.
 > For current behavior and limitations, see [the API reference](API.md) and
 > [limitations](LIMITATION.md).
+> Archived LM-comparison and mechanism-test JSON outputs are included under
+> `results/`, but their original experiment source files are unavailable.
+> Treat the numbers as historical snapshots, not independently rerunnable
+> measurements.
 
 A topological fluid architecture for sequence models: replace the
 transformer's quadratic attention with a cellular-sheaf diffusion whose
@@ -345,8 +349,8 @@ fluidlayer/
   losses.py      CE (+ tensor variant), sheaf energy, band decorrelation
   optim.py       Adam (decoupled WD, clipping, cosine schedule)
   data.py        Gutenberg corpus + char tokenizer + synthetic fallback
-selftest.py      15 numerical checks of the mathematics   -> results/selftest.json
-train.py         LM A/B + global-aggregation demo             -> results/train_results.json
+selftest.py      historical numerical checks
+train.py         historical LM A/B + global-aggregation demo (source unavailable; see archived results/)
 
 ### Run it
 

{fluidlayer-2.0.0 → fluidlayer-2.2.0}/docs/GETTING_STARTED.md

@@ -106,6 +106,23 @@ integration must handle the model's positional embeddings, attention masks,
 device placement, session boundaries, and task-specific gain calibration.
 Call `branch.reset()` when starting a new independent session.
 
+## Run the GPT-2/Qwen2 app kit
+
+The repository includes a standalone app kit that loads a local GPT-2 or
+Qwen2 checkpoint and demonstrates attachment and recall:
+
+```bash
+python -m pip install "fluidlayer[gpu]"
+hf download Qwen/Qwen2.5-0.5B --local-dir models/qwen05b
+python examples/appkit/attach_layer.py --model models/qwen05b
+```
+
+The Qwen2 forward implementation is in the published `fluidlayer` package;
+the Qwen tokenizer is provided by the optional Transformers dependency.
+Model weights are not bundled. This app kit is a research example, not a
+production serving wrapper. See [the E15 result](../results/e15_scale_model.json)
+and [reproduction guide](REPRODUCING.md#qwen2-scale-experiment-e15).
+
 ## Memory behavior and safety
 
 The attachable store is bounded. Its reported 20-byte slot cost is a logical