@ictechgy/context-guard 0.4.9 → 0.4.10

package/plugins/context-guard/bin/context-guard-cache-score

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""Static prompt cacheability lint for ContextGuard.
+
+``context-guard-cache-score`` is advisory-only: it does not call provider APIs,
+does not estimate price, does not observe cache hits, and does not write raw
+prompts to disk.  It only inspects a prompt/request fixture for stable-prefix
+shape, common dynamic markers, deterministic ordering hints, and provider cache
+eligibility using a tokenizer-free char/4 proxy.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+from pathlib import Path
+import re
+import stat
+import sys
+from typing import Any, NoReturn
+
+TOOL_NAME = "context-guard-cache-score"
+SCHEMA_VERSION = "contextguard.cache-score.v1"
+DEFAULT_MAX_INPUT_BYTES = 1_000_000
+TOKEN_PROXY_CHARS_PER_TOKEN = 4
+PROVIDER_MINIMUM_CACHEABLE_TOKENS = {
+    # Provider and model minimums move over time.  These defaults are advisory
+    # and can be overridden with --minimum-cacheable-tokens.
+    "openai": 1024,
+    "anthropic": 1024,
+    "gemini": 2048,
+    "generic": 1024,
+}
+PROVIDER_CAVEATS = {
+    "openai": (
+        "OpenAI prompt caching is automatic for eligible prompts; verify real "
+        "hits with provider usage.prompt_tokens_details.cached_tokens."
+    ),
+    "anthropic": (
+        "Anthropic prompt caching is model/platform-specific and usually needs "
+        "cache_control around the reusable prefix; verify cache_creation/read "
+        "usage fields."
+    ),
+    "gemini": (
+        "Gemini context caching thresholds vary by model/platform; verify with "
+        "provider cached-content usage fields and override the threshold when "
+        "your model differs."
+    ),
+    "generic": (
+        "Generic cache scoring uses a conservative threshold only; check your "
+        "provider documentation before claiming cache eligibility."
+    ),
+}
+ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
+    "tmp": Path("/private/tmp"),
+    "var": Path("/private/var"),
+}
+MAX_JSON_PATH_SEGMENT_CHARS = 64
+SAFE_JSON_PATH_SEGMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]{0,63}$")
+DYNAMIC_JSON_KEY_RE = re.compile(r"(?i)(request|trace|nonce|random|timestamp|created[_-]?at|updated[_-]?at|date)")
+SENSITIVE_JSON_KEY_RE = re.compile(
+    r"(?i)(authorization|api[_-]?key|apikey|token|secret|password|passwd|pwd|client[_-]?secret|credential|signature|sig|private[_-]?key|privatekey|ssh[_-]?key|sshkey)"
+)
+
+DYNAMIC_MARKERS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("iso_timestamp", re.compile(r"\b20\d{2}-\d{2}-\d{2}[T ][0-2]\d:[0-5]\d(?::[0-5]\d(?:\.\d{1,9})?)?(?:Z|[+-][0-2]\d:?[0-5]\d)?\b")),
+    ("uuid", re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\b")),
+    ("unix_epoch_ms", re.compile(r"\b1[6-9]\d{11}\b")),
+    ("request_id_key", re.compile(r"(?i)\b(?:request[_-]?id|trace[_-]?id|nonce|random[_-]?(?:id|seed)?|timestamp|created[_-]?at|updated[_-]?at|date_now)\b")),
+)
+
+
+class CacheScoreError(ValueError):
+    """User-facing fail-closed error."""
+
+
+def fail(message: str) -> NoReturn:
+    raise CacheScoreError(message)
+
+
+def byte_len_text(text: str) -> int:
+    return len(text.encode("utf-8", errors="replace"))
+
+
+def json_bytes(data: Any, *, indent: int | None = None) -> str:
+    return json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":") if indent is None else None, indent=indent)
+
+
+def json_path_child(path: str, key: object) -> str:
+    """Return a JSON warning path segment without echoing sensitive/dynamic keys."""
+    text = str(key)
+    if DYNAMIC_JSON_KEY_RE.search(text) or SENSITIVE_JSON_KEY_RE.search(text):
+        return f"{path}.[redacted-key]"
+    if SAFE_JSON_PATH_SEGMENT_RE.fullmatch(text):
+        return f"{path}.{text}"
+    if len(text) > MAX_JSON_PATH_SEGMENT_CHARS:
+        return f"{path}.[key:{len(text)} chars]"
+    return f"{path}.[key]"
+
+
+def bounded_int(value: object, *, default: int, minimum: int, maximum: int, name: str) -> int:
+    try:
+        number = int(default if value is None else value)
+    except (TypeError, ValueError, OverflowError):
+        fail(f"{name} must be an integer")
+    if number < minimum:
+        fail(f"{name} must be >= {minimum}")
+    if number > maximum:
+        fail(f"{name} must be <= {maximum}")
+    return number
+
+
+def normalized_link_target(parent: Path, raw_target: str) -> Path:
+    target = Path(raw_target)
+    if not target.is_absolute():
+        target = parent / target
+    return Path(os.path.normpath(str(target)))
+
+
+def normalize_allowed_first_absolute_symlink(path: Path) -> Path:
+    if not path.is_absolute() or len(path.parts) < 2:
+        return path
+    first = path.parts[1]
+    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(first)
+    if expected is None:
+        return path
+    link = Path(path.anchor) / first
+    try:
+        if not stat.S_ISLNK(os.lstat(link).st_mode):
+            return path
+        if normalized_link_target(Path(path.anchor), os.readlink(link)) != expected:
+            return path
+    except OSError:
+        return path
+    return expected.joinpath(*path.parts[2:])
+
+
+def reject_symlink_components(path: Path) -> None:
+    path = normalize_allowed_first_absolute_symlink(path)
+    current = Path(path.anchor) if path.is_absolute() else Path()
+    for part in path.parts:
+        if path.is_absolute() and part == path.anchor:
+            continue
+        current = current / part
+        try:
+            st = os.lstat(current)
+        except FileNotFoundError:
+            return
+        if stat.S_ISLNK(st.st_mode):
+            fail(f"refusing path with symlink component: {current}")
+        if not stat.S_ISDIR(st.st_mode) and current != path:
+            fail(f"refusing path through non-directory component: {current}")
+
+
+def read_limited_path(path: Path, max_bytes: int) -> str:
+    reject_symlink_components(path)
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(str(path), flags)
+    except OSError as exc:
+        fail(f"input read failed: {exc}")
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode):
+            fail("input must be a regular file")
+        if st.st_size > max_bytes:
+            fail(f"input exceeds --max-input-bytes: {st.st_size} > {max_bytes}")
+        data = os.read(fd, max_bytes + 1)
+    finally:
+        os.close(fd)
+    if len(data) > max_bytes:
+        fail(f"input exceeds --max-input-bytes: > {max_bytes}")
+    return data.decode("utf-8", errors="replace")
+
+
+def read_limited_stdin(max_bytes: int) -> str:
+    data = sys.stdin.buffer.read(max_bytes + 1)
+    if len(data) > max_bytes:
+        fail(f"input exceeds --max-input-bytes: > {max_bytes}")
+    return data.decode("utf-8", errors="replace")
+
+
+def estimate_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return int(math.ceil(len(text) / TOKEN_PROXY_CHARS_PER_TOKEN))
+
+
+def first_dynamic_marker(text: str) -> tuple[int | None, str | None]:
+    best_offset: int | None = None
+    best_name: str | None = None
+    for name, pattern in DYNAMIC_MARKERS:
+        match = pattern.search(text)
+        if match and (best_offset is None or match.start() < best_offset):
+            best_offset = match.start()
+            best_name = name
+    return best_offset, best_name
+
+
+def _walk_json(value: Any, path: str = "$") -> list[dict[str, Any]]:
+    warnings: list[dict[str, Any]] = []
+    if isinstance(value, dict):
+        keys = [str(key) for key in value]
+        if keys != sorted(keys):
+            warnings.append({
+                "code": "json_object_key_order_not_sorted",
+                "path": path,
+                "severity": "info",
+                "message": "Object keys are not in deterministic sorted order; keep generated JSON stable across runs.",
+            })
+        for key, item in value.items():
+            child_path = json_path_child(path, key)
+            if DYNAMIC_JSON_KEY_RE.search(str(key)):
+                warnings.append({
+                    "code": "dynamic_json_key",
+                    "path": child_path,
+                    "severity": "warn",
+                    "message": "Dynamic-looking JSON key appears in the prompt/request; place dynamic values after the reusable prefix.",
+                })
+            warnings.extend(_walk_json(item, child_path))
+    elif isinstance(value, list):
+        if path.endswith(".tools") and all(isinstance(item, dict) and "name" in item for item in value):
+            names = [str(item.get("name")) for item in value]
+            if names != sorted(names):
+                warnings.append({
+                    "code": "tool_order_not_sorted",
+                    "path": path,
+                    "severity": "info",
+                    "message": "Tool definitions are not sorted by name; deterministic ordering improves prefix reuse.",
+                })
+        for index, item in enumerate(value):
+            warnings.extend(_walk_json(item, f"{path}[{index}]"))
+    return warnings
+
+
+def json_shape_warnings(text: str) -> tuple[str, list[dict[str, Any]]]:
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return "text", []
+    if not isinstance(data, (dict, list)):
+        return "json-scalar", []
+    warnings = _walk_json(data)
+    canonical = json_bytes(data, indent=2) + "\n"
+    if canonical != text:
+        warnings.append({
+            "code": "json_not_canonical",
+            "path": "$",
+            "severity": "info",
+            "message": "JSON input is parseable but not canonical sort-key formatting; generated prompt JSON should be byte-stable.",
+        })
+    return "json", warnings
+
+
+def score_prompt(text: str, *, provider: str, minimum_cacheable_tokens: int) -> dict[str, Any]:
+    prompt_kind, shape_warnings = json_shape_warnings(text)
+    dynamic_offset, dynamic_marker = first_dynamic_marker(text)
+    prefix_text = text if dynamic_offset is None else text[:dynamic_offset]
+    estimated = estimate_tokens(text)
+    prefix_estimated = estimate_tokens(prefix_text)
+    total_chars = len(text)
+    static_ratio = 1.0 if total_chars == 0 else len(prefix_text) / total_chars
+    warnings = list(shape_warnings)
+    if dynamic_offset is not None:
+        warnings.append({
+            "code": "dynamic_marker_in_prompt",
+            "severity": "warn",
+            "message": "Dynamic-looking content appears before the end of the prompt; move timestamps/request IDs/user-specific values later.",
+            "offset": dynamic_offset,
+            "marker": dynamic_marker,
+        })
+    if prefix_estimated < minimum_cacheable_tokens:
+        warnings.append({
+            "code": "below_minimum_cacheable_tokens",
+            "severity": "warn",
+            "message": "Static prefix token proxy is below the selected provider threshold.",
+        })
+    if provider == "anthropic" and "cache_control" not in text:
+        warnings.append({
+            "code": "anthropic_cache_control_not_detected",
+            "severity": "info",
+            "message": "Anthropic caching usually requires cache_control around the reusable prefix.",
+        })
+
+    return {
+        "tool": TOOL_NAME,
+        "schema_version": SCHEMA_VERSION,
+        "provider": provider,
+        "prompt_kind": prompt_kind,
+        "minimum_cacheable_tokens": minimum_cacheable_tokens,
+        "eligible": prefix_estimated >= minimum_cacheable_tokens,
+        "estimated_tokens": estimated,
+        "cacheable_prefix_tokens": prefix_estimated,
+        "token_estimate": {
+            "method": "char4_proxy",
+            "chars_per_token": TOKEN_PROXY_CHARS_PER_TOKEN,
+            "estimated_tokens": estimated,
+            "cacheable_prefix_tokens": prefix_estimated,
+            "label": "provider_tokenizer_free_proxy_not_billed_tokens",
+        },
+        "input_chars": total_chars,
+        "cacheable_prefix_chars": len(prefix_text),
+        "first_dynamic_offset": dynamic_offset,
+        "first_dynamic_marker": dynamic_marker,
+        "static_prefix_ratio": round(static_ratio, 6),
+        "warnings": warnings,
+        "provider_caveat": PROVIDER_CAVEATS[provider],
+        "raw_prompt_stored": False,
+        "claim_boundary": {
+            "advisory_only": True,
+            "provider_measured_cache_hit": False,
+            "hosted_api_token_or_cost_savings_claim_allowed": False,
+            "requires_provider_usage_fields_for_claims": True,
+            "token_estimate_is_provider_tokenizer_free_proxy": True,
+        },
+    }
+
+
+def render_text(report: dict[str, Any]) -> str:
+    status = "eligible" if report.get("eligible") else "not eligible"
+    warnings = report.get("warnings") if isinstance(report.get("warnings"), list) else []
+    warning_codes = ", ".join(str(item.get("code")) for item in warnings if isinstance(item, dict)) or "none"
+    return (
+        f"{TOOL_NAME}: {status} for {report['provider']} "
+        f"(static_prefix≈{report['cacheable_prefix_tokens']} char/4 tokens, "
+        f"minimum={report['minimum_cacheable_tokens']})\n"
+        f"warnings: {warning_codes}\n"
+        "claim boundary: advisory static lint only; not a measured provider cache hit or cost saving.\n"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Static prompt cacheability lint. No provider calls, no pricing ledger, "
+            "and no measured cache-hit claims."
+        )
+    )
+    parser.add_argument("--input", help="prompt/request text or JSON path; stdin is used when omitted")
+    parser.add_argument("--provider", choices=sorted(PROVIDER_MINIMUM_CACHEABLE_TOKENS), default="generic")
+    parser.add_argument(
+        "--minimum-cacheable-tokens",
+        default=None,
+        help="override provider threshold for model/platform-specific cache minimums",
+    )
+    parser.add_argument("--max-input-bytes", default=DEFAULT_MAX_INPUT_BYTES, help=f"maximum input bytes (default: {DEFAULT_MAX_INPUT_BYTES})")
+    parser.add_argument("--json", action="store_true", help="emit stable JSON")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        max_input_bytes = bounded_int(args.max_input_bytes, default=DEFAULT_MAX_INPUT_BYTES, minimum=1, maximum=100_000_000, name="--max-input-bytes")
+        provider = str(args.provider)
+        default_minimum = PROVIDER_MINIMUM_CACHEABLE_TOKENS[provider]
+        minimum = bounded_int(
+            args.minimum_cacheable_tokens,
+            default=default_minimum,
+            minimum=1,
+            maximum=10_000_000,
+            name="--minimum-cacheable-tokens",
+        )
+        text = read_limited_path(Path(args.input), max_input_bytes) if args.input else read_limited_stdin(max_input_bytes)
+        report = score_prompt(text, provider=provider, minimum_cacheable_tokens=minimum)
+        if args.json:
+            sys.stdout.write(json_bytes(report, indent=2) + "\n")
+        else:
+            sys.stdout.write(render_text(report))
+        return 0
+    except CacheScoreError as exc:
+        print(f"{TOOL_NAME}: {exc}", file=sys.stderr)
+        return 1
+    except BrokenPipeError:
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugins/context-guard/bin/context-guard-compress

@@ -28,6 +28,9 @@ MAX_MAX_BYTES = 100_000_000
 # 메타데이터에 measurement="estimated" 로 명시해 관측 토큰 수와 혼동되지 않게 한다.
 TOKEN_PROXY_CHARS_PER_TOKEN = 4
 CONTENT_TYPES = ("json", "diff", "log", "search", "code", "prose")
+COMPRESSION_MODES = ("conservative", "readable")
+READABLE_COMPRESSION_SCHEMA_VERSION = "contextguard.compress-readable.v1"
+READABLE_SENTENCE_LIMIT = 5
 
 # diff 구조 라인(파일 헤더/헝크/변경)을 식별한다. 나머지 context 라인은 접어서 줄인다.
 DIFF_FILE_HEADER_RE = re.compile(r"^(diff --git |index [0-9a-f]|--- |\+\+\+ |rename |similarity |new file|deleted file)")
@@ -93,6 +96,20 @@ PROTECTED_DENIED_TRANSFORMS = (
     "path_rewrite",
     "quoted_literal_rewrite",
 )
+READABLE_BLOCKING_PROTECTED_KEYS = (
+    "code_fence",
+    "diff",
+    "hash",
+    "path",
+    "stack_frame",
+    "numeric_constant",
+    "quoted_string",
+    "json_key",
+)
+PROMPT_LIKE_INSTRUCTION_RE = re.compile(
+    r"(?i)\b(ignore (?:all )?(?:previous|above) instructions|system prompt|developer message|"
+    r"you are chatgpt|act as (?:a|an)|do not follow|BEGIN (?:SYSTEM|DEVELOPER)|END (?:SYSTEM|DEVELOPER))\b"
+)
 
 
 def bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
@@ -301,6 +318,43 @@ def build_transform_policy(protected_policy: dict[str, object]) -> dict[str, obj
     }
 
 
+def build_readable_compression_metadata(
+    *,
+    content_type: str,
+    strategy_detail: dict[str, object],
+    lossy: bool,
+) -> dict[str, object]:
+    blocking = strategy_detail.get("readable_blocking_signals", {})
+    if not isinstance(blocking, dict):
+        blocking = {}
+    applied = bool(strategy_detail.get("readable_applied"))
+    exact_fallback_required = bool(lossy or applied)
+    return {
+        "schema_version": READABLE_COMPRESSION_SCHEMA_VERSION,
+        "mode": "readable",
+        "preview_only": True,
+        "applied": applied,
+        "content_type": content_type,
+        "strategy": strategy_detail.get("strategy"),
+        "readable_strategy": strategy_detail.get("readable_strategy", "structural-preview"),
+        "omitted_reason": strategy_detail.get("readable_omitted_reason"),
+        "blocking_signal_counts": blocking,
+        "protected_spans_stored": False,
+        "source_verification": {
+            "exact_fallback_required": exact_fallback_required,
+            "recommended_command": "context-guard-artifact store --command 'readable-mode exact fallback' --json < sanitized-prose.txt",
+            "verify_before_edit_or_claim": True,
+        },
+        "claim_boundary": {
+            "deterministic_local_only": True,
+            "no_network_model_embedding_or_reranker": True,
+            "no_generated_semantic_rewrite": True,
+            "byte_and_token_counts_are_local_proxies": True,
+            "hosted_api_token_or_cost_savings_claim_allowed": False,
+        },
+    }
+
+
 def _looks_like_json(stripped: str) -> bool:
     if stripped[0] not in "{[":
         return False
@@ -434,6 +488,64 @@ def compress_prose(text: str) -> tuple[str, dict[str, object]]:
     return _whitespace_normalize(text, strategy="prose-whitespace", max_consecutive_blank=1)
 
 
+def readable_blocking_signal_counts(text: str, content_type: str) -> dict[str, int]:
+    counts = protected_zone_counts(text)
+    blocking = {
+        key: int(counts.get(key, 0) or 0)
+        for key in READABLE_BLOCKING_PROTECTED_KEYS
+        if int(counts.get(key, 0) or 0) > 0
+    }
+    prompt_like = len(PROMPT_LIKE_INSTRUCTION_RE.findall(text))
+    if prompt_like:
+        blocking["prompt_like_instruction"] = prompt_like
+    if content_type != "prose":
+        blocking["non_prose_content"] = 1
+    return blocking
+
+
+def split_prose_sentences(text: str) -> list[str]:
+    compact = " ".join(text.split())
+    if not compact:
+        return []
+    sentences = re.split(r"(?<=[.!?])\s+", compact)
+    return [sentence.strip() for sentence in sentences if sentence.strip()]
+
+
+def compress_prose_readable(text: str) -> tuple[str, dict[str, object]]:
+    """Readable opt-in sentence window for sanitized unprotected prose only."""
+    normalized, base_detail = compress_prose(text)
+    blocking = readable_blocking_signal_counts(normalized, "prose")
+    detail = dict(base_detail)
+    detail.update({
+        "readable_mode": True,
+        "readable_strategy": "sentence-window-preview",
+        "readable_blocking_signals": blocking,
+    })
+    if blocking:
+        detail["readable_applied"] = False
+        detail["readable_omitted_reason"] = "protected_or_prompt_like_signal"
+        return normalized, detail
+    sentences = split_prose_sentences(normalized)
+    if len(sentences) <= READABLE_SENTENCE_LIMIT:
+        detail["readable_applied"] = False
+        detail["readable_omitted_reason"] = "short_prose"
+        return normalized, detail
+    included_sentences = sentences[:3] + sentences[-1:]
+    kept = sentences[:3] + [f"[context-guard-readable] {len(sentences) - len(included_sentences)} sentence(s) omitted; retrieve exact source before relying on omitted detail."] + sentences[-1:]
+    preview = " ".join(kept)
+    if text.endswith("\n"):
+        preview += "\n"
+    detail.update({
+        "strategy": "prose-readable-window",
+        "lossy": True,
+        "readable_applied": True,
+        "sentences_original": len(sentences),
+        "sentences_included": len(included_sentences),
+        "sentences_omitted": len(sentences) - len(included_sentences),
+    })
+    return preview, detail
+
+
 def _whitespace_normalize(text: str, *, strategy: str, max_consecutive_blank: int) -> tuple[str, dict[str, object]]:
     out: list[str] = []
     blank_run = 0
@@ -482,6 +594,7 @@ def build_metadata(
     input_bytes: int,
     max_bytes: int,
     protected_policy_enabled: bool = False,
+    compression_mode: str = "conservative",
 ) -> dict[str, object]:
     """Assemble the compress receipt: observed byte/line counts plus an estimated token proxy.
 
@@ -550,6 +663,12 @@ def build_metadata(
                 "Protected lossy structural transform: store the full sanitized text with "
                 "`context-guard-artifact store` and retrieve exact slices before relying on omitted content."
             )
+    if compression_mode == "readable":
+        metadata["readable_compression"] = build_readable_compression_metadata(
+            content_type=content_type,
+            strategy_detail=strategy_detail,
+            lossy=lossy,
+        )
     return metadata
 
 
@@ -562,6 +681,7 @@ def compress_text(
     input_bytes: int,
     max_bytes: int,
     protected_policy_enabled: bool = False,
+    compression_mode: str = "conservative",
 ) -> tuple[str, dict[str, object]]:
     """Sanitize first, then classify and compress, then build the receipt.
 
@@ -573,11 +693,24 @@ def compress_text(
         content_type, type_source = forced_type, "override"
     else:
         content_type, type_source = classify_content(sanitized), "detected"
-    compressed, strategy_detail = STRATEGIES[content_type](sanitized)
+    if compression_mode == "readable" and content_type == "prose":
+        compressed, strategy_detail = compress_prose_readable(sanitized)
+    else:
+        compressed, strategy_detail = STRATEGIES[content_type](sanitized)
+        if compression_mode == "readable":
+            strategy_detail["readable_mode"] = True
+            strategy_detail["readable_strategy"] = "sentence-window-preview"
+            strategy_detail["readable_applied"] = False
+            strategy_detail["readable_omitted_reason"] = "non_prose_content"
+            strategy_detail["readable_blocking_signals"] = {"non_prose_content": 1}
     # 보수성 보장: 어떤 전략도 입력보다 큰 결과를 내보내지 않는다. 작은 입력에서
     # 접기 마커가 원본보다 길어지는 경우 살균된 원본을 그대로 유지한다.
     if byte_length(compressed) >= byte_length(sanitized):
         compressed = sanitized
+        if compression_mode == "readable" and strategy_detail.get("readable_applied"):
+            strategy_detail["lossy"] = False
+            strategy_detail["readable_applied"] = False
+            strategy_detail["readable_omitted_reason"] = "not_smaller_than_input"
         strategy_detail["reduced"] = False
     else:
         strategy_detail["reduced"] = True
@@ -592,6 +725,7 @@ def compress_text(
         input_bytes=input_bytes,
         max_bytes=max_bytes,
         protected_policy_enabled=protected_policy_enabled,
+        compression_mode=compression_mode,
     )
     return compressed, metadata
 
@@ -623,6 +757,10 @@ def render_text_receipt(metadata: dict[str, object]) -> str:
 def run_compress(args: argparse.Namespace) -> int:
     """Read stdin, compress, then emit JSON or (compressed text + stderr receipt)."""
     max_bytes = bounded_int(args.max_bytes, DEFAULT_MAX_BYTES, 1, MAX_MAX_BYTES)
+    compression_mode = args.mode
+    if compression_mode not in COMPRESSION_MODES:
+        print(f"context-guard-compress: unknown --mode: {compression_mode}", file=sys.stderr)
+        return 2
     raw_text, input_truncated, input_bytes = read_bounded_stdin(max_bytes)
     forced_type = args.type
     if forced_type is not None and forced_type not in STRATEGIES:
@@ -636,6 +774,7 @@ def run_compress(args: argparse.Namespace) -> int:
         input_bytes=input_bytes,
         max_bytes=max_bytes,
         protected_policy_enabled=bool(args.protected_policy),
+        compression_mode=compression_mode,
     )
     if args.json:
         payload = {"metadata": metadata, "content": compressed}
@@ -659,6 +798,12 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="force a content type instead of auto-detecting (json/diff/log/search/code/prose)",
     )
+    parser.add_argument(
+        "--mode",
+        choices=COMPRESSION_MODES,
+        default="conservative",
+        help="compression policy: conservative keeps existing deterministic strategies; readable adds opt-in readable preview/source-verification metadata",
+    )
     parser.add_argument("--json", action="store_true", help="emit JSON with metadata and compressed content")
     parser.add_argument(
         "--protected-policy",