zaxy-memory 2.3.3__tar.gz → 2.3.4__tar.gz

{zaxy_memory-2.3.3 → zaxy_memory-2.3.4}/AGENTS.md

@@ -184,7 +184,7 @@ Run with coverage: `pytest --cov` (default in pyproject.toml)
 | Neo4j upsert | <100ms | MERGE + index lookup |
 | Hybrid query | <200ms | Parallel exact + keyword + traversal |
 | Total context retrieval | <300ms | End-to-end |
-| Token reduction vs. chunk RAG | 70–90% | Structured paths vs. raw text |
+| Token reduction vs. chunk RAG | 70–90% (target; unvalidated) | Structured paths vs. raw text. Validate with `scripts/chunk_rag_token_compare.py` — quality-controlled (token reduction at *equal answer-bearing recall*, pinned chunk-RAG baseline) — driven by a gold-labeled QA dataset through the gated benchmark. |
 
 ## Current Status
 

{zaxy_memory-2.3.3 → zaxy_memory-2.3.4}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable Zaxy release changes are recorded here.
 
+## 2.3.4 - 2026-06-14
+
+- **Opt-in full tool-I/O provenance (offload sink).** Default capture stays lean
+  (240-char excerpts, redacted args). With `ZAXY_OFFLOAD_TOOL_IO` enabled, the
+  full command output / tool arguments are also written to a content-addressed
+  blob under `<eventloom>/refs/`, and the lean event carries a `full_io_ref`
+  (`{ref, sha256, bytes}`). The blob id *is* its sha256 and lives inside the
+  Eventloom directory, so it is self-contained and tamper-evident (unlike the
+  foreign `codex_source_ref` pointers, which the hash chain can't attest to).
+  Context and `memory_checkout` still see only the summary; drill down on demand
+  with `zaxy offload-get <sha256>`. Arguments are secret-masked before offload.
+  This closes the provenance gap on tool I/O without touching token leanness.
+- **Chunk-RAG token-reduction methodology** (`scripts/chunk_rag_token_compare.py`):
+  a quality-controlled harness that measures token reduction at *equal
+  answer-bearing recall* against a pinned chunk-RAG baseline, so the AGENTS.md
+  "70–90% vs chunk RAG" figure can be validated (it is now labeled an unvalidated
+  target pending a gated QA-dataset run) instead of asserted.
+
 ## 2.3.3 - 2026-06-13
 
 - Extended deterministic per-turn memory injection to **Codex**. Codex now ships

{zaxy_memory-2.3.3 → zaxy_memory-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zaxy-memory
-Version: 2.3.3
+Version: 2.3.4
 Summary: Coordinator memory for auditable multi-agent projects
 Project-URL: Homepage, https://syndicalt.github.io/zaxy/
 Project-URL: Documentation, https://syndicalt.github.io/zaxy/docs/getting-started.html

{zaxy_memory-2.3.3 → zaxy_memory-2.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zaxy-memory"
-version = "2.3.3"
+version = "2.3.4"
 description = "Coordinator memory for auditable multi-agent projects"
 readme = "README.md"
 requires-python = ">=3.11"

zaxy_memory-2.3.4/scripts/chunk_rag_token_compare.py

@@ -0,0 +1,166 @@
+"""Quality-controlled token-reduction methodology: structured cited memory vs chunk-RAG.
+
+Dev target #2: the AGENTS.md Performance-Targets table states "Token reduction vs
+chunk RAG: 70-90% (structured paths vs raw text)". That is an *unvalidated target*.
+This module is the reproducible methodology to validate (or correct) it.
+
+The trap this avoids: a raw token ratio is meaningless, because you can always
+"save tokens" by retrieving less and answering worse. So every comparison is
+**quality-controlled** — measured at EQUAL ANSWER-BEARING RECALL: both arms must
+surface the gold answer span, and we count the tokens each needs to get there.
+
+  reduction = 1 - structured_tokens / chunkrag_tokens   (over cases where BOTH reach gold)
+
+The chunk-RAG baseline is pinned and reported (chunk size, ranking) so the ratio
+is not gameable by quietly weakening the baseline.
+
+Run `python3 scripts/chunk_rag_token_compare.py` for a self-test on a worked
+example. To produce a *publishable* number, drive `compare_corpus()` with a real
+QA dataset (e.g. LongMemEval) through the gated benchmark apparatus; the headline
+number depends on workload and must be reported with both.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+# Prefer a real BPE tokenizer when available (benchmark runs), but stay
+# dependency-free otherwise: the methodology only needs a *consistent* tokenizer,
+# since it compares token counts at equal recall between two arms.
+_encode: Callable[[str], list]
+_decode: Callable[[list], str]
+try:  # pragma: no cover - depends on optional install
+    import tiktoken
+
+    _ENC = tiktoken.get_encoding("cl100k_base")
+    _encode = _ENC.encode
+    _decode = _ENC.decode
+    TOKENIZER = "tiktoken/cl100k_base"
+except Exception:  # noqa: BLE001 - any import/runtime failure -> fallback
+    _encode = lambda s: s.split()  # noqa: E731 - whitespace tokens
+    _decode = lambda t: " ".join(t)  # noqa: E731
+    TOKENIZER = "whitespace-fallback"
+
+DEFAULT_CHUNK_TOKENS = 512
+
+
+def tokens(text: str) -> int:
+    return len(_encode(text))
+
+
+def chunk_text(text: str, chunk_tokens: int = DEFAULT_CHUNK_TOKENS) -> list[str]:
+    toks = _encode(text)
+    return [_decode(toks[i : i + chunk_tokens]) for i in range(0, len(toks), chunk_tokens)]
+
+
+def _kw(text: str) -> list[str]:
+    return re.findall(r"\w+", text.lower())
+
+
+def _score(passage: str, query: str) -> int:
+    q = set(_kw(query))
+    return sum(1 for w in _kw(passage) if w in q)
+
+
+def _tokens_to_gold(passages: list[str], query: str, gold: str) -> tuple[int, bool]:
+    """Greedily accumulate the highest-scoring passages until gold appears.
+
+    Returns (tokens_used, reached_gold). Pure keyword ranking — a standard,
+    embedding-free chunk-RAG baseline (note: vector-RAG could differ).
+    """
+    ranked = sorted(passages, key=lambda p: -_score(p, query))
+    used: list[str] = []
+    total = 0
+    gold_l = gold.lower()
+    for p in ranked:
+        used.append(p)
+        total += tokens(p)
+        if gold_l in " ".join(used).lower():
+            return total, True
+    return total, False
+
+
+@dataclass
+class CaseResult:
+    query: str
+    structured_tokens: int
+    chunkrag_tokens: int
+    both_reached: bool
+
+    @property
+    def reduction(self) -> float | None:
+        if not self.both_reached or self.chunkrag_tokens == 0:
+            return None
+        return 1 - self.structured_tokens / self.chunkrag_tokens
+
+
+def compare_case(
+    *, query: str, gold: str, facts: list[str], raw_text: str, chunk_tokens: int = DEFAULT_CHUNK_TOKENS
+) -> CaseResult:
+    """One query: structured-cited retrieval vs chunk-RAG over raw_text, at equal recall."""
+    s_tok, s_ok = _tokens_to_gold(facts, query, gold)
+    c_tok, c_ok = _tokens_to_gold(chunk_text(raw_text, chunk_tokens), query, gold)
+    return CaseResult(query, s_tok, c_tok, s_ok and c_ok)
+
+
+def compare_corpus(cases: list[dict], *, chunk_tokens: int = DEFAULT_CHUNK_TOKENS) -> dict:
+    """Run a corpus of {query, gold, facts, raw_text} cases. Returns aggregate stats.
+
+    Only cases where BOTH arms reach gold count toward the reduction (equal recall).
+    """
+    results = [compare_case(chunk_tokens=chunk_tokens, **c) for c in cases]
+    scored = [r for r in results if r.reduction is not None]
+    reductions = [r.reduction for r in scored]
+    return {
+        "baseline": {
+            "chunk_tokens": chunk_tokens,
+            "ranking": "keyword-overlap (embedding-free)",
+            "tokenizer": TOKENIZER,
+        },
+        "cases_total": len(results),
+        "cases_equal_recall": len(scored),
+        "median_reduction": (sorted(reductions)[len(reductions) // 2] if reductions else None),
+        "mean_reduction": (sum(reductions) / len(reductions) if reductions else None),
+        "per_case": [
+            {"query": r.query, "structured_tok": r.structured_tokens,
+             "chunkrag_tok": r.chunkrag_tokens, "reduction": r.reduction}
+            for r in results
+        ],
+    }
+
+
+def _self_test_corpus() -> list[dict]:
+    """A worked example: a fact buried in verbose tool/dialogue text vs a compact card.
+
+    Illustrative only — the magnitude depends on raw verbosity, which is exactly why
+    a real run needs a QA dataset + the gated apparatus.
+    """
+    noise = ("INFO build step ok; cache warm; 0 warnings; retrying; " * 60)
+    raw = (
+        noise
+        + " The team decided the canonical session id is zaxy-default and froze the legacy zaxy session. "
+        + noise
+        + " Unrelated: the default graph backend for beta is Neo4j. "
+        + noise
+    )
+    facts = [
+        "[decision] canonical session id = zaxy-default; legacy 'zaxy' frozen. (eventloom://zaxy-default/events/77848)",
+        "[decision] default graph backend (beta) = Neo4j. (eventloom://zaxy-default/events/1200)",
+        "[goal] ship per-turn memory injection. (eventloom://zaxy-default/events/77889)",
+    ]
+    return [
+        {"query": "which session id is canonical", "gold": "zaxy-default", "facts": facts, "raw_text": raw},
+        {"query": "default graph backend for beta", "gold": "Neo4j", "facts": facts, "raw_text": raw},
+    ]
+
+
+if __name__ == "__main__":
+    import json
+
+    out = compare_corpus(_self_test_corpus())
+    print(json.dumps(out, indent=2))
+    print("\nNOTE: self-test is illustrative. A publishable 'X% vs chunk-RAG' number "
+          "requires driving compare_corpus() with a real QA dataset (gold-labeled) "
+          "through the freeze/gate/audit apparatus, reported with workload + baseline.")

{zaxy_memory-2.3.3 → zaxy_memory-2.3.4}/src/zaxy/cli/workspace.py

@@ -595,6 +595,7 @@ def hook_event(
             duration_ms=duration_ms,
             stdout=stdout,
             stderr=stderr,
+            eventloom_path=eventloom_path,
         )
         event = eventlog.append(
             event_input["event_type"],
@@ -648,6 +649,7 @@ def hook_event(
             call_id=call_id,
             arguments=arguments,
             result_summary=result_summary,
+            eventloom_path=eventloom_path,
         )
         event = eventlog.append(
             event_input["event_type"],
@@ -710,6 +712,22 @@ def hook_event(
         typer.echo(render_recovery_packet(packet))
 
 
+@app.command("offload-get")
+def offload_get(
+    sha256: str = typer.Argument(..., help="sha256 id from a full_io_ref pointer"),  # noqa: B008
+    eventloom_path: str = typer.Option(".eventloom", help="Eventloom directory holding refs/"),
+) -> None:
+    """Drill down to the full offloaded tool I/O behind a `full_io_ref` sha256."""
+    from zaxy.offload import read_offload_ref
+
+    content = read_offload_ref(eventloom_path, sha256)
+    if content is None:
+        raise typer.BadParameter(
+            f"no offload blob for {sha256} under {eventloom_path}/refs (missing or integrity mismatch)"
+        )
+    typer.echo(content, nl=False)
+
+
 def _resolve_cli_projection_backend(
     projection_backend: str | None,
     settings: Settings,

{zaxy_memory-2.3.3 → zaxy_memory-2.3.4}/src/zaxy/observation.py

@@ -11,6 +11,11 @@ from zaxy.lifecycle import (
     build_file_edit_applied_event,
     build_tool_call_completed_event,
 )
+from zaxy.offload import (
+    offload_command_output,
+    offload_tool_arguments,
+    tool_io_offload_enabled,
+)
 from zaxy.security import secure_payload
 
 SECRET_ARG_PATTERN = re.compile(
@@ -29,8 +34,14 @@ def build_command_observation(
     duration_ms: int | None = None,
     stdout: str = "",
     stderr: str = "",
+    eventloom_path: str | None = None,
 ) -> dict[str, Any]:
-    """Build a normalized command observation for automatic capture."""
+    """Build a normalized command observation for automatic capture.
+
+    The event stays lean (bounded excerpts) by default. When tool-I/O offload is
+    opted in (and ``eventloom_path`` is provided), the full output is also written
+    to a content-addressed ref and pointed to via ``full_io_ref``.
+    """
     event = build_command_completed_event(
         command=_redact_command(command),
         exit_code=exit_code,
@@ -43,6 +54,10 @@ def build_command_observation(
     event["payload"]["source"] = source
     if workspace:
         event["payload"]["workspace"] = workspace
+    if eventloom_path and tool_io_offload_enabled():
+        ref = offload_command_output(eventloom_path, stdout=stdout, stderr=stderr)
+        if ref is not None:
+            event["payload"]["full_io_ref"] = ref
     return event
 
 
@@ -83,8 +98,14 @@ def build_tool_call_observation(
     call_id: str | None = None,
     arguments: dict[str, Any] | None = None,
     result_summary: str | None = None,
+    eventloom_path: str | None = None,
 ) -> dict[str, Any]:
-    """Build a normalized tool-call observation without raw argument values."""
+    """Build a normalized tool-call observation without raw argument values.
+
+    Default keeps only ``argument_keys`` (values dropped). When tool-I/O offload is
+    opted in, the full (secret-masked) arguments are also written to a
+    content-addressed ref and pointed to via ``full_io_ref``.
+    """
     event = build_tool_call_completed_event(
         tool_name=tool_name,
         status=status,
@@ -97,6 +118,10 @@ def build_tool_call_observation(
     event["payload"]["source"] = source
     if workspace:
         event["payload"]["workspace"] = workspace
+    if eventloom_path and tool_io_offload_enabled() and arguments:
+        ref = offload_tool_arguments(eventloom_path, arguments)
+        if ref is not None:
+            event["payload"]["full_io_ref"] = ref
     return event
 
 

zaxy_memory-2.3.4/src/zaxy/offload.py

@@ -0,0 +1,108 @@
+"""Opt-in, Eventloom-owned content-addressed store for full tool I/O.
+
+Default capture stays lean: ``tool.call.completed`` keeps only ``argument_keys``,
+and ``command.completed`` truncates output to ``OUTPUT_EXCERPT_CHARS``. That keeps
+the log token-cheap and never persists secret argument values -- good defaults,
+but it caps the "full, replayable provenance" thesis for tool I/O.
+
+When ``ZAXY_OFFLOAD_TOOL_IO`` is enabled, the *full* text is additionally written
+to a content-addressed blob under ``<eventloom>/refs/`` and the lean event carries
+a ``full_io_ref`` pointer ``{ref, sha256, bytes}``. Properties:
+
+- **Self-contained & tamper-evident.** The blob id *is* its sha256, and it lives
+  inside the Eventloom directory -- unlike ``codex_source_ref``, which points at
+  foreign Codex rollout files the hash chain can't attest to.
+- **Lean by default.** Context / ``memory_checkout`` still see only the summary;
+  the full text is fetched on demand (drill-down) by sha.
+- **Privacy preserved.** Opt-in, and tool arguments are still secret-masked before
+  offload (values under secret-looking keys are dropped).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+OFFLOAD_ENV = "ZAXY_OFFLOAD_TOOL_IO"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+# Mask argument values whose KEY name looks secret-bearing.
+_SECRET_KEY = re.compile(
+    r"(?i)(?:api[-_]?key|authorization|bearer|cookie|credential|password|private[-_]?key|secret|token)"
+)
+
+
+def tool_io_offload_enabled() -> bool:
+    """True when full tool-I/O retention is opted in via env."""
+    return os.environ.get(OFFLOAD_ENV, "").strip().lower() in _TRUTHY
+
+
+def redact_secret_args(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Return args with secret-looking values masked, others preserved verbatim."""
+    return {
+        key: ("<redacted>" if _SECRET_KEY.search(str(key)) else value)
+        for key, value in arguments.items()
+    }
+
+
+def _refs_root(eventloom_path: str | Path) -> Path:
+    base = Path(eventloom_path)
+    if base.suffix == ".jsonl":
+        base = base.parent
+    return base / "refs"
+
+
+def _blob_path(eventloom_path: str | Path, sha256: str) -> Path:
+    return _refs_root(eventloom_path) / sha256[:2] / f"{sha256}.blob"
+
+
+def write_offload_ref(eventloom_path: str | Path, content: str) -> dict[str, Any]:
+    """Content-address ``content`` under ``<eventloom>/refs/`` and return a pointer.
+
+    Idempotent: identical content yields an identical ref, written once.
+    """
+    data = content.encode("utf-8")
+    sha = hashlib.sha256(data).hexdigest()
+    blob = _blob_path(eventloom_path, sha)
+    if not blob.exists():
+        blob.parent.mkdir(parents=True, exist_ok=True)
+        blob.write_bytes(data)
+    return {"ref": f"refs/{sha[:2]}/{sha}.blob", "sha256": sha, "bytes": len(data)}
+
+
+def read_offload_ref(eventloom_path: str | Path, sha256: str) -> str | None:
+    """Read a blob back by sha, verifying integrity. Returns None if missing/tampered."""
+    blob = _blob_path(eventloom_path, sha256)
+    if not blob.exists():
+        return None
+    data = blob.read_bytes()
+    if hashlib.sha256(data).hexdigest() != sha256:
+        return None  # tamper-evident: id must equal content hash
+    return data.decode("utf-8")
+
+
+def offload_command_output(
+    eventloom_path: str | Path, *, stdout: str, stderr: str
+) -> dict[str, Any] | None:
+    """Offload full command output when it exceeds the inline excerpt. Else None."""
+    from zaxy.lifecycle import OUTPUT_EXCERPT_CHARS
+
+    if len(stdout) <= OUTPUT_EXCERPT_CHARS and len(stderr) <= OUTPUT_EXCERPT_CHARS:
+        return None
+    full = f"=== stdout ===\n{stdout}\n=== stderr ===\n{stderr}" if stderr else stdout
+    return write_offload_ref(eventloom_path, full)
+
+
+def offload_tool_arguments(
+    eventloom_path: str | Path, arguments: dict[str, Any]
+) -> dict[str, Any] | None:
+    """Offload full tool arguments (secret-masked) for provenance. Else None."""
+    if not arguments:
+        return None
+    masked = redact_secret_args(arguments)
+    full = json.dumps(masked, ensure_ascii=False, sort_keys=True)
+    return write_offload_ref(eventloom_path, full)

zaxy_memory-2.3.4/tests/test_chunk_rag_methodology.py

@@ -0,0 +1,51 @@
+"""Tests for the chunk-RAG token-reduction methodology (dev target #2).
+
+These assert the METHODOLOGY is sound (equal-recall enforced; structured beats
+raw when a fact is buried in noise; baseline pinned) -- not a specific headline
+number, which requires a real QA dataset + the gated apparatus.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+
+from chunk_rag_token_compare import _self_test_corpus, compare_case, compare_corpus  # noqa: E402
+
+
+def test_equal_recall_excludes_cases_where_an_arm_misses_gold() -> None:
+    # gold appears in raw text but in NO structured fact -> structured can't reach it
+    r = compare_case(
+        query="where is the gold",
+        gold="UNIQUEGOLD",
+        facts=["[note] nothing relevant here", "[note] also irrelevant"],
+        raw_text="filler filler UNIQUEGOLD filler",
+    )
+    assert r.both_reached is False
+    assert r.reduction is None  # excluded from the ratio -> not gameable by asymmetric recall
+
+
+def test_structured_beats_raw_when_fact_is_buried() -> None:
+    out = compare_corpus(_self_test_corpus())
+    assert out["cases_equal_recall"] == out["cases_total"]  # both arms find every gold
+    # at equal recall, the compact cited card costs fewer tokens than chunk-RAG over noise
+    assert out["median_reduction"] is not None and out["median_reduction"] > 0
+    for case in out["per_case"]:
+        assert case["structured_tok"] < case["chunkrag_tok"]
+
+
+def test_baseline_is_pinned_and_reported() -> None:
+    out = compare_corpus(_self_test_corpus(), chunk_tokens=256)
+    assert out["baseline"]["chunk_tokens"] == 256
+    assert "keyword" in out["baseline"]["ranking"]
+
+
+def test_reduction_is_quality_controlled_definition() -> None:
+    # reduction is defined only over equal-recall cases; a no-recall corpus yields None
+    out = compare_corpus([
+        {"query": "q", "gold": "ZZZ", "facts": ["irrelevant"], "raw_text": "also irrelevant"}
+    ])
+    assert out["cases_equal_recall"] == 0
+    assert out["median_reduction"] is None

zaxy_memory-2.3.4/tests/test_offload.py

@@ -0,0 +1,120 @@
+"""Tests for opt-in Eventloom-owned tool-I/O offload (dev target #1)."""
+
+from __future__ import annotations
+
+import json
+
+from typer.testing import CliRunner
+
+from zaxy.__main__ import app
+from zaxy.lifecycle import OUTPUT_EXCERPT_CHARS
+from zaxy.observation import build_command_observation, build_tool_call_observation
+from zaxy.offload import read_offload_ref, redact_secret_args, write_offload_ref
+
+runner = CliRunner()
+
+BIG = "X" * (OUTPUT_EXCERPT_CHARS * 4)  # comfortably past the inline excerpt
+
+
+# ---- default (disabled) keeps the lean behavior unchanged ------------------
+
+def test_command_lean_when_offload_disabled(tmp_path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.delenv("ZAXY_OFFLOAD_TOOL_IO", raising=False)
+    ev = build_command_observation(
+        command="echo hi", exit_code=0, session_id="s", source="test",
+        stdout=BIG, stderr="", eventloom_path=str(tmp_path / ".eventloom"),
+    )
+    assert "full_io_ref" not in ev["payload"]
+    assert len(ev["payload"]["stdout_excerpt"]) == OUTPUT_EXCERPT_CHARS
+
+
+def test_tool_call_lean_when_offload_disabled(tmp_path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.delenv("ZAXY_OFFLOAD_TOOL_IO", raising=False)
+    ev = build_tool_call_observation(
+        tool_name="t", status="succeeded", session_id="s", source="test",
+        arguments={"q": "secret-value"}, eventloom_path=str(tmp_path / ".eventloom"),
+    )
+    assert "full_io_ref" not in ev["payload"]
+    assert ev["payload"]["arguments_redacted"] is True
+    assert ev["payload"]["argument_keys"] == ["q"]
+
+
+# ---- enabled: offload writes a recoverable, integrity-checked ref ----------
+
+def test_command_offload_when_enabled(tmp_path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.setenv("ZAXY_OFFLOAD_TOOL_IO", "1")
+    el = str(tmp_path / ".eventloom")
+    ev = build_command_observation(
+        command="run", exit_code=0, session_id="s", source="test",
+        stdout=BIG, stderr="boom", eventloom_path=el,
+    )
+    ref = ev["payload"]["full_io_ref"]
+    assert set(ref) == {"ref", "sha256", "bytes"}
+    # summary stays lean
+    assert len(ev["payload"]["stdout_excerpt"]) == OUTPUT_EXCERPT_CHARS
+    # full content recoverable and complete
+    full = read_offload_ref(el, ref["sha256"])
+    assert full is not None and BIG in full and "boom" in full
+
+
+def test_tool_args_offload_masks_secrets(tmp_path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.setenv("ZAXY_OFFLOAD_TOOL_IO", "true")
+    el = str(tmp_path / ".eventloom")
+    ev = build_tool_call_observation(
+        tool_name="t", status="ok", session_id="s", source="test",
+        arguments={"query": "keep me", "api_key": "sk-SECRET", "token": "abc"},
+        eventloom_path=el,
+    )
+    ref = ev["payload"]["full_io_ref"]
+    stored = json.loads(read_offload_ref(el, ref["sha256"]))
+    assert stored["query"] == "keep me"          # non-secret preserved
+    assert stored["api_key"] == "<redacted>"     # secret-keyed masked
+    assert stored["token"] == "<redacted>"
+
+
+def test_short_output_no_ref_even_when_enabled(tmp_path, monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    monkeypatch.setenv("ZAXY_OFFLOAD_TOOL_IO", "1")
+    ev = build_command_observation(
+        command="echo hi", exit_code=0, session_id="s", source="test",
+        stdout="short", stderr="", eventloom_path=str(tmp_path / ".eventloom"),
+    )
+    assert "full_io_ref" not in ev["payload"]  # nothing beyond the excerpt to keep
+
+
+# ---- content addressing + tamper-evidence ----------------------------------
+
+def test_content_addressing_idempotent(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    el = str(tmp_path / ".eventloom")
+    a = write_offload_ref(el, "same content")
+    b = write_offload_ref(el, "same content")
+    assert a == b  # identical content -> identical ref, written once
+
+
+def test_tamper_evident_read(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    el = tmp_path / ".eventloom"
+    ref = write_offload_ref(str(el), "trustworthy")
+    blob = el / ref["ref"]
+    blob.write_text("tampered", encoding="utf-8")  # corrupt the blob
+    assert read_offload_ref(str(el), ref["sha256"]) is None  # id no longer matches content
+
+
+def test_redact_secret_args_unit() -> None:
+    out = redact_secret_args({"password": "p", "name": "ok", "AUTHORIZATION": "z"})
+    assert out == {"password": "<redacted>", "name": "ok", "AUTHORIZATION": "<redacted>"}
+
+
+# ---- drill-down CLI ---------------------------------------------------------
+
+def test_offload_get_cli_roundtrip(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    el = str(tmp_path / ".eventloom")
+    ref = write_offload_ref(el, "full output here")
+    result = runner.invoke(app, ["offload-get", ref["sha256"], "--eventloom-path", el])
+    assert result.exit_code == 0
+    assert result.stdout == "full output here"
+
+
+def test_offload_get_cli_missing(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    result = runner.invoke(
+        app, ["offload-get", "0" * 64, "--eventloom-path", str(tmp_path / ".eventloom")]
+    )
+    assert result.exit_code != 0