redundo 0.1.0__py3-none-any.whl

redundo/__init__.py

@@ -0,0 +1,10 @@
+"""redundo: adapt agent traces to a common schema, then analyze them.
+
+    redundo adapt --source openinference traces/ | redundo analyze > report.html
+
+`redundo.adapter` and `redundo.analyzer` are independent packages
+joined by one contract, `redundo.analyzer.schema.Event` -- `analyze`
+doesn't know or care whether its input came from `adapt` or was hand-built
+NDJSON from a source this project doesn't support yet. See each
+subpackage's own docstring for its half of the pipeline.
+"""

redundo/adapter/__init__.py

@@ -0,0 +1,13 @@
+from .detect import Detection, DetectionError, Source, detect_source
+from .sources import convert_claude_code, convert_cowork, convert_openclaw, convert_openinference
+
+__all__ = [
+    "Source",
+    "Detection",
+    "DetectionError",
+    "detect_source",
+    "convert_openinference",
+    "convert_claude_code",
+    "convert_cowork",
+    "convert_openclaw",
+]

redundo/adapter/cli.py

@@ -0,0 +1,135 @@
+"""CLI entry point: a directory of captured OTLP JSON batches -> JSONL
+matching the redundo.analyzer schema contract.
+
+    redundo adapt ./otlp_traces -o trace.jsonl
+
+The source (OpenInference/Hermes, Claude Code, Cowork, or OpenClaw) is auto-detected
+from the captured data itself -- see detect.py for exactly how, and
+`--source` to skip detection and force one explicitly. A directory is
+accepted rather than a single file because every source's own exporter
+flushes on an interval, producing many small batch files per session
+rather than one large export.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .detect import DetectionError, Source, detect_source
+from .otlp import OtlpParseError, is_log_document, is_trace_document
+from .sources import convert_claude_code, convert_cowork, convert_openclaw, convert_openinference
+from .writer import write_jsonl
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="redundo adapt",
+        description="Convert a directory of captured OTLP JSON batches into JSONL "
+        "matching the redundo analyze schema contract. The source is "
+        "auto-detected from the data; pass --source to override.",
+    )
+    parser.add_argument(
+        "otlp_dir", type=Path,
+        help="Directory of *.json OTLP export batch files (traces and/or logs, any mix)",
+    )
+    parser.add_argument(
+        "-o", "--output", type=Path, default=None, metavar="PATH",
+        help="Write JSONL here instead of stdout",
+    )
+    parser.add_argument(
+        "--source", choices=[s.value for s in Source], default=None,
+        help="Skip auto-detection and force this source",
+    )
+    parser.add_argument(
+        "--summary",
+        action="store_true",
+        help="Print the conversion summary (record counts, content-provenance "
+        "stats, per-source notes) to stderr",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.otlp_dir.is_dir():
+        print(f"redundo adapt: not a directory: {args.otlp_dir}", file=sys.stderr)
+        return 1
+
+    documents = []
+    skipped_unrecognized = 0
+    for path in sorted(args.otlp_dir.glob("*.json")):
+        try:
+            doc = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"redundo adapt: {path}: {exc}", file=sys.stderr)
+            return 1
+        if is_trace_document(doc) or is_log_document(doc):
+            documents.append(doc)
+        else:
+            skipped_unrecognized += 1
+
+    if not documents:
+        print(
+            f"redundo adapt: no OTLP trace or log documents found in {args.otlp_dir}",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.source is not None:
+        source = Source(args.source)
+        reason = "--source flag"
+    else:
+        try:
+            detection = detect_source(documents)
+        except DetectionError as exc:
+            print(f"redundo adapt: {exc}", file=sys.stderr)
+            return 1
+        source, reason = detection.source, detection.reason
+
+    trace_docs = [d for d in documents if is_trace_document(d)]
+    log_docs = [d for d in documents if is_log_document(d)]
+
+    try:
+        if source is Source.OPENINFERENCE:
+            records, summary = convert_openinference(trace_docs)
+        elif source is Source.CLAUDE_CODE:
+            records, summary = convert_claude_code(documents)
+        elif source is Source.OPENCLAW:
+            records, summary = convert_openclaw(trace_docs)
+        else:
+            records, summary = convert_cowork(log_docs)
+    except OtlpParseError as exc:
+        print(f"redundo adapt: {exc}", file=sys.stderr)
+        return 1
+
+    if args.output:
+        with args.output.open("w", encoding="utf-8") as handle:
+            write_jsonl(records, handle)
+    else:
+        write_jsonl(records, sys.stdout)
+
+    if args.summary or not records:
+        print(f"\nsource: {source.value} (detected via {reason})", file=sys.stderr)
+        if skipped_unrecognized:
+            print(
+                f"  ({skipped_unrecognized} file(s) in {args.otlp_dir} were not "
+                "recognized OTLP trace/log exports and were ignored)",
+                file=sys.stderr,
+            )
+        skipped_by_kind = getattr(summary, "skipped_by_kind", None)
+        if skipped_by_kind:
+            for kind, count in sorted(skipped_by_kind.items()):
+                print(f"  - {count} span(s)/event(s) of kind {kind!r} skipped", file=sys.stderr)
+        for note in summary.notes():
+            print(f"  - {note}", file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

redundo/adapter/collector.py

@@ -0,0 +1,171 @@
+"""Minimal local OTLP/HTTP receiver -- point any source's OTLP exporter at
+it and it writes each POST out as OTLP JSON, one file per batch, into one
+output directory that `redundo adapt` reads directly.
+
+This is a convenience for local development and one-off analysis, not a
+production observability pipeline -- if you already run a real OTel
+Collector (or any backend with a file/JSON export path), point your
+source at that instead and hand its output directory to `redundo adapt`
+the same way. Every source this project supports needs both `/v1/traces`
+and `/v1/logs` served from the *same* endpoint (some sources use only one,
+some use both, and get one endpoint config to remember either way), so
+this collector always serves both.
+
+Requires the `collector` extra: `pip install redundo[collector]`
+
+Usage:
+    redundo collect --port 4318 --out-dir ./otlp_traces
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+try:
+    from google.protobuf.json_format import MessageToDict
+    from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import (
+        ExportLogsServiceRequest,
+        ExportLogsServiceResponse,
+    )
+    from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
+        ExportTraceServiceRequest,
+        ExportTraceServiceResponse,
+    )
+except ImportError:
+    print(
+        "redundo collect requires the 'collector' extra: "
+        "pip install redundo[collector]",
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
+OUT_DIR = Path("./otlp_traces")
+
+
+def _fix_span_ids_to_hex(request: ExportTraceServiceRequest, document: dict) -> None:
+    """MessageToDict base64-encodes `bytes` fields by default. The OTLP
+    spec carves out trace_id/span_id/parent_span_id as a documented
+    exception -- those are hex in real OTLP JSON, not base64. Overwrite
+    them from the original protobuf objects, which have the real bytes.
+    """
+    for rs_proto, rs_doc in zip(request.resource_spans, document.get("resourceSpans", [])):
+        for ss_proto, ss_doc in zip(rs_proto.scope_spans, rs_doc.get("scopeSpans", [])):
+            for span_proto, span_doc in zip(ss_proto.spans, ss_doc.get("spans", [])):
+                span_doc["traceId"] = span_proto.trace_id.hex()
+                span_doc["spanId"] = span_proto.span_id.hex()
+                if span_proto.parent_span_id:
+                    span_doc["parentSpanId"] = span_proto.parent_span_id.hex()
+                elif "parentSpanId" in span_doc:
+                    del span_doc["parentSpanId"]
+
+
+def _fix_log_ids_to_hex(request: ExportLogsServiceRequest, document: dict) -> None:
+    for rl_proto, rl_doc in zip(request.resource_logs, document.get("resourceLogs", [])):
+        for sl_proto, sl_doc in zip(rl_proto.scope_logs, rl_doc.get("scopeLogs", [])):
+            for rec_proto, rec_doc in zip(sl_proto.log_records, sl_doc.get("logRecords", [])):
+                if rec_proto.trace_id:
+                    rec_doc["traceId"] = rec_proto.trace_id.hex()
+                elif "traceId" in rec_doc:
+                    del rec_doc["traceId"]
+                if rec_proto.span_id:
+                    rec_doc["spanId"] = rec_proto.span_id.hex()
+                elif "spanId" in rec_doc:
+                    del rec_doc["spanId"]
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, fmt, *args):
+        print(f"[collector] {self.address_string()} - {fmt % args}")
+
+    def do_POST(self):
+        if self.path in ("/v1/traces", "/v1/traces/"):
+            self._handle_traces()
+        elif self.path in ("/v1/logs", "/v1/logs/"):
+            self._handle_logs()
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def _handle_traces(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length)
+        request = ExportTraceServiceRequest()
+        request.ParseFromString(body)
+        document = MessageToDict(
+            request, preserving_proto_field_name=False, use_integers_for_enums=True
+        )
+        _fix_span_ids_to_hex(request, document)
+
+        span_count = sum(
+            len(scope_span.get("spans", []))
+            for rs in document.get("resourceSpans", [])
+            for scope_span in rs.get("scopeSpans", [])
+        )
+        OUT_DIR.mkdir(parents=True, exist_ok=True)
+        out_path = OUT_DIR / f"traces-{time.time_ns()}.otlp.json"
+        out_path.write_text(json.dumps(document), encoding="utf-8")
+        print(f"[collector] wrote {span_count} span(s) -> {out_path}")
+
+        payload = ExportTraceServiceResponse().SerializeToString()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/x-protobuf")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _handle_logs(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length)
+        request = ExportLogsServiceRequest()
+        request.ParseFromString(body)
+        document = MessageToDict(
+            request, preserving_proto_field_name=False, use_integers_for_enums=True
+        )
+        _fix_log_ids_to_hex(request, document)
+
+        record_count = sum(
+            len(scope_log.get("logRecords", []))
+            for rl in document.get("resourceLogs", [])
+            for scope_log in rl.get("scopeLogs", [])
+        )
+        OUT_DIR.mkdir(parents=True, exist_ok=True)
+        out_path = OUT_DIR / f"logs-{time.time_ns()}.otlp.json"
+        out_path.write_text(json.dumps(document), encoding="utf-8")
+        print(f"[collector] wrote {record_count} log record(s) -> {out_path}")
+
+        payload = ExportLogsServiceResponse().SerializeToString()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/x-protobuf")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="redundo collect")
+    parser.add_argument("--port", type=int, default=4318)
+    parser.add_argument("--out-dir", type=Path, default=Path("./otlp_traces"))
+    args = parser.parse_args(argv)
+
+    global OUT_DIR
+    OUT_DIR = args.out_dir
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    server = ThreadingHTTPServer(("localhost", args.port), Handler)
+    print(f"[collector] listening on http://localhost:{args.port}/v1/traces and /v1/logs")
+    print(f"[collector] writing OTLP JSON batches to {OUT_DIR.resolve()}")
+    print("[collector] Ctrl+C to stop, then: redundo adapt <out-dir> -o trace.jsonl")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

redundo/adapter/detect.py

@@ -0,0 +1,136 @@
+"""Figure out which source produced a captured OTLP corpus, so the CLI can
+"just point it at your traces directory" without the user having to name
+the source themselves.
+
+Detection order, each check grounded in something actually verified
+against real captured data or real source code (see each source's
+docs/*.md), not assumed:
+
+1. Any span named `claude_code.*` -> Claude Code. Cowork never produces
+   trace spans in its documented configuration, and OpenInference spans
+   are never named this way, so this is unambiguous by itself.
+2. Any span named `openclaw.*` -> OpenClaw. Same reasoning: no other
+   supported source uses this prefix. This only catches OpenClaw's default
+   span naming -- an operator who has opted into
+   `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` gets spans
+   named `"<gen_ai.operation.name> <model>"` instead, which is genuinely
+   ambiguous with other gen_ai-semconv-instrumented sources and isn't
+   guessed at here -- see step 3's fallback and docs/openclaw.md.
+3. Any span carrying `openinference.span.kind` -> OpenInference (Hermes,
+   or anything else instrumented with an OpenInference-compatible
+   library -- see docs/openinference.md for what that covers and doesn't).
+4. Any span carrying `openclaw.model_call.observation_unit` -> OpenClaw.
+   Catches the gen_ai_latest_experimental-named case from step 2: this
+   attribute is present on every OpenClaw model-call span regardless of
+   naming mode (confirmed against the exporter's own source), and no other
+   supported source sets it.
+5. Otherwise (a logs-only corpus, no trace spans at all): Claude Code and
+   Cowork both emit an overlapping set of logs-signal event names
+   (`user_prompt`, `tool_result`, `api_request`, ...), so the event shape
+   alone is genuinely ambiguous -- confirmed empirically, not assumed
+   (see docs/claude-code.md and docs/cowork.md). Disambiguated by the
+   OTLP resource-level `service.name` attribute instead
+   (`resource.attributes`, attached once per resourceLogs entry,
+   describing the emitting process -- "claude-code" or "cowork",
+   confirmed against real captures / the Cowork monitoring reference).
+   Falls back to Claude-Code-only event names (`mcp_server_connection`,
+   `permission_mode_changed`, `auth` -- not in Cowork's documented event
+   list) if `service.name` is ever missing.
+
+Detection failure is reported, never guessed past -- see DetectionError.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from .otlp import document_resource_attributes, is_log_document, is_trace_document, parse_log_records, parse_spans
+
+
+class Source(str, Enum):
+    OPENINFERENCE = "openinference"
+    CLAUDE_CODE = "claude-code"
+    COWORK = "cowork"
+    OPENCLAW = "openclaw"
+
+
+class DetectionError(ValueError):
+    pass
+
+
+# Event names Cowork's monitoring reference documents in full -- an event
+# outside this set appearing in a logs-only corpus means it isn't Cowork.
+_COWORK_EVENT_NAMES = frozenset(
+    {"user_prompt", "assistant_response", "tool_result", "api_request", "api_error", "tool_decision"}
+)
+# Observed on real Claude Code captures, never documented for Cowork.
+_CLAUDE_CODE_ONLY_EVENT_NAMES = frozenset(
+    {"mcp_server_connection", "permission_mode_changed", "auth"}
+)
+
+_OPENINFERENCE_KIND_ATTR = "openinference.span.kind"
+_OPENCLAW_OBSERVATION_UNIT_ATTR = "openclaw.model_call.observation_unit"
+
+
+@dataclass
+class Detection:
+    source: Source
+    reason: str
+
+
+def detect_source(documents: list[dict[str, Any]]) -> Detection:
+    trace_docs = [d for d in documents if is_trace_document(d)]
+    log_docs = [d for d in documents if is_log_document(d)]
+
+    for doc in trace_docs:
+        for span in parse_spans(doc):
+            if span.name.startswith("claude_code."):
+                return Detection(Source.CLAUDE_CODE, f"span name {span.name!r}")
+            if span.name.startswith("openclaw."):
+                return Detection(Source.OPENCLAW, f"span name {span.name!r}")
+            if _OPENINFERENCE_KIND_ATTR in span.attributes:
+                return Detection(
+                    Source.OPENINFERENCE, f"span attribute {_OPENINFERENCE_KIND_ATTR!r}"
+                )
+            if _OPENCLAW_OBSERVATION_UNIT_ATTR in span.attributes:
+                return Detection(
+                    Source.OPENCLAW, f"span attribute {_OPENCLAW_OBSERVATION_UNIT_ATTR!r}"
+                )
+
+    for doc in trace_docs + log_docs:
+        for resource_attrs in document_resource_attributes(doc):
+            service_name = resource_attrs.get("service.name")
+            if service_name == "claude-code":
+                return Detection(Source.CLAUDE_CODE, "resource service.name='claude-code'")
+            if service_name == "cowork":
+                return Detection(Source.COWORK, "resource service.name='cowork'")
+
+    event_names: set[str] = set()
+    for doc in log_docs:
+        for rec in parse_log_records(doc):
+            name = rec.attributes.get("event.name")
+            if isinstance(name, str):
+                event_names.add(name)
+    if event_names:
+        if event_names & _CLAUDE_CODE_ONLY_EVENT_NAMES:
+            return Detection(
+                Source.CLAUDE_CODE,
+                f"event name(s) {sorted(event_names & _CLAUDE_CODE_ONLY_EVENT_NAMES)} "
+                "not in Cowork's documented event set",
+            )
+        if event_names <= _COWORK_EVENT_NAMES:
+            return Detection(
+                Source.COWORK,
+                "logs-only corpus with only Cowork-documented event names, no "
+                "service.name and no Claude-Code-only event present",
+            )
+
+    raise DetectionError(
+        "could not determine which source produced this corpus -- found "
+        f"{len(trace_docs)} trace document(s) and {len(log_docs)} log document(s), "
+        "but none carried a recognizable span name, openinference.span.kind "
+        "attribute, resource service.name, or logs-signal event.name. Pass "
+        "--source explicitly (openinference, claude-code, cowork, or openclaw)."
+    )

redundo/adapter/hashing.py

@@ -0,0 +1,145 @@
+"""Content hashing: the precise procedure, implemented once so it can be
+copied correctly. See docs/hashing.md for the written contract this implements and
+the reasoning behind each choice. Do not change this file's behavior
+without bumping HASH_SPEC -- comparisons across corpora depend on both
+sides having run identical code.
+
+The one invariant that matters most: nothing downstream of this module
+ever sees raw content, only hashes. That's what makes it safe to run this
+adapter against production traces without a security review of the
+analyzer. Don't let raw prompt/argument text leak into logs, exceptions,
+or the `name`/`workflow` fields this module doesn't touch.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import unicodedata
+from typing import Any
+
+HASH_SPEC = "v1"
+HASH_LENGTH = 16  # hex chars = 64 bits. See docs/hashing.md for the birthday-bound math.
+
+# Order matters: broader/more specific patterns first so a later pattern
+# can't partially match inside a token an earlier pass already replaced.
+_ISO_DATETIME_RE = re.compile(
+    r"\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?\b"
+)
+_ISO_DATE_ONLY_RE = re.compile(r"\b\d{4}-\d{2}-\d{2}\b")
+_RFC_DATE_RE = re.compile(
+    r"\b(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun),\s+\d{1,2}\s+"
+    r"(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w*\s+\d{4}\s+"
+    r"\d{2}:\d{2}:\d{2}\s+(?:GMT|UTC|[+-]\d{4})\b"
+)
+_UUID_RE = re.compile(
+    r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"
+)
+_DURATION_RE = re.compile(r"\b\d+(?:\.\d+)?(?:ms|us|µs|ns|s|m|h)\b")
+_HEX_ADDR_RE = re.compile(r"\b0x[0-9a-fA-F]{4,}\b")
+_TMP_PATH_RE = re.compile(r"(?:/tmp/|/var/folders/)\S*")
+_BARE_INTEGER_RE = re.compile(r"\b\d{5,}\b")  # opt-in only; see mask_volatile
+
+# (replacement token, pattern) in application order.
+_MASKS: list[tuple[str, re.Pattern[str]]] = [
+    ("<DATE>", _ISO_DATETIME_RE),
+    ("<DATE>", _ISO_DATE_ONLY_RE),
+    ("<DATE>", _RFC_DATE_RE),
+    ("<UUID>", _UUID_RE),
+    ("<DUR>", _DURATION_RE),
+    ("<ADDR>", _HEX_ADDR_RE),
+    ("<TMP>", _TMP_PATH_RE),
+]
+
+
+def normalize_text(text: str) -> str:
+    """Unicode NFC, collapse whitespace runs, strip ends. For plain-text
+    content (prompts, messages) -- not for structured content, which goes
+    through canonicalize_json instead.
+    """
+    text = unicodedata.normalize("NFC", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _normalize_numbers(value: Any) -> Any:
+    """Floats with no fractional part collapse to int, so 1 and 1.0
+    canonicalize identically. This is the one deliberate departure from
+    "serialize exactly what json.loads gave you" -- documented in docs/hashing.md.
+    """
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, dict):
+        return {k: _normalize_numbers(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_normalize_numbers(v) for v in value]
+    return value
+
+
+def canonicalize_json(value: Any) -> str:
+    """Sorted keys, no insignificant whitespace, normalized numbers.
+    `value` may already be a parsed object, or a JSON string -- both are
+    accepted so callers don't need to know which they have.
+    """
+    if isinstance(value, str):
+        value = json.loads(value)
+    normalized = _normalize_numbers(value)
+    return json.dumps(normalized, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def mask_volatile(text: str, *, mask_integers: bool = False) -> tuple[str, int]:
+    """Replace volatile spans with stable placeholder tokens. Returns
+    (masked_text, spans_masked) -- the count is the diagnostic signal:
+    surface it in metadata so "zero repeats" and "zero repeats because
+    something volatile leaked through" don't look identical.
+
+    mask_integers is opt-in and off by default: a bare integer could be an
+    epoch timestamp or an order ID, and masking order IDs would collapse
+    genuinely different calls into one hash -- a false positive in the
+    headline metric, which is worse than a false negative here.
+    """
+    total = 0
+    for token, pattern in _MASKS:
+        text, n = pattern.subn(token, text)
+        total += n
+    if mask_integers:
+        text, n = _BARE_INTEGER_RE.subn("<NUM>", text)
+        total += n
+    return text, total
+
+
+def content_hash(
+    raw: Any,
+    *,
+    structured: bool = False,
+    mask_integers: bool = False,
+) -> tuple[str, int]:
+    """The full procedure: normalize (text) or canonicalize (structured),
+    mask volatile spans, hash. Returns (hash_hex, masked_span_count).
+
+    `structured=True` for tool call arguments / JSON payloads.
+    `structured=False` (default) for free-text prompts and messages.
+
+    A `structured=True` value that isn't actually valid JSON (a mime_type
+    attribute claiming application/json on malformed content, for
+    instance) falls back to plain-text normalization instead of raising.
+    This adapter runs inside the boundary that's supposed to keep raw
+    content contained; letting one malformed record's parse error
+    propagate as an uncaught exception is the wrong failure mode here --
+    it aborts the whole conversion, and an exception object risks
+    carrying a fragment of that content into a log or traceback somewhere
+    outside this function's control. Degrading to text-mode hashing
+    keeps every record processed and keeps content from ever needing to
+    leave this function in the first place.
+    """
+    if structured:
+        try:
+            text = canonicalize_json(raw)
+        except (TypeError, ValueError):
+            text = normalize_text(str(raw))
+    else:
+        text = normalize_text(str(raw))
+    masked_text, span_count = mask_volatile(text, mask_integers=mask_integers)
+    digest = hashlib.sha256(masked_text.encode("utf-8")).hexdigest()[:HASH_LENGTH]
+    return digest, span_count