interp-engine 1.2.5__tar.gz → 1.2.7__tar.gz

{interp_engine-1.2.5 → interp_engine-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: interp-engine
-Version: 1.2.5
+Version: 1.2.7
 Summary: A fast, standardized interpretability engine that supports most modern models and architectures. Powers Neuronpedia.
 Project-URL: Homepage, https://github.com/decoderesearch/interp-engine
 Project-URL: Repository, https://github.com/decoderesearch/interp-engine

{interp_engine-1.2.5 → interp_engine-1.2.7}/docs/AGENT_INTEGRATION.md

@@ -236,7 +236,7 @@ mistake you made.
 | `UnknownCoordinate` | an address carried a coordinate this version has no field for | version skew between processes — align the engine version on both |
 | `{key} fired twice in one forward pass` | one address resolved to a module invoked more than once | a re-entrant trunk; capture per-invocation or name a narrower address |
 | `Captured nothing at {missing}: the resolved module(s) did not run` | a quantized or fused kernel replaced the block's forward and computes the tensor inline | different point, or an unfused load |
-| `NoChatTemplateError` | the tokenizer has no chat template | `model.tok.has_chat_template()` first; do not hand-write one |
+| `NoChatTemplateError` | the model has no chat format (no Jinja template and no code formatter) | `model.tok.has_chat_template()` first; do not hand-write one, and do not read `tokenizer.chat_template` — it is `None` for families that define their format in code |
 | `CapabilityUnsupported` | you asked one backend for something only the other can do | the message names the call that works; `CAPABILITIES` is the table it came from (rule 13) |
 | `... cannot run from inside a running event loop` | a sync free function or `sync_model` call from async code | `await` the method it wraps; the message names it |
 | `... needs vLLM, but vLLM is not installed` | missing extra, or a non-Linux/CUDA box | `pip install 'interp-engine[vllm]'`, or `backend="eager"`; gate on `vllm_installed()` to branch instead of catching |

{interp_engine-1.2.5 → interp_engine-1.2.7}/docs/ARCHITECTURE_QUIRKS.md

@@ -38,16 +38,24 @@ in `facts.py` instead.
 | `points.py`                | The canonical hook points as data: scope, width, vLLM support and the reason for each limit. Consumers (the vLLM served-point gate, the width guard, the reshape set, the docs footnotes) derive from it.                                                                                                                                               | **Never for a new model** — a point is architecture-independent by construction. Only when adding a _point_, and then `tests/test_points_registry.py` tells you what else needs updating.           |
 | `chat_conventions.py`      | How a model structures what it **generates**: harmony markers (gpt-oss), reasoning delimiters (`REASONING_TAGS`, e.g. `<think>`/`</think>`), and generic turn-end tokens.                                                                                                                                                                               | Only when a model introduces a _new_ reasoning delimiter pair — append one `ReasoningTags` entry. Models reusing `<think>` need no change.                                                          |
 | `chat_compose.py`          | Consumes the table above to turn a generation back into messages (`compose_assistant_turns`), normalizing every family's reasoning to `<think>…</think>` in the message content.                                                                                                                                                                        | Never for a new model — it reads `chat_conventions.py`. Only to change the _wire shape_ clients receive.                                                                                            |
+| `chat_formatters.py`       | `CODE_CHAT_FORMATS`: the few architectures that ship **no** `chat_template` and define their prompt format in Python instead (DeepSeek-V4), mapped to a loader that imports the checkpoint's own encoder.                                                                                                                                               | Only when a model has no chat template at all. A model with a template needs no entry — that is the other 99%, and the default path below.                                                          |
 
 Two deliberate non-entries:
 
-- **Prompt-side chat structure has no table, in either direction.** Going _in_,
+- **Prompt-side chat structure needs no per-family entry, in either direction.** Going _in_,
   `Tokenize.message_spans` renders through the model's real chat template and derives per-token
   role/section by diffing renders, so every family (ChatML, Gemma, Llama, harmony) works without
   per-family code. Coming back _out_, `chat_compose.py` reads only the generated text and lets the
   caller supply the prompt messages it already holds, so no code ever parses a rendered prompt back
   into messages. Between them they replaced the frontend's per-family state machines and the
   inference app's per-model response parsers.
+
+  `CODE_CHAT_FORMATS` is the one exception, and it is narrow on purpose: it holds only checkpoints
+  that publish **no** template, where there is no render to diff and the format exists solely as
+  code. Even then the entry is a _loader_, not a description — the format itself is read from the
+  encoder shipped beside the weights, so the table names which architectures are affected and
+  never what their prompts look like. Adding a model that _has_ a template here would be the
+  mistake the paragraph above is about.
 - **Nothing keys on a model-name _substring_.** Both tables above key on architecture class or on
   added-token-vocab membership, i.e. on **capability**. A substring match (`"llama-3" in
 name_or_path`) is the anti-pattern this structure exists to avoid: a substring is a claim about a

{interp_engine-1.2.5 → interp_engine-1.2.7}/docs/USAGE.md

@@ -197,8 +197,37 @@ prompt = model.tok.apply_chat_template([{"role": "user", "content": "Hi"}])
 token_ids = model.tok.apply_chat_template([{"role": "user", "content": "Hi"}], tokenize=True)
 ```
 
-`apply_chat_template` raises `NoChatTemplateError` when the tokenizer has none, rather than inventing
-a format the model was never trained on; `model.tok.has_chat_template()` asks first.
+`apply_chat_template` raises `NoChatTemplateError` when the model has no chat format at all, rather
+than inventing one it was never trained on; `model.tok.has_chat_template()` asks first.
+
+A few checkpoints ship no Jinja `chat_template` because they define their format in Python instead —
+DeepSeek-V4 carries an `encoding/encoding_dsv4.py` in the repo, beside the weights, and a Jinja
+template could not express its other half (`parse_message_from_completion_text`). The engine
+downloads and imports that file rather than vendoring a copy of it, so those models render chat
+through the same three calls above, and `has_chat_template()` says yes. Reading
+`tokenizer.chat_template` directly is what gets this wrong: it is `None` for a model that renders
+chat perfectly well. Loading the file is remote code execution, so it needs `trust_remote_code=True`;
+without it the model still loads and chat is simply unavailable.
+
+`model.tok.accepted_template_kwargs([...])` reports which optional controls (`enable_thinking`,
+`reasoning_effort`) this model actually reads, whichever of the two renders it. Adding a family means
+one entry in `chat_formatters.CODE_CHAT_FORMATS`.
+
+To attribute *tokens* to messages there are two methods, and the difference matters. `message_spans`
+gives per-token role, channel and section (`header` / `content` / `footer`), leaving the trailing
+generation scaffold owned by no message — use it to read or display structure. `message_partition`
+gives one contiguous `[start, end)` span per message that together cover every token, which is what
+mean-pooling activations per turn needs:
+
+```python
+token_ids, spans = model.tok.message_partition([{"role": "user", "content": "Hi"}])
+per_turn = [acts[start:end].mean(0) for start, end in spans]
+```
+
+Only `message_partition` is correct for a code-rendered model. Computing the same spans by rendering
+growing message prefixes and taking length deltas assumes appending a message only appends tokens;
+DeepSeek-V4 rewrites earlier turns once a later user turn exists (it drops their reasoning), so the
+deltas land in the wrong places and still look like a partition.
 
 ## Capture while generating
 

{interp_engine-1.2.5 → interp_engine-1.2.7}/interp_engine/tokenize.py

@@ -297,6 +297,62 @@ class Tokenize:
             )
         )
 
+    def message_partition(
+        self,
+        messages: list[dict[str, str]],
+        **template_kwargs: Any,
+    ) -> tuple[list[int], list[tuple[int, int]]]:
+        """The closed conversation's ids, plus one contiguous ``[start, end)`` span per message.
+
+        A *partition*, which is a different contract from :meth:`message_spans`: the spans are
+        contiguous, cover every token, and align 1:1 with ``messages``. ``message_spans`` splits
+        each message into header/content/footer sections and leaves the trailing generation
+        scaffold owned by nobody, so a caller that mean-pools activations per turn wants this
+        one. Rendered closed, since a scaffold belongs to the turn nobody has written yet.
+
+        The two branches below are deliberately NOT unified. Where a code formatter renders, the
+        boundaries are exact, because the formatter reports its own message blocks. Where a Jinja
+        template does, they come from the length each render grows by as one more message is
+        appended -- an assumption that the template only ever appends, and also the arithmetic
+        every existing caller's numbers were computed with. Preserving it verbatim is the point:
+        a mean pooled over a span whose edge moved by one token is a different number, and these
+        feed persona projections that are compared across runs. So a template-rendered model is
+        unaffected by this method existing, and a code-rendered one gets boundaries the
+        prefix-delta could not have found.
+        """
+        if not messages:
+            return [], []
+
+        if self.formatter is not None:
+            rendered = self.formatter.render(
+                messages,
+                add_generation_prompt=False,
+                continue_final_message=False,
+                **template_kwargs,
+            )
+            full_ids = self._encode_rendered(rendered.text)
+            bounds = [0]
+            for j in range(1, len(messages)):
+                cut = _common_prefix_len(self._encode_rendered(rendered.upto(j)), full_ids)
+                bounds.append(max(bounds[-1], min(cut, len(full_ids))))
+            # The last message closes the sequence by construction (`upto(n)` is the whole
+            # render once the generation scaffold is off), stated rather than measured so the
+            # spans cover every token even if a tokenizer merges across the final cut.
+            bounds.append(len(full_ids))
+            return full_ids, list(zip(bounds, bounds[1:]))
+
+        bounds = [0]
+        full_ids: list[int] = []
+        for j in range(1, len(messages) + 1):
+            full_ids = self._render_ids(
+                messages[:j],
+                add_generation_prompt=False,
+                continue_final_message=False,
+                **template_kwargs,
+            )
+            bounds.append(len(full_ids))
+        return full_ids, list(zip(bounds, bounds[1:]))
+
     def message_spans(
         self,
         messages: list[dict[str, str]],

{interp_engine-1.2.5 → interp_engine-1.2.7}/interp_engine/vllm_capture/freeze.py

@@ -252,8 +252,24 @@ def resolve_freeze_points(
     ``graph_replay`` is False only when freeze is omitted and ``enforce_eager`` is not False
     (today's hooked vLLM). ``freeze_points="auto"`` or ``enforce_eager=False`` with no list
     freezes ``resid_post`` at every layer on a conventional trunk, and ``resid_streams`` at
-    every layer on a hyper-connection trunk.
+    every layer on a hyper-connection trunk -- to read AND to write.
+
+    Auto covers the write because the two are one decision for the caller who asks for it. ``auto``
+    says "serve the residual endpoints on this engine", and read taps alone serve half of them: a
+    lens read-out works, and every steer, ablation and swap derived from that read-out is refused
+    for want of a site at the very address already being tapped. Nothing in the caller's vocabulary
+    distinguished the two halves, either -- ``freeze_writes`` is a list of addresses, so asking for
+    the write meant restating every layer of a set ``auto`` had just built.
+
+    An explicit list is left alone, since a caller who named the points named what they wanted. So
+    is ``freeze_writes=[]``, which is how to ask for the reads WITHOUT the write buffers: those
+    buffers are per layer and per token, and they are what steps ``max_num_batched_tokens`` down
+    when the ladder in :func:`fit_max_num_batched_tokens` cannot fit them.
     """
+    # `None` and `[]` mean different things here and nowhere else in this signature: the first is
+    # "say nothing about writes", which auto fills in, and the second is "no writes", which it must
+    # not. Read before the comprehension below, which cannot tell them apart.
+    writes_declared = freeze_writes is not None
     writes = [to_address(a) for a in (freeze_writes or ())]
     graph = freeze_points is not None or bool(writes) or enforce_eager is False
     if not graph:
@@ -264,14 +280,21 @@ def resolve_freeze_points(
             "Do not pass enforce_eager=True with a freeze set; omit freeze_points for hooked vLLM."
         )
 
+    auto = False
     if freeze_points is None:
-        reads: list[Address] = [] if writes else _auto_reads(n_layers, n_streams)
+        # Writes without a read list stay writes-only: naming a write site is already explicit
+        # about what this engine is for, and auto-reading every layer beside it is not implied.
+        auto = not writes
+        reads: list[Address] = _auto_reads(n_layers, n_streams) if auto else []
     elif isinstance(freeze_points, str):
         if freeze_points != "auto":
             raise ValueError(f"freeze_points must be 'auto', a list of addresses, or []; got {freeze_points!r}")
         reads = _auto_reads(n_layers, n_streams)
+        auto = True
     else:
         reads = [to_address(a) for a in freeze_points]
+    if auto and not writes_declared:
+        writes = list(reads)
 
     for address in (*reads, *writes):
         reason = freeze_unsupported_reason(address.name) or multi_stream_refusal_reason(address.name, n_streams)
@@ -990,7 +1013,16 @@ def worker_install_freeze(worker: object) -> None:
 
 
 def _install_mhc_freeze(worker: object, mhc_sites: Sequence[_Site]) -> None:
-    from interp_engine.vllm_capture.mhc import mhc_taps, require_available
+    """Wrap the mHC kernels for every stacked freeze site, refusing one this model cannot serve.
+
+    A site that carries a ``delta`` is asked the STEER question rather than the capture one, because
+    they differ by exactly the thing a write depends on: ``resid_streams`` is written by running the
+    fused kernel's second half again on the edited stack, so that half has to be forwardable
+    (:func:`~interp_engine.vllm_capture.mhc.pre_rerun_gap`). Asked here because freeze installs in
+    ``Worker.load_model`` -- a gap found later surfaces mid-forward, on an engine that has already
+    started and reported itself healthy.
+    """
+    from interp_engine.vllm_capture.mhc import mhc_taps, require_available, require_steerable
 
     model = _worker_model(worker)
     taps = mhc_taps(worker)
@@ -999,7 +1031,10 @@ def _install_mhc_freeze(worker: object, mhc_sites: Sequence[_Site]) -> None:
         if id(site) in seen:
             continue
         seen.add(id(site))
-        require_available(model, site.address.name, site.address.layer)
+        if site.delta is not None:
+            require_steerable(model, site.address.name, site.address.layer)
+        else:
+            require_available(model, site.address.name, site.address.layer)
         taps.add(site.address, _freeze_mhc_recorder(worker, site))
 
 

{interp_engine-1.2.5 → interp_engine-1.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "interp-engine"
-version = "1.2.5"
+version = "1.2.7"
 description = "A fast, standardized interpretability engine that supports most modern models and architectures. Powers Neuronpedia."
 readme = "README.md"
 license = "Apache-2.0"

{interp_engine-1.2.5 → interp_engine-1.2.7}/tests/test_chat_formatters.py

@@ -393,6 +393,127 @@ def test_prefill_spans_end_on_content(tok: Tokenize):
     assert spans[-1].role == "assistant"
 
 
+# --------------------------------------------------------------------------- #
+# Per-message partition (what activation pooling indexes by)
+# --------------------------------------------------------------------------- #
+
+
+def _legacy_partition(tok: Tokenize, messages: list[dict[str, str]]) -> tuple[list[int], list[tuple[int, int]]]:
+    """The prefix-delta arithmetic that callers ran inline before ``message_partition``.
+
+    Kept here verbatim as the reference implementation. A template-rendered model has to
+    partition identically to this forever: the spans index activation mean-pooling, so an edge
+    that moves by one token silently changes a published number.
+    """
+    spans: list[tuple[int, int]] = []
+    previous = 0
+    full_ids: list[int] = []
+    for index in range(len(messages)):
+        current = tok.apply_chat_template(messages[: index + 1], tokenize=True, add_generation_prompt=False)
+        assert isinstance(current, list)
+        spans.append((previous, len(current)))
+        previous = len(current)
+        full_ids = current
+    return full_ids, spans
+
+
+class _RecordingTokenizer(_CharTokenizer):
+    """A templated tokenizer that records how it was asked to render."""
+
+    chat_template = "{# present; contents never evaluated here #}"
+
+    def __init__(self):
+        super().__init__()
+        self.calls: list[tuple] = []
+
+    def apply_chat_template(
+        self,
+        messages: list[dict[str, str]],
+        tokenize: bool = True,
+        add_generation_prompt: bool = False,
+        continue_final_message: bool = False,
+        **_: Any,
+    ):
+        self.calls.append(
+            (tuple(m["content"] for m in messages), add_generation_prompt, continue_final_message, tokenize)
+        )
+        return list(range(1, 2 * len(messages) + 1))
+
+
+def test_partition_asks_a_template_exactly_what_the_old_inline_code_asked():
+    """The guarantee that no template-rendered model's pooled activations move.
+
+    Asserted on the *calls* rather than on one template's output, because that covers every
+    template rather than whichever ones happen to be cached: same message slices, same flags,
+    same tokenizing path means the same ids come back, whatever the template does with them.
+    """
+    tokenizer = _RecordingTokenizer()
+    messages = [{"role": "user", "content": "a"}, {"role": "assistant", "content": "b"}]
+
+    full_ids, spans = Tokenize(tokenizer).message_partition(messages)
+
+    assert tokenizer.calls == [
+        (("a",), False, False, True),
+        (("a", "b"), False, False, True),
+    ]
+    assert full_ids == [1, 2, 3, 4]
+    assert spans == [(0, 2), (2, 4)]
+
+
+def test_partition_equals_the_legacy_arithmetic_on_a_template():
+    tokenizer = _RecordingTokenizer()
+    messages = [{"role": "user", "content": "a"}, {"role": "assistant", "content": "b"}]
+    tok = Tokenize(tokenizer)
+
+    assert tok.message_partition(messages) == _legacy_partition(tok, messages)
+
+
+def test_partition_of_no_messages_is_empty():
+    assert Tokenize(_RecordingTokenizer()).message_partition([]) == ([], [])
+
+
+def test_partition_covers_every_token_exactly_once(tok: Tokenize):
+    """Contiguous, gapless, and ending on the last token — a partition, not a tagging.
+
+    Pooling reads `acts[start:end]` per message, so a gap drops activations from every mean and
+    an overlap double-counts them into two turns.
+    """
+    full_ids, spans = tok.message_partition(MULTI_TURN)
+
+    assert len(spans) == len(MULTI_TURN)
+    assert spans[0][0] == 0
+    assert spans[-1][1] == len(full_ids)
+    assert all(before[1] == after[0] for before, after in zip(spans, spans[1:]))
+
+
+def test_partition_blocks_match_the_formatters_own_boundaries(tok: Tokenize, formatter: DeepseekV4Formatter):
+    """Where a formatter renders, the boundaries are read off it rather than inferred.
+
+    Message 0 also carries the leading scaffold (the BOS token, in ``RenderedChat.prefix``),
+    which is where the prefix-delta arithmetic puts it too — there is no earlier message to
+    attribute it to, and leaving it unowned would break the partition.
+    """
+    rendered = formatter.render(MULTI_TURN, add_generation_prompt=False)
+    _, spans = tok.message_partition(MULTI_TURN)
+
+    for index, (start, end) in enumerate(spans):
+        expected = rendered.blocks[index]
+        if index == 0:
+            expected = rendered.prefix + expected
+        assert end - start == len(tok.tokenizer.encode(expected)), f"message {index} span is not its own block"
+
+
+def test_the_legacy_arithmetic_would_misplace_a_code_rendered_conversation(tok: Tokenize):
+    """Why this method exists rather than the caller keeping its inline loop.
+
+    The prefix delta assumes appending a message only appends tokens. DeepSeek-V4 rewrites
+    earlier turns once a later user turn exists (a turn stops being the *last* user turn), so
+    the deltas land in the wrong places — and the failure is silent, since they still look like
+    a partition.
+    """
+    assert tok.message_partition(MULTI_TURN) != _legacy_partition(tok, MULTI_TURN)
+
+
 # --------------------------------------------------------------------------- #
 # The real encoder, from the checkpoint
 # --------------------------------------------------------------------------- #

{interp_engine-1.2.5 → interp_engine-1.2.7}/tests/test_chat_templates.py

@@ -186,3 +186,34 @@ def test_reasoning_markers_present_in_tokenizer_vocab():
     """
     model = _load(QWEN_THINKING)
     assert detect_reasoning_tags(model.tokenizer.get_added_vocab().keys()) is not None
+
+
+@pytest.mark.parametrize("spec", CHAT_PARAMS)
+def test_message_partition_matches_the_prefix_delta_it_replaced(spec: ModelSpec):
+    """``message_partition`` must not move a template-rendered model's message boundaries.
+
+    Callers that mean-pool activations per turn (the persona / assistant-axis path) used to run
+    this arithmetic inline against the tokenizer. The spans index the pooling, so an edge that
+    shifts by one token quietly changes a published projection — on every deployed instruct
+    model, none of which needed the change. The generalisation to every template is asserted on
+    the render calls in ``test_chat_formatters.py``; this is the same claim against a real
+    template and a real BPE vocabulary.
+    """
+    model = _load(spec)
+    messages = [
+        {"role": "user", "content": "What is 2+2?"},
+        {"role": "assistant", "content": "Four."},
+        {"role": "user", "content": "And 3+3?"},
+    ]
+
+    spans: list[tuple[int, int]] = []
+    previous = 0
+    reference_ids: list[int] = []
+    for count in range(1, len(messages) + 1):
+        reference_ids = _coerce_ids(
+            model.tokenizer.apply_chat_template(messages[:count], tokenize=True, add_generation_prompt=False)
+        )
+        spans.append((previous, len(reference_ids)))
+        previous = len(reference_ids)
+
+    assert model.tok.message_partition(messages) == (reference_ids, spans)

{interp_engine-1.2.5 → interp_engine-1.2.7}/tests/test_freeze_set.py

@@ -8,6 +8,7 @@ import pytest
 import torch
 
 from interp_engine.address import Address
+from interp_engine.points import steer_refusal_reason
 from interp_engine.vllm_capture.freeze import (
     BREAKABLE_ENV,
     FREEZE_SKIP_ABSENT_ENV,
@@ -59,21 +60,22 @@ def test_empty_list_is_graphs_with_no_taps():
 def test_auto_is_resid_post_at_every_layer():
     reads, writes, graph = resolve_freeze_points("auto", n_layers=3, n_streams=1)
     assert graph is True
-    assert writes == []
     assert reads == [Address("resid_post", 0), Address("resid_post", 1), Address("resid_post", 2)]
+    assert writes == reads
 
 
 def test_enforce_eager_false_with_no_list_is_auto():
-    reads, _, graph = resolve_freeze_points(None, n_layers=2, n_streams=1, enforce_eager=False)
+    reads, writes, graph = resolve_freeze_points(None, n_layers=2, n_streams=1, enforce_eager=False)
     assert graph is True
     assert reads == [Address("resid_post", 0), Address("resid_post", 1)]
+    assert writes == reads, "the same set either way in; auto is auto however it was reached"
 
 
 def test_auto_is_resid_streams_on_a_hyper_connection_trunk():
     reads, writes, graph = resolve_freeze_points("auto", n_layers=3, n_streams=4)
     assert graph is True
-    assert writes == []
     assert reads == [Address("resid_streams", 0), Address("resid_streams", 1), Address("resid_streams", 2)]
+    assert writes == reads
 
 
 def test_resid_streams_can_be_frozen():
@@ -105,11 +107,69 @@ def test_explicit_mlp_out_is_allowed_on_a_hyper_connection_trunk():
     assert reads == [Address("mlp_out", 21)]
 
 
-def test_writes_are_not_implied_by_auto():
-    _, writes, _ = resolve_freeze_points("auto", n_layers=2, n_streams=1)
+def test_auto_writes_where_it_reads_so_a_read_out_can_be_intervened_on():
+    """The point of the change: an auto engine can steer at the addresses it captures.
+
+    Reads alone made the two halves of the residual endpoints disagree -- a lens read at layer 7
+    came back, and the steer, ablation or swap that read implies was refused for want of a site at
+    ``resid_post.7``, which was already tapped a few bytes away.
+    """
+    reads, writes, _ = resolve_freeze_points("auto", n_layers=2, n_streams=1)
+    assert writes == reads
+    assert writes == [Address("resid_post", 0), Address("resid_post", 1)]
+
+
+def test_an_explicit_read_list_still_implies_no_writes():
+    """Auto is a default, not a rewrite rule. A caller who named the points named all of them."""
+    reads, writes, _ = resolve_freeze_points([Address("resid_post", 1)], n_layers=4, n_streams=1)
+    assert reads == [Address("resid_post", 1)]
     assert writes == []
 
 
+def test_an_empty_write_list_asks_auto_for_the_reads_without_the_write_buffers():
+    """``[]`` and None have to part company here, and nowhere else in this signature.
+
+    This is the opt-out for the memory: write buffers are per layer and per token, so on a pod
+    where they would step ``max_num_batched_tokens`` down, a caller who only ever reads can say so.
+    """
+    reads, writes, graph = resolve_freeze_points("auto", n_layers=2, n_streams=1, freeze_writes=[])
+    assert graph is True
+    assert reads == [Address("resid_post", 0), Address("resid_post", 1)]
+    assert writes == []
+
+
+def test_an_empty_write_list_alone_is_still_not_a_reason_to_capture_graphs():
+    """Distinguishing ``[]`` from None must not turn ``freeze_writes=[]`` into a freeze request."""
+    reads, writes, graph = resolve_freeze_points(None, n_layers=2, n_streams=1, freeze_writes=[])
+    assert (reads, writes, graph) == ([], [], False)
+
+
+def test_a_named_write_is_not_joined_by_reads_it_did_not_ask_for():
+    reads, writes, graph = resolve_freeze_points(
+        None, n_layers=4, n_streams=1, freeze_writes=[Address("resid_post", 1)], enforce_eager=False
+    )
+    assert graph is True
+    assert reads == []
+    assert writes == [Address("resid_post", 1)]
+
+
+def test_a_generation_only_engine_gains_neither_half():
+    """``[]`` is graphs with no taps at all, and the auto write must not creep into it."""
+    reads, writes, graph = resolve_freeze_points([], n_layers=12, n_streams=1)
+    assert (reads, writes, graph) == ([], [], True)
+
+
+def test_the_auto_writes_on_a_stacked_trunk_are_ones_the_engine_agrees_are_writable():
+    """Auto now hands ``resid_streams`` to the write validation below, which used to see only reads.
+
+    A write set built by default has to clear the same bar as one a caller typed, or DeepSeek-V4
+    would refuse to load with `cannot freeze-write` from a set nobody asked for.
+    """
+    _, writes, _ = resolve_freeze_points("auto", n_layers=3, n_streams=4)
+    assert {a.name for a in writes} == {"resid_streams"}
+    assert all(steer_refusal_reason(a.name) is None for a in writes)
+
+
 def test_freeze_writes_without_reads_is_still_graph_mode():
     reads, writes, graph = resolve_freeze_points(
         None, n_layers=4, n_streams=1, freeze_writes=[Address("resid_post", 1)]