superlocalmemory 3.5.7 → 3.6.0

package/src/superlocalmemory/optimize/compress/align.py

@@ -0,0 +1,153 @@
+# compress/align.py
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+#
+# Volatile-detection algorithm adapted from:
+#   headroom/transforms/cache_aligner.py (Apache-2.0, Headroom contributors)
+#   Specifically: _is_uuid(), _is_iso8601(), _is_jwt_shape(), _is_hex_hash(),
+#   _classify_token(), _split_tokens(), detect_volatile_content()
+#   Lines: cache_aligner.py:76-200
+#   Attribution: See ATTRIBUTION.md.
+
+"""CacheAligner — volatile-token detector for system prompt prefix stability.
+
+Phase 2: Detection only. No mutation of the system prompt.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import logging
+import uuid as _uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+
+logger = logging.getLogger("slm.optimize.compress.align")
+
+_HEX_HASH_LENGTHS = frozenset({32, 40, 64})
+_UUID_CANONICAL_LEN = 36  # L-02: 36 chars INCLUDING 4 dashes (RFC 4122 canonical form: 8-4-4-4-12)
+_JWT_SEGMENT_COUNT = 3
+_JWT_MIN_SEGMENT_BYTES = 4
+
+_LABEL_UUID = "uuid"
+_LABEL_ISO8601 = "iso8601"
+_LABEL_JWT = "jwt"
+_LABEL_HEX_HASH = "hex_hash"
+
+
+@dataclass(frozen=True)
+class VolatileFinding:
+    label: str
+    sample: str
+
+
+@dataclass
+class AlignResult:
+    prefix_stable: bool = True
+    stability_score: float = 1.0
+    findings: list[VolatileFinding] = field(default_factory=list)
+    total_tokens_scanned: int = 0
+
+
+class CacheAligner:
+    """Detects volatile tokens in system prompts. No mutation. Thread-safe."""
+
+    def detect(self, system_prompt: str) -> AlignResult:
+        try:
+            return _detect(system_prompt)
+        except Exception as exc:
+            logger.debug("CacheAligner.detect failed (non-fatal): %s", exc)
+            return AlignResult()
+
+
+def _detect(text: str) -> AlignResult:
+    tokens = _split_tokens(text)
+    findings: list[VolatileFinding] = []
+    volatile_count = 0
+
+    for token in tokens:
+        label = _classify_token(token)
+        if label is not None:
+            volatile_count += 1
+            if len(findings) < 20:
+                findings.append(VolatileFinding(label=label, sample=token[:20]))
+
+    total = len(tokens)
+    score = 1.0 - (volatile_count / total) if total > 0 else 1.0
+
+    return AlignResult(
+        prefix_stable=(volatile_count == 0),
+        stability_score=round(score, 4),
+        findings=findings,
+        total_tokens_scanned=total,
+    )
+
+
+def _split_tokens(content: str) -> list[str]:
+    if not content:
+        return []
+    tokens: list[str] = []
+    for raw in content.split():
+        cleaned = raw.strip(".,;:!?\"'()[]{}<>`|\\")
+        if cleaned:
+            tokens.append(cleaned)
+    return tokens
+
+
+def _classify_token(token: str) -> str | None:
+    if _is_uuid(token):
+        return _LABEL_UUID
+    if "." in token and _is_jwt_shape(token):
+        return _LABEL_JWT
+    if _is_iso8601(token):
+        return _LABEL_ISO8601
+    if _is_hex_hash(token):
+        return _LABEL_HEX_HASH
+    return None
+
+
+def _is_uuid(token: str) -> bool:
+    if len(token) != _UUID_CANONICAL_LEN or token.count("-") != 4:
+        return False
+    try:
+        _uuid.UUID(token)
+    except (ValueError, AttributeError):
+        return False
+    return True
+
+
+def _is_iso8601(token: str) -> bool:
+    if len(token) < 8 or ("T" not in token and "-" not in token):
+        return False
+    candidate = token[:-1] + "+00:00" if token.endswith("Z") else token
+    try:
+        datetime.fromisoformat(candidate)
+    except (ValueError, TypeError):
+        return False
+    return True
+
+
+def _is_jwt_shape(token: str) -> bool:
+    if token.count(".") != _JWT_SEGMENT_COUNT - 1:
+        return False
+    segments = token.split(".")
+    for seg in segments:
+        if len(seg) < _JWT_MIN_SEGMENT_BYTES:
+            return False
+        padded = seg + "=" * (-len(seg) % 4)
+        try:
+            base64.urlsafe_b64decode(padded.encode("ascii"))
+        except (binascii.Error, ValueError, UnicodeEncodeError):
+            return False
+    return True
+
+
+def _is_hex_hash(token: str) -> bool:
+    if len(token) not in _HEX_HASH_LENGTHS:
+        return False
+    try:
+        int(token, 16)
+    except ValueError:
+        return False
+    return True

package/src/superlocalmemory/optimize/compress/ccr.py

@@ -0,0 +1,157 @@
+# compress/ccr.py
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+#
+# CCR (Compressed Context Retrieval) concept and pattern:
+#   headroom/ccr/ package (Apache-2.0, Headroom contributors)
+#   Specifically: batch_store.py (BatchContext dataclass, TTL pattern),
+#   tool_injection.py (MCP tool injection pattern)
+#   Attribution: See ATTRIBUTION.md.
+# Storage: llmcache_ccr table defined in INTERFACE-CONTRACT §1.
+# Database access: CacheDB.ccr_put() and CacheDB.ccr_get() per INTERFACE-CONTRACT §1.
+
+"""CCRStore — stores pre-compression originals, provides retrieval tool."""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+
+logger = logging.getLogger("slm.optimize.compress.ccr")
+
+# SEC-C-04: UUID4 format validator — only ^UUID4^ values pass
+_UUID4_RE = re.compile(
+    r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
+)
+
+
+class CCRStore:
+    """Stores compression originals and retrieves them by ccr_id.
+
+    Thread-safe. Singleton per daemon instance.
+    """
+
+    _instance: "CCRStore | None" = None
+    _lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def get_instance(cls) -> "CCRStore":
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def __init__(self) -> None:
+        self._db: "CacheDB | None" = None
+
+    def store(
+        self,
+        original: bytes,
+        model: str = "",
+        tenant_id: str = "default",
+        ttl_seconds: int | None = None,
+    ) -> str:
+        """Store a pre-compression original. Returns ccr_id (UUID4) or '' on failure.
+
+        B-03: Called BEFORE compression runs.
+        RB-05: Only original bytes accepted; compressed bytes stored via update_compressed().
+        """
+        try:
+            import uuid as _uuid_mod
+            import time as _time_mod
+            ccr_id = str(_uuid_mod.uuid4())
+            db = self._get_db()
+            ttl_expires = (
+                _time_mod.time() + ttl_seconds
+                if ttl_seconds is not None
+                else None
+            )
+            db.ccr_put(ccr_id, original, ttl_expires=ttl_expires)
+            logger.debug("CCR stored ccr_id=%s orig_bytes=%d", ccr_id, len(original))
+            return ccr_id
+        except Exception as exc:
+            logger.warning("CCRStore.store failed (fail-open): %s", exc)
+            return ""
+
+    def update_compressed(self, ccr_id: str, compressed_bytes: bytes) -> None:
+        """Update the compressed_hash for an existing CCR row. Non-fatal if fails."""
+        try:
+            db = self._get_db()
+            if hasattr(db, "ccr_update_compressed"):
+                db.ccr_update_compressed(ccr_id, compressed_bytes)
+        except Exception as exc:
+            logger.debug("CCRStore.update_compressed failed (non-fatal): %s", exc)
+
+    def retrieve(self, ccr_id: str) -> bytes | None:
+        """Retrieve a CCR original by ccr_id. Returns None if not found or TTL expired."""
+        try:
+            db = self._get_db()
+            return db.ccr_get(ccr_id)
+        except Exception as exc:
+            logger.warning("CCRStore.retrieve failed (ccr_id=%s): %s", ccr_id, exc)
+            return None
+
+    def get_mcp_tool_definition(self) -> dict:
+        return {
+            "name": "headroom_retrieve",
+            "description": (
+                "Retrieve the original (pre-compression) text for a compressed content block. "
+                "Use this when you need the full, uncompressed version of content that was "
+                "compressed by SLM. Provide the ccr_id from the compression stub comment."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "ccr_id": {
+                        "type": "string",
+                        "description": "The ccr_id from the compression stub comment.",
+                    }
+                },
+                "required": ["ccr_id"],
+            },
+        }
+
+    async def handle_mcp_call(self, arguments: dict) -> dict:
+        ccr_id = arguments.get("ccr_id", "")
+        if not ccr_id:
+            return {
+                "isError": True,
+                "content": [{"type": "text", "text": "ccr_id is required"}],
+            }
+        if not _UUID4_RE.match(ccr_id):
+            return {
+                "isError": True,
+                "content": [{
+                    "type": "text",
+                    "text": f"ccr_id must be a UUID4, got {ccr_id!r}",
+                }],
+            }
+        original = self.retrieve(ccr_id)
+        if original is None:
+            return {
+                "isError": True,
+                "content": [{
+                    "type": "text",
+                    "text": (
+                        f"CCR original not found for ccr_id={ccr_id!r}. "
+                        "Possible causes: entry expired, never stored, or ccr_id incorrect."
+                    ),
+                }],
+            }
+        try:
+            text = original.decode("utf-8")
+        except UnicodeDecodeError:
+            logger.warning(
+                "CCR ccr_id=%s: original bytes not valid UTF-8; falling back to latin-1",
+                ccr_id,
+            )
+            text = original.decode("latin-1")
+        return {"content": [{"type": "text", "text": text}]}
+
+    def _get_db(self) -> "CacheDB":
+        if self._db is None:
+            from superlocalmemory.optimize.storage.db import CacheDB
+            self._db = CacheDB()
+        return self._db

package/src/superlocalmemory/optimize/compress/extractive_code.py

@@ -0,0 +1,311 @@
+# compress/extractive_code.py
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+#
+# AST structural patterns adapted from:
+#   headroom/compression/handlers/code_handler.py:66-138 (Apache-2.0)
+#   Specifically: _STRUCTURAL_NODE_TYPES per-language dict, CodeLanguage enum
+#   headroom/compression/handlers/code_handler.py:141-150 — _SIGNATURE_PATTERNS regex fallback
+#   Attribution: See ATTRIBUTION.md.
+
+"""CodeCompressor — AST-aware extractive code compressor.
+
+Supported languages: Python, JavaScript, Go, Rust, Java, C++.
+Path A (tree-sitter): used if tree-sitter-language-pack installed.
+Path B (regex fallback): used otherwise. Tests pass on both paths.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+logger = logging.getLogger("slm.optimize.compress.code")
+
+_BODY_STUB_BY_LANG: dict[str, str] = {
+    "python":     "    # [slm: body compressed — retrieve with ccr_id={ccr_id}]",
+    "javascript": "    // [slm: body compressed — retrieve with ccr_id={ccr_id}]",
+    "go":         "    // [slm: body compressed — retrieve with ccr_id={ccr_id}]",
+    "rust":       "    // [slm: body compressed — retrieve with ccr_id={ccr_id}]",
+    "java":       "    // [slm: body compressed — retrieve with ccr_id={ccr_id}]",
+    "cpp":        "    // [slm: body compressed — retrieve with ccr_id={ccr_id}]",
+}
+_BODY_STUB_NO_CCR_BY_LANG: dict[str, str] = {
+    "python":     "    # [slm: body compressed]",
+    "javascript": "    // [slm: body compressed]",
+    "go":         "    // [slm: body compressed]",
+    "rust":       "    // [slm: body compressed]",
+    "java":       "    // [slm: body compressed]",
+    "cpp":        "    // [slm: body compressed]",
+}
+
+_MIN_BODY_LINES: int = 4
+
+
+class CodeLanguage(Enum):
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    GO = "go"
+    RUST = "rust"
+    JAVA = "java"
+    CPP = "cpp"
+
+
+@dataclass(frozen=True)
+class CodeSpan:
+    start_line: int
+    end_line: int
+    role: str  # "import" | "signature" | "body" | "class_header" | "decorator"
+    is_structural: bool
+
+
+# ── Signature patterns for regex path (Path B) ────────────────────────────────
+
+_SIGNATURE_PATTERNS: dict[str, list[str]] = {
+    "python": [
+        r"^\s*(async\s+)?def\s+\w+\s*\([^)]*\)\s*(->\s*[^:]+)?:",
+        r"^\s*class\s+\w+(\([^)]*\))?:",
+        r"^\s*import\s+",
+        r"^\s*from\s+\w+\s+import",
+        r"^\s*@\w+",
+    ],
+    "javascript": [
+        r"^\s*(async\s+)?function\s+\w+\s*\([^)]*\)",
+        r"^\s*class\s+\w+(\s+extends\s+\w+)?",
+        r"^\s*import\s+",
+        r"^\s*const\s+\w+\s*=\s*(async\s+)?\(",
+        r"^\s*export\s+(default\s+|const\s+|class\s+|function\s+)",
+    ],
+    "go": [
+        r"^\s*func\s+(\(\w+\s+\*?\w+\)\s*)?\w+\s*\(",
+        r"^\s*import\s+",
+        r"^\s*package\s+",
+        r"^\s*type\s+\w+\s+(struct|interface)\s*\{",
+    ],
+    "rust": [
+        r"^\s*(pub\s+)?(async\s+)?fn\s+\w+",
+        r"^\s*use\s+",
+        r"^\s*impl\s+",
+        r"^\s*struct\s+",
+        r"^\s*enum\s+",
+        r"^\s*trait\s+",
+    ],
+    "java": [
+        r"^\s*(public|private|protected)\s+(static\s+)?\w+\s+\w+\s*\(",
+        r"^\s*import\s+",
+        r"^\s*(public|private|protected)?\s*class\s+\w+",
+    ],
+    "cpp": [
+        r"^\s*\w[\w\s\*&:<,>]*\s+\w+\s*\([^)]*\)\s*(const\s*)?\{",
+        r"^\s*#include\s+",
+        r"^\s*(class|struct)\s+\w+",
+    ],
+}
+
+
+class CodeCompressor:
+    """AST-aware extractive code compressor. Thread-safe (no mutable state)."""
+
+    def compress(self, code: str, language: str, ccr_id: str = "") -> str:
+        try:
+            lang = CodeLanguage(language)
+        except ValueError:
+            logger.warning("CodeCompressor: unknown language %r — passthrough", language)
+            return code
+
+        try:
+            if _tree_sitter_available():
+                return self._compress_with_tree_sitter(code, lang, ccr_id)
+            else:
+                return self._compress_with_regex(code, lang, ccr_id)
+        except Exception as exc:
+            logger.warning("CodeCompressor.compress failed — passthrough: %s", exc)
+            return code
+
+    def _compress_with_tree_sitter(self, code: str, lang: CodeLanguage, ccr_id: str) -> str:
+        from tree_sitter_language_pack import get_parser  # type: ignore[import]
+        parser = get_parser(lang.value)
+        tree = parser.parse(code.encode())
+        lines = code.split("\n")
+        spans = _collect_spans_tree_sitter(tree.root_node, lang)
+        return _apply_spans(lines, spans, ccr_id, lang.value)
+
+    def _compress_with_regex(self, code: str, lang: CodeLanguage, ccr_id: str) -> str:
+        lines = code.split("\n")
+        spans = _collect_spans_regex(lines, lang)
+        return _apply_spans(lines, spans, ccr_id, lang.value)
+
+
+# ── Span collection ───────────────────────────────────────────────────────────
+
+def _collect_spans_tree_sitter(root_node: object, lang: CodeLanguage) -> list[CodeSpan]:
+    _STRUCTURAL_TYPES: dict[str, set[str]] = {
+        "python": {"import_statement", "import_from_statement", "function_definition",
+                   "class_definition", "decorated_definition", "type_alias_statement"},
+        "javascript": {"import_statement", "export_statement", "function_declaration",
+                       "class_declaration", "method_definition", "arrow_function"},
+        "go": {"import_declaration", "function_declaration", "method_declaration",
+               "type_declaration", "interface_type"},
+        "rust": {"use_declaration", "function_item", "impl_item", "struct_item",
+                 "enum_item", "trait_item"},
+        "java": {"import_declaration", "class_declaration", "method_declaration",
+                 "interface_declaration", "annotation"},
+        "cpp": {"function_definition", "preproc_include", "class_specifier"},
+    }
+    structural = _STRUCTURAL_TYPES.get(lang.value, set())
+    spans: list[CodeSpan] = []
+
+    def _walk(node: object, depth: int = 0) -> None:
+        start_row: int = getattr(node, "start_point", (0, 0))[0]
+        end_row: int = getattr(node, "end_point", (0, 0))[0]
+        node_type: str = getattr(node, "type", "")
+        is_struct = node_type in structural
+
+        if is_struct and node_type in {
+            "function_definition", "method_definition", "function_declaration",
+            "function_item", "method_declaration",
+        }:
+            body_node = _find_child(node, "block") or _find_child(node, "body")
+            if body_node is not None:
+                body_start = getattr(body_node, "start_point", (0, 0))[0]
+                sig_end = body_start - 1
+                if sig_end > start_row:
+                    spans.append(CodeSpan(start_row, sig_end, "signature", True))
+                spans.append(CodeSpan(body_start, end_row, "body", False))
+            else:
+                spans.append(CodeSpan(start_row, end_row, "signature", True))
+        elif is_struct and node_type in {"decorated_definition"}:
+            def_node = _find_child(node, "function_definition") or _find_child(node, "class_definition")
+            if def_node is not None:
+                def_start = getattr(def_node, "start_point", (0, 0))[0]
+                spans.append(CodeSpan(start_row, def_start - 1, "decorator", True))
+                _walk(def_node, depth + 1)
+            else:
+                spans.append(CodeSpan(start_row, end_row, node_type, True))
+        elif is_struct:
+            spans.append(CodeSpan(start_row, end_row, "signature", True))
+        else:
+            children = getattr(node, "children", None)
+            if children is not None:
+                has_named = False
+                for child in children:
+                    if getattr(child, "is_named", False):
+                        has_named = True
+                        _walk(child, depth + 1)
+                if not has_named:
+                    spans.append(CodeSpan(start_row, end_row, "body", False))
+
+    _walk(root_node)
+    return spans
+
+
+def _find_child(node: object, child_type: str) -> object | None:
+    children = getattr(node, "children", None)
+    if children is None:
+        return None
+    for child in children:
+        if hasattr(child, "type") and child.type == child_type:
+            return child
+    return None
+
+
+def _collect_spans_regex(lines: list[str], lang: CodeLanguage) -> list[CodeSpan]:
+    patterns = _SIGNATURE_PATTERNS.get(lang.value, [])
+    spans: list[CodeSpan] = []
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        line = lines[i]
+        matched = False
+        for pat in patterns:
+            if re.search(pat, line):
+                body_start = i + 1
+                body_end = body_start
+                while body_end < n and (
+                    lines[body_end].startswith((" ", "\t", "", "#", "//", "/*", "*/", "{"))
+                    or re.match(r"^\s*$", lines[body_end])
+                ):
+                    if re.match(r"^\s*($|#|//|/\*|\*/|\*|}|\)|\])", lines[body_end]):
+                        body_end += 1
+                    else:
+                        break
+                body_len = body_end - body_start
+                if body_len >= _MIN_BODY_LINES and _looks_like_body(lines, body_start, body_end):
+                    spans.append(CodeSpan(i, i, "signature", True))
+                    spans.append(CodeSpan(body_start, body_end, "body", False))
+                    i = body_end
+                    matched = True
+                    break
+                else:
+                    body_start = body_end
+            # else: pattern didn't match
+        if not matched:
+            i += 1
+    return spans
+
+
+def _looks_like_body(lines: list[str], start: int, end: int) -> bool:
+    body_lines = [l for l in lines[start:end] if l.strip() and not l.strip().startswith(("#", "//"))]
+    return len(body_lines) >= _MIN_BODY_LINES
+
+
+def _apply_spans(
+    lines: list[str],
+    spans: list[CodeSpan],
+    ccr_id: str,
+    lang: str = "python",
+) -> str:
+    if not spans:
+        return "\n".join(lines)
+
+    stub_tmpl = _BODY_STUB_BY_LANG.get(lang, _BODY_STUB_BY_LANG["python"])
+    stub_no_ccr = _BODY_STUB_NO_CCR_BY_LANG.get(lang, _BODY_STUB_NO_CCR_BY_LANG["python"])
+    stub = stub_tmpl.format(ccr_id=ccr_id) if ccr_id else stub_no_ccr
+
+    sorted_spans = sorted(spans, key=lambda s: s.start_line)
+    start_set = set()
+    deduped: list[CodeSpan] = []
+    for s in sorted_spans:
+        if s.start_line not in start_set:
+            deduped.append(s)
+            start_set.add(s.start_line)
+
+    span_by_start: dict[int, CodeSpan] = {s.start_line: s for s in deduped}
+
+    result_lines: list[str] = []
+    i = 0
+    n = len(lines)
+
+    while i < n:
+        span = span_by_start.get(i)
+        if span is not None and not span.is_structural:
+            end = min(span.end_line, n - 1)
+            body_len = end - i + 1
+            if body_len >= _MIN_BODY_LINES:
+                result_lines.append(stub)
+                i = end + 1
+            else:
+                for j in range(i, end + 1):
+                    result_lines.append(lines[j])
+                i = end + 1
+        elif span is not None and span.is_structural:
+            end = min(span.end_line, n - 1)
+            for j in range(i, end + 1):
+                result_lines.append(lines[j])
+            i = end + 1
+        else:
+            result_lines.append(lines[i])
+            i += 1
+
+    return "\n".join(result_lines)
+
+
+def _tree_sitter_available() -> bool:
+    try:
+        import tree_sitter_language_pack  # noqa: F401
+        return True
+    except ImportError:
+        return False

package/src/superlocalmemory/optimize/compress/extractive_json.py

@@ -0,0 +1,72 @@
+# compress/extractive_json.py
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+#
+# Structural masking pattern adapted from:
+#   headroom/compression/handlers/json_handler.py (Apache-2.0, Headroom contributors)
+#   Specifically: JSONStructureHandler._extract_mask(), JSONToken, JSONTokenType
+#   Attribution: See ATTRIBUTION.md.
+#
+# HARD RULE: This compressor MUST NEVER prune or reorder JSON keys.
+# Keys pruned = structured semantics corrupted non-recoverably. Not configurable.
+
+"""JSONCompressor — lossless-ish extractive JSON compressor."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger("slm.optimize.compress.json")
+
+VALUE_TRUNCATE_CHARS: int = 120
+VALUE_TRUNCATE_SUFFIX: str = "\u2026"  # ellipsis
+MAX_ARRAY_ITEMS_SHOWN: int = 5
+ARRAY_REMAINDER_KEY: str = "__slm_omitted__"
+MIN_VALUE_LEN_TO_TRUNCATE: int = 40
+
+
+class JSONCompressor:
+    """Lossless-ish JSON compressor. Thread-safe (no mutable state)."""
+
+    def compress(self, parsed: Any) -> str:
+        try:
+            masked = self._mask(parsed, depth=0)
+            return json.dumps(masked, ensure_ascii=False, separators=(",", ":"))
+        except Exception as exc:
+            logger.warning("JSONCompressor.compress failed — returning original: %s", exc)
+            return json.dumps(parsed, ensure_ascii=False, separators=(",", ":"))
+
+    def _mask(self, obj: Any, depth: int) -> Any:
+        if isinstance(obj, dict):
+            return {k: self._mask(v, depth + 1) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return self._mask_array(obj, depth)
+        if isinstance(obj, str):
+            return self._mask_string(obj)
+        return obj
+
+    def _mask_array(self, arr: list, depth: int) -> list:
+        if len(arr) <= MAX_ARRAY_ITEMS_SHOWN:
+            return [self._mask(item, depth + 1) for item in arr]
+        shown = [self._mask(item, depth + 1) for item in arr[:MAX_ARRAY_ITEMS_SHOWN]]
+        collision = any(
+            isinstance(item, dict) and ARRAY_REMAINDER_KEY in item
+            for item in arr
+        )
+        if collision:
+            logger.warning(
+                "JSONCompressor: input contains reserved key %r — skipping array sentinel",
+                ARRAY_REMAINDER_KEY,
+            )
+        else:
+            shown.append({ARRAY_REMAINDER_KEY: len(arr) - MAX_ARRAY_ITEMS_SHOWN})
+        return shown
+
+    def _mask_string(self, s: str) -> str:
+        if len(s) < MIN_VALUE_LEN_TO_TRUNCATE:
+            return s
+        if len(s) <= VALUE_TRUNCATE_CHARS:
+            return s
+        return s[:VALUE_TRUNCATE_CHARS] + VALUE_TRUNCATE_SUFFIX