arcaeon-compact 0.1.0__py3-none-any.whl

arcaeon_compact/__init__.py

@@ -0,0 +1,376 @@
+"""arcaeon_compact — tamper-evident receipts for context compaction.
+
+When an agent compacts context — summarizes a conversation, prunes memory,
+truncates history — nothing, today, proves what was dropped. The summary says
+"nothing important was lost" and you take its word. A CompactionReceipt fixes
+the provable part: a hash-chained record binding
+
+  - a digest of the FULL pre-compaction content,
+  - a digest of the post-compaction SURVIVOR,
+  - a drop-manifest: per-dropped-item digests + count + byte totals
+    (digests only, NEVER content — privacy by construction),
+  - the compactor's identity string + method label,
+  - a timestamp,
+
+appended as one row to an `arcaeon-ledger` chain, so the receipt itself is
+tamper-evident and ordered against every other receipt.
+
+Three calls:
+
+    from arcaeon_compact import CompactionReceipt, verify_receipt
+
+    receipt = CompactionReceipt.open(pre_content)     # list[str | bytes | dict]
+    receipt.record_kept(post_content)                 # dropped inferred by digest
+    row = receipt.seal("receipts.jsonl", compactor="summarizer-v2",
+                       method="llm-summary")
+
+    verify_receipt(row)                               # self-consistency, always
+    verify_receipt(row, pre_content, post_content)    # recompute + compare
+
+WHAT IT PROVES, AND WHAT IT DOESN'T — the boundary is the product:
+
+  1. It proves WHAT was dropped, never that dropping was WISE. The receipt has
+     no opinion on salience. A compactor that keeps the pleasantries and drops
+     the wire-transfer instructions gets a perfectly valid receipt saying
+     exactly that.
+  2. It proves the compactor's CLAIM about its inputs, not that the inputs were
+     complete (the gateway problem). If content was withheld before `open()`
+     ever saw it, the receipt faithfully notarizes the partial view. The
+     receipt binds what crossed the gate, not what existed behind it.
+  3. Digests only means content is NOT recoverable from the receipt. Feature:
+     dropped secrets don't leak into the audit trail. Limitation: you can
+     prove an item you still HOLD was dropped (hash it, find it in the
+     manifest); you cannot resurrect an item you lost.
+
+Stdlib + arcaeon-ledger only. MIT.
+"""
+from __future__ import annotations
+
+import json
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+from arcaeon_ledger import Ledger, digest_bytes, digest_json
+
+__version__ = "0.1.0"
+__all__ = ["CompactionReceipt", "verify_receipt", "SCHEMA"]
+
+# The receipt schema label, frozen at v1. A future shape change mints v2;
+# old rows keep v1 forever, so a schema drift never reads history as tampered.
+SCHEMA = "arcaeon-compact:receipt:v1"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _digest_item(item: Any) -> tuple[str, int]:
+    """(self-describing digest, byte length) for one content item.
+
+    The type rule is part of the v1 schema — frozen, so a stranger can
+    reproduce any manifest entry from content they hold:
+
+      bytes / bytearray -> raw-bytes digest of the bytes, as-is
+      str               -> raw-bytes digest of the UTF-8 encoding
+      anything else     -> json-c14n digest of the canonicalized value
+                           (arcaeon-ledger's pinned recipe: sorted keys,
+                           compact separators, UTF-8, NaN rejected)
+
+    Digests are always self-describing (`sha256:<recipe>:<ver>:<hex>`) —
+    never a bare hex hash — so each manifest entry carries its own recipe.
+    """
+    if isinstance(item, (bytes, bytearray)):
+        b = bytes(item)
+        return digest_bytes(b), len(b)
+    if isinstance(item, str):
+        b = item.encode("utf-8")
+        return digest_bytes(b), len(b)
+    canon = json.dumps(item, sort_keys=True, separators=(",", ":"),
+                       ensure_ascii=False, allow_nan=False).encode("utf-8")
+    return digest_json(item), len(canon)
+
+
+def _digest_content(items: Iterable[Any]) -> tuple[list[str], list[int], str, int]:
+    """Digest a content list: (per-item digests, per-item bytes, whole, total).
+
+    The WHOLE digest is `digest_json` over the ordered list of per-item digest
+    strings — a digest of digests. Deterministic, order-sensitive, and
+    recomputable from content alone, without ever storing content.
+    """
+    digests: list[str] = []
+    sizes: list[int] = []
+    for it in items:
+        d, n = _digest_item(it)
+        digests.append(d)
+        sizes.append(n)
+    return digests, sizes, digest_json(digests), sum(sizes)
+
+
+def _well_formed(digest: str) -> bool:
+    """A self-describing digest has exactly 4 colon-parts with a hex tail."""
+    parts = digest.split(":") if isinstance(digest, str) else []
+    if len(parts) != 4 or not all(parts):
+        return False
+    try:
+        int(parts[3], 16)
+    except ValueError:
+        return False
+    return True
+
+
+class CompactionReceipt:
+    """One compaction event, opened on the full content, sealed to a ledger.
+
+    Lifecycle: `open(pre)` -> `record_kept(post)` [-> `record_dropped(items)`]
+    -> `seal(...)`. After seal the receipt is immutable; recording or sealing
+    again raises. `record_dropped` is optional — the drop set is inferred as
+    pre-minus-kept by digest (multiset, duplicates counted); if you do record
+    it explicitly, seal() reconciles your claim against the inference and
+    refuses to notarize a receipt that disagrees with itself.
+    """
+
+    def __init__(self, *_a: Any, **_k: Any):
+        raise TypeError("use CompactionReceipt.open(pre_content)")
+
+    @classmethod
+    def open(cls, pre_content: Sequence[Any]) -> "CompactionReceipt":
+        """Digest every pre-compaction item + the whole; start the receipt."""
+        self = object.__new__(cls)
+        self._pre_digests, self._pre_sizes, self._pre_whole, self._pre_bytes = \
+            _digest_content(pre_content)
+        self._opened_at = _now_iso()
+        self._post: tuple[list[str], list[int], str, int] | None = None
+        self._dropped_explicit: list[str] | None = None
+        self._sealed_row: dict | None = None
+        return self
+
+    def _require_unsealed(self) -> None:
+        if self._sealed_row is not None:
+            raise RuntimeError("receipt already sealed; open a new one")
+
+    def record_kept(self, post_content: Sequence[Any]) -> None:
+        """Digest the post-compaction survivor content."""
+        self._require_unsealed()
+        self._post = _digest_content(post_content)
+
+    def record_dropped(self, items: Sequence[Any]) -> None:
+        """Explicitly claim the dropped items (optional; else inferred).
+
+        seal() checks this claim against pre-minus-kept and raises on any
+        disagreement — the receipt never notarizes an inconsistent claim.
+        """
+        self._require_unsealed()
+        self._dropped_explicit = [_digest_item(it)[0] for it in items]
+
+    def seal(self, ledger_path: str | Path, *, compactor: str,
+             method: str) -> dict:
+        """Append the receipt row to an arcaeon-ledger chain; return the row.
+
+        `compactor` is the identity string of whatever did the compacting
+        (an agent id, a model name, a service); `method` labels how
+        ("llm-summary", "fifo-truncate", "salience-prune", ...). Both are
+        claims, bound tamper-evidently — the chain proves they weren't edited
+        after the fact, not that they were true when written.
+        """
+        self._require_unsealed()
+        if self._post is None:
+            raise ValueError(
+                "seal() before record_kept() — record the survivor first "
+                "(an empty list is a valid survivor: everything was dropped)")
+        post_digests, _post_sizes, post_whole, post_bytes = self._post
+
+        # Inferred drop set: pre minus kept, as a multiset over digests, in
+        # pre order. Duplicates count: keeping one copy of a twice-seen item
+        # still drops the other.
+        remaining = Counter(post_digests)
+        dropped: list[str] = []
+        dropped_bytes = 0
+        for d, n in zip(self._pre_digests, self._pre_sizes):
+            if remaining[d] > 0:
+                remaining[d] -= 1
+            else:
+                dropped.append(d)
+                dropped_bytes += n
+        # Whatever the survivor holds that pre never did was INTRODUCED by the
+        # compactor (the summary text itself, typically).
+        introduced = sum(remaining.values())
+
+        if self._dropped_explicit is not None and \
+                Counter(self._dropped_explicit) != Counter(dropped):
+            raise ValueError(
+                "record_dropped() claim disagrees with pre-minus-kept "
+                f"(claimed {len(self._dropped_explicit)} item(s), inferred "
+                f"{len(dropped)}); refusing to seal an inconsistent receipt")
+
+        body = {
+            "schema": SCHEMA,
+            "pre": {"count": len(self._pre_digests), "bytes": self._pre_bytes,
+                    "digest": self._pre_whole},
+            "post": {"count": len(post_digests), "bytes": post_bytes,
+                     "digest": post_whole},
+            "dropped": {"count": len(dropped), "bytes": dropped_bytes,
+                        "items": dropped},
+            "introduced": {"count": introduced},
+            "compactor": compactor,
+            "method": method,
+        }
+        row = dict(body)
+        row["kind"] = "compaction_receipt"
+        row["opened_at"] = self._opened_at
+        # The receipt digest covers the deterministic core (body) only — not
+        # timestamps or the chain — so it is reproducible from content alone
+        # and a receipt row stays checkable even copied OUT of its ledger.
+        row["receipt_digest"] = digest_json(body)
+        row["ts"] = _now_iso()
+        row["chain"] = Ledger(ledger_path).append(row)
+        self._sealed_row = row
+        return row
+
+
+def _core_body(row: dict) -> dict:
+    """The deterministic core the receipt_digest covers."""
+    return {k: row.get(k) for k in
+            ("schema", "pre", "post", "dropped", "introduced",
+             "compactor", "method")}
+
+
+def verify_receipt(row: dict, pre_content: Sequence[Any] | None = None,
+                   post_content: Sequence[Any] | None = None) -> dict:
+    """Verify a receipt row. Self-consistency always; recompute if given content.
+
+    Self-consistency (no content needed): schema known, every digest
+    well-formed, the counts add up (pre = kept + dropped, post = kept +
+    introduced), the manifest length matches its count, and the
+    receipt_digest reproduces from the row's own core — so an edited row is
+    caught even when it's been copied out of its ledger. (Inside a ledger the
+    chain catches the same edit; this check travels with the row.)
+
+    With `pre_content` and/or `post_content`: recompute the digests from the
+    content you hold and compare. With BOTH, the drop set itself is
+    recomputed (pre minus post, by digest) and compared against the manifest
+    — a receipt that claims nothing was dropped while something was, fails
+    here by construction.
+
+    Returns:
+        {"ok": bool,                       # self_consistent AND content didn't mismatch
+         "self_consistent": bool,
+         "content": "skipped" | "match" | "mismatch",
+         "notes": [<str>, ...]}
+
+    What a pass MEANS, exactly: the row is internally coherent and, if you
+    provided content, that content reproduces the claim. It does not mean the
+    drop was wise, and it does not mean the pre-content the compactor showed
+    the receipt was everything that existed (the gateway problem).
+    """
+    notes: list[str] = []
+    out = {"ok": False, "self_consistent": False, "content": "skipped",
+           "notes": notes}
+
+    # --- self-consistency ---------------------------------------------------
+    sc = True
+    if row.get("schema") != SCHEMA:
+        notes.append(f"unknown schema {row.get('schema')!r} — cannot verify")
+        return out
+    try:
+        pre, post, dropped = row["pre"], row["post"], row["dropped"]
+        introduced = row["introduced"]
+        counts = (pre["count"], post["count"], dropped["count"],
+                  introduced["count"], pre["bytes"], post["bytes"],
+                  dropped["bytes"])
+        manifest = dropped["items"]
+    except (KeyError, TypeError) as e:
+        notes.append(f"malformed receipt row: missing {e}")
+        return out
+    if not all(isinstance(c, int) and c >= 0 for c in counts):
+        sc = False
+        notes.append("counts/bytes must be non-negative integers")
+    for label, d in [("pre.digest", pre.get("digest")),
+                     ("post.digest", post.get("digest")),
+                     ("receipt_digest", row.get("receipt_digest"))] + \
+                    [(f"dropped.items[{i}]", d) for i, d in enumerate(manifest)]:
+        if not _well_formed(d):
+            sc = False
+            notes.append(f"{label} is not a well-formed self-describing digest")
+    if len(manifest) != dropped["count"]:
+        sc = False
+        notes.append(f"manifest length {len(manifest)} != dropped.count "
+                     f"{dropped['count']}")
+    kept = pre["count"] - dropped["count"]
+    if kept < 0:
+        sc = False
+        notes.append("dropped.count exceeds pre.count")
+    elif post["count"] - introduced["count"] != kept:
+        sc = False
+        notes.append("counts do not reconcile: post - introduced != pre - dropped")
+    if row.get("receipt_digest") != digest_json(_core_body(row)):
+        sc = False
+        notes.append("receipt_digest does not reproduce from the row's core "
+                     "— the row was altered")
+    out["self_consistent"] = sc
+
+    # --- content recomputation ----------------------------------------------
+    mismatch = False
+    checked = False
+    pre_digests = pre_sizes = None
+    if pre_content is not None:
+        checked = True
+        pre_digests, pre_sizes, whole, total = _digest_content(pre_content)
+        for label, got, want in [("pre.digest", whole, pre.get("digest")),
+                                 ("pre.count", len(pre_digests), pre["count"]),
+                                 ("pre.bytes", total, pre["bytes"])]:
+            if got != want:
+                mismatch = True
+                notes.append(f"{label}: recomputed {got!r} != claimed {want!r}")
+        # every manifest entry must exist in pre (multiset)
+        avail = Counter(pre_digests)
+        for d in manifest:
+            if avail[d] > 0:
+                avail[d] -= 1
+            else:
+                mismatch = True
+                notes.append(f"manifest digest {d[:40]}… not found in "
+                             "pre_content — receipt claims a drop of an item "
+                             "the pre-content never contained")
+    post_digests = None
+    if post_content is not None:
+        checked = True
+        post_digests, _sizes, whole, total = _digest_content(post_content)
+        for label, got, want in [("post.digest", whole, post.get("digest")),
+                                 ("post.count", len(post_digests), post["count"]),
+                                 ("post.bytes", total, post["bytes"])]:
+            if got != want:
+                mismatch = True
+                notes.append(f"{label}: recomputed {got!r} != claimed {want!r}")
+    if pre_digests is not None and post_digests is not None:
+        # Recompute the drop set from BOTH sides and hold it against the
+        # manifest — the planted-drop catch. A compactor that dropped item X
+        # while claiming it dropped nothing fails exactly here.
+        remaining = Counter(post_digests)
+        actual: list[str] = []
+        actual_bytes = 0
+        for d, n in zip(pre_digests, pre_sizes):
+            if remaining[d] > 0:
+                remaining[d] -= 1
+            else:
+                actual.append(d)
+                actual_bytes += n
+        if Counter(actual) != Counter(manifest):
+            mismatch = True
+            notes.append(f"drop-manifest disagrees with content: recomputed "
+                         f"{len(actual)} dropped item(s), manifest claims "
+                         f"{len(manifest)}")
+        elif actual_bytes != dropped["bytes"]:
+            mismatch = True
+            notes.append(f"dropped.bytes: recomputed {actual_bytes} != "
+                         f"claimed {dropped['bytes']}")
+        if sum(remaining.values()) != introduced["count"]:
+            mismatch = True
+            notes.append(f"introduced.count: recomputed "
+                         f"{sum(remaining.values())} != claimed "
+                         f"{introduced['count']}")
+
+    out["content"] = "mismatch" if mismatch else ("match" if checked else "skipped")
+    out["ok"] = sc and not mismatch
+    return out

arcaeon_compact/selftest.py

@@ -0,0 +1,116 @@
+"""Self-test: golden receipt-digest vectors + the planted-drop fixture.
+
+    python -m arcaeon_compact.selftest
+
+Ships in the package rather than living in CI, so a stranger runs it on THEIR
+machine and trusts their own output, not ours:
+
+1. Golden vectors. The receipt digest is only a reliable signal if every
+   environment computes the same one from the same content. These constants
+   were frozen when the v1 schema was frozen (0.1.0, 2026-08-14). If your
+   Python, your platform, or a future release computes anything else, this
+   command fails loudly — do not trust receipts it produces.
+
+2. The planted drop. The whole product claim is "a compactor cannot claim
+   nothing was dropped while dropping something." So the load-bearing test
+   plants exactly that lie — record_kept(everything) while the shipped
+   survivor is missing an item — and verify_receipt MUST catch it. The honest
+   receipt over the same drop MUST pass. Both run here, every time.
+
+Exit code 0 = every check passed.
+"""
+from __future__ import annotations
+
+import sys
+import tempfile
+from pathlib import Path
+
+from . import CompactionReceipt, verify_receipt, _digest_item
+
+# The fixture content. Covers all three item types (str, dict, bytes) so the
+# frozen type rule (str -> UTF-8 raw-bytes, dict -> json-c14n, bytes -> raw)
+# is enforced, not just documented.
+PRE = ["the quick brown fox",
+       {"role": "user", "text": "hello"},
+       b"\x00\x01binary"]
+POST = ["the quick brown fox", "summary: user said hello"]
+
+# Frozen at schema freeze (arcaeon-compact:receipt:v1, 0.1.0, 2026-08-14).
+# These never change. A v2 schema gets NEW vectors alongside these.
+GOLDEN_RECEIPT_DIGEST = ("sha256:json-c14n:v1:"
+    "9a0f4bb37b78f8433f52ae14603d20f1fc2413265e434beb9ad15613fc5947a4")
+GOLDEN_PRE_DIGEST = ("sha256:json-c14n:v1:"
+    "0fa1adc5dd156a66d78b1e32a52632ce8b98fabc7dfe9d25813375e75ddc82a7")
+GOLDEN_ITEMS = [
+    ("str item (raw-bytes of UTF-8)", PRE[0], "sha256:raw-bytes:v1:"
+     "9ecb36561341d18eb65484e833efea61edc74b84cf5e6ae1b81c63533e25fc8f"),
+    ("dict item (json-c14n)", PRE[1], "sha256:json-c14n:v1:"
+     "09a32d6caf7737200a34ee38c65c82446831be896aa5d5aa6b858729ee13beb1"),
+    ("bytes item (raw-bytes)", PRE[2], "sha256:raw-bytes:v1:"
+     "f8c1ccc7df7243da4740c5b7875f88b70e3f935d99c7b37a5f7239d152d994e6"),
+]
+
+
+def run() -> int:
+    failures = 0
+
+    print("== golden vectors (schema enforcement) ==")
+    for name, item, want in GOLDEN_ITEMS:
+        got = _digest_item(item)[0]
+        ok = got == want
+        failures += 0 if ok else 1
+        print(f"  {'PASS' if ok else 'FAIL'}  {name}")
+        if not ok:
+            print(f"        want {want}\n        got  {got}")
+
+    with tempfile.TemporaryDirectory() as td:
+        led = Path(td) / "receipts.jsonl"
+        r = CompactionReceipt.open(PRE)
+        r.record_kept(POST)
+        row = r.seal(led, compactor="golden-fixture", method="test:v1")
+        for name, got, want in [
+                ("pre.digest vector", row["pre"]["digest"], GOLDEN_PRE_DIGEST),
+                ("receipt_digest vector", row["receipt_digest"],
+                 GOLDEN_RECEIPT_DIGEST)]:
+            ok = got == want
+            failures += 0 if ok else 1
+            print(f"  {'PASS' if ok else 'FAIL'}  {name}")
+            if not ok:
+                print(f"        want {want}\n        got  {got}")
+
+        print("== the planted drop (the load-bearing lie) ==")
+        # Honest branch: the same drop, receipted truthfully, must pass fully.
+        v = verify_receipt(row, PRE, POST)
+        ok = v["ok"] and v["content"] == "match"
+        failures += 0 if ok else 1
+        print(f"  {'PASS' if ok else 'FAIL'}  honest receipt -> "
+              f"ok={v['ok']} content={v['content']!r} (must be True/'match')")
+
+        # The lie: claim the survivor is EVERYTHING (nothing dropped), while
+        # the actually-shipped survivor is missing the binary item.
+        liar = CompactionReceipt.open(PRE)
+        liar.record_kept(PRE)                      # "nothing was dropped"
+        lied_row = liar.seal(led, compactor="liar", method="test:v1")
+        shipped = PRE[:2]                          # ...something was.
+        v = verify_receipt(lied_row, PRE, shipped)
+        ok = (not v["ok"]) and v["content"] == "mismatch"
+        failures += 0 if ok else 1
+        print(f"  {'PASS' if ok else 'FAIL'}  planted drop   -> "
+              f"ok={v['ok']} content={v['content']!r} (must be False/'mismatch')")
+
+        # And the lying row alone (no content) must still be SELF-consistent:
+        # the receipt binds the claim; only content exposes the lie. Stating
+        # this precisely is part of the product, so it is asserted, not hoped.
+        v = verify_receipt(lied_row)
+        ok = v["ok"] and v["content"] == "skipped"
+        failures += 0 if ok else 1
+        print(f"  {'PASS' if ok else 'FAIL'}  lie w/o content -> "
+              f"ok={v['ok']} (self-consistency cannot expose it: by design, "
+              f"and said out loud)")
+
+    print(f"\n{'ALL CHECKS PASSED' if failures == 0 else f'{failures} CHECK(S) FAILED'}")
+    return 0 if failures == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(run())

arcaeon_compact-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: arcaeon-compact
+Version: 0.1.0
+Summary: Tamper-evident receipts for context compaction. Prove what your summarizer dropped.
+Project-URL: Homepage, https://arcaeon.io
+Author: Arcaeon
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,compaction,context,memory,provenance,summarization,tamper-evident
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: arcaeon-ledger>=0.5.1
+Description-Content-Type: text/markdown
+
+# arcaeon-compact
+
+**Your summarizer says it kept what mattered. `arcaeon-compact` makes it prove
+what it dropped.**
+
+Every agent compacts context — summarizes the conversation, prunes memory,
+truncates history — and today that step is a black hole: content goes in,
+a survivor comes out, and nothing attests to the difference. A
+**CompactionReceipt** is a tamper-evident record of exactly that difference:
+digests of the full pre-compaction content and the post-compaction survivor,
+plus a drop-manifest naming every dropped item by digest, chained onto an
+[`arcaeon-ledger`](https://pypi.org/project/arcaeon-ledger/) log so the receipt
+itself can't be quietly edited later.
+
+```
+pip install arcaeon-compact     # brings arcaeon-ledger; nothing else
+```
+
+```python
+from arcaeon_compact import CompactionReceipt, verify_receipt
+
+pre  = conversation_turns                  # list of str | bytes | dict
+post = summarize(pre)                      # your compactor, any compactor
+
+receipt = CompactionReceipt.open(pre)      # digest every item + the whole
+receipt.record_kept(post)                  # dropped = pre minus kept, by digest
+row = receipt.seal("receipts.jsonl",       # one chained row on an arcaeon-ledger
+                   compactor="summarizer-v2", method="llm-summary")
+
+verify_receipt(row)                        # self-consistency, always
+verify_receipt(row, pre, post)             # recompute from content and compare
+```
+
+Three calls in, one call out. That's the whole API.
+
+## What it does NOT prove — read this before the features
+
+Being precise about the boundary is the product, not a disclaimer.
+
+**1. It proves WHAT was dropped, never that dropping was wise.** The receipt
+has no opinion on salience. A compactor that keeps the small talk and drops the
+wire-transfer instructions gets a perfectly valid receipt saying exactly that.
+The receipt turns "trust me, nothing important was lost" into a checkable
+claim — judging the loss is still your job.
+
+**2. It proves the compactor's claim about its inputs, not that the inputs
+were complete.** The gateway problem: if content was withheld before `open()`
+ever saw it, the receipt faithfully notarizes the partial view. The receipt
+binds what crossed the gate, not what existed behind it. Closing that gap means
+receipting the *producing* side too (the ledger's artefact-binding is the tool
+for that) — a layer you add, stated here, not implied away.
+
+**3. Digests only means dropped content is NOT recoverable from the receipt.**
+This is privacy by construction — a receipt can be published, shipped to an
+auditor, or held by a counterparty without leaking one byte of the
+conversation. It is also a real limitation, stated plainly: you can prove an
+item you still *hold* was dropped (hash it, find it in the manifest); you
+cannot resurrect an item you lost. The receipt is a witness, not a backup.
+
+And, inherited honestly from the chain underneath: the ledger proves the
+receipt row wasn't altered *in place* — for truncation-resistance you pin the
+ledger head externally, exactly as `arcaeon-ledger`'s docs describe.
+
+## The receipt, anatomically
+
+```json
+{
+  "schema": "arcaeon-compact:receipt:v1",
+  "pre":     {"count": 4, "bytes": 121, "digest": "sha256:json-c14n:v1:0fa1…"},
+  "post":    {"count": 2, "bytes": 49,  "digest": "sha256:json-c14n:v1:2623…"},
+  "dropped": {"count": 3, "bytes": 84,  "items": ["sha256:raw-bytes:v1:9ecb…", "…"]},
+  "introduced": {"count": 1},
+  "compactor": "summarizer-v2",
+  "method": "llm-summary",
+  "opened_at": "2026-08-14T17:40:00Z",
+  "receipt_digest": "sha256:json-c14n:v1:9a0f…",
+  "ts": "…", "chain": "…"
+}
+```
+
+- Every digest is **self-describing** (`sha256:<recipe>:<ver>:<hex>`), carrying
+  its own pinned canonicalization recipe from `arcaeon-ledger` — never a bare
+  hex hash a stranger can't reproduce. The per-item type rule is frozen into
+  the v1 schema: `bytes` are hashed raw, `str` as UTF-8, everything else
+  through the pinned `json-c14n` recipe.
+- The **whole-content digests** are a digest over the ordered per-item digests,
+  so they recompute from content alone — content is never stored.
+- **`introduced`** counts survivor items that were never in the pre-content:
+  the summary text itself, typically. It closes the arithmetic
+  (`pre = kept + dropped`, `post = kept + introduced`) so the counts can't be
+  fudged independently.
+- **`receipt_digest`** covers the deterministic core, so an edited row is
+  caught even when it's been copied *out* of its ledger. Inside the ledger,
+  the chain catches the same edit; this check travels with the row.
+- Duplicates are counted as a **multiset**: keeping one copy of a twice-seen
+  item still drops the other, and the manifest says so.
+
+## Verification, honestly scoped
+
+```python
+verify_receipt(row)
+# {"ok": True, "self_consistent": True, "content": "skipped", "notes": []}
+
+verify_receipt(row, pre_content=pre, post_content=post)
+# {"ok": True, "self_consistent": True, "content": "match", "notes": []}
+```
+
+Self-consistency (no content needed) checks the schema, every digest's shape,
+the count arithmetic, and the `receipt_digest`. With content provided, every
+digest is recomputed and compared — and with **both** sides provided, the drop
+set itself is recomputed (pre minus post, by digest) and held against the
+manifest. That last comparison is the point of the whole library:
+
+```python
+# the compactor claims nothing was dropped...
+receipt = CompactionReceipt.open(pre)
+receipt.record_kept(pre)                       # "kept everything"
+row = receipt.seal("receipts.jsonl", compactor="liar", method="llm-summary")
+
+# ...but what it actually shipped is missing an item
+verify_receipt(row, pre, shipped_post)
+# {"ok": False, "content": "mismatch",
+#  "notes": ["post.digest: recomputed … != claimed …",
+#            "drop-manifest disagrees with content: recomputed 1 dropped
+#             item(s), manifest claims 0"]}
+```
+
+Stated with equal honesty: the lying row **alone** is self-consistent — a
+receipt binds the claim; only content exposes the lie. The self-test asserts
+this out loud rather than letting you discover it. What the receipt guarantees
+is that the claim is *frozen*: the compactor committed to specific digests at
+seal time, and anyone who ever holds the content can check that commitment.
+
+`record_dropped(items)` is optional — the drop set is inferred as
+pre-minus-kept by digest. If you do record it explicitly, `seal()` reconciles
+the claim against the inference and **refuses to seal a receipt that disagrees
+with itself**, so an internally inconsistent receipt never exists to be
+believed.
+
+## Prove your own install
+
+```
+python -m arcaeon_compact.selftest
+```
+
+Golden digest vectors frozen at the v1 schema freeze — if your environment
+computes anything else, the command fails loudly and you should not trust
+receipts it produces — plus the planted-drop fixture above, run for real in a
+temp dir every time. The negative test ships in the package because "trust our
+CI" is exactly the posture this library exists to replace.
+
+## Built on arcaeon-ledger
+
+Receipts append to a standard [`arcaeon-ledger`](https://pypi.org/project/arcaeon-ledger/)
+chain, so everything the ledger gives you composes for free: `verify` names
+the exact tampered line, `head()` pins close the truncation gap, and a
+`WitnessStore` gives you an external record a re-minter cannot advance. A
+receipts file is just a ledger file; the receipt is just a row with a schema.
+
+## Status
+
+v0.1.0. Library + packaged self-test, tested against the planted-drop lie,
+in-row edits, multiset duplicates, byte totals, and lifecycle misuse
+(`test_compact.py`). Extracted from the context-compaction flow of a
+long-running agent that wanted receipts for its own memory pruning before
+selling them to anyone else.
+
+MIT.

arcaeon_compact-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+arcaeon_compact/__init__.py,sha256=ub0K8LtKHswfo4onI0RMNl1Qa3cseALuz2pZhzvdOMw,16837
+arcaeon_compact/selftest.py,sha256=Po6RIgL0mqYsEH8z3YI-rB6oCmNILTRiFOBHqhUIh2A,5184
+arcaeon_compact-0.1.0.dist-info/METADATA,sha256=pQzqUrGAwg2mkLAOKcq-t5bqVDf1S7A1Om6mgJM1CLE,8478
+arcaeon_compact-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+arcaeon_compact-0.1.0.dist-info/licenses/LICENSE,sha256=X891VWc5gAsgzxxpN3G8LJ2dvQDKca9SUivd0m2IftQ,1064
+arcaeon_compact-0.1.0.dist-info/RECORD,,

arcaeon_compact-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

arcaeon_compact-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcaeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.