ingero-annotate 0.1.0__tar.gz

ingero_annotate-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Binaries
+/bin/
+/ingero
+*.a
+
+# eBPF generated. The committed *_bpfel.go and *_bpfel.o pairs ARE
+# release artifacts; CI and goreleaser embed them. The committed
+# bpf/headers/vmlinux.h is the canonical type catalog the per-arch
+# CO-RE compile reads (see Makefile `generate` target). It is host-
+# arch independent — CO-RE relocates field accesses against the
+# loaded kernel BTF at runtime, not the headers used at compile time.
+
+# Go
+vendor/
+
+# Build output
+dist/
+.output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+*.pem
+*.key
+
+# VM state
+.tensordock-vm.json
+.lambdalabs-vm*.json
+.azure-vm.json
+
+# Logs (session logs, test output)
+/logs/
+
+# Claude Code (local-only project context)
+.claude/
+CLAUDE.md
+
+# Test artifacts
+coverage.out
+*.test
+
+# MCP Registry publisher tokens
+.mcpregistry_*
+
+# Asciinema recordings (large, used to generate GIFs)
+docs/assets/*.cast
+
+# Python bytecode cache from the examples/ integration test suites
+__pycache__/
+*.pyc
+.pytest_cache/

ingero_annotate-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ingero_annotate-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: ingero-annotate
+Version: 0.1.0
+Summary: Writer for the Ingero agent annotation socket. Speaks the agent v0.17+ NDJSON annotation protocol; framework-agnostic.
+Project-URL: Homepage, https://github.com/ingero-io/ingero
+Project-URL: Repository, https://github.com/ingero-io/ingero
+Project-URL: Documentation, https://github.com/ingero-io/ingero/blob/main/docs/commands.md
+Project-URL: Issues, https://github.com/ingero-io/ingero/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: annotation,ebpf,gpu,ingero,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ingero-annotate
+
+Writer for the Ingero agent annotation socket. Speaks the agent's
+v0.17 NDJSON annotation protocol and nothing else, so any training
+framework or inference frontend can inject `step`, `epoch`,
+`task_id`, `request_id`, `model`, or any custom label into a live
+recorded trace without a framework-specific dependency.
+
+## Install
+
+```
+pip install ingero-annotate
+```
+
+## Use
+
+```python
+from ingero_annotate import AnnotationWriter
+
+writer = AnnotationWriter()               # default socket: /run/ingero/annotate.sock
+writer.write({"step": "42"})              # instant annotation
+writer.write_span({"epoch": "3"}, ...)    # span annotation
+```
+
+The full public surface is documented in the module's docstring;
+see `python/ingero-annotate/ingero_annotate.py`.
+
+The agent must be running with the annotation socket bound
+(`ingero trace --record --annotate`). When the socket is absent or
+the agent has not bound it, the writer drops silently and the
+caller's code path is untouched.
+
+## What this is and is not
+
+This is the protocol layer. It validates label keys and values
+against the agent's contract (`pkg/contract/annotate.go` in the
+agent repo), opens the Unix-domain socket, sends NDJSON, handles
+reconnect, and gives you back a small Python API. It has no
+framework dependency.
+
+The framework adapters live in the Ingero agent repository under
+[`examples/integrations/`](https://github.com/ingero-io/ingero/tree/main/examples/integrations):
+
+- `pytorch-lightning/ingero_lightning.py` (Lightning callback)
+- `ray/ingero_ray.py` (Ray task hook)
+- `hf-trainer/ingero_hf.py` (HF Trainer callback)
+- `deepspeed/ingero_deepspeed.py` (DeepSpeed wrapper)
+- `accelerate/ingero_accelerate.py` (Accelerate hook)
+- `vllm/ingero_vllm.py` (per-request inference emitter, v0.19+)
+
+Each of those imports from this package and adds the
+framework-specific wiring.
+
+## Wire protocol summary
+
+Each line is one NDJSON annotation object:
+
+```json
+{"labels": {"step": "42"}, "pid": 1234, "ts": 1700000000000000000}
+```
+
+`labels` is required. `pid` scopes to a process incarnation; without
+it the annotation is trace-wide. `ts` is optional unix nanoseconds
+(the agent stamps receive time when absent). Spans add `span_start`
+and `span_end` (both unix nanoseconds).
+
+The full contract, including label-key/value charsets, length
+limits, and the v0.19 per-request keys, is documented in
+`pkg/contract/annotate.go` and `docs/commands.md` in the agent
+repository.
+
+## Honesty notes for per-request inference correlation
+
+v0.19+ adds `request_id`, `model`, `prompt_len`, `output_len`,
+`preempted`, `arrival`, `first_token`, `finished` to the contract.
+When used with `ingero explain --by-request` / `ingero query
+--by-request`, the output is a TIME-OVERLAP slice, not exclusive
+kernel ownership. Continuous batching shares kernel launches across
+many in-flight requests; the agent's renderer prints this caveat
+verbatim every time. The library does not interpret `request_id`
+semantics beyond label validation; the agent does.
+
+## License
+
+Apache-2.0.

ingero_annotate-0.1.0/README.md

@@ -0,0 +1,85 @@
+# ingero-annotate
+
+Writer for the Ingero agent annotation socket. Speaks the agent's
+v0.17 NDJSON annotation protocol and nothing else, so any training
+framework or inference frontend can inject `step`, `epoch`,
+`task_id`, `request_id`, `model`, or any custom label into a live
+recorded trace without a framework-specific dependency.
+
+## Install
+
+```
+pip install ingero-annotate
+```
+
+## Use
+
+```python
+from ingero_annotate import AnnotationWriter
+
+writer = AnnotationWriter()               # default socket: /run/ingero/annotate.sock
+writer.write({"step": "42"})              # instant annotation
+writer.write_span({"epoch": "3"}, ...)    # span annotation
+```
+
+The full public surface is documented in the module's docstring;
+see `python/ingero-annotate/ingero_annotate.py`.
+
+The agent must be running with the annotation socket bound
+(`ingero trace --record --annotate`). When the socket is absent or
+the agent has not bound it, the writer drops silently and the
+caller's code path is untouched.
+
+## What this is and is not
+
+This is the protocol layer. It validates label keys and values
+against the agent's contract (`pkg/contract/annotate.go` in the
+agent repo), opens the Unix-domain socket, sends NDJSON, handles
+reconnect, and gives you back a small Python API. It has no
+framework dependency.
+
+The framework adapters live in the Ingero agent repository under
+[`examples/integrations/`](https://github.com/ingero-io/ingero/tree/main/examples/integrations):
+
+- `pytorch-lightning/ingero_lightning.py` (Lightning callback)
+- `ray/ingero_ray.py` (Ray task hook)
+- `hf-trainer/ingero_hf.py` (HF Trainer callback)
+- `deepspeed/ingero_deepspeed.py` (DeepSpeed wrapper)
+- `accelerate/ingero_accelerate.py` (Accelerate hook)
+- `vllm/ingero_vllm.py` (per-request inference emitter, v0.19+)
+
+Each of those imports from this package and adds the
+framework-specific wiring.
+
+## Wire protocol summary
+
+Each line is one NDJSON annotation object:
+
+```json
+{"labels": {"step": "42"}, "pid": 1234, "ts": 1700000000000000000}
+```
+
+`labels` is required. `pid` scopes to a process incarnation; without
+it the annotation is trace-wide. `ts` is optional unix nanoseconds
+(the agent stamps receive time when absent). Spans add `span_start`
+and `span_end` (both unix nanoseconds).
+
+The full contract, including label-key/value charsets, length
+limits, and the v0.19 per-request keys, is documented in
+`pkg/contract/annotate.go` and `docs/commands.md` in the agent
+repository.
+
+## Honesty notes for per-request inference correlation
+
+v0.19+ adds `request_id`, `model`, `prompt_len`, `output_len`,
+`preempted`, `arrival`, `first_token`, `finished` to the contract.
+When used with `ingero explain --by-request` / `ingero query
+--by-request`, the output is a TIME-OVERLAP slice, not exclusive
+kernel ownership. Continuous batching shares kernel launches across
+many in-flight requests; the agent's renderer prints this caveat
+verbatim every time. The library does not interpret `request_id`
+semantics beyond label validation; the agent does.
+
+## License
+
+Apache-2.0.

ingero_annotate-0.1.0/ingero_annotate.py

@@ -0,0 +1,296 @@
+"""Framework-agnostic writer for the Ingero agent annotation socket.
+
+This module carries no PyTorch / Lightning dependency. It speaks the
+agent's NDJSON annotation protocol (agent v0.17.0) and nothing else, so
+the protocol and socket behaviour can be unit-tested without importing a
+training framework.
+
+Wire protocol (see pkg/contract/annotate.go in the agent repo):
+
+  - The agent, when run as `ingero trace --record --annotate`, binds a
+    Unix-domain socket at /run/ingero/annotate.sock (or, when /run is not
+    writable, ~/.ingero/annotate/annotate.sock).
+  - A writer connects and sends newline-delimited JSON. Each line is one
+    annotation object:
+
+        {"labels": {"step": "42"}, "pid": 1234, "ts": 1700000000000000000}
+
+  - `labels` is required and non-empty. `pid` scopes the annotation to a
+    process incarnation. `ts` is optional unix nanoseconds; the agent
+    stamps receive time when it is absent.
+
+Validation limits below mirror the agent's contract exactly. A line that
+violates them is rejected by the agent without dropping the listener;
+this writer rejects it locally first so a caller sees a clear error.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import socket
+import threading
+import time
+
+logger = logging.getLogger("ingero.annotate")
+
+# --- Protocol constants, pinned to pkg/contract/annotate.go ----------------
+
+ANNOTATION_PROTOCOL_VERSION = 1
+ANNOTATION_SOCKET_NAME = "annotate.sock"
+ANNOTATION_SOCKET_DIR = "/run/ingero"
+
+MAX_LABEL_KEY_LEN = 64
+MAX_LABEL_VALUE_LEN = 256
+MAX_LABELS_PER_ANNOTATION = 32
+MAX_LINE_BYTES = 16 * 1024
+
+# Well-known label keys the distribution integrations standardize on.
+KEY_STEP = "step"
+KEY_EPOCH = "epoch"
+KEY_TASK_ID = "task_id"
+KEY_PHASE = "phase"
+KEY_RUN_ID = "run_id"
+
+# Allowed label-key bytes: ASCII letters, digits, underscore, dot, hyphen.
+_KEY_CHARS = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-"
+)
+
+
+class AnnotationError(ValueError):
+    """Raised when an annotation violates the agent's contract limits."""
+
+
+def is_valid_label_key(key: str) -> bool:
+    """Report whether key satisfies the agent's label-key contract.
+
+    Non-empty, at most MAX_LABEL_KEY_LEN bytes, every byte in the
+    [A-Za-z0-9_.-] charset. Mirrors contract.IsValidAnnotationLabelKey.
+    """
+    if not key or len(key.encode("utf-8")) > MAX_LABEL_KEY_LEN:
+        return False
+    return all(c in _KEY_CHARS for c in key)
+
+
+def validate_labels(labels: dict) -> None:
+    """Validate a label map against the agent contract.
+
+    Raises AnnotationError on the first violation. Mirrors the checks in
+    pkg/annotate/annotation.go Validate().
+    """
+    if not labels:
+        raise AnnotationError("annotation has no labels")
+    if len(labels) > MAX_LABELS_PER_ANNOTATION:
+        raise AnnotationError(
+            f"annotation has {len(labels)} labels, max {MAX_LABELS_PER_ANNOTATION}"
+        )
+    for key, value in labels.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise AnnotationError("label keys and values must be strings")
+        if not is_valid_label_key(key):
+            raise AnnotationError(
+                f"invalid label key {key!r} (charset A-Za-z0-9_.-, "
+                f"max {MAX_LABEL_KEY_LEN} bytes)"
+            )
+        vbytes = value.encode("utf-8")
+        if len(vbytes) > MAX_LABEL_VALUE_LEN:
+            raise AnnotationError(
+                f"label {key!r} value is {len(vbytes)} bytes, "
+                f"max {MAX_LABEL_VALUE_LEN}"
+            )
+        for ch in value:
+            o = ord(ch)
+            if o < 0x20 or o == 0x7F:
+                raise AnnotationError(
+                    f"label {key!r} value contains a control character "
+                    f"(0x{o:02x})"
+                )
+
+
+def encode_annotation(labels: dict, pid: int | None = None,
+                       ts_ns: int | None = None) -> bytes:
+    """Encode one annotation as a single NDJSON line (terminated by \\n).
+
+    Validates against the contract first, then checks the encoded line
+    against MAX_LINE_BYTES. Raises AnnotationError on any violation.
+    """
+    validate_labels(labels)
+    obj: dict = {"labels": labels}
+    if pid is not None:
+        obj["pid"] = int(pid)
+    if ts_ns is not None:
+        obj["ts"] = int(ts_ns)
+    line = json.dumps(obj, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    if len(line) + 1 > MAX_LINE_BYTES:
+        raise AnnotationError(
+            f"encoded annotation is {len(line) + 1} bytes, max {MAX_LINE_BYTES}"
+        )
+    return line + b"\n"
+
+
+def default_socket_path() -> str:
+    """Return the annotation socket path the agent binds.
+
+    Prefers the canonical /run/ingero/annotate.sock when a socket is
+    actually bound there (the privileged-trace case). Otherwise falls
+    back to ~/.ingero/annotate/annotate.sock, mirroring the agent's
+    resolveSocketDir / SocketPath logic for the unprivileged-trace case.
+    """
+    run_path = os.path.join(ANNOTATION_SOCKET_DIR, ANNOTATION_SOCKET_NAME)
+    try:
+        # This exists/is-socket check is advisory only - it just picks the
+        # more likely path. The real guard is _connect's OSError handling,
+        # which copes with the socket vanishing between here and connect.
+        # Do not "harden" this into a stricter pre-flight check: that would
+        # introduce a TOCTOU race for no gain.
+        if os.path.exists(run_path) and _is_socket(run_path):
+            return run_path
+    except OSError:
+        pass
+    home = os.path.expanduser("~")
+    return os.path.join(home, ".ingero", "annotate", ANNOTATION_SOCKET_NAME)
+
+
+def _is_socket(path: str) -> bool:
+    import stat
+    try:
+        return stat.S_ISSOCK(os.lstat(path).st_mode)
+    except OSError:
+        return False
+
+
+class AnnotationWriter:
+    """A reusable, thread-safe connection to the agent annotation socket.
+
+    The writer opens the Unix-domain socket once and reuses it for every
+    annotation. It is graceful by design: if the socket does not exist
+    (the agent is not running with `--annotate`) the writer starts as a
+    silent no-op after one log line. It never raises into the caller's
+    hot path - a contract violation is the only thing surfaced, and only
+    from the explicit `write` call.
+
+    On a write failure (the agent restarted mid-run, the peer closed) the
+    writer makes exactly one bounded reconnect attempt: it closes the
+    dead socket, reconnects once, and retries the write. If the reconnect
+    or the retried write also fails it goes inert for the rest of the
+    run. One attempt only - no retry loop, no backoff, no retry storm in
+    a training hot path.
+
+    Typical use from a framework hook:
+
+        w = AnnotationWriter()        # connects, or becomes a no-op
+        w.write({"step": "10"}, pid=os.getpid())
+        ...
+        w.close()
+    """
+
+    def __init__(self, socket_path: str | None = None,
+                 connect_timeout: float = 2.0):
+        self._path = socket_path or default_socket_path()
+        self._timeout = connect_timeout
+        self._lock = threading.Lock()
+        self._sock: socket.socket | None = None
+        self._active = False
+        self._logged_unavailable = False
+        self._connect()
+
+    @property
+    def active(self) -> bool:
+        """True when the socket is connected and annotations will be sent."""
+        return self._active
+
+    @property
+    def socket_path(self) -> str:
+        return self._path
+
+    def _connect(self) -> None:
+        try:
+            s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            s.settimeout(self._timeout)
+            s.connect(self._path)
+            s.settimeout(None)
+            self._sock = s
+            self._active = True
+        except OSError as exc:
+            self._sock = None
+            self._active = False
+            if not self._logged_unavailable:
+                logger.info(
+                    "ingero annotation socket unavailable at %s (%s); "
+                    "annotations disabled. Run the agent with "
+                    "'trace --record --annotate' to enable.",
+                    self._path, exc,
+                )
+                self._logged_unavailable = True
+
+    def write(self, labels: dict, pid: int | None = None,
+              ts_ns: int | None = None) -> bool:
+        """Send one annotation. Returns True if it was written to the socket.
+
+        A contract violation raises AnnotationError - that is a caller
+        bug, surfaced loudly. A transport failure (socket gone, peer
+        closed) is swallowed: the writer makes one bounded reconnect
+        attempt and retries the write; if that also fails it flips to
+        no-op and returns False so a training loop is never interrupted
+        by agent unavailability.
+        """
+        line = encode_annotation(labels, pid=pid, ts_ns=ts_ns)
+        with self._lock:
+            if not self._active or self._sock is None:
+                return False
+            try:
+                self._sock.sendall(line)
+                return True
+            except OSError as exc:
+                logger.info(
+                    "ingero annotation socket write failed (%s); "
+                    "attempting one reconnect.", exc,
+                )
+                self._close_locked()
+                # One bounded reconnect attempt - the agent may have
+                # restarted mid-run. No loop, no backoff.
+                self._connect()
+                if not self._active or self._sock is None:
+                    logger.info(
+                        "ingero annotation reconnect failed; annotations "
+                        "disabled for the rest of this run.",
+                    )
+                    return False
+                try:
+                    self._sock.sendall(line)
+                    return True
+                except OSError as exc2:
+                    logger.info(
+                        "ingero annotation write failed after reconnect "
+                        "(%s); annotations disabled for the rest of this "
+                        "run.", exc2,
+                    )
+                    self._close_locked()
+                    return False
+
+    def _close_locked(self) -> None:
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+        self._sock = None
+        self._active = False
+
+    def close(self) -> None:
+        """Close the socket. Safe to call more than once."""
+        with self._lock:
+            self._close_locked()
+
+    def __enter__(self) -> "AnnotationWriter":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+def now_ns() -> int:
+    """Current time in unix nanoseconds, for an explicit annotation ts."""
+    return time.time_ns()

ingero_annotate-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ingero-annotate"
+version = "0.1.0"
+description = "Writer for the Ingero agent annotation socket. Speaks the agent v0.17+ NDJSON annotation protocol; framework-agnostic."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+keywords = ["ebpf", "gpu", "observability", "annotation", "ingero"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+]
+
+[project.urls]
+Homepage = "https://github.com/ingero-io/ingero"
+Repository = "https://github.com/ingero-io/ingero"
+Documentation = "https://github.com/ingero-io/ingero/blob/main/docs/commands.md"
+Issues = "https://github.com/ingero-io/ingero/issues"
+
+[tool.hatch.build.targets.wheel]
+# Single-module package: the importable name is `ingero_annotate`,
+# the file sits at the package root. Hatchling includes top-level
+# `.py` files automatically when `packages` is empty, but listing the
+# module makes the layout intent explicit.
+packages = []
+include = ["ingero_annotate.py"]
+
+[tool.hatch.build.targets.sdist]
+include = ["ingero_annotate.py", "README.md", "tests/"]

ingero_annotate-0.1.0/tests/test_e2e_install_and_use.py

@@ -0,0 +1,447 @@
+"""End-to-end install-and-use tests for the ingero-annotate package.
+
+These tests simulate exactly what a user does on a fresh machine:
+
+    pip install ingero-annotate
+    python -c "from ingero_annotate import AnnotationWriter; ..."
+
+with the agent's annotation socket on the other end. The tests run
+`pip install` (not `python -m build` + extract; pip is the actual
+distribution channel) against the source tree, then spawn a fresh
+Python subprocess that:
+
+  1. Imports `ingero_annotate` FROM THE INSTALLED LOCATION (the
+     source tree is intentionally NOT on sys.path; if the wrong copy
+     is imported, the assertion on `__file__` catches it).
+  2. Stands up a Unix-domain socket server in a background thread.
+  3. Uses the public API (`AnnotationWriter`, `encode_annotation`,
+     `validate_labels`) to write annotations.
+  4. Verifies the wire payload reached the server with the right
+     NDJSON shape.
+
+The test catches every category of release-day "doesn't work on the
+first try" failure:
+
+  - `pyproject.toml` is malformed (`pip install` would refuse).
+  - Hatchling wheel target misses the module file (`pip install`
+    succeeds but import fails).
+  - Public symbols are renamed or removed (subprocess import fails).
+  - The wire payload regresses (subprocess assertion fails).
+
+A maintainer who ships a v0.1.1 (or any future release) and breaks
+ANY of those will see this test fail in CI long before PyPI.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+
+# python/ingero-annotate/tests/this_file -> 3x parent = repo root.
+REPO_ROOT = Path(__file__).resolve().parents[3]
+PKG_DIR = REPO_ROOT / "python" / "ingero-annotate"
+
+
+def _have_pip() -> bool:
+    return shutil.which("pip") is not None or shutil.which("pip3") is not None
+
+
+# The driver script is run in a SEPARATE Python subprocess against the
+# installed-target directory. It must not import anything from the
+# source tree, so it self-contains everything (no helpers from this
+# test file's scope are accessible).
+DRIVER = textwrap.dedent(
+    """
+    import json
+    import os
+    import socket
+    import sys
+    import threading
+    import time
+
+    install_dir, sock_path = sys.argv[1], sys.argv[2]
+
+    # Force imports to come from the installed-target dir ONLY.
+    # We deliberately do NOT add the source tree to sys.path; the
+    # test asserts on __file__ that the loaded module is the
+    # installed one.
+    sys.path.insert(0, install_dir)
+
+    from ingero_annotate import (
+        AnnotationWriter,
+        encode_annotation,
+        validate_labels,
+    )
+    import ingero_annotate as _mod
+
+    # Print the resolved module path so the test can assert it landed
+    # in the install dir, not in the source tree.
+    print("MODULE_FILE:", _mod.__file__, flush=True)
+    print("DRIVER_PID:", os.getpid(), flush=True)
+
+    # Exercise the no-socket helpers first - encode_annotation and
+    # validate_labels are part of the public API and would surface
+    # an import-time crash from a partial-copy wheel.
+    validate_labels({"step": "42", "request_id": "req-abc.123"})
+    encoded = encode_annotation(
+        labels={"step": "42", "request_id": "req-abc.123"},
+        pid=os.getpid(),
+        ts_ns=1_700_000_000_000_000_000,
+    )
+    assert isinstance(encoded, (bytes, bytearray, str)), (
+        f"encode_annotation returned wrong type: {type(encoded)}"
+    )
+    print("ENCODE_LEN:", len(encoded), flush=True)
+
+    # Stand up the UDS server before the writer connects.
+    received = []
+    ready = threading.Event()
+
+    def serve():
+        srv = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        srv.bind(sock_path)
+        srv.listen(1)
+        srv.settimeout(5.0)
+        ready.set()
+        try:
+            conn, _ = srv.accept()
+        finally:
+            srv.close()
+        with conn:
+            conn.settimeout(5.0)
+            buf = b""
+            while len(received) < 1:
+                try:
+                    chunk = conn.recv(4096)
+                except socket.timeout:
+                    break
+                if not chunk:
+                    break
+                buf += chunk
+                while b"\\n" in buf:
+                    line, buf = buf.split(b"\\n", 1)
+                    received.append(line)
+
+    t = threading.Thread(target=serve, daemon=True)
+    t.start()
+    if not ready.wait(2.0):
+        sys.exit("server failed to bind in 2s")
+
+    # Public-API smoke: open a writer, send one annotation, observe
+    # the wire payload.
+    writer = AnnotationWriter(socket_path=sock_path)
+    try:
+        writer.write({"step": "42", "request_id": "req-abc.123"}, pid=os.getpid())
+    finally:
+        writer.close()
+
+    # Wait briefly for the server thread to drain.
+    t.join(timeout=3.0)
+    if not received:
+        sys.exit("no annotation line received within 3s")
+
+    # Echo the line back so the test can assert on the JSON shape.
+    print("LINE:", received[0].decode("utf-8"), flush=True)
+    """
+)
+
+
+@pytest.mark.skipif(not _have_pip(), reason="pip is required for this E2E test")
+def test_pip_install_then_import_and_write(tmp_path: Path) -> None:
+    """The full user flow: pip install -> import -> write -> verify."""
+    install_dir = tmp_path / "site"
+    install_dir.mkdir()
+
+    # Step 1: real `pip install --target` against the package
+    # directory. This goes through the build backend (hatchling),
+    # builds a wheel, and installs it as if from PyPI. --no-deps
+    # keeps the test hermetic.
+    pip_cmd = [
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--target",
+        str(install_dir),
+        "--no-deps",
+        "--quiet",
+        "--disable-pip-version-check",
+        str(PKG_DIR),
+    ]
+    result = subprocess.run(
+        pip_cmd,
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    if result.returncode != 0:
+        pytest.fail(
+            "`pip install` of the package failed. This is exactly the "
+            "release-day blocker the test exists to catch.\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}"
+        )
+
+    # Step 2: the wheel must have placed ingero_annotate.py in the
+    # install target. Hatchling's wheel target ships the top-level
+    # module; if pyproject.toml's `include` ever drifts, this fires.
+    installed_module = install_dir / "ingero_annotate.py"
+    if not installed_module.is_file():
+        contents = sorted(p.name for p in install_dir.iterdir())
+        pytest.fail(
+            "pip install succeeded but ingero_annotate.py is missing "
+            f"from {install_dir}. Contents: {contents}"
+        )
+
+    # Step 3: the dist-info dir must also be present (proves it
+    # actually went through the wheel pipeline, not a copy).
+    dist_info = list(install_dir.glob("ingero_annotate-*.dist-info"))
+    assert dist_info, (
+        f"no ingero_annotate-*.dist-info in {install_dir}; "
+        "the install did not go through the wheel pipeline"
+    )
+
+    # Step 4: run the driver subprocess. It uses the installed
+    # module exclusively. The subprocess inherits NO PYTHONPATH from
+    # the test process (env=clean-ish) so the source tree cannot
+    # accidentally shadow the installed copy.
+    sock_path = str(tmp_path / "annotate.sock")
+    driver_file = tmp_path / "driver.py"
+    driver_file.write_text(DRIVER)
+
+    # Strip any inherited PYTHONPATH that could point at the source
+    # tree; pass the install dir explicitly via argv instead. PATH
+    # and other env stay intact so the subprocess can find Python.
+    env = {k: v for k, v in os.environ.items() if k != "PYTHONPATH"}
+
+    proc = subprocess.run(
+        [sys.executable, str(driver_file), str(install_dir), sock_path],
+        capture_output=True,
+        text=True,
+        timeout=30,
+        env=env,
+    )
+    if proc.returncode != 0:
+        pytest.fail(
+            "driver subprocess failed (user-flow simulation broke).\n"
+            f"argv: install_dir={install_dir} sock={sock_path}\n"
+            f"stdout:\n{proc.stdout}\n"
+            f"stderr:\n{proc.stderr}"
+        )
+
+    # Step 5: verify what the subprocess reported.
+    lines = proc.stdout.splitlines()
+
+    # 5a: the loaded module file MUST be the installed one. If the
+    # subprocess imported from the source tree, the install was a
+    # no-op and the test would silently lie about coverage.
+    module_lines = [l for l in lines if l.startswith("MODULE_FILE:")]
+    assert module_lines, f"driver did not print MODULE_FILE: {proc.stdout!r}"
+    loaded_path = module_lines[0].split(":", 1)[1].strip()
+    assert str(install_dir) in loaded_path, (
+        f"driver imported the WRONG ingero_annotate module: "
+        f"loaded {loaded_path!r}, expected one under {install_dir!r}"
+    )
+
+    # 5b: encode_annotation returned a non-empty payload (the
+    # public helper is intact).
+    encode_lines = [l for l in lines if l.startswith("ENCODE_LEN:")]
+    assert encode_lines, "driver did not print ENCODE_LEN"
+    assert int(encode_lines[0].split(":", 1)[1].strip()) > 0
+
+    # 5c: a real NDJSON line crossed the wire. Parse and verify
+    # the v0.17 wire-shape fields.
+    line_lines = [l for l in lines if l.startswith("LINE:")]
+    assert line_lines, f"driver did not print LINE: {proc.stdout!r}"
+    wire = line_lines[0].split(":", 1)[1].strip()
+    payload = json.loads(wire)
+    assert "labels" in payload, f"missing labels: {payload}"
+    assert payload["labels"]["step"] == "42"
+    assert payload["labels"]["request_id"] == "req-abc.123"
+    # pid on the wire must match the driver subprocess (NOT this
+    # test process), since the writer ran inside the subprocess.
+    driver_pid_lines = [l for l in lines if l.startswith("DRIVER_PID:")]
+    assert driver_pid_lines, "driver did not print DRIVER_PID"
+    driver_pid = int(driver_pid_lines[0].split(":", 1)[1].strip())
+    assert payload.get("pid") == driver_pid, (
+        f"wire pid {payload.get('pid')} != driver pid {driver_pid}"
+    )
+
+
+@pytest.mark.skipif(not _have_pip(), reason="pip is required for this E2E test")
+def test_pip_install_from_sdist(tmp_path: Path) -> None:
+    """sdist install path (pip falls back to sdist when no wheel
+    matches the platform).
+
+    Distributors and corporate gates sometimes prefer the sdist.
+    If the source distribution is broken (missing files in
+    `tool.hatch.build.targets.sdist.include`, etc.), the wheel
+    test above still passes but a user on the sdist path is
+    stuck. This test pins both paths.
+    """
+    pytest.importorskip("build", reason="`build` not installed; skip sdist E2E")
+    import build  # noqa: F401
+
+    dist_dir = tmp_path / "dist"
+    dist_dir.mkdir()
+
+    # Build the sdist. `--no-isolation` reuses the current Python
+    # environment so the test does not require python3-venv on the
+    # host (CI images often skip it). Hatchling is already on the
+    # path of any environment that has `build` installed.
+    try:
+        import hatchling  # noqa: F401
+    except ImportError:
+        pytest.skip("hatchling not importable; cannot run --no-isolation build")
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "build",
+            "--sdist",
+            "--no-isolation",
+            "--outdir",
+            str(dist_dir),
+            str(PKG_DIR),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    if result.returncode != 0:
+        pytest.fail(
+            f"`python -m build --sdist --no-isolation` failed:\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}"
+        )
+
+    sdists = list(dist_dir.glob("ingero_annotate-*.tar.gz")) + list(
+        dist_dir.glob("ingero-annotate-*.tar.gz")
+    )
+    assert sdists, f"no sdist produced in {dist_dir}; files: {list(dist_dir.iterdir())}"
+
+    # Install from the sdist into a clean target.
+    install_dir = tmp_path / "site"
+    install_dir.mkdir()
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "pip",
+            "install",
+            "--target",
+            str(install_dir),
+            "--no-deps",
+            "--quiet",
+            "--disable-pip-version-check",
+            str(sdists[0]),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    if result.returncode != 0:
+        pytest.fail(
+            f"`pip install <sdist>` failed:\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}"
+        )
+
+    assert (install_dir / "ingero_annotate.py").is_file(), (
+        "sdist install did not deposit ingero_annotate.py"
+    )
+
+    # Quick import smoke from the installed location.
+    env = {k: v for k, v in os.environ.items() if k != "PYTHONPATH"}
+    smoke = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import sys; sys.path.insert(0, sys.argv[1]); "
+            "from ingero_annotate import AnnotationWriter, encode_annotation; "
+            "import ingero_annotate; print(ingero_annotate.__file__)",
+            str(install_dir),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=15,
+        env=env,
+    )
+    if smoke.returncode != 0:
+        pytest.fail(
+            f"sdist-installed import smoke failed:\n"
+            f"stdout:\n{smoke.stdout}\n"
+            f"stderr:\n{smoke.stderr}"
+        )
+    assert str(install_dir) in smoke.stdout, (
+        f"sdist-installed module loaded from wrong path: {smoke.stdout!r}"
+    )
+
+
+@pytest.mark.skipif(not _have_pip(), reason="pip is required for this E2E test")
+def test_pip_install_metadata_is_well_formed(tmp_path: Path) -> None:
+    """The PyPI metadata that pip+twine read MUST parse cleanly.
+
+    A malformed `pyproject.toml` (wrong classifier syntax, missing
+    required field, license declared without license-files) often
+    `pip install`s fine on the local machine but fails on
+    twine upload. This test runs pip with `--dry-run` if available
+    OR a minimal metadata-only build to catch those issues before
+    they hit PyPI.
+    """
+    install_dir = tmp_path / "site"
+    install_dir.mkdir()
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "pip",
+            "install",
+            "--target",
+            str(install_dir),
+            "--no-deps",
+            "--quiet",
+            "--disable-pip-version-check",
+            str(PKG_DIR),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    if result.returncode != 0:
+        pytest.fail(
+            "metadata install failed - pyproject.toml is likely malformed:\n"
+            f"stdout:\n{result.stdout}\n"
+            f"stderr:\n{result.stderr}"
+        )
+
+    # The dist-info dir is what pip / twine / pypi.org actually use.
+    # Parse the METADATA file and verify the v0.1.0 fields are sane.
+    dist_info = list(install_dir.glob("ingero_annotate-*.dist-info"))
+    assert dist_info, f"no dist-info in {install_dir}"
+    metadata = (dist_info[0] / "METADATA").read_text(encoding="utf-8")
+
+    # The header lines pip parses are case-sensitive; assert the
+    # essentials are present and shaped correctly.
+    required_lines = [
+        "Metadata-Version:",
+        "Name: ingero-annotate",
+        "Version: ",
+        "Summary: ",
+        "Requires-Python:",
+    ]
+    for needle in required_lines:
+        assert needle in metadata, (
+            f"METADATA missing required field {needle!r}; "
+            "PyPI upload will reject or warn"
+        )

ingero_annotate-0.1.0/tests/test_no_vendored_copies.py

@@ -0,0 +1,86 @@
+"""Regression test: the canonical ingero_annotate.py lives ONLY in
+python/ingero-annotate/. The 5 vendored copies (md5 2aed7ca2)
+previously sat inside each adapter directory and drifted invisibly;
+v0.19 Phase E.2 consolidated them, and this test pins the
+consolidation so a future contributor cannot silently re-vendor.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+
+# Walk up from this test file to the repository root. The package
+# layout is `<repo>/python/ingero-annotate/tests/this_file`, so two
+# `parent` steps land at the package root and a third lands at
+# `<repo>/python/`. We want `<repo>/`.
+REPO_ROOT = Path(__file__).resolve().parents[3]
+CANONICAL = REPO_ROOT / "python" / "ingero-annotate" / "ingero_annotate.py"
+
+
+def test_canonical_module_exists() -> None:
+    assert CANONICAL.is_file(), (
+        f"canonical ingero_annotate.py missing at {CANONICAL}"
+    )
+
+
+def test_no_vendored_copies_in_adapter_dirs() -> None:
+    """No adapter directory may carry its own ingero_annotate.py.
+
+    Pre-v0.19, five adapters (pytorch-lightning, ray, hf-trainer,
+    deepspeed, accelerate) each vendored an identical 296-line copy.
+    Maintaining 5 copies of one library is the kind of footgun that
+    quietly drifts. v0.19 Phase E.2 deleted them; this test pins
+    the deletion.
+    """
+    integrations = REPO_ROOT / "examples" / "integrations"
+    if not integrations.is_dir():
+        # Some packaging layouts may not ship the integrations dir;
+        # the canonical module is what matters. Skip gracefully.
+        return
+    offending: list[str] = []
+    for d in integrations.iterdir():
+        if not d.is_dir():
+            continue
+        local = d / "ingero_annotate.py"
+        if local.is_file():
+            offending.append(str(local.relative_to(REPO_ROOT)))
+    assert not offending, (
+        "vendored ingero_annotate.py copies still present in:\n  "
+        + "\n  ".join(offending)
+        + "\nDelete them and import from the ingero-annotate package."
+    )
+
+
+def test_canonical_module_is_well_formed() -> None:
+    """The canonical module is non-empty and importable as text.
+
+    A future packaging mistake (empty file, build cleared the module)
+    would otherwise let this test suite pass with no actual code.
+    """
+    text = CANONICAL.read_text(encoding="utf-8")
+    assert len(text) > 1000, f"canonical module is suspiciously small: {len(text)} bytes"
+    # The module must expose AnnotationWriter (the public class) and
+    # at least one of the protocol helpers. Pinning both catches a
+    # broken build (empty file, partial copy) without being too
+    # strict about every internal symbol.
+    for sym in ("class AnnotationWriter", "def encode_annotation", "def validate_labels"):
+        assert sym in text, f"canonical module is missing: {sym}"
+
+
+def test_canonical_module_md5_stable() -> None:
+    """Pin the md5 of the canonical module. A future edit MUST update
+    this value deliberately; an unintended drift fails the test.
+
+    The original 5 vendored copies all hashed to 2aed7ca2fc98cfbdfcd1611b7d86a03e.
+    The canonical module is byte-identical at consolidation time.
+    """
+    h = hashlib.md5(CANONICAL.read_bytes()).hexdigest()
+    # Recorded at consolidation time (v0.19 Phase E.2, 2026-05-24).
+    expected = "2aed7ca2fc98cfbdfcd1611b7d86a03e"
+    assert h == expected, (
+        f"canonical module md5 drifted: got {h}, expected {expected}. "
+        "Update this pin INTENTIONALLY when you change the module."
+    )