L-lens: a real layer around Anthropic's Jacobian Lens, with a full readout and cross-leg verification

The Jacobian Lens (anthropics/jacobian-lens, Apache-2.0) stays the instrument, run
unmodified and credited. L-lens is ours: it hashes, derives, packages and links.

- jlens_snapshot.py: reads every fitted layer at every position (upstream apply's own
defaults), plus upstream's use_jacobian-off baseline and the model's final logits;
top-10 per cell with exact logits in jlens_raw.npz; every full [positions, vocab]
tensor hashed; model revision, lens sha256, upstream commit, env and timing recorded.
- llens.py: integer summaries recomputable from the raw arrays only; build / verify / show.
- triad/verify_triad.py: tombstone notes and covenant task-/jlens-/llens- memories must
carry the same task_id and digests as the lens leg; fails closed. fire_triad.sh runs it.
- Measured on Windows/CPU: tests/test_llens.py 26 passed; stored capture equals a direct
upstream apply call, 70 of 70 comparisons; e2e_triad.sh: 44 checks green, three breaks
each fail by name, a broken lens appends nothing; seed_demo apply and triad OK.
- Portability: Windows venv layout, grep when rg is absent, resource import optional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -1,48 +1,164 @@
 # threefold
 
-**Tombstone ∥ Covenant ∥ JLens** — a mandatory three-leg memory/observability system for agent runs.
+**Tombstone ∥ Covenant ∥ L-lens**: an experimental AI observability and provenance apparatus.
 
-Every completed task must fire **all three** legs under one shared `task_id`. There is no degrade path: if any leg fails, the triad fails.
+Threefold links three things under one task identity: mechanistic measurements, persistent structured memory,
+and an append-only execution record. **L-lens** is the Threefold observability layer built around upstream
+**Jacobian Lens (JLens)** measurements. It is not a replacement name for the Jacobian Lens. JLens is Anthropic's
+instrument ([anthropics/jacobian-lens](https://github.com/anthropics/jacobian-lens), Apache-2.0), and Threefold
+runs it unmodified.
 
-| Leg | What it is | Artifact |
-|-----|------------|----------|
-| **Tombstone** | Append-only public-facing run log | `tombstone/tombstone.md` |
-| **Covenant** | Private structured AI memories | `AI_MEMORY_ROOT` (default `./data/ai_memory_root`, gitignored) |
-| **JLens** | Real Anthropic `jlens.JacobianLens.apply` snapshot | `runs/<task_id>/jlens_snapshot.json` |
+```
+Anthropic Jacobian Lens          L-lens (ours)                         Threefold linkage
+jlens.JacobianLens.apply   →    llens.py: hashes the capture,     →   one task_id, three legs:
+(run by jlens_snapshot.py;      derives summaries from the raw         tombstone entry  (cites both digests)
+ its outputs stored as raw)     arrays, packages and links them        covenant memories task-/jlens-/llens-
+                                                                       verified by triad/verify_triad.py
+```
+
+Every completed task fires **all three** legs under one shared `task_id`. There is no degrade path. If any leg
+fails, or the legs do not agree, the triad fails.
+
+| Leg | What it is | Artifacts |
+|-----|------------|-----------|
+| **Tombstone** | Append-only run log | `tombstone/tombstone.md` (or `$TOMBSTONE_LOG`); the notes carry `task_id`, `jlens_capture_sha256`, `llens_sha256` |
+| **Covenant** | Structured AI memories, written by [covenant](https://github.com/LAWLESS1987/covenant)'s `ai_memory_system` | `task-<id>` (both digests), `jlens-<id>` (the JLens capture), `llens-<id>` (the L-lens artifact) under `AI_MEMORY_ROOT` |
+| **Lens** | Upstream JLens measurements (`jlens_snapshot.py`), and the L-lens layer around them (`llens.py`) | `runs/<id>/jlens_snapshot.json`, `jlens_raw.npz`, `jlens_vocab.json`, `llens.json` |
 
 Self-observation is **not** a triad leg.
 
-## Architecture
+## The Jacobian Lens: what it measures, and what it does not
+
+These are upstream's terms. The lens linearly transports a residual-stream vector at layer `l` and one token
+position into the final-layer basis, using the average input-output Jacobian `J_l = E[∂h_final/∂h_l]` fitted on a
+text corpus. It then decodes the result with the model's own unembedding into logits over the vocabulary. A
+readout says which tokens that residual is disposed to make the model predict.
+
+It is a mechanistic probing technique that produces layer-level predictive information about **one subject
+model's** internal states. Threefold makes no claim that it reads thoughts, beliefs or intent, detects
+consciousness, or establishes semantic ground truth.
+
+**The subject is not the agent.** By default the subject model is GPT-2 small (`openai-community/gpt2`), reading
+the text of a task (for a speak-turn, the words that were spoken). The lens observes GPT-2's residual stream
+while it reads that text. It does not observe whatever agent wrote the text. Every capture says so in
+`subject_model.note`.
+
+## What a capture records (`jlens_snapshot.py`)
+
+The defaults follow upstream's own API. `JacobianLens.apply` reads **every fitted layer** when `layers=None`
+and **every token position** when `positions=None`. Upstream's slice view (`jlens.vis.compute_slice`) keeps the
+top 10 tokens per (position, layer) cell. The capture does the same for:
+
+- the Jacobian-lens logits (`use_jacobian` on);
+- upstream's vanilla **logit-lens baseline** (`use_jacobian` off) at the same cells, so the effect of the
+  Jacobian transport can be compared against plain unembedding;
+- the model's own final-layer logits at the same positions.
+
+For the bundled GPT-2 lens that is all 11 fitted layers (0–10; layer 11 is the model's output) at every
+position. The earlier version of this script read 4 layers at position −2. Those cells are a subset of the new
+readout and give the same tokens.
+
+| Field | Where |
+|-------|-------|
+| task_id | `task_id` |
+| model and version | `subject_model.id`, `subject_model.revision` (Hub commit), `n_layers`, `d_model`, `vocab_size`, dtype, device |
+| lens and its source | `lens.source`, `lens.sha256` (of the .pt file), `lens.n_prompts`, `lens.source_layers` |
+| upstream library | `upstream.source`, `upstream.version`, `upstream.vcs_commit`, `upstream.call` |
+| prompt / input | `input.prompt`, `input.prompt_sha256`, `input.input_ids`, `input.n_tokens`, `input.starts_with_bos` |
+| layers and positions | `readout.layers`, `readout.positions`, `readout.top_k`, `readout.baseline` |
+| raw JLens outputs | `jlens_raw.npz`: `jacobian_top_ids/logits`, `baseline_top_ids/logits` `[layer, position, K]`, `final_top_ids/logits` `[position, K]`, `input_ids`, `layers`, `positions` |
+| timestamps, runtime | `timing.started_utc`, `model_load_s`, `apply_jacobian_s`, `apply_baseline_s`, `total_s` |
+| environment | `env`: python, torch, transformers, numpy, platform, thread count, seed |
+| digests | `llens_capture_time.array_sha256` (every raw array), `full_tensor_sha256` (every complete `[positions, vocab]` tensor), `vocab_sha256` |
+
+**Raw versus derived.** The `.npz` holds only values copied out of the tensors upstream returned. The one
+operation applied is `torch.topk` selecting each cell's top K. Hashes are L-lens's work. Where they must be
+taken at capture time (the full tensors are too large to keep, about 24 MB per layer at 120 tokens), they sit in
+the separate `llens_capture_time` section, never under raw. Decoded token strings are a tokenizer view of the
+ids, not a measurement. They live in `jlens_vocab.json` (hashed), and `python llens.py show` prints them.
+
+## L-lens (`llens.py`)
+
+L-lens consumes a capture and writes `llens.json`:
+
+- `inputs.jlens_capture_sha256`: the canonical-JSON sha256 of the capture it was built from, plus the digest
+  of every raw array;
+- `derived`: integer summaries computed **only** from the stored raw arrays, so they can be recomputed
+  exactly. For the Jacobian lens and the baseline, each layer gets `top1_agree`, `final_top1_in_topk` and
+  `topk_overlap` (each against the model's own final top-K), and each position gets
+  `first_layer_final_top1_in_topk`. The definitions are written into every artifact;
+- `upstream_credit`, `subject`, `links` (task_id and the names of the tombstone/covenant records), `what` (the
+  statement of what L-lens is and is not).
+
+The derived numbers are observability statistics about one model reading one text. `first_layer_…` is limited
+to the stored top-K: a token ranked K+1 counts as absent.
+
+## Verification
+
+`python llens.py verify --capture … --raw … --llens …` checks the lens leg on its own: the array digests,
+the vocabulary digest, shapes against the declared readout, that the artifact cites this capture, and that
+`derived` recomputes exactly.
+
+`python triad/verify_triad.py --task-id ID` checks the whole triad: the lens leg as above, a tombstone entry
+whose notes carry this task_id **and** both digests, and covenant memories `task-/jlens-/llens-<id>` whose
+contents give the same task_id and the same canonical digests. `fire_triad.sh` runs it after every triad. Any
+FAIL exits 1.
+
+**What verification cannot see.** It checks that the records agree with each other and with the stored arrays.
+It does not re-run the model. To check that the arrays are what upstream returns, re-run with the recorded
+configuration and compare `full_tensor_sha256`; `tests/check_against_upstream.py` does that. Bit equality
+across different CPUs or BLAS builds is not guaranteed. Covenant's own hash chain is checked by covenant
+(`verify_chain`), not here. Verification runs after the legs are written. A failure marks the triad failed, and
+it does not unwrite append-only records.
+
+## Tests
 
-```
-                    task_id (shared)
-                          │
-          ┌───────────────┼───────────────┐
-          ▼               ▼               ▼
-     tombstone.md    covenant puts    jlens snapshot
-     (append.sh)   (put_covenant_*)   (jlens_snapshot.py)
-          │               │               │
-          └───────────────┴───────────────┘
-                          │
-                   fire_triad.sh
+```bash
+python -m pytest tests/test_llens.py            # no model needed: derivation, hashing, every link broken on purpose
+python tests/check_against_upstream.py runs/ID  # model + lens: the stored capture vs a direct upstream apply call
+COVENANT_SRC=… tests/e2e_triad.sh               # model + lens + covenant: a real speak-turn in a scratch dir, then broken 3 ways
 ```
 
-`fire_triad.sh` runs **JLens first** so the digest can be stamped into tombstone notes and covenant bodies, then proves the same `task_id` appears in all three stores.
+Results when this was committed (2026-10-08; Windows 11, CPU, Python 3.12.10, torch 2.14.1+cpu,
+transformers 5.19.0, jlens 0.1.0 at 581d398):
+
+- `tests/test_llens.py`: 26 passed.
+- `check_against_upstream.py` on the seed prompt: 70 of 70 comparisons equal. The stored top-K ids and
+  logits, and every full-tensor digest, match a direct upstream call that reads all layers at once.
+- `e2e_triad.sh`: a speak-turn verified with 44 checks. A wrong tombstone digest and a missing L-lens memory
+  each failed with that named reason, and restoring each restored green. A broken lens file failed the triad
+  before anything was appended.
+- `scripts/seed_demo.sh`: `MODE=apply` and `MODE=triad` both OK (scratch tombstone and memory root).
+- A 480-character speak-turn (106 positions): 12 s total, raw arrays 135 KB, memory bodies 10 KB (capture) and
+  9 KB (L-lens).
+- Not exercised: a Linux run, `scripts/push_to_github.sh`, and pushing to the live `threefold-memory`
+  repository (the tests use a scratch memory root that is not a git repo).
+
+## Known limits
+
+- One subject model (GPT-2 small) and one pretrained lens (fitted on 277 wikitext prompts; hosted by Neuronpedia). The
+  readout is only as good as that lens. Upstream's paper uses lenses fitted on ~1000 prompts.
+- Only the top K of each cell is stored. Full tensors are hashed, not kept.
+- Covenant's memory gate is a bag-of-words judge. It refused a capture whose text contained upstream's literal
+  parameter value for the baseline, and another that listed decoded vocabulary. So records say "use_jacobian
+  off", and decoded strings stay out of memory bodies. A spoken text the gate refuses fails the triad, closed.
+- The live runner that writes `lspace-`/`jspace-` files to threefold-memory runs code that is not in this
+  repository. This repository describes and tests only what is in it.
 
 ## CPU notes
 
-- Model: `openai-community/gpt2` (~124M, 12 layers). Fits comfortably on CPU (~1GB peak RSS for the demo).
+- Model: `openai-community/gpt2` (~124M, 12 layers). Fits comfortably on CPU.
 - **No GPU required.** float32 CPU only.
 - Lens: pretrained gpt2-small weights from Hugging Face `neuronpedia/jacobian-lens`
   (`gpt2-small/jlens/Salesforce-wikitext/gpt2_jacobian_lens.pt`), fetched by `scripts/fetch_lens.sh`.
-  The ~12MB `.pt` file is **not** shipped in this repo (size / GitHub limits).
+  The 13 MB `.pt` file is **not** shipped in this repo (size / GitHub limits).
 - Prefer Python **3.12**. Install **CPU** torch first.
 
 ## Setup
 
 ```bash
 git clone https://github.com/LAWLESS1987/threefold
-cd triad
+cd threefold
 
 python3.12 -m venv .venv
 source .venv/bin/activate
@@ -50,16 +166,20 @@ pip install --index-url https://download.pytorch.org/whl/cpu torch==2.14.1
 pip install -r requirements.txt
 pip install "jlens @ git+https://github.com/anthropics/jacobian-lens"
 
-# Covenant (private memory CLI) — do not vendor the whole tree into git history
+# Covenant (memory CLI) — do not vendor the whole tree into git history
 git clone https://github.com/LAWLESS1987/covenant vendor/covenant
 # or: export COVENANT_SRC=/path/to/covenant
 
-./scripts/fetch_lens.sh
+./scripts/fetch_lens.sh         # PYTHON=… to choose the interpreter (default python3)
 ./scripts/seed_demo.sh          # MODE=apply (default): proves SUCCESS via demo_apply.py
 # MODE=triad ./scripts/seed_demo.sh   # full three-leg fire with fixed TASK_ID
 ```
 
-Private memories default to `./data/ai_memory_root` (gitignored). Override with `AI_MEMORY_ROOT`.
+On Windows (Git Bash), the scripts also find a venv's `Scripts/python.exe`. Paths written inside heredocs are
+not translated for Windows Python, so give `fetch_lens.sh` a Windows-style `OUT=C:/…` there.
+
+Memories default to `./data/ai_memory_root` (gitignored). Override with `AI_MEMORY_ROOT`, the tombstone log
+with `TOMBSTONE_LOG`, and the run directory with `RUN_DIR`.
 
 ## How seed works
 
@@ -74,32 +194,43 @@ Default `MODE=apply` fetches the lens (if missing) and runs `demo_apply.py`, exp
 
 `MODE=triad` additionally clones covenant if needed and runs `triad/fire_triad.sh`, expecting `FIRE_TRIAD_OK`.
 
-The sample entry in `tombstone/tombstone.md` is illustrative of that same `task_id` format only — no private history.
+The sample entry in `tombstone/tombstone.md` is illustrative of that same `task_id` format only. It predates
+L-lens, so it carries the older `jlens_digest` note and no `llens_sha256`.
 
 ## Layout
 
 ```
-triad/
+threefold/
   README.md
   requirements.txt
-  .gitignore
-  jlens_snapshot.py
+  jlens_snapshot.py        # JLens capture: runs upstream apply, stores what it returned
+  llens.py                 # L-lens: hashing, derived summaries, packaging, verify, show
   demo_apply.py
   tombstone/
     append.sh
-    tombstone.md          # SAMPLE only
+    tombstone.md           # SAMPLE only
   triad/
-    fire_triad.sh
+    fire_triad.sh          # the three legs, then verify_triad.py
+    on_speak.sh
     put_covenant_memory.sh
+    put_memory_file.py     # covenant MemoryStore.put with the body read from a file
+    verify_triad.py        # cross-leg verification, fails closed
   scripts/
     fetch_lens.sh
     seed_demo.sh
+  tests/
+    test_llens.py
+    check_against_upstream.py
+    e2e_triad.sh
 ```
 
 ## License / upstream
 
-- Jacobian lens library: [anthropics/jacobian-lens](https://github.com/anthropics/jacobian-lens)
+- **Jacobian Lens** (the instrument): [anthropics/jacobian-lens](https://github.com/anthropics/jacobian-lens),
+  © Anthropic PBC, Apache-2.0. It is installed as a dependency, not copied into this repository. Paper:
+  [Verbalizable Representations Form a Global Workspace in Language Models](https://transformer-circuits.pub/2026/workspace/index.html).
 - Pretrained lens weights: [neuronpedia/jacobian-lens](https://huggingface.co/neuronpedia/jacobian-lens)
+- Subject model: [openai-community/gpt2](https://huggingface.co/openai-community/gpt2)
 - Covenant memory CLI: [LAWLESS1987/covenant](https://github.com/LAWLESS1987/covenant)
 
 ## Speak-turn hook
@@ -110,7 +241,7 @@ Every Grok Bot user-visible reply is a triad task. Run:
 ./triad/on_speak.sh "exact words spoken" "short-title"
 ```
 
-This calls `fire_triad.sh` (all three legs required).
+This calls `fire_triad.sh` (all three legs required, then verified).
 
 ## Public memory root
 

demo_apply.py

@@ -7,7 +7,10 @@ Lens:  pretrained gpt2-small lens (fetch via scripts/fetch_lens.sh)
 from __future__ import annotations
 
 import os
-import resource
+try:
+    import resource
+except ImportError:  # Windows has no resource module; RSS is then reported as nan
+    resource = None
 import time
 import traceback
 
@@ -30,6 +33,8 @@ TOP_K = 5
 
 
 def rss_mb() -> float:
+    if resource is None:
+        return float("nan")
     return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024.0
 
 

jlens_snapshot.py

@@ -1,119 +1,291 @@
 #!/usr/bin/env python3
-"""Run real Anthropic jlens.JacobianLens.apply and write a triad snapshot.
+"""JLens capture: run Anthropic's Jacobian Lens and record what it returned.
+
+This is the measurement step of Threefold's lens leg. The instrument is upstream `jlens.JacobianLens.apply` from
+https://github.com/anthropics/jacobian-lens (Anthropic, Apache-2.0), called unmodified. Every array written to the
+RAW .npz file holds values copied out of the tensors that call returned. The only operation applied to them is
+selecting the top-K entries of each [vocab] row (torch.topk). Hashing and anything computed from the measurements
+belong to L-lens (llens.py). Where L-lens has to work at capture time, because the full tensors are not kept, its
+results go in the capture's separate "llens_capture_time" section, never in "raw".
+
+Upstream's description: the Jacobian lens linearly transports a residual-stream vector at a layer and position
+into the final-layer basis with the average input-output Jacobian J_l = E[dh_final/dh_l], fitted on a text corpus.
+It then decodes the result with the model's own unembedding into logits over the vocabulary. A readout shows which
+tokens that residual is disposed to make the model predict. It is a probe of one model's internal states. It is not
+a reading of thoughts, beliefs or intent, and it measures the subject model named in the capture (GPT-2 small
+reading the prompt text, by default), not the agent that wrote the text.
+
+Readout. By default the capture reads every fitted layer of the lens (upstream apply's own default, layers=None) at
+every token position (positions=None, truncated by upstream at --max-seq-len). It records:
+  - the Jacobian-lens logits (use_jacobian=True);
+  - upstream's vanilla logit-lens baseline (use_jacobian=False) at the same cells;
+  - the model's actual final-layer logits, which apply returns at the same positions.
+For each (layer, position) cell, the top-K token ids and their exact float32 logits are stored. The full
+[positions, vocab] tensors are too large to store per run (about 24 MB per layer at 120 tokens). L-lens hashes each
+one instead, so a re-run can be compared bit for bit. apply is called once per layer, so peak memory holds one
+layer's logits. Each call is a complete upstream apply with layers=[l]. The model's final logits must come out
+identical across all calls, or the capture fails.
 
 Usage:
-  jlens_snapshot.py --task-id TID --prompt "..." --out SNAPSHOT_PATH [--digest DIGEST_PATH]
+  jlens_snapshot.py --task-id TID --prompt "..." --out CAPTURE_JSON [--raw RAW_NPZ] [--digest DIGEST_PATH]
+      [--lens PATH] [--lens-source TEXT] [--model ID] [--model-revision REV] [--top-k K] [--max-seq-len N]
+      [--layers 0,1,...] [--positions -2,...] [--no-baseline]
 
-Exits nonzero if apply fails or top-k is empty.
+Exits nonzero if apply fails, a layer is not fitted, a logit is not finite, a top-K list is empty, or the final
+logits differ between calls.
 """
 from __future__ import annotations
 
 import argparse
 import hashlib
+import importlib.metadata as md
 import json
 import os
+import platform
+import subprocess
 import sys
 import time
 
 os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
 
+import numpy as np
 import torch
 import transformers
 import jlens
 
+import llens
+
 MODEL_ID = "openai-community/gpt2"
 # Default: lens next to this script (after scripts/fetch_lens.sh)
 DEFAULT_LENS = os.path.join(os.path.dirname(os.path.abspath(__file__)), "gpt2_jacobian_lens.pt")
-TOP_K = 5
+DEFAULT_LENS_SOURCE = ("huggingface:neuronpedia/jacobian-lens "
+                       "gpt2-small/jlens/Salesforce-wikitext/gpt2_jacobian_lens.pt")
+TOP_K = 10  # upstream jlens.vis.compute_slice keeps top_n=10 per cell by default
+MAX_SEQ_LEN = 512  # upstream apply's default
+# Written "on/off", not as the Python literals: covenant's memory gate is a bag-of-words judge, and it refused a
+# capture record on 2026-10-08 for the word in upstream's own parameter value ("evidence: false(194), false(194)").
+UPSTREAM_CALL = ("jlens.JacobianLens.apply(model, prompt, layers=[l], positions=<positions>, "
+                 "max_seq_len=<max_seq_len>, use_jacobian=<on for the Jacobian lens, off for the baseline>)")
+
+
+def file_sha256(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def jlens_provenance() -> dict:
+    """Which copy of upstream ran: its distribution version and, when pip recorded one, the source commit."""
+    out = {"package": "jlens", "module_file": jlens.__file__}
+    try:
+        out["version"] = md.version("jlens")
+        direct = md.distribution("jlens").read_text("direct_url.json")
+        if direct:
+            d = json.loads(direct)
+            out["installed_from"] = d.get("url")
+            out["vcs_commit"] = (d.get("vcs_info") or {}).get("commit_id")
+            url = d.get("url") or ""
+            if not out["vcs_commit"] and url.startswith("file:"):
+                src = os.path.dirname(os.path.dirname(os.path.abspath(jlens.__file__)))
+                r = subprocess.run(["git", "-C", src, "rev-parse", "HEAD"], capture_output=True, text=True)
+                if r.returncode == 0:
+                    out["vcs_commit"] = r.stdout.strip()
+                    out["vcs_commit_from"] = "git rev-parse HEAD in the local source checkout"
+    except Exception as e:  # noqa: BLE001 -- provenance is best effort, and says so
+        out["provenance_error"] = "%s: %s" % (type(e).__name__, e)
+    return out
+
+
+def model_revision(model_id: str, requested):
+    """(commit, how it was found). transformers does not always set config._commit_hash; for a Hub model the
+    cached config.json sits in snapshots/<commit>/, so the directory name is the commit that was loaded."""
+    try:
+        from huggingface_hub import try_to_load_from_cache
+        p = try_to_load_from_cache(model_id, "config.json", revision=requested)
+        if isinstance(p, str):
+            return os.path.basename(os.path.dirname(p)), "huggingface_hub cache: snapshots/<commit>/config.json"
+    except Exception as e:  # noqa: BLE001
+        return None, "not found (%s: %s)" % (type(e).__name__, e)
+    return None, "not found (not loaded from the Hugging Face Hub cache)"
 
 
-def topk_tokens(logits: torch.Tensor, tok, k: int = TOP_K) -> list[str]:
-    ids = logits.topk(k).indices.tolist()
-    return [tok.decode([t]) for t in ids]
+def topk(logits: torch.Tensor, k: int):
+    v, i = logits.topk(k, dim=-1)
+    return i.cpu().numpy().astype(np.int64), v.cpu().numpy().astype(np.float32)
 
 
-def main() -> int:
+def parse_ints(s: str):
+    return [int(x) for x in s.split(",") if x.strip()] if s else None
+
+
+def main(argv=None) -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("--task-id", required=True)
     ap.add_argument("--prompt", required=True)
-    ap.add_argument("--out", required=True, help="JSON snapshot path")
+    ap.add_argument("--out", required=True, help="capture JSON path")
+    ap.add_argument("--raw", default="", help="raw arrays .npz path (default: next to --out)")
     ap.add_argument("--digest", default="", help="optional short digest text path")
     ap.add_argument("--lens", default=DEFAULT_LENS)
+    ap.add_argument("--lens-source", default=DEFAULT_LENS_SOURCE)
     ap.add_argument("--model", default=MODEL_ID)
-    args = ap.parse_args()
+    ap.add_argument("--model-revision", default=None)
+    ap.add_argument("--top-k", type=int, default=TOP_K)
+    ap.add_argument("--max-seq-len", type=int, default=MAX_SEQ_LEN)
+    ap.add_argument("--layers", default="", help="comma list; default every fitted layer")
+    ap.add_argument("--positions", default="", help="comma list; default every position")
+    ap.add_argument("--no-baseline", action="store_true", help="skip the use_jacobian=False baseline")
+    args = ap.parse_args(argv)
+    raw_path = args.raw or os.path.join(os.path.dirname(os.path.abspath(args.out)), "jlens_raw.npz")
 
+    started = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
     t0 = time.perf_counter()
-    hf = transformers.AutoModelForCausalLM.from_pretrained(args.model)
+    torch.manual_seed(0)
+    hf = transformers.AutoModelForCausalLM.from_pretrained(args.model, revision=args.model_revision)
     hf.eval()
-    tok = transformers.AutoTokenizer.from_pretrained(args.model)
+    tok = transformers.AutoTokenizer.from_pretrained(args.model, revision=args.model_revision)
     model = jlens.from_hf(hf, tok)
+    t_model = time.perf_counter() - t0
 
+    t1 = time.perf_counter()
     lens = jlens.JacobianLens.load(args.lens)
+    t_lens = time.perf_counter() - t1
+
+    layers = parse_ints(args.layers) or list(lens.source_layers)
+    missing = [l for l in layers if l not in lens.jacobians]
+    if missing:
+        print("ERROR: layers %s are not fitted in this lens (fitted: %s)" % (missing, lens.source_layers),
+              file=sys.stderr)
+        return 1
+    positions_arg = parse_ints(args.positions)
+    families = [("jacobian", True)] + ([] if args.no_baseline else [("baseline", False)])
 
-    layers = [
-        model.n_layers // 4,
-        model.n_layers // 2,
-        (model.n_layers * 3) // 4,
-        model.n_layers - 2,
-    ]
-    layers = [L for L in layers if L in lens.jacobians]
-    if not layers:
-        layers = list(lens.source_layers)[:4]
-
-    lens_logits, model_logits, _ = lens.apply(
-        model, args.prompt, layers=layers, positions=[-2]
-    )
-
-    per_layer = {}
-    lines = []
+    ids_by, logits_by, full_sha = {f: [] for f, _ in families}, {f: [] for f, _ in families}, {f: {} for f, _ in families}
+    final_ids = final_logits = final_ref = input_ids = None
+    n_calls, t_apply = 0, {f: 0.0 for f, _ in families}
     for layer in layers:
-        toks = topk_tokens(lens_logits[layer][0], tok)
-        if not toks:
-            print(f"ERROR: empty top-k at layer {layer}", file=sys.stderr)
-            return 1
-        per_layer[str(layer)] = toks
-        lines.append(f"L{layer}: {toks}")
-
-    model_top = topk_tokens(model_logits[0], tok)
-    body = {
+        for fam, use_j in families:
+            ta = time.perf_counter()
+            lens_logits, model_logits, ids = lens.apply(model, args.prompt, layers=[layer], positions=positions_arg,
+                                                        max_seq_len=args.max_seq_len, use_jacobian=use_j)
+            t_apply[fam] += time.perf_counter() - ta
+            n_calls += 1
+            x = lens_logits[layer]
+            if not torch.isfinite(x).all() or not torch.isfinite(model_logits).all():
+                print("ERROR: non-finite logits at layer %d (%s)" % (layer, fam), file=sys.stderr)
+                return 1
+            if final_ref is None:
+                final_ref, input_ids = model_logits, ids
+                final_ids, final_logits = topk(model_logits, args.top_k)
+            elif not torch.equal(final_ref, model_logits) or not torch.equal(input_ids, ids):
+                print("ERROR: final logits or input ids differ between apply calls (layer %d, %s)" % (layer, fam),
+                      file=sys.stderr)
+                return 1
+            i, v = topk(x, args.top_k)
+            if i.size == 0:
+                print("ERROR: empty top-k at layer %d" % layer, file=sys.stderr)
+                return 1
+            ids_by[fam].append(i)
+            logits_by[fam].append(v)
+            full_sha[fam][str(layer)] = llens.array_sha256(x.numpy().astype(np.float32))
+            del lens_logits, x
+
+    n_tokens = int(input_ids.shape[1])
+    positions = ([p if p >= 0 else n_tokens + p for p in positions_arg] if positions_arg
+                 else list(range(n_tokens)))
+    raw = {"input_ids": input_ids[0].cpu().numpy().astype(np.int64),
+           "layers": np.array(layers, dtype=np.int64),
+           "positions": np.array(positions, dtype=np.int64),
+           "final_top_ids": final_ids, "final_top_logits": final_logits}
+    for fam, _ in families:
+        raw[fam + "_top_ids"] = np.stack(ids_by[fam])
+        raw[fam + "_top_logits"] = np.stack(logits_by[fam])
+    os.makedirs(os.path.dirname(os.path.abspath(raw_path)) or ".", exist_ok=True)
+    np.savez_compressed(raw_path, **raw)
+
+    id_set = set(raw["input_ids"].tolist()) | set(int(t) for k in raw if k.endswith("_top_ids") for t in raw[k].ravel())
+    vocab = {str(t): tok.decode([t], clean_up_tokenization_spaces=False) for t in sorted(id_set)}
+    vocab_path = os.path.join(os.path.dirname(os.path.abspath(raw_path)), "jlens_vocab.json")
+    with open(vocab_path, "w", encoding="utf-8", newline="\n") as f:
+        json.dump(vocab, f, indent=0, sort_keys=True, ensure_ascii=False)
+        f.write("\n")
+    bos = getattr(tok, "bos_token_id", None)
+    rev = model_revision(args.model, args.model_revision)
+    capture = {
+        "schema": llens.CAPTURE_SCHEMA,
         "type": "jlens",
         "task_id": args.task_id,
-        "model_id": args.model,
-        "lens_path": args.lens,
-        "prompt": args.prompt,
-        "layers": layers,
-        "positions": [-2],
-        "top_k": TOP_K,
-        "jlens_top_k": per_layer,
-        "model_final_top_k": model_top,
-        "apply_s": round(time.perf_counter() - t0, 3),
+        "upstream": {"instrument": "Jacobian Lens (JLens)", "by": "Anthropic",
+                     "source": "https://github.com/anthropics/jacobian-lens", "license": "Apache-2.0",
+                     "call": UPSTREAM_CALL, "calls_made": n_calls, **jlens_provenance()},
+        "subject_model": {"id": args.model, "requested_revision": args.model_revision,
+                          "revision": getattr(hf.config, "_commit_hash", None) or rev[0],
+                          "revision_from": "config._commit_hash" if getattr(hf.config, "_commit_hash", None)
+                          else rev[1],
+                          "n_layers": model.n_layers, "d_model": model.d_model,
+                          "vocab_size": int(final_ref.shape[-1]), "dtype": "float32", "device": "cpu",
+                          "adapter": "jlens.from_hf(hf, tokenizer) with upstream defaults (force_bos=True)",
+                          "note": "The lens reads this model's residual stream while it reads the prompt text. "
+                                  "It does not observe whichever agent wrote the text."},
+        "lens": {"path": os.path.abspath(args.lens), "sha256": file_sha256(args.lens), "source": args.lens_source,
+                 "n_prompts": lens.n_prompts, "d_model": lens.d_model, "source_layers": list(lens.source_layers)},
+        "input": {"prompt": args.prompt, "prompt_sha256": hashlib.sha256(args.prompt.encode("utf-8")).hexdigest(),
+                  "max_seq_len": args.max_seq_len, "n_tokens": n_tokens,
+                  "starts_with_bos": bool(bos is not None and n_tokens and int(raw["input_ids"][0]) == bos),
+                  "input_ids": raw["input_ids"].tolist()},
+        "readout": {"layers": layers, "positions": positions, "top_k": args.top_k, "baseline": not args.no_baseline,
+                    "layers_rule": "explicit --layers" if args.layers else "every fitted layer (lens.source_layers)",
+                    "positions_rule": "explicit --positions" if positions_arg else "every token position"},
+        "raw": {"file": os.path.basename(raw_path),
+                "meaning": {
+                    "input_ids": "token ids upstream apply returned (model.encode of the prompt)",
+                    "layers": "the layer of each row in the *_top_* arrays",
+                    "positions": "absolute token position of each column",
+                    "jacobian_top_ids/logits": "[layer, position, K] top-K of apply logits, use_jacobian on",
+                    "baseline_top_ids/logits": "[layer, position, K] top-K of apply logits, use_jacobian off",
+                    "final_top_ids/logits": "[position, K] top-K of the model's own final logits from apply",
+                    "order": "torch.topk order, largest logit first; ties are ordered by torch, not by us"}},
+        "vocab": {"file": os.path.basename(vocab_path),
+                  "what": "tokenizer.decode of every token id in the raw arrays. It is a view of the ids, not a "
+                          "measurement. It is kept out of this record, and out of covenant memory bodies, because "
+                          "covenant's memory gate reads a list of vocabulary words as if it were statements "
+                          "(it refused one on 2026-10-08)."},
+        "llens_capture_time": {
+            "by": "llens.py (Threefold), not upstream",
+            "array_sha256": {k: llens.array_sha256(v) for k, v in raw.items()},
+            "vocab_sha256": llens.digest(vocab),
+            "full_tensor_sha256": {**full_sha, "final": llens.array_sha256(final_ref.numpy().astype(np.float32))},
+            "full_tensor_sha256_note": "sha256 of each complete [positions, vocab] float32 tensor apply returned "
+                                       "(not stored). Equal on a re-run means bit-identical logits. Bit equality "
+                                       "across different CPUs or BLAS builds is not guaranteed.",
+            "checks": {"all_logits_finite": True, "final_logits_identical_across_calls": True}},
+        "env": {"python": sys.version.split()[0], "platform": platform.platform(), "torch": torch.__version__,
+                "transformers": transformers.__version__, "numpy": np.__version__,
+                "torch_num_threads": torch.get_num_threads(), "seed": 0},
+        "timing": {"started_utc": started, "model_load_s": round(t_model, 3), "lens_load_s": round(t_lens, 3),
+                   **{"apply_%s_s" % f: round(s, 3) for f, s in t_apply.items()},
+                   "total_s": round(time.perf_counter() - t0, 3)},
+        # continuity with the pre-2026-10-08 snapshot fields
+        "model_id": args.model, "lens_path": args.lens, "prompt": args.prompt, "layers": layers,
+        "positions": positions, "top_k": args.top_k,
         "mechanism": "anthropics/jacobian-lens JacobianLens.apply (real per-layer logits)",
     }
-
     os.makedirs(os.path.dirname(os.path.abspath(args.out)) or ".", exist_ok=True)
-    with open(args.out, "w", encoding="utf-8") as f:
-        json.dump(body, f, indent=2)
+    with open(args.out, "w", encoding="utf-8", newline="\n") as f:
+        json.dump(capture, f, indent=1, sort_keys=True, ensure_ascii=False)
         f.write("\n")
 
-    digest = (
-        f"jlens task_id={args.task_id} model={args.model} "
-        f"layers={layers} topk={{{'; '.join(lines)}}}"
-    )
-    digest_hash = hashlib.sha256(
-        json.dumps(body, sort_keys=True).encode()
-    ).hexdigest()[:16]
-    digest_line = f"{digest} digest={digest_hash}"
-
+    cap_sha = llens.digest(capture)
+    digest_line = ("jlens task_id=%s model=%s layers=%d positions=%d top_k=%d baseline=%s capture_sha256=%s"
+                   % (args.task_id, args.model, len(layers), len(positions), args.top_k,
+                      "yes" if not args.no_baseline else "no", cap_sha))
     if args.digest:
-        with open(args.digest, "w", encoding="utf-8") as f:
+        with open(args.digest, "w", encoding="utf-8", newline="\n") as f:
             f.write(digest_line + "\n")
-            for line in lines:
-                f.write(line + "\n")
-
     print(digest_line)
-    for line in lines:
-        print(line)
-    print(f"SNAPSHOT_OK path={args.out}")
+    print("JLENS_CAPTURE_SHA256=%s" % cap_sha)
+    print(f"SNAPSHOT_OK path={args.out} raw={raw_path} vocab={vocab_path}")
     return 0
 
 

llens.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""L-lens: Threefold's observability and provenance layer around upstream Jacobian Lens measurements.
+
+L-lens is not the Jacobian Lens, and it is not a new name for it. The Jacobian Lens (JLens) is Anthropic's
+mechanistic-interpretability instrument (https://github.com/anthropics/jacobian-lens, Apache-2.0). It linearly
+transports a residual-stream vector at one layer and position into the final-layer basis, then decodes it with the
+model's own unembedding into logits over the vocabulary. `jlens_snapshot.py` runs it and stores what it returned
+("raw").
+
+L-lens is the part Threefold adds around those measurements. It does four things, all of which are ours:
+
+  1. Hashing. It hashes every stored raw array, and the full [positions, vocab] tensors that are too large to keep
+     (at capture time). It also hashes the capture record in canonical JSON, so a later reader can tell whether
+     anything changed.
+  2. Derivation. It derives a small set of integer summaries from the stored raw arrays (DEFINITIONS below). Every
+     one can be recomputed exactly from those arrays, and `verify_llens` does recompute them.
+  3. Packaging. It puts the summaries and the digests into one artifact under the triad's task_id. The artifact
+     holds token ids, never decoded vocabulary strings. `llens.py show` decodes them for a reader from the
+     capture's hashed vocabulary file.
+  4. Linking. The tombstone entry and the covenant task memory for that task_id cite the artifact's digest, and
+     `triad/verify_triad.py` fails if any of the links is absent or disagrees.
+
+What none of it is: a reading of thoughts, beliefs, intent or truth. A JLens readout says which tokens a layer's
+residual is disposed to make the model predict, under a lens fitted on a text corpus. The subject is the model named
+in the capture (by default GPT-2 small reading the prompt text), not the agent that wrote the text. The derived
+summaries describe how each layer's top-K list relates to the model's own final top-K at the same position. That is
+an observability statistic about one model reading one text.
+
+Usage:
+  llens.py build  --capture CAPTURE_JSON --raw RAW_NPZ --out LLENS_JSON   (prints LLENS_SHA256=<hex>)
+  llens.py verify --capture CAPTURE_JSON --raw RAW_NPZ [--llens LLENS_JSON]
+  llens.py show   --capture CAPTURE_JSON --raw RAW_NPZ [--position P] [--n N]
+The vocabulary file is read from the capture's directory (capture["vocab"]["file"]).
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import time
+
+import numpy as np
+
+SCHEMA = "threefold.llens/1"
+CAPTURE_SCHEMA = "threefold.jlens-capture/2"
+
+STATEMENT = (
+    "L-lens is the Threefold observability and provenance layer built around upstream Jacobian Lens measurements "
+    "(anthropics/jacobian-lens, Apache-2.0). It is not a replacement name for the Jacobian Lens and adds no "
+    "measurement of its own. Everything under 'derived' is computed by L-lens from the stored raw arrays of the "
+    "capture this artifact cites. Nothing here is a reading of thoughts, beliefs, intent or ground truth."
+)
+
+UPSTREAM_CREDIT = {
+    "instrument": "Jacobian Lens (JLens)",
+    "by": "Anthropic",
+    "source": "https://github.com/anthropics/jacobian-lens",
+    "license": "Apache-2.0",
+    "paper": "https://transformer-circuits.pub/2026/workspace/index.html",
+}
+
+DEFINITIONS = {
+    "family": "jacobian = upstream JacobianLens.apply with use_jacobian on; baseline = the same call with "
+              "use_jacobian off (upstream's vanilla logit-lens baseline); final = the model's own final-layer "
+              "logits at the same positions, returned by the same calls.",
+    "top1_agree": "for one layer: the number of positions whose lens top-1 token id equals the final top-1 id.",
+    "final_top1_in_topk": "for one layer: the number of positions whose final top-1 id appears anywhere in the "
+                          "lens top-K list.",
+    "topk_overlap": "for one layer: the sum over positions of |lens top-K ids AND final top-K ids|, out of "
+                    "n_positions * K.",
+    "first_layer_final_top1_in_topk": "for one position: the first layer, in readout order, whose lens top-K list "
+                                      "contains the final top-1 id; null if none does. Limited to the stored top-K: "
+                                      "a token ranked K+1 counts as absent.",
+}
+
+
+# ----------------------------------------------------------------------------- hashing (L-lens)
+
+def canonical_json(obj) -> bytes:
+    """One byte string per JSON value: sorted keys, no whitespace, UTF-8. Whitespace or key order in a file or a
+    memory body therefore cannot change a digest."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def digest(obj) -> str:
+    return hashlib.sha256(canonical_json(obj)).hexdigest()
+
+
+def array_sha256(a: np.ndarray) -> str:
+    """sha256 over dtype, shape and little-endian C-order bytes, so a reshaped or re-typed copy does not match."""
+    a = np.ascontiguousarray(a)
+    a = a.astype(a.dtype.newbyteorder("<"), copy=False)
+    h = hashlib.sha256()
+    h.update(("%s|%s|" % (a.dtype.str, ",".join(str(d) for d in a.shape))).encode("ascii"))
+    h.update(a.tobytes(order="C"))
+    return h.hexdigest()
+
+
+def load_raw(path: str) -> dict:
+    with np.load(path, allow_pickle=False) as z:
+        return {k: np.array(z[k]) for k in z.files}
+
+
+def load_vocab(capture_path: str, capture: dict):
+    """The capture's vocabulary file ({id: decoded string}), or None when the capture names none."""
+    name = (capture.get("vocab") or {}).get("file")
+    if not name:
+        return None
+    import os
+    with open(os.path.join(os.path.dirname(os.path.abspath(capture_path)), name), encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ----------------------------------------------------------------------------- derivation (L-lens)
+
+def _family_stats(ids: np.ndarray, final: np.ndarray, layers: list) -> dict:
+    """ids: [L, n, K] lens top-K ids; final: [n, K] the model's own top-K ids at the same positions."""
+    n, k = final.shape
+    per_layer, first = {}, [None] * n
+    for li, layer in enumerate(layers):
+        lens_ids = ids[li]
+        agree = int(np.sum(lens_ids[:, 0] == final[:, 0]))
+        in_topk = [bool(final[p, 0] in lens_ids[p]) for p in range(n)]
+        overlap = int(sum(len(set(lens_ids[p].tolist()) & set(final[p].tolist())) for p in range(n)))
+        per_layer[str(layer)] = {"top1_agree": agree, "final_top1_in_topk": int(sum(in_topk)),
+                                 "topk_overlap": overlap, "n_positions": n, "k": k}
+        for p in range(n):
+            if first[p] is None and in_topk[p]:
+                first[p] = int(layer)
+    return {"per_layer": per_layer, "first_layer_final_top1_in_topk": first}
+
+
+def derive(raw: dict) -> dict:
+    """The derived section: a pure function of the stored raw arrays, so verify can recompute it exactly."""
+    layers = [int(x) for x in raw["layers"].tolist()]
+    out = {"definitions": DEFINITIONS, "layers": layers, "positions": [int(x) for x in raw["positions"].tolist()],
+           "jacobian": _family_stats(raw["jacobian_top_ids"], raw["final_top_ids"], layers)}
+    if "baseline_top_ids" in raw:
+        out["baseline"] = _family_stats(raw["baseline_top_ids"], raw["final_top_ids"], layers)
+    return out
+
+
+def readable(raw: dict, vocab: dict, position: int = -1, n_tokens: int = 5) -> dict:
+    """A human view of one position, decoded with the capture's vocabulary file (the subject model's own tokenizer
+    output at capture time). Presentation only: it is not stored in the artifact, and nothing is computed here."""
+    word = lambda i: (vocab or {}).get(str(int(i)), "<id %d>" % int(i))  # noqa: E731
+    p = position % int(raw["final_top_ids"].shape[0])
+    layers = [int(x) for x in raw["layers"].tolist()]
+    out = {"position": int(raw["positions"][p]),
+           "jacobian_top_tokens_by_layer": {str(l): [word(i) for i in raw["jacobian_top_ids"][li, p, :n_tokens]]
+                                            for li, l in enumerate(layers)},
+           "final_top_tokens": [word(i) for i in raw["final_top_ids"][p, :n_tokens]]}
+    if "baseline_top_ids" in raw:
+        out["baseline_top_tokens_by_layer"] = {str(l): [word(i) for i in raw["baseline_top_ids"][li, p, :n_tokens]]
+                                               for li, l in enumerate(layers)}
+    return out
+
+
+def build(capture: dict, raw: dict, vocab=None) -> dict:
+    problems = [why for ok, _, why in verify_capture(capture, raw, vocab) if not ok]
+    if problems:
+        raise ValueError("capture does not verify; L-lens will not package it: " + "; ".join(problems))
+    task_id = capture["task_id"]
+    return {
+        "schema": SCHEMA,
+        "type": "llens",
+        "task_id": task_id,
+        "what": STATEMENT,
+        "upstream_credit": UPSTREAM_CREDIT,
+        "subject": {"model_id": capture["subject_model"]["id"],
+                    "revision": capture["subject_model"].get("revision"),
+                    "note": capture["subject_model"].get("note")},
+        "inputs": {"jlens_capture_sha256": digest(capture), "jlens_capture_schema": capture.get("schema"),
+                   "raw_array_sha256": capture["llens_capture_time"]["array_sha256"]},
+        "derived": derive(raw),
+        "links": {"task_id": task_id,
+                  "tombstone": "the tombstone entry whose notes carry task_id=%s and llens_sha256" % task_id,
+                  "covenant": ["task-%s" % task_id, "jlens-%s" % task_id, "llens-%s" % task_id]},
+        "created_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+
+
+# ----------------------------------------------------------------------------- verification
+
+def verify_capture(capture: dict, raw: dict, vocab=None) -> list:
+    """[(ok, check, why)] -- the capture's own consistency: its arrays match the digests it recorded, their shapes
+    match the readout it declares, and (when given) the vocabulary file is the one it recorded."""
+    out = []
+
+    def check(ok, name, why=""):
+        out.append((bool(ok), name, why))
+
+    if vocab is not None:
+        check(digest(vocab) == (capture.get("llens_capture_time") or {}).get("vocab_sha256"), "vocab digest",
+              "the vocabulary file is not the one recorded at capture time")
+
+    check(capture.get("schema") == CAPTURE_SCHEMA, "capture schema", "schema is %r" % capture.get("schema"))
+    check(bool(capture.get("task_id")), "capture task_id", "no task_id")
+    recorded = (capture.get("llens_capture_time") or {}).get("array_sha256") or {}
+    check(set(recorded) == set(raw), "raw array set",
+          "recorded %s, file has %s" % (sorted(recorded), sorted(raw)))
+    for name in sorted(set(recorded) & set(raw)):
+        check(array_sha256(raw[name]) == recorded[name], "raw %s digest" % name, "%s changed since capture" % name)
+    ro = capture.get("readout") or {}
+    try:
+        L, n, K = len(ro["layers"]), len(ro["positions"]), int(ro["top_k"])
+        shapes = {"jacobian_top_ids": (L, n, K), "jacobian_top_logits": (L, n, K),
+                  "final_top_ids": (n, K), "final_top_logits": (n, K), "layers": (L,), "positions": (n,)}
+        if ro.get("baseline"):
+            shapes.update(baseline_top_ids=(L, n, K), baseline_top_logits=(L, n, K))
+        for name, shape in shapes.items():
+            check(name in raw and tuple(raw[name].shape) == shape, "raw %s shape" % name,
+                  "%s is %s, readout says %s" % (name, tuple(raw[name].shape) if name in raw else None, shape))
+        check("layers" in raw and [int(x) for x in raw["layers"]] == list(ro["layers"]), "raw layers agree",
+              "the layers array is not the declared readout")
+        check("positions" in raw and [int(x) for x in raw["positions"]] == list(ro["positions"]),
+              "raw positions agree", "the positions array is not the declared readout")
+    except (KeyError, TypeError, ValueError) as e:
+        check(False, "readout declared", "%s: %s" % (type(e).__name__, e))
+    return out
+
+
+def verify_llens(llens: dict, capture: dict, raw: dict, vocab=None) -> list:
+    out = verify_capture(capture, raw, vocab)
+
+    def check(ok, name, why=""):
+        out.append((bool(ok), name, why))
+
+    check(llens.get("schema") == SCHEMA, "llens schema", "schema is %r" % llens.get("schema"))
+    check(llens.get("task_id") == capture.get("task_id"), "llens task_id agrees",
+          "llens %r, capture %r" % (llens.get("task_id"), capture.get("task_id")))
+    check((llens.get("inputs") or {}).get("jlens_capture_sha256") == digest(capture), "llens cites this capture",
+          "the capture's digest is not the one L-lens recorded")
+    check(llens.get("derived") == json.loads(json.dumps(derive(raw))), "derived recomputes from raw",
+          "the stored derived section is not what the raw arrays give")
+    return out
+
+
+def _report(results) -> int:
+    bad = [r for r in results if not r[0]]
+    for ok, name, why in results:
+        print("  %s  %s%s" % ("PASS" if ok else "FAIL", name, "" if ok else "  -- " + why))
+    return 1 if bad else 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    b = sub.add_parser("build")
+    b.add_argument("--capture", required=True)
+    b.add_argument("--raw", required=True)
+    b.add_argument("--out", required=True)
+    v = sub.add_parser("verify")
+    v.add_argument("--capture", required=True)
+    v.add_argument("--raw", required=True)
+    v.add_argument("--llens", default="")
+    s = sub.add_parser("show")
+    s.add_argument("--capture", required=True)
+    s.add_argument("--raw", required=True)
+    s.add_argument("--position", type=int, default=-1, help="index into the readout's positions (default last)")
+    s.add_argument("--n", type=int, default=5)
+    a = ap.parse_args(argv)
+
+    with open(a.capture, encoding="utf-8") as f:
+        capture = json.load(f)
+    raw = load_raw(a.raw)
+    try:
+        vocab = load_vocab(a.capture, capture)
+    except OSError as e:
+        print("LLENS_FAIL the capture names a vocabulary file that cannot be read: %s" % e, file=sys.stderr)
+        return 1
+    if a.cmd == "show":
+        print(json.dumps(readable(raw, vocab, a.position, a.n), indent=1, ensure_ascii=False))
+        return 0
+    if a.cmd == "build":
+        try:
+            art = build(capture, raw, vocab)
+        except ValueError as e:
+            print("LLENS_FAIL %s" % e, file=sys.stderr)
+            return 1
+        with open(a.out, "w", encoding="utf-8", newline="\n") as f:
+            json.dump(art, f, indent=1, sort_keys=True, ensure_ascii=False)
+            f.write("\n")
+        print("LLENS_SHA256=%s" % digest(art))
+        print("LLENS_OK path=%s" % a.out)
+        return 0
+    if a.llens:
+        with open(a.llens, encoding="utf-8") as f:
+            rc = _report(verify_llens(json.load(f), capture, raw, vocab))
+    else:
+        rc = _report(verify_capture(capture, raw, vocab))
+    print("LLENS_VERIFY_OK" if rc == 0 else "LLENS_VERIFY_FAIL")
+    return rc
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

requirements.txt

@@ -8,5 +8,7 @@
 torch==2.14.1
 transformers==5.19.0
 huggingface_hub>=0.20.0
+numpy
+# tests: pip install pytest
 # jlens: install from git (not on PyPI as a stable pin here)
 #   pip install "jlens @ git+https://github.com/anthropics/jacobian-lens"

scripts/fetch_lens.sh

@@ -8,6 +8,7 @@
 # Usage:
 #   ./scripts/fetch_lens.sh
 #   OUT=/path/to/gpt2_jacobian_lens.pt ./scripts/fetch_lens.sh
+#   PYTHON=/path/to/venv/python ./scripts/fetch_lens.sh   (default python3)
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
@@ -28,8 +29,8 @@ if command -v huggingface-cli >/dev/null 2>&1; then
   huggingface-cli download "$REPO_ID" "$HF_PATH" --local-dir "$TMPDIR" --local-dir-use-symlinks False
   mv "$TMPDIR/$HF_PATH" "$OUT"
   rm -rf "$TMPDIR"
-elif python3 -c "import huggingface_hub" 2>/dev/null; then
-  python3 - <<PY
+elif "${PYTHON:-python3}" -c "import huggingface_hub" 2>/dev/null; then
+  "${PYTHON:-python3}" - <<PY
 from huggingface_hub import hf_hub_download
 import shutil, os
 path = hf_hub_download(repo_id="${REPO_ID}", filename="${HF_PATH}")

scripts/seed_demo.sh

@@ -43,6 +43,8 @@ export JLENS_LENS="${JLENS_LENS:-$REPO_ROOT/gpt2_jacobian_lens.pt}"
 # Resolve python
 if [[ -x "$JLENS_VENV/bin/python" ]]; then
   PYTHON="$JLENS_VENV/bin/python"
+elif [[ -x "$JLENS_VENV/Scripts/python.exe" ]]; then
+  PYTHON="$JLENS_VENV/Scripts/python.exe"   # a Windows venv
 else
   PYTHON="$(command -v python3)"
 fi
@@ -51,7 +53,7 @@ echo "PYTHON=$PYTHON"
 if [[ "$MODE" == "apply" ]]; then
   echo "--- demo_apply.py ---"
   TRIAD_PROMPT="$PROMPT" JLENS_LENS="$JLENS_LENS" "$PYTHON" "$REPO_ROOT/demo_apply.py" | tee /tmp/triad_seed_demo_apply.log
-  rg -n "SUCCESS: lens.apply returned real top-k tokens" /tmp/triad_seed_demo_apply.log
+  grep -n -F "SUCCESS: lens.apply returned real top-k tokens" /tmp/triad_seed_demo_apply.log
   echo "SEED_DEMO_OK mode=apply"
   exit 0
 fi
@@ -79,7 +81,7 @@ if [[ "$MODE" == "triad" ]]; then
     "none" \
     "Third leg must be real jlens.apply not self-observation" \
     "seed-demo" | tee /tmp/triad_seed_demo_triad.log
-  rg -n "FIRE_TRIAD_OK" /tmp/triad_seed_demo_triad.log
+  grep -n -F "FIRE_TRIAD_OK" /tmp/triad_seed_demo_triad.log
   echo "SEED_DEMO_OK mode=triad task_id=$TASK_ID"
   exit 0
 fi

tests/check_against_upstream.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Does a stored capture hold what upstream returns? An independent re-run, compared cell by cell.
+
+For a capture made by jlens_snapshot.py, this loads the same model and lens, calls upstream
+jlens.JacobianLens.apply the way the upstream README does (all requested layers in ONE call, which
+jlens_snapshot.py does not do), and checks:
+  - the stored top-K ids and logits equal the direct call's, exactly, for every layer and position;
+  - the stored final-layer top-K equals the direct call's model_logits top-K;
+  - each full [positions, vocab] tensor hashes to the full_tensor_sha256 L-lens recorded at capture time;
+  - the use_jacobian=False baseline, likewise.
+Exit 0 only if everything matches. Needs torch, transformers, jlens, the model and the lens file.
+
+Usage: check_against_upstream.py RUN_DIR [--lens PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+import numpy as np
+import torch
+import transformers
+import jlens
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, HERE)
+import llens  # noqa: E402
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("run_dir")
+    ap.add_argument("--lens", default="")
+    a = ap.parse_args(argv)
+    cap = json.load(open(os.path.join(a.run_dir, "jlens_snapshot.json"), encoding="utf-8"))
+    raw = llens.load_raw(os.path.join(a.run_dir, cap["raw"]["file"]))
+    ro = cap["readout"]
+    lens_path = a.lens or cap["lens"]["path"]
+    if llens_sha(lens_path) != cap["lens"]["sha256"]:
+        print("FAIL lens file differs from the one the capture recorded")
+        return 1
+    hf = transformers.AutoModelForCausalLM.from_pretrained(cap["subject_model"]["id"],
+                                                           revision=cap["subject_model"].get("revision"))
+    hf.eval()
+    tok = transformers.AutoTokenizer.from_pretrained(cap["subject_model"]["id"],
+                                                     revision=cap["subject_model"].get("revision"))
+    model = jlens.from_hf(hf, tok)
+    lens = jlens.JacobianLens.load(lens_path)
+    k, bad, n = ro["top_k"], 0, 0
+    fams = [("jacobian", True)] + ([("baseline", False)] if ro["baseline"] else [])
+    for fam, use_j in fams:
+        lens_logits, model_logits, ids = lens.apply(model, cap["input"]["prompt"], layers=ro["layers"],
+                                                    positions=ro["positions"], max_seq_len=cap["input"]["max_seq_len"],
+                                                    use_jacobian=use_j)
+        n += 1
+        if ids[0].tolist() != cap["input"]["input_ids"]:
+            print("FAIL %s: input ids differ" % fam)
+            bad += 1
+        for li, layer in enumerate(ro["layers"]):
+            v, i = lens_logits[layer].topk(k, dim=-1)
+            ok_ids = np.array_equal(i.numpy(), raw[fam + "_top_ids"][li])
+            ok_val = np.array_equal(v.numpy().astype(np.float32), raw[fam + "_top_logits"][li])
+            ok_full = (llens.array_sha256(lens_logits[layer].numpy().astype(np.float32))
+                       == cap["llens_capture_time"]["full_tensor_sha256"][fam][str(layer)])
+            n += 3
+            if not (ok_ids and ok_val and ok_full):
+                bad += 1
+                print("FAIL %s layer %d: ids %s, logits %s, full-tensor digest %s" % (fam, layer, ok_ids, ok_val, ok_full))
+        v, i = model_logits.topk(k, dim=-1)
+        ok = (np.array_equal(i.numpy(), raw["final_top_ids"]) and np.array_equal(v.numpy(), raw["final_top_logits"])
+              and llens.array_sha256(model_logits.numpy().astype(np.float32))
+              == cap["llens_capture_time"]["full_tensor_sha256"]["final"])
+        n += 1
+        if not ok:
+            bad += 1
+            print("FAIL %s: final-layer top-K or digest differs" % fam)
+    print("UPSTREAM_MATCH %d of %d comparisons" % (n - bad, n) if not bad else "UPSTREAM_MISMATCH %d" % bad)
+    return 1 if bad else 0
+
+
+def llens_sha(path):
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/e2e_triad.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# e2e_triad.sh — the whole triad on a real model, in a scratch directory, driven both ways.
+#
+# Runs triad/on_speak.sh with the tombstone log, the memory root and the run
+# directory all inside a fresh temp dir. It never touches tombstone/tombstone.md,
+# and never pushes: the scratch memory root is not a git repo, so the push step
+# is skipped. Then it breaks the triad on purpose, and each break must fail:
+#   1. a tombstone entry citing another L-lens artifact  -> verify_triad exits 1
+#   2. the L-lens memory removed from covenant            -> verify_triad exits 1
+#   3. a lens file that is not a lens                     -> fire_triad exits
+#      nonzero BEFORE the tombstone is written (fail closed, nothing appended)
+#
+# Needs: the venv (JLENS_VENV, default <repo>/.venv), the lens file, the model,
+# rg, and covenant's ai_memory_system (COVENANT_SRC).
+# Prints E2E_TRIAD_OK when every step behaved as stated.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SCRATCH="$(mktemp -d)"
+trap 'rm -rf "$SCRATCH"' EXIT
+export JLENS_VENV="${JLENS_VENV:-$REPO_ROOT/.venv}"
+export JLENS_LENS="${JLENS_LENS:-$REPO_ROOT/gpt2_jacobian_lens.pt}"
+export COVENANT_SRC="${COVENANT_SRC:?set COVENANT_SRC to a covenant checkout}"
+export TOMBSTONE_LOG="$SCRATCH/tombstone.md"
+export AI_MEMORY_ROOT="$SCRATCH/memory"
+export RUN_DIR="$SCRATCH/runs"
+if [[ -x "$JLENS_VENV/bin/python" ]]; then PY="$JLENS_VENV/bin/python"; else PY="$JLENS_VENV/Scripts/python.exe"; fi
+printf '# scratch tombstone log\n' > "$TOMBSTONE_LOG"
+mkdir -p "$AI_MEMORY_ROOT"
+SAMPLE_BEFORE="$(sha256sum "$REPO_ROOT/tombstone/tombstone.md" | cut -c1-64)"
+
+fail() { echo "E2E FAIL: $*" >&2; exit 1; }
+
+echo "=== 1. a real speak-turn fires all three legs and verifies ==="
+export TASK_ID="e2e-$(date -u +%Y%m%d-%H%M%S)-$$"
+OUT="$("$REPO_ROOT/triad/on_speak.sh" "The covenant keeps its record append-only, and every claim cites the check that backs it." "e2e")" \
+  || { printf '%s\n' "$OUT"; fail "on_speak.sh exited nonzero on a clean run"; }
+printf '%s\n' "$OUT" | grep -E "SNAPSHOT_OK|LLENS_OK|LLENS_VERIFY_OK|VERIFY_TRIAD_OK|FIRE_TRIAD_OK|Wrote covenant"
+printf '%s\n' "$OUT" | grep -q "^VERIFY_TRIAD_OK task_id=$TASK_ID" || fail "no VERIFY_TRIAD_OK"
+printf '%s\n' "$OUT" | grep -q "^FIRE_TRIAD_OK task_id=$TASK_ID" || fail "no FIRE_TRIAD_OK"
+for m in task jlens llens; do [[ -f "$AI_MEMORY_ROOT/$m-$TASK_ID.md" ]] || fail "covenant memory $m-$TASK_ID absent"; done
+V=("$PY" "$REPO_ROOT/triad/verify_triad.py" --task-id "$TASK_ID" --run-dir "$RUN_DIR/$TASK_ID"
+   --tombstone-log "$TOMBSTONE_LOG" --memory-root "$AI_MEMORY_ROOT")
+"${V[@]}" >/dev/null || fail "verify_triad fails on the clean triad"
+
+echo "=== 2. break: the tombstone cites another L-lens artifact ==="
+cp "$TOMBSTONE_LOG" "$SCRATCH/tombstone.bak"
+sed -i -E "s/llens_sha256=[0-9a-f]{64}/llens_sha256=$(printf '0%.0s' {1..64})/" "$TOMBSTONE_LOG"
+if "${V[@]}" > "$SCRATCH/v2.txt"; then fail "verify_triad passed with a wrong tombstone digest"; fi
+grep "FAIL  tombstone: llens_sha256 agrees" "$SCRATCH/v2.txt" || fail "the wrong digest was not the named failure"
+cp "$SCRATCH/tombstone.bak" "$TOMBSTONE_LOG"
+"${V[@]}" >/dev/null || fail "restoring the tombstone did not restore green"
+
+echo "=== 3. break: the L-lens memory is gone from covenant ==="
+mv "$AI_MEMORY_ROOT/llens-$TASK_ID.md" "$SCRATCH/llens.bak"
+if "${V[@]}" > "$SCRATCH/v3.txt"; then fail "verify_triad passed without the L-lens memory"; fi
+grep "FAIL  covenant: llens-$TASK_ID present" "$SCRATCH/v3.txt" || fail "the missing memory was not the named failure"
+mv "$SCRATCH/llens.bak" "$AI_MEMORY_ROOT/llens-$TASK_ID.md"
+"${V[@]}" >/dev/null || fail "restoring the memory did not restore green"
+
+echo "=== 4. break: the lens leg fails; nothing may be appended ==="
+LINES_BEFORE="$(wc -l < "$TOMBSTONE_LOG")"
+printf 'not a lens\n' > "$SCRATCH/bad_lens.pt"
+if JLENS_LENS="$SCRATCH/bad_lens.pt" TASK_ID="e2e-bad-$$" "$REPO_ROOT/triad/on_speak.sh" "x" "e2e-bad" > "$SCRATCH/bad.txt" 2>&1; then
+  fail "fire_triad succeeded with a broken lens"
+fi
+[[ "$(wc -l < "$TOMBSTONE_LOG")" == "$LINES_BEFORE" ]] || fail "the tombstone was written although the lens leg failed"
+[[ ! -e "$AI_MEMORY_ROOT/task-e2e-bad-$$.md" ]] || fail "a covenant memory was written although the lens leg failed"
+echo "lens leg failed as it should; tombstone and covenant untouched"
+
+[[ "$(sha256sum "$REPO_ROOT/tombstone/tombstone.md" | cut -c1-64)" == "$SAMPLE_BEFORE" ]] || fail "the repo's tombstone sample changed"
+echo "E2E_TRIAD_OK task_id=$TASK_ID"

tests/test_llens.py

@@ -0,0 +1,281 @@
+"""L-lens and triad verification, without a model: synthetic captures, then each link broken on purpose.
+
+Every check is driven both ways. A clean artifact passes, and one specific tamper must fail with a named reason. A
+verifier that has only been seen passing has not been observed.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+import sys
+
+import numpy as np
+import pytest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+sys.path.insert(0, os.path.join(ROOT, "triad"))
+import llens  # noqa: E402
+import verify_triad  # noqa: E402
+
+TASK = "20261008-000000-1"
+
+
+def synthetic(task_id=TASK, baseline=True):
+    """2 layers x 3 positions x K=2, with known answers:
+    final top ids per position: [5,6], [7,8], [9,1]
+    jacobian layer 0: [5,0], [0,7], [2,3]   -> top1 agree 1 (pos 0); final top1 in top-K: pos0, pos1 -> 2
+    jacobian layer 1: [5,6], [7,8], [1,9]   -> top1 agree 2; in top-K 3; overlap 2+2+2 = 6
+    first layer the final top1 is in top-K: pos0 -> 0, pos1 -> 0, pos2 -> 1
+    """
+    raw = {"input_ids": np.array([50256, 11, 12], dtype=np.int64),
+           "layers": np.array([0, 1], dtype=np.int64), "positions": np.array([0, 1, 2], dtype=np.int64),
+           "final_top_ids": np.array([[5, 6], [7, 8], [9, 1]], dtype=np.int64),
+           "final_top_logits": np.array([[3, 2], [3, 2], [3, 2]], dtype=np.float32),
+           "jacobian_top_ids": np.array([[[5, 0], [0, 7], [2, 3]], [[5, 6], [7, 8], [1, 9]]], dtype=np.int64),
+           "jacobian_top_logits": np.ones((2, 3, 2), dtype=np.float32)}
+    if baseline:
+        raw["baseline_top_ids"] = np.array([[[0, 1], [2, 3], [4, 5]], [[5, 0], [7, 0], [9, 0]]], dtype=np.int64)
+        raw["baseline_top_logits"] = np.ones((2, 3, 2), dtype=np.float32)
+    cap = {"schema": llens.CAPTURE_SCHEMA, "type": "jlens", "task_id": task_id,
+           "subject_model": {"id": "synthetic", "revision": None, "note": "test"},
+           "input": {"prompt": "a b", "input_ids": [50256, 11, 12]},
+           "readout": {"layers": [0, 1], "positions": [0, 1, 2], "top_k": 2, "baseline": baseline},
+           "vocab": {"file": "jlens_vocab.json"},
+           "llens_capture_time": {"array_sha256": {k: llens.array_sha256(v) for k, v in raw.items()},
+                                  "vocab_sha256": llens.digest(VOCAB)}}
+    return cap, raw
+
+
+VOCAB = {str(i): "t%d" % i for i in range(20)} | {"50256": "<|endoftext|>"}
+
+
+def roundtrip(obj):
+    return json.loads(json.dumps(obj))
+
+
+# --------------------------------------------------------------------------- derivation
+
+def test_derived_values_are_the_hand_computed_ones():
+    cap, raw = synthetic()
+    d = llens.derive(raw)
+    j = d["jacobian"]["per_layer"]
+    assert j["0"] == {"top1_agree": 1, "final_top1_in_topk": 2, "topk_overlap": 2, "n_positions": 3, "k": 2}
+    assert j["1"] == {"top1_agree": 2, "final_top1_in_topk": 3, "topk_overlap": 6, "n_positions": 3, "k": 2}
+    assert d["jacobian"]["first_layer_final_top1_in_topk"] == [0, 0, 1]
+    assert d["baseline"]["per_layer"]["0"]["top1_agree"] == 0
+    assert d["baseline"]["first_layer_final_top1_in_topk"] == [1, 1, 1]
+
+
+def test_no_baseline_means_no_baseline_section():
+    cap, raw = synthetic(baseline=False)
+    assert "baseline" not in llens.derive(raw)
+    assert all(ok for ok, _, _ in llens.verify_capture(cap, raw))
+
+
+def test_artifact_says_what_it_is_and_credits_upstream():
+    cap, raw = synthetic()
+    art = llens.build(cap, raw)
+    assert art["type"] == "llens" and art["task_id"] == TASK
+    assert "not a replacement name for the Jacobian Lens" in art["what"]
+    assert art["upstream_credit"]["source"] == "https://github.com/anthropics/jacobian-lens"
+    assert art["upstream_credit"]["license"] == "Apache-2.0"
+    assert art["inputs"]["jlens_capture_sha256"] == llens.digest(cap)
+
+
+# --------------------------------------------------------------------------- hashing
+
+def test_canonical_digest_ignores_whitespace_and_key_order_but_not_content():
+    a = {"b": 1, "a": [1, 2]}
+    assert llens.digest(a) == llens.digest(json.loads(json.dumps(a, indent=4)))
+    assert llens.digest(a) != llens.digest({"b": 1, "a": [2, 1]})
+
+
+def test_array_digest_sees_dtype_and_shape():
+    x = np.arange(6, dtype=np.int64)
+    assert llens.array_sha256(x) != llens.array_sha256(x.reshape(2, 3))
+    assert llens.array_sha256(x) != llens.array_sha256(x.astype(np.int32))
+    assert llens.array_sha256(x) == llens.array_sha256(x.copy())
+
+
+# --------------------------------------------------------------------------- verify, both ways
+
+def test_clean_capture_and_artifact_verify():
+    cap, raw = synthetic()
+    art = roundtrip(llens.build(cap, raw))
+    assert all(ok for ok, _, _ in llens.verify_llens(art, cap, raw))
+
+
+def failing(results):
+    return [name for ok, name, _ in results if not ok]
+
+
+def test_a_changed_raw_value_fails_its_digest():
+    cap, raw = synthetic()
+    art = roundtrip(llens.build(cap, raw))
+    raw["jacobian_top_ids"][1, 2, 0] = 4
+    assert "raw jacobian_top_ids digest" in failing(llens.verify_llens(art, cap, raw))
+
+
+def test_a_changed_derived_section_fails_recompute():
+    cap, raw = synthetic()
+    art = roundtrip(llens.build(cap, raw))
+    art["derived"]["jacobian"]["per_layer"]["1"]["top1_agree"] = 3
+    assert failing(llens.verify_llens(art, cap, raw)) == ["derived recomputes from raw"]
+
+
+def test_an_edited_capture_is_no_longer_the_one_cited():
+    cap, raw = synthetic()
+    art = roundtrip(llens.build(cap, raw))
+    cap["input"]["prompt"] = "a c"
+    assert failing(llens.verify_llens(art, cap, raw)) == ["llens cites this capture"]
+
+
+def test_a_different_task_id_fails():
+    cap, raw = synthetic()
+    art = roundtrip(llens.build(cap, raw))
+    art["task_id"] = "other"
+    assert "llens task_id agrees" in failing(llens.verify_llens(art, cap, raw))
+
+
+def test_a_shape_that_disagrees_with_the_readout_fails():
+    cap, raw = synthetic()
+    cap["readout"]["top_k"] = 3
+    assert "raw jacobian_top_ids shape" in failing(llens.verify_capture(cap, raw))
+
+
+def test_build_refuses_a_capture_that_does_not_verify():
+    cap, raw = synthetic()
+    raw["final_top_ids"][0, 0] = 1
+    with pytest.raises(ValueError, match="does not verify"):
+        llens.build(cap, raw)
+
+
+# --------------------------------------------------------------------------- the triad, end to end on disk
+
+def write_memory(root, name, body):
+    with open(os.path.join(root, name + ".md"), "w", encoding="utf-8", newline="\n") as f:
+        f.write("---\nname: %s\ndescription: test\nmetadata:\n  type: project\n---\n\n%s\n" % (name, body))
+
+
+def triad(tmp_path, task_id=TASK):
+    cap, raw = synthetic(task_id)
+    art = llens.build(cap, raw)
+    run = tmp_path / "runs" / task_id
+    run.mkdir(parents=True)
+    json.dump(cap, open(run / "jlens_snapshot.json", "w", encoding="utf-8"), indent=1)
+    np.savez_compressed(run / "jlens_raw.npz", **raw)
+    json.dump(art, open(run / "llens.json", "w", encoding="utf-8"), indent=1)
+    json.dump(VOCAB, open(run / "jlens_vocab.json", "w", encoding="utf-8"), indent=0)
+    cs, ls = llens.digest(cap), llens.digest(art)
+    log = tmp_path / "tombstone.md"
+    log.write_text("# log\n\n### 2026-10-08T00:00:00Z | t\n- id: 1\n- task: t\n- outcome: success\n"
+                   "- notes: task_id=%s; jlens_capture_sha256=%s; llens_sha256=%s; jlens_digest=jlens x=1\n"
+                   % (task_id, cs, ls), encoding="utf-8")
+    mem = tmp_path / "mem"
+    mem.mkdir()
+    write_memory(mem, "task-" + task_id, "task_id=%s\ntitle=t\njlens_capture_sha256=%s\nllens_sha256=%s" % (task_id, cs, ls))
+    write_memory(mem, "jlens-" + task_id, json.dumps(cap, indent=2))
+    write_memory(mem, "llens-" + task_id, json.dumps(art, indent=2))
+    return {"run": str(run), "log": str(log), "mem": str(mem), "cap_sha": cs, "ll_sha": ls}
+
+
+def run_verify(t, task_id=TASK):
+    return verify_triad.verify(task_id, t["run"], t["log"], t["mem"])
+
+
+def test_a_complete_triad_verifies(tmp_path):
+    res = run_verify(triad(tmp_path))
+    assert failing(res) == [] and len(res) > 20
+
+
+def test_verifier_main_exits_1_on_failure_and_0_when_clean(tmp_path):
+    t = triad(tmp_path)
+    args = ["--task-id", TASK, "--run-dir", t["run"], "--tombstone-log", t["log"], "--memory-root", t["mem"]]
+    assert verify_triad.main(args) == 0
+    os.remove(os.path.join(t["mem"], "llens-%s.md" % TASK))
+    assert verify_triad.main(args) == 1
+
+
+def test_no_tombstone_entry_for_the_task_fails(tmp_path):
+    t = triad(tmp_path)
+    open(t["log"], "w", encoding="utf-8").write("# log\n")
+    assert "tombstone: an entry for this task_id" in failing(run_verify(t))
+
+
+def test_a_tombstone_entry_citing_another_artifact_fails(tmp_path):
+    t = triad(tmp_path)
+    text = open(t["log"], encoding="utf-8").read().replace(t["ll_sha"], "0" * 64)
+    open(t["log"], "w", encoding="utf-8").write(text)
+    assert failing(run_verify(t)) == ["tombstone: llens_sha256 agrees"]
+
+
+def test_a_missing_covenant_memory_fails(tmp_path):
+    t = triad(tmp_path)
+    os.remove(os.path.join(t["mem"], "jlens-%s.md" % TASK))
+    assert failing(run_verify(t)) == ["covenant: jlens-%s present" % TASK]
+
+
+def test_a_covenant_task_memory_under_another_id_fails(tmp_path):
+    t = triad(tmp_path)
+    p = os.path.join(t["mem"], "task-%s.md" % TASK)
+    text = open(p, encoding="utf-8").read()
+    open(p, "w", encoding="utf-8").write(text.replace("task_id=%s" % TASK, "task_id=x"))
+    assert failing(run_verify(t)) == ["covenant: task memory task_id"]
+
+
+def test_an_altered_covenant_llens_body_fails(tmp_path):
+    t = triad(tmp_path)
+    art = json.load(open(os.path.join(t["run"], "llens.json"), encoding="utf-8"))
+    art["what"] = art["what"] + " (edited)"
+    write_memory(t["mem"], "llens-" + TASK, json.dumps(art))
+    assert failing(run_verify(t)) == ["covenant: llens-%s body digest agrees" % TASK]
+
+
+def test_a_missing_lens_artifact_fails_closed(tmp_path):
+    t = triad(tmp_path)
+    os.remove(os.path.join(t["run"], "llens.json"))
+    f = failing(run_verify(t))
+    assert "lens leg: llens.json present" in f
+    assert "tombstone: llens_sha256 agrees" in f  # no artifact, so nothing can agree with the tombstone
+
+
+def test_reformatting_a_memory_body_is_not_a_change(tmp_path):
+    t = triad(tmp_path)
+    cap = json.load(open(os.path.join(t["run"], "jlens_snapshot.json"), encoding="utf-8"))
+    write_memory(t["mem"], "jlens-" + TASK, json.dumps(cap, separators=(",", ":"), sort_keys=True))
+    assert failing(run_verify(t)) == []
+
+
+def test_raw_npz_swapped_for_another_tasks_fails(tmp_path):
+    t = triad(tmp_path)
+    cap2, raw2 = synthetic("other-task")
+    raw2["jacobian_top_ids"][0, 0, 1] = 19
+    np.savez_compressed(os.path.join(t["run"], "jlens_raw.npz"), **raw2)
+    assert "lens leg: raw jacobian_top_ids digest" in failing(run_verify(t))
+
+
+def test_the_artifact_holds_no_decoded_vocabulary(tmp_path):
+    cap, raw = synthetic()
+    text = json.dumps(llens.build(cap, raw, VOCAB))
+    assert not any(w in text for w in VOCAB.values())
+
+
+def test_show_decodes_from_the_vocab_file_only():
+    cap, raw = synthetic()
+    r = llens.readable(raw, VOCAB, position=0, n_tokens=2)
+    assert r["final_top_tokens"] == ["t5", "t6"] and r["jacobian_top_tokens_by_layer"]["1"] == ["t5", "t6"]
+
+
+def test_a_changed_vocab_file_fails(tmp_path):
+    t = triad(tmp_path)
+    v = dict(VOCAB, **{"5": "changed"})
+    json.dump(v, open(os.path.join(t["run"], "jlens_vocab.json"), "w", encoding="utf-8"))
+    assert failing(run_verify(t)) == ["lens leg: vocab digest"]
+
+
+def test_a_missing_vocab_file_fails_closed(tmp_path):
+    t = triad(tmp_path)
+    os.remove(os.path.join(t["run"], "jlens_vocab.json"))
+    assert "lens leg: artifacts readable" in failing(run_verify(t))

tombstone/tombstone.md

@@ -4,7 +4,10 @@ Public sample only. Real deployments append locally; do not commit private entri
 
 Format: each entry is a markdown subsection with `id`, `task`, `done`, `outcome`,
 `mistakes`, `lessons`, and `notes`. Triad runs stamp `task_id=...` and
-`jlens_digest=...` into notes so the three legs share one id.
+`jlens_digest=...` into notes so the three legs share one id. Since 2026-10-08 they
+also stamp `jlens_capture_sha256=...` and `llens_sha256=...`, which
+`triad/verify_triad.py` checks against the lens leg and covenant. The entry below
+predates that and is kept as written.
 
 ### 2026-10-07T02:09:13Z | jlens-triad-e2e
 - id: 20261007-020913

triad/fire_triad.sh

@@ -1,14 +1,20 @@
 #!/usr/bin/env bash
-# fire_triad.sh — mandatory three-leg triad (tombstone + covenant + real JLens)
+# fire_triad.sh — mandatory three-leg triad (tombstone + covenant + lens leg:
+#                 L-lens over real Anthropic Jacobian Lens measurements)
 #
 # Usage:
 #   ./fire_triad.sh TITLE TASK DONE OUTCOME PROMPT [MISTAKES] [LESSONS] [NOTES]
 # Or env: TITLE TASK DONE OUTCOME PROMPT MISTAKES LESSONS NOTES TASK_ID
 #
 # Legs (all required; any failure => exit nonzero):
-#   (a) tombstone append with JLens digest in notes
-#   (b) covenant puts (task-{id} + jlens-{id} type:jlens snapshot)
-#   (c) real Anthropic jlens.JacobianLens.apply snapshot
+#   (a) tombstone append; notes carry task_id, jlens_capture_sha256, llens_sha256
+#   (b) covenant puts: task-{id} (both digests), jlens-{id} (the JLens capture),
+#       llens-{id} (the L-lens artifact)
+#   (c) lens leg: jlens_snapshot.py runs upstream jlens.JacobianLens.apply
+#       (anthropics/jacobian-lens) and stores what it returned; llens.py
+#       builds the L-lens artifact from that capture and checks it
+# After all three: triad/verify_triad.py checks the legs agree (task_id and
+# digests); a disagreement or an absent artifact fails the triad.
 #
 # Defaults resolve relative to REPO_ROOT (parent of triad/).
 set -euo pipefail
@@ -21,6 +27,9 @@ JLENS_VENV="${JLENS_VENV:-${REPO_ROOT}/.venv}"
 # Prefer repo-local scripts; allow override for shared venvs.
 JLENS_SNAPSHOT_PY="${JLENS_SNAPSHOT_PY:-$REPO_ROOT/jlens_snapshot.py}"
 JLENS_LENS="${JLENS_LENS:-$REPO_ROOT/gpt2_jacobian_lens.pt}"
+LLENS_PY="${LLENS_PY:-$REPO_ROOT/llens.py}"
+VERIFY_PY="${VERIFY_PY:-$DIR/verify_triad.py}"
+export TOMBSTONE_LOG="${TOMBSTONE_LOG:-$REPO_ROOT/tombstone/tombstone.md}"
 RUN_DIR="${RUN_DIR:-$REPO_ROOT/runs}"
 export AI_MEMORY_ROOT="${AI_MEMORY_ROOT:-$REPO_ROOT/data/ai_memory_root}"
 export COVENANT_SRC="${COVENANT_SRC:-$REPO_ROOT/vendor/covenant}"
@@ -44,6 +53,8 @@ SNAP_DIR="$RUN_DIR/$TASK_ID"
 mkdir -p "$SNAP_DIR"
 SNAP_JSON="$SNAP_DIR/jlens_snapshot.json"
 SNAP_DIGEST="$SNAP_DIR/jlens_digest.txt"
+SNAP_RAW="$SNAP_DIR/jlens_raw.npz"
+LLENS_JSON="$SNAP_DIR/llens.json"
 
 echo "=== fire_triad task_id=$TASK_ID ==="
 echo "prompt=$PROMPT"
@@ -52,6 +63,8 @@ echo "REPO_ROOT=$REPO_ROOT"
 # Resolve python: JLENS_VENV, else python3 on PATH
 if [[ -x "$JLENS_VENV/bin/python" ]]; then
   PYTHON="$JLENS_VENV/bin/python"
+elif [[ -x "$JLENS_VENV/Scripts/python.exe" ]]; then
+  PYTHON="$JLENS_VENV/Scripts/python.exe"   # a Windows venv
 elif command -v python3 >/dev/null 2>&1; then
   PYTHON="$(command -v python3)"
 else
@@ -59,8 +72,8 @@ else
   exit 1
 fi
 
-# --- Leg (c) FIRST so digest can go into tombstone notes ---
-echo "--- leg c: JLens apply ---"
+# --- Leg (c) FIRST so its digests can go into tombstone notes ---
+echo "--- leg c: JLens capture (upstream jlens.JacobianLens.apply) ---"
 if [[ ! -f "$JLENS_SNAPSHOT_PY" ]]; then
   echo "Missing jlens_snapshot.py at $JLENS_SNAPSHOT_PY" >&2
   exit 1
@@ -71,14 +84,26 @@ if [[ ! -f "$JLENS_LENS" ]]; then
   exit 1
 fi
 
-"$PYTHON" "$JLENS_SNAPSHOT_PY" \
+SNAP_OUT="$("$PYTHON" "$JLENS_SNAPSHOT_PY" \
   --task-id "$TASK_ID" \
   --prompt "$PROMPT" \
   --out "$SNAP_JSON" \
+  --raw "$SNAP_RAW" \
   --digest "$SNAP_DIGEST" \
-  --lens "$JLENS_LENS"
+  --lens "$JLENS_LENS")"
+printf '%s\n' "$SNAP_OUT"
 JLENS_DIGEST="$(head -1 "$SNAP_DIGEST")"
-JLENS_BODY="$(cat "$SNAP_JSON")"
+JLENS_CAPTURE_SHA256="$(printf '%s\n' "$SNAP_OUT" | sed -n 's/^JLENS_CAPTURE_SHA256=//p' | tr -d '\r')"
+
+echo "--- leg c: L-lens artifact (llens.py, built on the capture) ---"
+LLENS_OUT="$("$PYTHON" "$LLENS_PY" build --capture "$SNAP_JSON" --raw "$SNAP_RAW" --out "$LLENS_JSON")"
+printf '%s\n' "$LLENS_OUT"
+LLENS_SHA256="$(printf '%s\n' "$LLENS_OUT" | sed -n 's/^LLENS_SHA256=//p' | tr -d '\r')"
+if [[ ! "$JLENS_CAPTURE_SHA256" =~ ^[0-9a-f]{64}$ || ! "$LLENS_SHA256" =~ ^[0-9a-f]{64}$ ]]; then
+  echo "Lens leg produced no digest (capture=${JLENS_CAPTURE_SHA256:-none} llens=${LLENS_SHA256:-none})" >&2
+  exit 1
+fi
+"$PYTHON" "$LLENS_PY" verify --capture "$SNAP_JSON" --raw "$SNAP_RAW" --llens "$LLENS_JSON"
 
 # --- Leg (a) tombstone with JLens digest in notes ---
 echo "--- leg a: tombstone ---"
@@ -86,7 +111,7 @@ if [[ ! -x "$TOMBSTONE_APPEND" ]]; then
   echo "Missing tombstone append at $TOMBSTONE_APPEND" >&2
   exit 1
 fi
-COMBINED_NOTES="task_id=${TASK_ID}; jlens_digest=${JLENS_DIGEST}"
+COMBINED_NOTES="task_id=${TASK_ID}; jlens_capture_sha256=${JLENS_CAPTURE_SHA256}; llens_sha256=${LLENS_SHA256}; jlens_digest=${JLENS_DIGEST}"
 if [[ -n "$NOTES" ]]; then
   COMBINED_NOTES="${COMBINED_NOTES}; ${NOTES}"
 fi
@@ -105,24 +130,33 @@ done=${DONE}
 outcome=${OUTCOME}
 prompt=${PROMPT}
 jlens_digest=${JLENS_DIGEST}
+jlens_capture_sha256=${JLENS_CAPTURE_SHA256}
+llens_sha256=${LLENS_SHA256}
 "
-JLENS_BODY="$JLENS_BODY" "$PUT_COVENANT" "$TASK_ID" "$TASK_BODY" \
-  "triad task memory for ${TASK_ID}"
+JLENS_BODY_FILE="$SNAP_JSON" LLENS_BODY_FILE="$LLENS_JSON" COVENANT_SRC="$COVENANT_SRC" \
+  "$PUT_COVENANT" "$TASK_ID" "$TASK_BODY" "triad task memory for ${TASK_ID}"
 
-# Proof: all three legs share task_id
+# Proof: all three legs share task_id (rg when installed, else grep -F: same fixed-string search)
+has_rg() { command -v rg >/dev/null 2>&1; }
 echo "=== triad proof ==="
 echo "task_id=$TASK_ID"
 echo "jlens_snapshot=$SNAP_JSON"
-rg -n --fixed-strings "$TASK_ID" "$REPO_ROOT/tombstone/tombstone.md" | tail -5 || {
+{ if has_rg; then rg -n --fixed-strings "$TASK_ID" "$TOMBSTONE_LOG"; else grep -n -F "$TASK_ID" "$TOMBSTONE_LOG"; fi; } | tail -5 || {
   echo "PROOF FAIL: task_id not in tombstone" >&2
   exit 1
 }
-rg -n --fixed-strings "$TASK_ID" "$AI_MEMORY_ROOT" -g '*.md' | head -20 || {
+{ if has_rg; then rg -n --fixed-strings "$TASK_ID" "$AI_MEMORY_ROOT" -g '*.md'; else grep -rn -F --include='*.md' "$TASK_ID" "$AI_MEMORY_ROOT"; fi; } | head -20 || {
   echo "PROOF FAIL: task_id not in covenant memories" >&2
   exit 1
 }
-rg -n --fixed-strings "$TASK_ID" "$SNAP_JSON" || {
+{ if has_rg; then rg -n --fixed-strings "$TASK_ID" "$SNAP_JSON"; else grep -n -F "$TASK_ID" "$SNAP_JSON"; fi; } || {
   echo "PROOF FAIL: task_id not in jlens snapshot" >&2
   exit 1
 }
-echo "FIRE_TRIAD_OK task_id=$TASK_ID (tombstone + covenant + real jlens.apply)"
+echo "=== triad verification (task_id and digests agree across all three legs) ==="
+"$PYTHON" "$VERIFY_PY" --task-id "$TASK_ID" --run-dir "$SNAP_DIR" \
+  --tombstone-log "$TOMBSTONE_LOG" --memory-root "$AI_MEMORY_ROOT" || {
+  echo "PROOF FAIL: the three legs do not agree (see FAIL lines above)" >&2
+  exit 1
+}
+echo "FIRE_TRIAD_OK task_id=$TASK_ID (tombstone + covenant + L-lens over real jlens.apply; verified)"

triad/on_speak.sh

@@ -2,7 +2,7 @@
 # on_speak.sh — fire the mandatory triad for one Grok Bot spoken turn.
 #
 # Lawrence rule: every time Grok Bot speaks (SendToUser), it counts as a task.
-# This hook assigns a task_id and runs fire_triad.sh (tombstone ∥ covenant ∥ JLens).
+# This hook assigns a task_id and runs fire_triad.sh (tombstone ∥ covenant ∥ L-lens over Anthropic's Jacobian Lens).
 # No degrade mode: any leg failure exits nonzero.
 #
 # Usage:

triad/put_covenant_memory.sh

@@ -9,6 +9,12 @@
 #   JLENS_BODY — if set, also writes jlens-{TASK_ID} (type:jlens snapshot)
 #                CLI enum only allows user|feedback|project|reference;
 #                we use --type project and stamp type:jlens in body+description.
+#   JLENS_BODY_FILE / LLENS_BODY_FILE — the upstream JLens capture and the
+#                L-lens artifact, read from files (they can exceed one
+#                command-line argument); written as jlens-{TASK_ID} and
+#                llens-{TASK_ID} through triad/put_memory_file.py, which makes
+#                the same MemoryStore.put call main.py makes.
+#   PYTHON_COV — python for covenant's memory code (default python3)
 #   OBS_BODY — retired; ignored (self-observation is not a triad leg)
 set -euo pipefail
 DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -39,13 +45,32 @@ safe_name() { printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '-'; }
 MEM_NAME="$(safe_name "task-${TASK_ID}")"
 
 echo "AI_MEMORY_ROOT=$AI_MEMORY_ROOT"
-python3 "$MAIN" --root "$AI_MEMORY_ROOT" put "$MEM_NAME" \
+"${PYTHON_COV:-python3}" "$MAIN" --root "$AI_MEMORY_ROOT" put "$MEM_NAME" \
   --description "$DESCRIPTION" \
   --type "$MEMORY_TYPE" \
   --body "$BODY" \
   --agent "$AGENT_NAME"
 
-if [[ -n "${JLENS_BODY:-}" ]]; then
+PUT_FILE="$DIR/put_memory_file.py"
+WROTE_EXTRA=""
+if [[ -n "${JLENS_BODY_FILE:-}" ]]; then
+  JLENS_NAME="$(safe_name "jlens-${TASK_ID}")"
+  "${PYTHON_COV:-python3}" "$PUT_FILE" --root "$AI_MEMORY_ROOT" --name "$JLENS_NAME" \
+    --description "type:jlens upstream Jacobian Lens capture (anthropics/jacobian-lens, Apache-2.0) for ${TASK_ID}" \
+    --type project --agent "$AGENT_NAME" --body-file "$JLENS_BODY_FILE" --covenant-src "$COVENANT_SRC"
+  WROTE_EXTRA="$WROTE_EXTRA $JLENS_NAME"
+fi
+if [[ -n "${LLENS_BODY_FILE:-}" ]]; then
+  LLENS_NAME="$(safe_name "llens-${TASK_ID}")"
+  "${PYTHON_COV:-python3}" "$PUT_FILE" --root "$AI_MEMORY_ROOT" --name "$LLENS_NAME" \
+    --description "type:llens Threefold L-lens observability/provenance artifact built on the JLens capture jlens-${TASK_ID}" \
+    --type project --agent "$AGENT_NAME" --body-file "$LLENS_BODY_FILE" --covenant-src "$COVENANT_SRC"
+  WROTE_EXTRA="$WROTE_EXTRA $LLENS_NAME"
+fi
+
+if [[ -n "$WROTE_EXTRA" ]]; then
+  echo "Wrote covenant memories: $MEM_NAME$WROTE_EXTRA under $AI_MEMORY_ROOT"
+elif [[ -n "${JLENS_BODY:-}" ]]; then
   JLENS_NAME="$(safe_name "jlens-${TASK_ID}")"
   # Real CLI type enum has no 'jlens'; stamp type:jlens in description+body.
   python3 "$MAIN" --root "$AI_MEMORY_ROOT" put "$JLENS_NAME" \

triad/put_memory_file.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Put one covenant memory whose body is read from a FILE.
+
+Covenant's CLI takes the body as a command-line argument (main.py put --body). A JLens capture or an L-lens artifact
+can be larger than one argument may be (32 KB on Windows, 128 KB per argument on Linux). This helper therefore makes
+the same call main.py makes, MemoryStore(root).put(name, description, type, body, agent), using the same covenant
+code, with the body read from a file.
+
+Usage: put_memory_file.py --root ROOT --name NAME --description TEXT --type TYPE --agent AGENT --body-file PATH
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True)
+    ap.add_argument("--name", required=True)
+    ap.add_argument("--description", required=True)
+    ap.add_argument("--type", default="project")
+    ap.add_argument("--agent", default="cli")
+    ap.add_argument("--body-file", required=True)
+    ap.add_argument("--covenant-src", default=os.environ.get("COVENANT_SRC", ""))
+    a = ap.parse_args(argv)
+    amd = os.path.join(a.covenant_src, "ai_memory_system")
+    if not os.path.isfile(os.path.join(amd, "memory_store.py")):
+        print("covenant memory_store.py not found under %r (set COVENANT_SRC)" % amd, file=sys.stderr)
+        return 1
+    sys.path.insert(0, amd)
+    from memory_store import MemoryStore  # noqa: E402 -- covenant's own store, not a copy
+    with open(a.body_file, encoding="utf-8") as f:
+        body = f.read()
+    out = MemoryStore(a.root).put(a.name, a.description, a.type, body, a.agent)
+    print(json.dumps(out, indent=1, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

triad/verify_triad.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Verify one triad: all three legs exist for one task_id, and their links agree.
+
+Fails closed. An absent artifact, an unreadable one, a task_id that differs, or a digest that differs is a FAIL,
+and the exit status is 1. Checks, in order:
+
+  lens leg   runs/<task_id>/jlens_snapshot.json (the JLens capture), jlens_raw.npz, jlens_vocab.json and
+             llens.json exist. The capture's raw arrays and vocabulary file match the digests recorded at capture
+             time. The L-lens artifact cites this capture, and its derived section recomputes exactly from the raw
+             arrays (llens.verify_llens).
+  tombstone  an entry in the tombstone log whose notes carry task_id=<id>, jlens_capture_sha256=<the capture's
+             digest> and llens_sha256=<the L-lens artifact's digest>.
+  covenant   memories task-<id>, jlens-<id> and llens-<id> exist under AI_MEMORY_ROOT. The task memory carries the
+             same task_id and both digests. The jlens and llens memories hold bodies whose canonical digests equal
+             the capture's and the artifact's.
+
+What it cannot see. It checks that the records agree with each other and with the stored arrays. It does not re-run
+the model, so it cannot tell whether the arrays are what upstream would return today. For that, re-run
+jlens_snapshot.py with the recorded configuration and compare llens_capture_time.full_tensor_sha256. It also does
+not check covenant's own hash chain; covenant's verify_chain does that.
+
+Usage:
+  verify_triad.py --task-id ID [--run-dir DIR] [--tombstone-log PATH] [--memory-root DIR]
+Defaults: --run-dir $RUN_DIR/<id> or <repo>/runs/<id>; --tombstone-log $TOMBSTONE_LOG or
+<repo>/tombstone/tombstone.md; --memory-root $AI_MEMORY_ROOT.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, REPO_ROOT)
+import llens  # noqa: E402
+
+HEX64 = r"[0-9a-f]{64}"
+
+
+def safe_name(s: str) -> str:
+    """put_covenant_memory.sh's safe_name: every character outside [A-Za-z0-9._-] becomes '-'."""
+    return re.sub(r"[^A-Za-z0-9._-]", "-", s)
+
+
+def tombstone_entries(text: str) -> list:
+    """Each '### ' section of the tombstone log as {field: value}."""
+    out = []
+    for block in re.split(r"(?m)^### ", text)[1:]:
+        fields = {"heading": block.splitlines()[0].strip()}
+        for line in block.splitlines()[1:]:
+            m = re.match(r"^- ([a-z_]+): ?(.*)$", line)
+            if m:
+                fields[m.group(1)] = m.group(2)
+        out.append(fields)
+    return out
+
+
+def note_value(notes: str, key: str):
+    m = re.search(r"(?:^|;\s*)%s=([^;]*)" % re.escape(key), notes or "")
+    return m.group(1).strip() if m else None
+
+
+def memory_body(root: str, name: str):
+    """The body of covenant memory <name> (text after the closing frontmatter fence), or None."""
+    path = os.path.join(root, safe_name(name) + ".md")
+    if not os.path.isfile(path):
+        return None
+    text = open(path, encoding="utf-8").read()
+    m = re.match(r"^---\n.*?\n---\n(.*)$", text, re.S)
+    return (m.group(1) if m else text).strip()
+
+
+def verify(task_id: str, run_dir: str, tombstone_log: str, memory_root: str) -> list:
+    out = []
+
+    def check(ok, name, why=""):
+        out.append((bool(ok), name, why))
+        return bool(ok)
+
+    cap_p, raw_p, ll_p = (os.path.join(run_dir, f) for f in ("jlens_snapshot.json", "jlens_raw.npz", "llens.json"))
+    present = [check(os.path.isfile(p), "lens leg: %s present" % os.path.basename(p), "missing: %s" % p)
+               for p in (cap_p, raw_p, ll_p)]
+    cap_sha = ll_sha = None
+    if all(present):
+        try:
+            capture = json.load(open(cap_p, encoding="utf-8"))
+            art = json.load(open(ll_p, encoding="utf-8"))
+            raw = llens.load_raw(raw_p)
+            vocab = llens.load_vocab(cap_p, capture)
+        except Exception as e:  # noqa: BLE001 -- unreadable is a failure, named
+            check(False, "lens leg: artifacts readable", "%s: %s" % (type(e).__name__, e))
+        else:
+            check(capture.get("task_id") == task_id, "lens leg: capture task_id",
+                  "capture says %r" % capture.get("task_id"))
+            out.extend((ok, "lens leg: " + name, why) for ok, name, why in llens.verify_llens(art, capture, raw, vocab))
+            cap_sha, ll_sha = llens.digest(capture), llens.digest(art)
+
+    # tombstone
+    if check(os.path.isfile(tombstone_log), "tombstone: log present", "missing: %s" % tombstone_log):
+        entries = [e for e in tombstone_entries(open(tombstone_log, encoding="utf-8").read())
+                   if note_value(e.get("notes"), "task_id") == task_id]
+        if check(entries, "tombstone: an entry for this task_id", "no entry's notes carry task_id=%s" % task_id):
+            e = entries[-1]
+            for key, want in (("jlens_capture_sha256", cap_sha), ("llens_sha256", ll_sha)):
+                got = note_value(e.get("notes"), key)
+                check(want is not None and got == want, "tombstone: %s agrees" % key,
+                      "entry has %r, lens leg gives %r" % (got, want))
+
+    # covenant
+    if check(memory_root and os.path.isdir(memory_root), "covenant: memory root present",
+             "AI_MEMORY_ROOT %r is not a directory" % memory_root):
+        body = memory_body(memory_root, "task-" + task_id)
+        if check(body is not None, "covenant: task-%s present" % task_id, "no such memory"):
+            lines = dict(l.split("=", 1) for l in body.splitlines() if "=" in l)
+            check(lines.get("task_id") == task_id, "covenant: task memory task_id", "has %r" % lines.get("task_id"))
+            for key, want in (("jlens_capture_sha256", cap_sha), ("llens_sha256", ll_sha)):
+                check(want is not None and lines.get(key) == want, "covenant: task memory %s agrees" % key,
+                      "memory has %r, lens leg gives %r" % (lines.get(key), want))
+        for prefix, want in (("jlens-", cap_sha), ("llens-", ll_sha)):
+            b = memory_body(memory_root, prefix + task_id)
+            if check(b is not None, "covenant: %s%s present" % (prefix, task_id), "no such memory"):
+                try:
+                    got = llens.digest(json.loads(b))
+                except ValueError as e:
+                    got = "unparseable (%s)" % e
+                check(want is not None and got == want, "covenant: %s%s body digest agrees" % (prefix, task_id),
+                      "memory body gives %r, lens leg gives %r" % (got, want))
+    return out
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--task-id", required=True)
+    ap.add_argument("--run-dir", default="")
+    ap.add_argument("--tombstone-log", default=os.environ.get("TOMBSTONE_LOG")
+                    or os.path.join(REPO_ROOT, "tombstone", "tombstone.md"))
+    ap.add_argument("--memory-root", default=os.environ.get("AI_MEMORY_ROOT", ""))
+    a = ap.parse_args(argv)
+    run_dir = a.run_dir or os.path.join(os.environ.get("RUN_DIR") or os.path.join(REPO_ROOT, "runs"), a.task_id)
+    results = verify(a.task_id, run_dir, a.tombstone_log, a.memory_root)
+    for ok, name, why in results:
+        print("  %s  %s%s" % ("PASS" if ok else "FAIL", name, "" if ok else "  -- " + why))
+    bad = sum(1 for r in results if not r[0])
+    print("VERIFY_TRIAD_OK task_id=%s checks=%d" % (a.task_id, len(results)) if not bad
+          else "VERIFY_TRIAD_FAIL task_id=%s failed=%d of %d" % (a.task_id, bad, len(results)))
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())