nodii-grpc-interfaces 0.1.0__tar.gz

nodii_grpc_interfaces-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+node_modules/
+dist/
+build/
+coverage/
+.DS_Store
+*.log
+.env
+.env.local
+.env.*.local
+.turbo/
+.bun/
+
+# AI review loop artifacts (scripts/review/ai-review.ts)
+.claude-pre-review.md
+.claude-pre-review.json
+.claude/pending-patches/
+
+# Agent session state (not committed; per-session)
+.claude/endpoints-snapshot.json
+.agent-todo.md
+
+# Python (uv)
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Go
+*.test
+*.out
+go.work.sum
+
+# Generated proto artifacts (regenerate via `bun proto:gen`)
+ts/_generated/
+python/_generated/
+go/_generated/
+
+# Test-stack volumes (docker-compose persistent data)
+infra/test-stack/data/
+# synthetic consumer go binaries
+synthetic-consumers/telemetry/go/nodii-synthetic-telemetry
+synthetic-consumers/pii/go/nodii-synthetic-pii
+synthetic-consumers/auth-sdk/go/nodii-synthetic-auth-sdk

nodii_grpc_interfaces-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: nodii-grpc-interfaces
+Version: 0.1.0
+Summary: Canonical gRPC interface contracts for the Nodii stack. Ships the vendored .proto bytes + runtime-compiled grpcio stubs for nodii.dsar.v1.DataLifecycleService and nodii.tenant.v1.TenantSnapshotService so consumer services can add_*_to_server(...) without running buf codegen.
+Project-URL: Homepage, https://github.com/cognion-nucleus/nodii-libs
+Project-URL: Repository, https://github.com/cognion-nucleus/nodii-libs
+Author-email: Nodii <ops@nodii.co>
+License: MIT
+Keywords: dsar,grpc,interfaces,nodii,proto,tenant-snapshot
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: grpcio-tools>=1.60
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.25

nodii_grpc_interfaces-0.1.0/proto/README.md

@@ -0,0 +1,19 @@
+# proto/ — vendored canonical gRPC contracts
+
+These `.proto` files are **vendored byte-for-byte** from the nodii-libs
+canonical proto mirror at `proto/nodii/**` (sourced from the planning hub).
+They ship inside the `@nodii/grpc-interfaces` npm artifact (see `files` in
+`package.json`) so the library is self-contained and consumers can load the
+ServiceDefinitions at runtime via `@grpc/proto-loader` — no buf-remote
+pipeline required.
+
+| File | Package | Service |
+|---|---|---|
+| `nodii/dsar/v1/dsar.proto` | `nodii.dsar.v1` | `DataLifecycleService` (9 RPCs; D108 — 9th RPC is `ListActiveHolds`) |
+| `nodii/tenant/v1/tenant_snapshot.proto` | `nodii.tenant.v1` | `TenantSnapshotService` (5 streaming bootstrap RPCs) |
+
+## Parity contract
+
+The vendored copies MUST stay byte-equal to the repo-root `proto/nodii/**`
+canonical files. The `tests/proto-parity.test.ts` fence asserts this on every
+run. To update, re-copy from the canonical mirror — never hand-edit here.

nodii_grpc_interfaces-0.1.0/proto/nodii/dsar/v1/dsar.proto

@@ -0,0 +1,176 @@
+syntax = "proto3";
+
+// DataLifecycleService — ticketing's DSAR Pattern A gRPC surface over its OWN
+// data subjects (DCO ticket rows + ticket-side PII), called by
+// nodii-tenant-service.DsarOrchestratorService (compliance-dsar-pattern-a /
+// global 11-dsar § 6 / D109). Wired via @nodii/dsar.bindPatternA — the lib's
+// DsarServiceImpl handler map is mounted onto this service definition.
+//
+// D108 / drift 7a24d546: the 9th RPC is ListActiveHolds (NOT the legacy
+// Acknowledge). @nodii/dsar@0.3.2's DsarServiceImpl implements ListActiveHolds;
+// ticketing AUTHORS this contract per D190 (producer authors its own gRPC
+// contract) because the canonical proto vendored in @nodii/role-catalog@0.1.5 is
+// the pre-D108 (Acknowledge) artifact — see drift 33066346 / request 39e64d25
+// (nodii-libs proto fix in flight). RPCs 1-8 + their messages are transcribed
+// verbatim from that proto (which is correct for those); only the 9th is
+// corrected to ListActiveHolds per the live decision.
+//
+// Uniform envelope: every request carries (request_id, tenant_id, subject_kind,
+// subject_id, …); the 8 lifecycle RPCs return LifecycleResponse{status, …};
+// ListActiveHolds returns ListActiveHoldsResponse{holds}.
+
+package nodii.dsar.v1;
+
+import "google/protobuf/timestamp.proto";
+
+service DataLifecycleService {
+  // GDPR subject rights.
+  rpc AccessData(AccessDataRequest) returns (LifecycleResponse);
+  rpc EraseData(EraseDataRequest) returns (LifecycleResponse);
+  rpc RectifyData(RectifyDataRequest) returns (LifecycleResponse);
+  rpc ExportPortableData(ExportPortableDataRequest) returns (LifecycleResponse);
+  rpc RestrictProcessing(RestrictProcessingRequest) returns (LifecycleResponse);
+
+  // Retention hold pair.
+  rpc PlaceRetentionHold(PlaceRetentionHoldRequest) returns (LifecycleResponse);
+  rpc LiftRetentionHold(LiftRetentionHoldRequest) returns (LifecycleResponse);
+
+  // Visibility.
+  rpc GetLifecycleRequestStatus(GetLifecycleRequestStatusRequest)
+      returns (LifecycleResponse);
+  // D108 (drift 7a24d546): ListActiveHolds replaces the legacy Acknowledge.
+  rpc ListActiveHolds(ListActiveHoldsRequest) returns (ListActiveHoldsResponse);
+}
+
+enum SubjectKind {
+  SUBJECT_KIND_UNSPECIFIED = 0;
+  SUBJECT_KIND_USER = 1;
+  SUBJECT_KIND_EMPLOYEE = 2;
+  SUBJECT_KIND_CUSTOMER = 3;
+  SUBJECT_KIND_PLATFORM_ADMIN = 4;
+  SUBJECT_KIND_TENANT = 5;  // synthetic — tenant-level holds + per-tenant erase
+}
+
+enum Status {
+  STATUS_UNSPECIFIED = 0;
+  STATUS_ACCEPTED = 1;
+  STATUS_COMPLETED = 2;
+  STATUS_NO_DATA = 3;
+  STATUS_PARTIAL = 4;
+  STATUS_FAILED = 5;
+  STATUS_HELD = 6;
+}
+
+// ---- Request messages (RPCs 1-8 — verbatim from the canonical proto) -------
+
+message AccessDataRequest {
+  string request_id = 1;          // UUIDv7
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string reason = 5;
+  string requested_by = 6;
+}
+
+message EraseDataRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string reason = 5;
+  string requested_by = 6;
+  string scope = 7;  // "subject" | "tenant"
+}
+
+message RectifyDataRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string reason = 5;
+  string requested_by = 6;
+  map<string, string> patches = 7;
+}
+
+message ExportPortableDataRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string reason = 5;
+  string requested_by = 6;
+  string region = 7;  // for S3 artifact bucket selection
+}
+
+message RestrictProcessingRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string reason = 5;
+  string requested_by = 6;
+  string restriction_kind = 7;  // free-form
+}
+
+message PlaceRetentionHoldRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string statute_citation = 5;
+  google.protobuf.Timestamp expires_at = 6;
+  string requested_by = 7;
+}
+
+message LiftRetentionHoldRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;
+  string subject_id = 4;
+  string justification = 5;
+  string requested_by = 6;
+}
+
+message GetLifecycleRequestStatusRequest {
+  string request_id = 1;
+  string rpc_method = 2;
+  string tenant_id = 3;
+}
+
+// ---- ListActiveHolds (D108 9th RPC — replaces Acknowledge) -----------------
+
+message ListActiveHoldsRequest {
+  string request_id = 1;
+  string tenant_id = 2;
+  SubjectKind subject_kind = 3;     // optional narrowing filter (UNSPECIFIED = any)
+  string subject_id = 4;            // optional narrowing filter ("" = any)
+  string hold_kind = 5;             // optional "erase" | "restrict" ("" = any)
+  string requested_by = 6;
+}
+
+message ActiveHold {
+  string id = 1;
+  string tenant_id = 2;
+  string subject_id = 3;            // "" / unset for tenant-level holds
+  string hold_kind = 4;             // "erase" | "restrict"
+  string statute_citation = 5;
+  string placed_by = 6;
+  google.protobuf.Timestamp placed_at = 7;
+  google.protobuf.Timestamp expires_at = 8;  // unset = no expiry
+}
+
+message ListActiveHoldsResponse {
+  repeated ActiveHold holds = 1;
+}
+
+// ---- Uniform lifecycle response (8 RPCs) -----------------------------------
+
+message LifecycleResponse {
+  string request_id = 1;
+  Status status = 2;
+  string reason = 3;
+  string result_artifact_uri = 4;
+  google.protobuf.Timestamp expires_at = 5;
+  string statute_citation = 6;
+}
+

nodii_grpc_interfaces-0.1.0/proto/nodii/tenant/v1/tenant_snapshot.proto

@@ -0,0 +1,93 @@
+syntax = "proto3";
+
+// TenantSnapshotService — tenant-service's cold-start bootstrap surface for
+// every sibling service maintaining a tenant-aggregate replica, called by
+// `@nodii/replica-consumer`'s snapshotRpc client per [`09-replication-doctrine
+// § 7`](../../../../../../../global/09-replication-doctrine.md).
+//
+// Locked + shipped per drift 2b30f6c5 adjudication (R0: 09-replication § 7.6
+// wins over the feature_doc's 11-typed-message draft). Authored by
+// nodii-tenant-service per D190 (producer-authored gRPC contracts); ingested
+// to canonical mirror via contract-lock-notice 4e683dea.
+//
+// Phase 1 (this lock): 5 of 11 RPCs — for the 5 aggregates that have tables +
+// emitters today (Tenant + UserMembership + CustomerMembership + AuthPolicy +
+// TenantSubscription per 09-replication § 2.2a lines 109-117).
+//
+// Deferred to subsequent locks (R1 — no RPCs over non-existent tables):
+//   - BootstrapAccessTokenSnapshot        ← access-control-personal-access-tokens
+//   - BootstrapOAuthAppSnapshot           ← access-control-oauth-apps
+//   - BootstrapOAuthAppInstallationSnapshot ← access-control-oauth-apps
+//   - BootstrapCustomDomainSnapshot       ← custom-domains
+//   - BootstrapChildSubdomainSnapshot     ← custom-domains
+//
+// Removed from § 2.2a as STALE (per drift 2b30f6c5 audit confirmed by
+// tenant-service in 4e683dea):
+//   - TenantModuleSubscription — no owning table; tenant_subscriptions IS the
+//     TenantSubscription aggregate. Hub follow-up: doctrine PR removing this
+//     row from § 2.2a.
+//
+// HWM (stream_high_water_mark) emission is DEFERRED to the outbox→Redis Streams
+// dispatcher landing per § 9.2 + D209 SET-NX-EX lease. Until the dispatcher
+// ships, the server streams data chunks then closes the gRPC stream without
+// a terminal HWM chunk. Consumers bootstrap via LWW(entity_version) monotonicity;
+// the HWM stitch arrives with the dispatcher.
+
+package nodii.tenant.v1;
+
+service TenantSnapshotService {
+  // S2S scope: tenant:snapshot:read.
+  // Each RPC streams the full set of rows for its aggregate (no filtering —
+  // bootstrap is full-or-none per § 7.6). Pagination is implicit via gRPC
+  // backpressure on the streaming response.
+
+  rpc BootstrapTenantSnapshot(BootstrapSnapshotRequest)
+      returns (stream TenantSnapshotChunk);
+
+  rpc BootstrapUserMembershipSnapshot(BootstrapSnapshotRequest)
+      returns (stream TenantSnapshotChunk);
+
+  rpc BootstrapCustomerMembershipSnapshot(BootstrapSnapshotRequest)
+      returns (stream TenantSnapshotChunk);
+
+  rpc BootstrapAuthPolicySnapshot(BootstrapSnapshotRequest)
+      returns (stream TenantSnapshotChunk);
+
+  rpc BootstrapTenantSubscriptionSnapshot(BootstrapSnapshotRequest)
+      returns (stream TenantSnapshotChunk);
+}
+
+// No filtering — bootstrap is full or none per § 7.6.
+message BootstrapSnapshotRequest {}
+
+// The single canonical chunk message per § 7.6 (NOT 11 typed
+// `<Aggregate>Snapshot`/`<Aggregate>Payload` messages — that draft was
+// rejected per drift 2b30f6c5).
+message TenantSnapshotChunk {
+  // Singular PascalCase aggregate name, byte-for-byte equal to the
+  // 09-replication § 2.2a enum value. Consumer's `@nodii/replica-consumer`
+  // `defineReplica({ aggregateKind: ... })` must match.
+  string aggregate_kind = 1;
+
+  // Aggregate root's primary key.
+  string aggregate_id = 2;
+
+  // Current monotonic version — the ordering primitive (NOT
+  // `google.protobuf.Timestamp`; that was rejected per drift 2b30f6c5).
+  int64 entity_version = 3;
+
+  // Identical byte-equal payload to the equivalent live event's payload
+  // (the `*.created.v1` payload for the aggregate). Status / lifecycle
+  // changes are NOT included — those arrive via the live stream's
+  // `*.status_changed.v1`, `*.closed.v1`, etc. events.
+  // Consumer requirement: apply `lead_id` (and other "absence-means-unknown"
+  // fields) set-if-absent on snapshot apply — do NOT LWW-null a non-null
+  // replicated lead_id from a snapshot.
+  string payload_json = 4;
+
+  // Populated ONLY on the final chunk of the stream (the HWM "I'm caught up
+  // to here on the live stream" marker). Empty string until the
+  // outbox→Redis Streams dispatcher lands per § 9.2 + D209; consumers
+  // bootstrap via LWW(entity_version) monotonicity in the interim.
+  string stream_high_water_mark = 5;
+}

nodii_grpc_interfaces-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "nodii-grpc-interfaces"
+version = "0.1.0"
+description = "Canonical gRPC interface contracts for the Nodii stack. Ships the vendored .proto bytes + runtime-compiled grpcio stubs for nodii.dsar.v1.DataLifecycleService and nodii.tenant.v1.TenantSnapshotService so consumer services can add_*_to_server(...) without running buf codegen."
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Nodii", email = "ops@nodii.co" },
+]
+keywords = ["nodii", "grpc", "proto", "dsar", "tenant-snapshot", "interfaces"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "grpcio>=1.60",
+    "grpcio-tools>=1.60",
+    "protobuf>=4.25",
+]
+
+[project.urls]
+Homepage = "https://github.com/cognion-nucleus/nodii-libs"
+Repository = "https://github.com/cognion-nucleus/nodii-libs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nodii_grpc_interfaces"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "proto/", "README.md", "LICENSE", "pyproject.toml"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.7",
+    "mypy>=1.13",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=6.0",
+    "types-protobuf>=4.25",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "B", "C4", "UP", "N", "ASYNC", "S", "PT", "RET", "SIM",
+]
+ignore = [
+    "S101",   # use of assert detected — fine in tests
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "S105", "S106", "B017", "PT011"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+disallow_untyped_decorators = true
+# grpcio + protobuf-generated stubs lack type info; allow them through.
+[[tool.mypy.overrides]]
+module = ["grpc", "grpc.*", "grpc_tools", "grpc_tools.*", "google.protobuf", "google.protobuf.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]

nodii_grpc_interfaces-0.1.0/src/nodii_grpc_interfaces/__init__.py

@@ -0,0 +1,42 @@
+"""nodii_grpc_interfaces — canonical gRPC interface contracts for the Nodii stack.
+
+Ships the vendored .proto bytes (under proto/) + runtime-compiled grpcio stubs
+for the two canonical services, so a consumer service can register its own
+handler implementation without running buf codegen.
+
+Resolves hub requests:
+  - daa248c0 — dsar.proto (nodii.dsar.v1.DataLifecycleService)
+  - d7cd41dc — tenant_snapshot.proto (nodii.tenant.v1.TenantSnapshotService)
+  - a0919cfa — DataLifecycleService ServiceDefinition codegen for consumers
+
+Public API (parity with @nodii/grpc-interfaces):
+  - load_dsar_stubs / load_tenant_snapshot_stubs — (pb2, pb2_grpc) tuples.
+  - data_lifecycle_servicer_base / tenant_snapshot_servicer_base — grpcio
+    ServicerBase classes for the consumer to subclass.
+  - SERVICE_NAMES — fully-qualified service names.
+"""
+
+from nodii_grpc_interfaces.proto_loader import (
+    data_lifecycle_servicer_base,
+    load_dsar_stubs,
+    load_tenant_snapshot_stubs,
+    tenant_snapshot_servicer_base,
+)
+
+__version__ = "0.1.0"
+LIB_NAME = "grpc-interfaces"
+
+SERVICE_NAMES = {
+    "DataLifecycleService": "nodii.dsar.v1.DataLifecycleService",
+    "TenantSnapshotService": "nodii.tenant.v1.TenantSnapshotService",
+}
+
+__all__ = [
+    "LIB_NAME",
+    "SERVICE_NAMES",
+    "__version__",
+    "data_lifecycle_servicer_base",
+    "load_dsar_stubs",
+    "load_tenant_snapshot_stubs",
+    "tenant_snapshot_servicer_base",
+]

nodii_grpc_interfaces-0.1.0/src/nodii_grpc_interfaces/proto_loader.py

@@ -0,0 +1,163 @@
+"""Dynamic gRPC stub loader for the canonical Nodii interface contracts.
+
+We compile the vendored protos at import time using grpcio_tools.protoc into a
+temporary import path. This keeps the library a single self-contained package
+(no buf-codegen dependency) and matches what the TS lib does with
+@grpc/proto-loader.
+
+Two services are shipped:
+  - nodii.dsar.v1.DataLifecycleService   (request daa248c0 / a0919cfa; D108)
+  - nodii.tenant.v1.TenantSnapshotService (request d7cd41dc)
+
+Usage by a consumer service:
+
+    from nodii_grpc_interfaces.proto_loader import load_dsar_stubs
+
+    pb2, pb2_grpc = load_dsar_stubs()
+    pb2_grpc.add_DataLifecycleServiceServicer_to_server(MyServicer(), server)
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+import tempfile
+import threading
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+_lock = threading.Lock()
+_compiled: dict[str, tuple[ModuleType, ModuleType]] = {}
+
+# (proto path relative to the proto root, pb2 module name, grpc module name).
+_DSAR_PROTO = ("nodii/dsar/v1/dsar.proto",
+               "nodii.dsar.v1.dsar_pb2",
+               "nodii.dsar.v1.dsar_pb2_grpc")
+_TENANT_PROTO = ("nodii/tenant/v1/tenant_snapshot.proto",
+                 "nodii.tenant.v1.tenant_snapshot_pb2",
+                 "nodii.tenant.v1.tenant_snapshot_pb2_grpc")
+
+# Persistent gen dir (survives the call); subsequent imports reuse the cached
+# sys.modules entries. Overridable for wheel-install layouts where proto/ is
+# not co-located with the package source.
+_GEN_DIR_ENV = "NODII_GRPC_INTERFACES_GEN_DIR"
+_PROTO_ROOT_ENV = "NODII_GRPC_INTERFACES_PROTO_ROOT"
+
+
+def _find_proto_root() -> Path:
+    here = Path(__file__).resolve().parent
+    candidates: list[Path] = []
+    env_override = os.environ.get(_PROTO_ROOT_ENV)
+    if env_override:
+        candidates.append(Path(env_override))
+    candidates.extend(
+        [
+            here / "proto",  # bundled with wheel (preferred)
+            here.parent.parent / "proto",  # python/grpc-interfaces/proto (dev)
+            here.parent / "proto",
+        ]
+    )
+    for c in candidates:
+        if (c / "nodii" / "dsar" / "v1" / "dsar.proto").is_file():
+            return c
+    raise FileNotFoundError(
+        f"nodii_grpc_interfaces: cannot locate the vendored protos. Tried: {candidates}. "
+        f"Set {_PROTO_ROOT_ENV} to point at the proto root, or install the wheel "
+        "with bundled protos."
+    )
+
+
+def _compile_all_protos() -> Path:
+    """Compile every vendored proto into a persistent gen dir; return that dir.
+
+    Both protos are compiled in a single protoc invocation so cross-file +
+    well-known-type imports resolve consistently.
+    """
+    try:
+        from grpc_tools import protoc as _protoc  # type: ignore[import-not-found,import-untyped,unused-ignore]  # noqa: WPS433, I001
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError(
+            "nodii_grpc_interfaces requires grpcio-tools to compile its protos. "
+            "Install grpcio-tools."
+        ) from e
+
+    proto_root = _find_proto_root()
+    gen_dir = Path(
+        os.environ.get(
+            _GEN_DIR_ENV,
+            Path(tempfile.gettempdir()) / "nodii_grpc_interfaces_gen",
+        )
+    )
+    gen_dir.mkdir(parents=True, exist_ok=True)
+
+    grpc_tools_mod = importlib.import_module("grpc_tools")
+    grpc_tools_file = grpc_tools_mod.__file__
+    if grpc_tools_file is None:
+        raise RuntimeError("grpc_tools module has no __file__ — broken install?")
+    wkt_include = Path(grpc_tools_file).parent / "_proto"
+
+    args = [
+        "protoc",
+        f"-I{proto_root}",
+        f"-I{wkt_include}",
+        f"--python_out={gen_dir}",
+        f"--grpc_python_out={gen_dir}",
+        str(proto_root / _DSAR_PROTO[0]),
+        str(proto_root / _TENANT_PROTO[0]),
+    ]
+    rc = _protoc.main(args)
+    if rc != 0:
+        raise RuntimeError(f"nodii_grpc_interfaces: grpc_tools.protoc exited with code {rc}")
+
+    # Ensure every parent dir is an importable package.
+    for sub in ("", "nodii", "nodii/dsar", "nodii/dsar/v1",
+                "nodii/tenant", "nodii/tenant/v1"):
+        init = gen_dir / sub / "__init__.py"
+        init.parent.mkdir(parents=True, exist_ok=True)
+        if not init.exists():
+            init.write_text("")
+
+    if str(gen_dir) not in sys.path:
+        sys.path.insert(0, str(gen_dir))
+    return gen_dir
+
+
+def _load(pb2_name: str, grpc_name: str) -> tuple[ModuleType, ModuleType]:
+    with _lock:
+        cached = _compiled.get(pb2_name)
+        if cached is not None:
+            return cached
+        _compile_all_protos()
+        pb2 = importlib.import_module(pb2_name)
+        grpc_mod = importlib.import_module(grpc_name)
+        result = (pb2, grpc_mod)
+        _compiled[pb2_name] = result
+        return result
+
+
+def load_dsar_stubs() -> tuple[ModuleType, ModuleType]:
+    """Returns (pb2, pb2_grpc) for nodii.dsar.v1.DataLifecycleService."""
+    return _load(_DSAR_PROTO[1], _DSAR_PROTO[2])
+
+
+def load_tenant_snapshot_stubs() -> tuple[ModuleType, ModuleType]:
+    """Returns (pb2, pb2_grpc) for nodii.tenant.v1.TenantSnapshotService."""
+    return _load(_TENANT_PROTO[1], _TENANT_PROTO[2])
+
+
+def data_lifecycle_servicer_base() -> Any:
+    """The grpcio ServicerBase for DataLifecycleService.
+
+    A consumer subclasses this and implements the 9 RPC methods, then calls
+    `add_DataLifecycleServiceServicer_to_server(impl, server)`.
+    """
+    _pb2, grpc_mod = load_dsar_stubs()
+    return grpc_mod.DataLifecycleServiceServicer
+
+
+def tenant_snapshot_servicer_base() -> Any:
+    """The grpcio ServicerBase for TenantSnapshotService."""
+    _pb2, grpc_mod = load_tenant_snapshot_stubs()
+    return grpc_mod.TenantSnapshotServiceServicer

nodii_grpc_interfaces-0.1.0/tests/test_proto_loader.py

@@ -0,0 +1,91 @@
+"""Asserts the runtime-compiled stubs load and expose the expected RPCs.
+
+The grpcio-generated ``<Service>Servicer`` base class carries one method per
+RPC (named with the proto-declared PascalCase RPC name), and the
+``add_<Service>Servicer_to_server`` registrar is what a consumer calls — so
+introspecting the servicer base is the consumer-facing contract surface.
+"""
+
+from __future__ import annotations
+
+from nodii_grpc_interfaces import SERVICE_NAMES
+from nodii_grpc_interfaces.proto_loader import (
+    load_dsar_stubs,
+    load_tenant_snapshot_stubs,
+)
+
+# The 9 canonical DataLifecycleService RPCs (D108 — ListActiveHolds, NOT Acknowledge).
+DSAR_RPCS = {
+    "AccessData",
+    "EraseData",
+    "RectifyData",
+    "ExportPortableData",
+    "RestrictProcessing",
+    "PlaceRetentionHold",
+    "LiftRetentionHold",
+    "GetLifecycleRequestStatus",
+    "ListActiveHolds",
+}
+
+# The 5 phase-1 TenantSnapshotService streaming bootstrap RPCs.
+TENANT_RPCS = {
+    "BootstrapTenantSnapshot",
+    "BootstrapUserMembershipSnapshot",
+    "BootstrapCustomerMembershipSnapshot",
+    "BootstrapAuthPolicySnapshot",
+    "BootstrapTenantSubscriptionSnapshot",
+}
+
+
+def _servicer_rpc_names(servicer_cls: type) -> set[str]:
+    # grpcio servicer bases define one public method per RPC.
+    return {
+        name
+        for name in dir(servicer_cls)
+        if not name.startswith("_") and callable(getattr(servicer_cls, name))
+    }
+
+
+def test_dsar_stubs_load_and_expose_nine_rpcs() -> None:
+    pb2, pb2_grpc = load_dsar_stubs()
+    assert hasattr(pb2_grpc, "DataLifecycleServiceServicer")
+    assert hasattr(pb2_grpc, "DataLifecycleServiceStub")
+    assert hasattr(pb2_grpc, "add_DataLifecycleServiceServicer_to_server")
+
+    rpcs = _servicer_rpc_names(pb2_grpc.DataLifecycleServiceServicer)
+    assert rpcs == DSAR_RPCS
+    assert len(rpcs) == 9
+
+
+def test_dsar_ninth_rpc_is_list_active_holds_not_acknowledge() -> None:
+    _pb2, pb2_grpc = load_dsar_stubs()
+    rpcs = _servicer_rpc_names(pb2_grpc.DataLifecycleServiceServicer)
+    assert "ListActiveHolds" in rpcs
+    assert "Acknowledge" not in rpcs
+
+
+def test_dsar_list_active_holds_wire_messages_present() -> None:
+    pb2, _pb2_grpc = load_dsar_stubs()
+    # The D108 wire messages exist; the retired Acknowledge message is gone.
+    assert hasattr(pb2, "ListActiveHoldsRequest")
+    assert hasattr(pb2, "ListActiveHoldsResponse")
+    assert hasattr(pb2, "ActiveHold")
+    assert not hasattr(pb2, "AcknowledgeRequest")
+
+
+def test_tenant_snapshot_stubs_load_and_expose_five_rpcs() -> None:
+    pb2, pb2_grpc = load_tenant_snapshot_stubs()
+    assert hasattr(pb2_grpc, "TenantSnapshotServiceServicer")
+    assert hasattr(pb2_grpc, "TenantSnapshotServiceStub")
+    assert hasattr(pb2_grpc, "add_TenantSnapshotServiceServicer_to_server")
+    assert hasattr(pb2, "TenantSnapshotChunk")
+    assert hasattr(pb2, "BootstrapSnapshotRequest")
+
+    rpcs = _servicer_rpc_names(pb2_grpc.TenantSnapshotServiceServicer)
+    assert rpcs == TENANT_RPCS
+    assert len(rpcs) == 5
+
+
+def test_service_names_are_canonical() -> None:
+    assert SERVICE_NAMES["DataLifecycleService"] == "nodii.dsar.v1.DataLifecycleService"
+    assert SERVICE_NAMES["TenantSnapshotService"] == "nodii.tenant.v1.TenantSnapshotService"

nodii_grpc_interfaces-0.1.0/tests/test_proto_parity.py

@@ -0,0 +1,51 @@
+"""Contract fence: the vendored proto bytes carry the canonical wire contract.
+
+These protos are vendored byte-equal from the planning-hub grpc-interfaces
+canonical mirror. nodii-grpc-interfaces IS the canonical proto/stub vendor
+surface (daa248c0/d7cd41dc/D190); it is NOT bound to the repo-root proto/ tree
+(which feeds dsar/role-catalog codegen and still carries the pre-D108 dsar proto
+pending drift 39e64d25). So we assert the vendored bytes carry the canonical
+contract markers (incl. D108 ListActiveHolds, NOT the legacy Acknowledge) rather
+than byte-comparing to the stale root. A failure means the vendored contract
+drifted — an R0 violation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+_VENDORED_ROOT = _HERE.parent / "proto"
+
+
+def _read(rel: str) -> str:
+    return (_VENDORED_ROOT / rel).read_text(encoding="utf-8")
+
+
+def test_dsar_proto_is_canonical_d108() -> None:
+    src = _read("nodii/dsar/v1/dsar.proto")
+    assert "package nodii.dsar.v1;" in src
+    assert "service DataLifecycleService" in src
+    # D108: 9th RPC is ListActiveHolds, NOT the legacy Acknowledge.
+    assert "rpc ListActiveHolds" in src
+    assert "ListActiveHoldsRequest" in src
+    assert "ListActiveHoldsResponse" in src
+    assert "rpc Acknowledge" not in src
+    for rpc in (
+        "AccessData",
+        "EraseData",
+        "RectifyData",
+        "ExportPortableData",
+        "RestrictProcessing",
+        "PlaceRetentionHold",
+        "LiftRetentionHold",
+        "GetLifecycleRequestStatus",
+        "ListActiveHolds",
+    ):
+        assert f"rpc {rpc}" in src, f"missing rpc {rpc}"
+
+
+def test_tenant_snapshot_proto_is_canonical() -> None:
+    src = _read("nodii/tenant/v1/tenant_snapshot.proto")
+    assert "package nodii.tenant.v1;" in src
+    assert "service TenantSnapshotService" in src