@ictechgy/context-guard 0.4.4 → 0.4.6

package/context-guard-kit/claude_transcript_cost_audit.py

@@ -46,7 +46,8 @@ COST_KEYS = ("total_cost_usd", "cost_usd", "costUSD")
 MODEL_KEYS = ("model", "model_id", "modelId")
 QUERY_SOURCE_KEYS = ("query_source", "querySource")
 TIMESTAMP_KEYS = ("timestamp", "created_at", "createdAt", "time", "ts")
-FEASIBILITY_SCHEMA_VERSION = "contextguard.metric-feasibility.v1.2"
+FEASIBILITY_SCHEMA_VERSION = "contextguard.metric-feasibility.v1.3"
+MAC_VISIBILITY_SCHEMA_VERSION = "contextguard.mac-visibility.v1"
 FEASIBILITY_PRODUCER = "context-guard-audit"
 CACHE_DIAGNOSTICS_SCHEMA_VERSION = "contextguard.cache-diagnostics.v1"
 CACHE_LAYOUT_ADVICE_SCHEMA_VERSION = "contextguard.cache-layout-advice.v1"
@@ -1635,6 +1636,168 @@ def build_metric_caveats(summary: UsageSummary) -> list[str]:
     return caveats
 
 
+def _mac_card(
+    card_id: str,
+    title: str,
+    status: str,
+    binding_paths: list[str],
+    *,
+    required_observation: str | None = None,
+) -> dict[str, Any]:
+    card: dict[str, Any] = {
+        "id": card_id,
+        "title": title,
+        "status": status,
+        "binding_paths": binding_paths,
+    }
+    if required_observation:
+        card["required_observation"] = required_observation
+    return card
+
+
+def build_mac_visibility_contract(
+    *,
+    availability: dict[str, Any],
+    integrity: dict[str, Any],
+    cache_layout_advice: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the pre-GUI macOS visibility binding contract.
+
+    This is intentionally a thin index over already-emitted stable feasibility
+    fields. It does not recompute metrics, read diagnostic summary data, or infer
+    live context/headroom from historical transcript totals.
+    """
+    token_status = str((availability.get("tokens") or {}).get("status", "missing"))
+    scan_status = str(integrity.get("status", "partial"))
+    if token_status == "available" and scan_status == "complete":
+        readiness_status = "ready"
+        readiness_reason = "Transcript token totals are available and the scan completed within configured limits."
+    elif token_status in {"available", "partial"}:
+        readiness_status = "partial"
+        readiness_reason = "Some stable fields can be shown, but scan integrity or metric availability is partial."
+    else:
+        readiness_status = "missing"
+        readiness_reason = "Token totals are missing from the transcript scan; show setup or unavailable state."
+
+    context_status = str((availability.get("context") or {}).get("status", "missing"))
+    headroom_status = str((availability.get("headroom") or {}).get("status", "missing"))
+    cache_status = str((availability.get("cache") or {}).get("status", "missing"))
+    cost_status = str((availability.get("cost") or {}).get("status", "missing"))
+    advice_status = str(cache_layout_advice.get("status", "missing"))
+
+    missing_live_observations: list[dict[str, Any]] = []
+    if context_status == "missing":
+        missing_live_observations.append({
+            "id": "live_context_window",
+            "required_observation": "live_statusline_snapshot",
+            "affects": ["context_availability", "metric_availability.context"],
+            "reason": "Historical transcript scans do not include live Claude Code context_window data.",
+        })
+    if headroom_status == "missing":
+        missing_live_observations.append({
+            "id": "live_headroom",
+            "required_observation": "live_statusline_snapshot",
+            "affects": ["headroom_availability", "cache_diagnostics.headroom_diagnostics"],
+            "reason": "Historical transcript totals are not remaining-token or live headroom observations.",
+        })
+
+    return {
+        "schema_version": MAC_VISIBILITY_SCHEMA_VERSION,
+        "surface_kind": "local_macos_visibility_contract",
+        "readiness": {
+            "status": readiness_status,
+            "reason": readiness_reason,
+        },
+        "bind_to_top_level_fields": [
+            "source_kind",
+            "source_freshness",
+            "scan_integrity",
+            "metric_availability",
+            "metric_caveats",
+            "redaction_mode",
+            "context_availability",
+            "headroom_availability",
+            "cache_friendliness",
+            "cache_diagnostics",
+            "cache_layout_advice",
+            "totals",
+        ],
+        "diagnostic_only_fields": ["summary"],
+        "primary_cards": [
+            _mac_card(
+                "source_freshness",
+                "Source freshness",
+                "available",
+                ["source_kind", "source_freshness.status", "source_freshness.generated_at"],
+            ),
+            _mac_card(
+                "scan_integrity",
+                "Scan integrity",
+                scan_status,
+                [
+                    "scan_integrity.status",
+                    "scan_integrity.files_scanned",
+                    "scan_integrity.records_scanned",
+                    "scan_integrity.skipped_files",
+                    "scan_integrity.skipped_records",
+                ],
+            ),
+            _mac_card(
+                "token_totals",
+                "Token totals",
+                token_status,
+                [
+                    "totals.total_tokens",
+                    "totals.tokens.input",
+                    "totals.tokens.output",
+                    "totals.tokens.cache_read",
+                    "totals.tokens.cache_creation",
+                ],
+            ),
+            _mac_card(
+                "cache_reuse",
+                "Cache-read share and reuse ratio",
+                cache_status,
+                ["totals.cache_read_share", "totals.cache_reuse_ratio", "metric_availability.cache"],
+            ),
+            _mac_card(
+                "observed_cost",
+                "Observed transcript cost",
+                cost_status,
+                ["totals.cost_usd_observed", "metric_availability.cost"],
+            ),
+            _mac_card(
+                "context_availability",
+                "Context availability",
+                context_status,
+                ["context_availability", "metric_availability.context"],
+                required_observation="live_statusline_snapshot" if context_status == "missing" else None,
+            ),
+            _mac_card(
+                "headroom_availability",
+                "Headroom availability",
+                headroom_status,
+                ["headroom_availability", "cache_diagnostics.headroom_diagnostics"],
+                required_observation="live_statusline_snapshot" if headroom_status == "missing" else None,
+            ),
+            _mac_card(
+                "cache_layout_advice",
+                "Cache layout advice",
+                advice_status,
+                ["cache_layout_advice", "cache_friendliness", "cache_diagnostics.dynamic_prefix_breakers"],
+            ),
+        ],
+        "missing_live_observations": missing_live_observations,
+        "claim_boundaries": [
+            "Local transcript observations are not invoice-grade billing records.",
+            "Provider cache fields are telemetry, not ContextGuard-caused token reduction and do not prove provider cache hits.",
+            "Historical transcript totals do not infer live context headroom or remaining tokens.",
+            "This contract does not guarantee token or cost savings.",
+        ],
+        "redaction_required": True,
+    }
+
+
 def feasibility_json(
     summary: UsageSummary,
     top: int = 15,
@@ -1652,6 +1815,11 @@ def feasibility_json(
     cache_friendliness = cache_friendliness_for_summary(summary)
     cache_diagnostics = cache_diagnostics_for_summary(summary)
     cache_layout_advice = cache_layout_advice_for_summary(summary)
+    mac_visibility = build_mac_visibility_contract(
+        availability=availability,
+        integrity=integrity,
+        cache_layout_advice=cache_layout_advice,
+    )
     return {
         "schema_version": FEASIBILITY_SCHEMA_VERSION,
         "producer": FEASIBILITY_PRODUCER,
@@ -1672,6 +1840,7 @@ def feasibility_json(
                 "cache_friendliness",
                 "cache_diagnostics",
                 "cache_layout_advice",
+                "mac_visibility",
                 "totals",
             ],
             "diagnostic_fields": ["summary"],
@@ -1701,6 +1870,7 @@ def feasibility_json(
         "cache_friendliness": cache_friendliness,
         "cache_diagnostics": cache_diagnostics,
         "cache_layout_advice": cache_layout_advice,
+        "mac_visibility": mac_visibility,
         "totals": {
             "total_tokens": stable_total_tokens,
             "tokens": stable_tokens,

package/context-guard-kit/context_pack.py

@@ -729,29 +729,95 @@ def ensure_private_pack_dir(root: Path) -> tuple[Path | None, int | None, str |
                 pass
 
 
-def write_private_json_at(dir_fd: int, filename: str, data: dict[str, Any]) -> None:
+def atomic_write_ops_supported() -> bool:
+    return (
+        os.open in os.supports_dir_fd
+        and os.rename in os.supports_dir_fd
+        and os.unlink in os.supports_dir_fd
+    )
+
+
+def fsync_dir_fd(dir_fd: int) -> None:
+    os.fsync(dir_fd)
+
+
+def validate_existing_output_target_at(dir_fd: int, filename: str, option_name: str) -> None:
+    flags = os.O_WRONLY
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NONBLOCK"):
+        flags |= os.O_NONBLOCK
+    file_fd = -1
+    try:
+        file_fd = os.open(filename, flags, dir_fd=dir_fd)
+        st = os.fstat(file_fd)
+        if not stat.S_ISREG(st.st_mode):
+            raise PackError(f"invalid {option_name}: unsafe_path")
+    except FileNotFoundError:
+        return
+    except IsADirectoryError as exc:
+        raise PackError(f"invalid {option_name}: unsafe_path") from exc
+    except OSError as exc:
+        raise PackError(f"invalid {option_name}: {exc.strerror or exc.__class__.__name__}") from exc
+    finally:
+        if file_fd >= 0:
+            try:
+                os.close(file_fd)
+            except OSError:
+                pass
+
+
+def write_text_atomic_at(dir_fd: int, filename: str, content: str, *, mode: int, option_name: str) -> None:
     if "/" in filename or filename in {"", ".", ".."}:
-        raise PackError("unsafe_artifact_path")
-    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+        raise PackError(f"invalid {option_name}: unsafe_path")
+    if not atomic_write_ops_supported():
+        raise PackError(f"invalid {option_name}: atomic_write_unsupported")
+    validate_existing_output_target_at(dir_fd, filename, option_name)
+    digest = hashlib.sha256(f"{filename}:{os.getpid()}:{time.time_ns()}".encode("utf-8", "replace")).hexdigest()[:16]
+    temp_name = f".context-guard-pack-{digest}.tmp"
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
     if hasattr(os, "O_NOFOLLOW"):
         flags |= os.O_NOFOLLOW
     if hasattr(os, "O_CLOEXEC"):
         flags |= os.O_CLOEXEC
-    fd = os.open(filename, flags, 0o600, dir_fd=dir_fd)
+    fd = -1
+    temp_created = False
     try:
-        with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            json.dump(data, handle, ensure_ascii=False, indent=2, sort_keys=True)
-            handle.write("\n")
-    except Exception:
+        fd = os.open(temp_name, flags, mode, dir_fd=dir_fd)
+        temp_created = True
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
+            fd = -1
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        fsync_dir_fd(dir_fd)
+        os.rename(temp_name, filename, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+        temp_created = False
         try:
-            os.close(fd)
-        except OSError:
+            os.chmod(filename, mode, dir_fd=dir_fd, follow_symlinks=False)
+        except (OSError, TypeError, NotImplementedError):
             pass
-        raise
-    try:
-        os.chmod(filename, 0o600, dir_fd=dir_fd, follow_symlinks=False)
-    except (OSError, TypeError, NotImplementedError):
-        pass
+        fsync_dir_fd(dir_fd)
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if temp_created:
+            try:
+                os.unlink(temp_name, dir_fd=dir_fd)
+            except OSError:
+                pass
+
+
+def write_private_json_at(dir_fd: int, filename: str, data: dict[str, Any]) -> None:
+    if "/" in filename or filename in {"", ".", ".."}:
+        raise PackError("unsafe_artifact_path")
+    content = json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    write_text_atomic_at(dir_fd, filename, content, mode=0o600, option_name="artifact receipt")
 
 
 def finalize_receipt_size(receipt: dict[str, Any]) -> int:
@@ -1453,27 +1519,13 @@ def write_text_under_root(root: Path, raw_path: str, content: str, option_name:
     parent_parts = rel.parts[:-1]
     filename = rel.parts[-1]
     current_fd: int | None = None
-    file_fd = -1
     try:
         current_fd = open_dir_no_follow(root)
         for part in parent_parts:
             next_fd = open_dir_no_follow(part, dir_fd=current_fd)
             os.close(current_fd)
             current_fd = next_fd
-        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
-        if hasattr(os, "O_NOFOLLOW"):
-            flags |= os.O_NOFOLLOW
-        if hasattr(os, "O_CLOEXEC"):
-            flags |= os.O_CLOEXEC
-        if hasattr(os, "O_NONBLOCK"):
-            flags |= os.O_NONBLOCK
-        file_fd = os.open(filename, flags, 0o600, dir_fd=current_fd)
-        st = os.fstat(file_fd)
-        if not stat.S_ISREG(st.st_mode):
-            raise PackError(f"invalid {option_name}: unsafe_path")
-        with os.fdopen(file_fd, "w", encoding="utf-8") as handle:
-            file_fd = -1
-            handle.write(content)
+        write_text_atomic_at(current_fd, filename, content, mode=0o600, option_name=option_name)
     except PackError:
         raise
     except FileNotFoundError as exc:
@@ -1481,11 +1533,6 @@ def write_text_under_root(root: Path, raw_path: str, content: str, option_name:
     except OSError as exc:
         raise PackError(f"invalid {option_name}: {exc.strerror or exc.__class__.__name__}") from exc
     finally:
-        if file_fd >= 0:
-            try:
-                os.close(file_fd)
-            except OSError:
-                pass
         if current_fd is not None:
             try:
                 os.close(current_fd)