data-contract-registry 0.1.1__py3-none-any.whl

data_contract_registry/__init__.py

@@ -0,0 +1,54 @@
+"""
+data-contract-registry — schema registry for data contracts.
+
+This package answers one question for a data team: *can this producer ship the
+new schema without breaking any downstream consumer it has a contract with?*
+Contracts carry the schema itself, plus the things that always matter and
+usually get lost in slack — owners, freshness SLA, deprecation policy.
+
+Two surfaces:
+
+    Library:  `from data_contract_registry import DataContract, ContractRegistry`
+    HTTP:     `uvicorn data_contract_registry.app:app` (optional `[api]` extra)
+
+Compatibility modes follow the Confluent schema-registry conventions so this
+slots into existing data org playbooks:
+
+    BACKWARD      new schema can read data produced by the previous schema
+    FORWARD       previous schema can read data produced by the new schema
+    FULL          both of the above
+    NONE          anything goes (use for first-time onboarding only)
+"""
+
+from __future__ import annotations
+
+from .compatibility import CompatibilityChecker, CompatibilityMode
+from .from_decision_card import contract_owner_from_decision_card
+from .models import (
+    CompatibilityReport,
+    ContractStatus,
+    DataContract,
+    DataField,
+    FieldType,
+    FreshnessSLA,
+    Owner,
+)
+from .registry import ContractRegistry, RegistryError
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "CompatibilityChecker",
+    "CompatibilityMode",
+    "CompatibilityReport",
+    "ContractRegistry",
+    "ContractStatus",
+    "DataContract",
+    "DataField",
+    "FieldType",
+    "FreshnessSLA",
+    "Owner",
+    "RegistryError",
+    "__version__",
+    "contract_owner_from_decision_card",
+]

data_contract_registry/app.py

@@ -0,0 +1,228 @@
+"""
+FastAPI app — eight endpoints around the in-memory registry.
+
+  GET  /                               service info
+  GET  /healthz                        liveness probe
+  GET  /datasets                       list registered dataset IDs
+  POST /contracts                      register / promote a contract
+  POST /contracts/check                dry-run compatibility check
+  GET  /contracts/{ds}/latest          latest ACTIVE contract for a dataset
+  GET  /contracts/{ds}/versions        full history
+  GET  /contracts/{ds}/versions/{v}    fetch a specific version
+  POST /contracts/{ds}/versions/{v}/deprecate
+  POST /contracts/{ds}/versions/{v}/archive
+  POST /contracts/owners/from-decision-card  cross-ecosystem hook
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+from fastapi import FastAPI, HTTPException, status
+from pydantic import BaseModel, ValidationError
+
+from . import __version__, audit_stream
+from .compatibility import CompatibilityMode
+from .from_decision_card import contract_owner_from_decision_card
+from .models import CompatibilityReport, DataContract, Owner
+from .registry import ContractRegistry, RegistryError
+
+
+class _RegisterRequest(BaseModel):
+    contract: DataContract
+    compatibility: CompatibilityMode = "backward"
+
+
+class _DeprecateRequest(BaseModel):
+    deprecation_uri: str
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+    app.state.registry = ContractRegistry()
+    # Shared httpx client for best-effort audit-stream emission. Always
+    # created; the audit_stream module no-ops when AUDIT_STREAM_URL is unset.
+    app.state.http_client = httpx.AsyncClient(
+        headers={"User-Agent": f"data-contract-registry/{__version__} (+https://kineticgain.com)"},
+    )
+    try:
+        yield
+    finally:
+        await app.state.http_client.aclose()
+
+
+app = FastAPI(
+    title="data-contract-registry",
+    version=__version__,
+    description=(
+        "Schema registry for data contracts: semver, compatibility checks, "
+        "ownership, freshness SLAs. Bridges to procurement-decision-api via "
+        "POST /contracts/owners/from-decision-card."
+    ),
+    lifespan=_lifespan,
+)
+
+
+def _registry() -> ContractRegistry:
+    """Typed accessor so mypy strict doesn't choke on app.state."""
+    registry = app.state.registry
+    assert isinstance(registry, ContractRegistry)
+    return registry
+
+
+def _http_client() -> httpx.AsyncClient:
+    """Shared httpx client used by audit_stream.emit (best-effort)."""
+    client = app.state.http_client
+    assert isinstance(client, httpx.AsyncClient)
+    return client
+
+
+@app.get("/", tags=["meta"])
+async def root() -> dict[str, Any]:
+    return {
+        "name": "data-contract-registry",
+        "version": __version__,
+        "description": (
+            "Registers + checks data contracts. Compatibility modes follow Confluent: "
+            "backward / forward / full / none."
+        ),
+        "endpoints": {
+            "GET  /": "this page",
+            "GET  /healthz": "liveness probe",
+            "GET  /datasets": "list registered dataset IDs",
+            "POST /contracts": "register a contract (checks compatibility first)",
+            "POST /contracts/check": "dry-run compatibility check without registering",
+            "GET  /contracts/{ds}/latest": "latest active contract for a dataset",
+            "GET  /contracts/{ds}/versions": "full version history",
+            "GET  /contracts/{ds}/versions/{v}": "one specific version",
+            "POST /contracts/{ds}/versions/{v}/deprecate": "mark a version deprecated",
+            "POST /contracts/{ds}/versions/{v}/archive": "archive a version",
+            "POST /contracts/owners/from-decision-card": "Decision Card -> Owner list",
+        },
+    }
+
+
+@app.get("/healthz", tags=["meta"])
+async def healthz() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/datasets", tags=["catalog"])
+async def list_datasets() -> dict[str, list[str]]:
+    return {"datasets": _registry().datasets()}
+
+
+@app.post("/contracts", tags=["contracts"], status_code=201)
+async def register_contract(req: _RegisterRequest) -> dict[str, Any]:
+    try:
+        report = _registry().register(req.contract, compatibility=req.compatibility)
+    except RegistryError as err:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err)) from err
+
+    if not report.compatible:
+        await audit_stream.emit(
+            _http_client(),
+            kind="contract_compatibility_failed",
+            payload={
+                "dataset_id": req.contract.dataset_id,
+                "version": req.contract.version,
+                "mode": report.mode,
+                "issue_count": len(report.issues),
+                "issues": [i.model_dump(mode="json") for i in report.issues],
+            },
+        )
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail={
+                "compatible": False,
+                "mode": report.mode,
+                "issues": [i.model_dump(mode="json") for i in report.issues],
+            },
+        )
+    await audit_stream.emit(
+        _http_client(),
+        kind="contract_promoted",
+        payload={
+            "dataset_id": req.contract.dataset_id,
+            "version": req.contract.version,
+            "mode": report.mode,
+            "owners": [o.team for o in req.contract.owners],
+        },
+    )
+    return {
+        "status": "registered",
+        "dataset_id": req.contract.dataset_id,
+        "version": req.contract.version,
+        "compatibility": report.model_dump(mode="json"),
+    }
+
+
+@app.post("/contracts/check", tags=["contracts"])
+async def check_contract(req: _RegisterRequest) -> CompatibilityReport:
+    return _registry().check(req.contract, compatibility=req.compatibility)
+
+
+@app.get("/contracts/{dataset_id}/latest", tags=["contracts"])
+async def latest_contract(dataset_id: str) -> DataContract:
+    try:
+        return _registry().latest(dataset_id)
+    except RegistryError as err:
+        raise HTTPException(status_code=404, detail=str(err)) from err
+
+
+@app.get("/contracts/{dataset_id}/versions", tags=["contracts"])
+async def contract_history(dataset_id: str) -> list[DataContract]:
+    try:
+        return _registry().history(dataset_id)
+    except RegistryError as err:
+        raise HTTPException(status_code=404, detail=str(err)) from err
+
+
+@app.get("/contracts/{dataset_id}/versions/{version}", tags=["contracts"])
+async def get_version(dataset_id: str, version: str) -> DataContract:
+    try:
+        return _registry().get(dataset_id, version)
+    except RegistryError as err:
+        raise HTTPException(status_code=404, detail=str(err)) from err
+
+
+@app.post("/contracts/{dataset_id}/versions/{version}/deprecate", tags=["contracts"])
+async def deprecate_version(
+    dataset_id: str,
+    version: str,
+    req: _DeprecateRequest,
+) -> DataContract:
+    try:
+        contract = _registry().deprecate(dataset_id, version, deprecation_uri=req.deprecation_uri)
+    except RegistryError as err:
+        raise HTTPException(status_code=404, detail=str(err)) from err
+    await audit_stream.emit(
+        _http_client(),
+        kind="contract_deprecated",
+        payload={
+            "dataset_id": dataset_id,
+            "version": version,
+            "deprecation_uri": req.deprecation_uri,
+        },
+    )
+    return contract
+
+
+@app.post("/contracts/{dataset_id}/versions/{version}/archive", tags=["contracts"])
+async def archive_version(dataset_id: str, version: str) -> DataContract:
+    try:
+        return _registry().archive(dataset_id, version)
+    except RegistryError as err:
+        raise HTTPException(status_code=404, detail=str(err)) from err
+
+
+@app.post("/contracts/owners/from-decision-card", tags=["bridge"])
+async def owners_from_decision_card(card: dict[str, Any]) -> list[Owner]:
+    """The cross-ecosystem hook — pull owners out of a Decision Card."""
+    try:
+        return contract_owner_from_decision_card(card)
+    except (ValueError, ValidationError) as err:
+        raise HTTPException(status_code=400, detail=str(err)) from err

data_contract_registry/audit_stream.py

@@ -0,0 +1,84 @@
+"""
+Optional audit-stream-py integration.
+
+When the `AUDIT_STREAM_URL` env var is set, this module fires governance
+events at `{AUDIT_STREAM_URL}/events` for the moments the service produces.
+Best-effort: a failed POST is logged, not raised — audit-stream outages
+must never block contract registration or deprecation.
+
+Event kinds this service emits:
+    contract_promoted              on POST /contracts when the new version
+                                   is compatible and successfully registered
+    contract_compatibility_failed  on POST /contracts when the compatibility
+                                   check fails (HTTP 422). This is the
+                                   "we tried to ship a breaking change"
+                                   governance signal — record it.
+    contract_deprecated            on POST /contracts/{ds}/versions/{v}/deprecate
+
+Same opt-in pattern as procurement-decision-api.audit_stream,
+aeo-validator-service.audit_stream, and policy-as-code-engine.audit_stream.
+Identical config envvars.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_TIMEOUT_S = 2.5
+
+
+def is_enabled() -> bool:
+    """True when AUDIT_STREAM_URL is set to a non-empty value."""
+    return bool(os.environ.get("AUDIT_STREAM_URL", "").strip())
+
+
+def base_url() -> str | None:
+    """Stripped audit-stream base URL, or None when disabled."""
+    raw = os.environ.get("AUDIT_STREAM_URL", "").strip()
+    if not raw:
+        return None
+    return raw.rstrip("/")
+
+
+def timeout_s() -> float:
+    """Configured per-call timeout. Defaults to 2.5s."""
+    raw = os.environ.get("AUDIT_STREAM_TIMEOUT_S", "").strip()
+    if not raw:
+        return DEFAULT_TIMEOUT_S
+    try:
+        return max(0.1, float(raw))
+    except ValueError:
+        return DEFAULT_TIMEOUT_S
+
+
+async def emit(
+    client: httpx.AsyncClient,
+    *,
+    kind: str,
+    payload: dict[str, Any],
+) -> None:
+    """Fire one event. Silent no-op when AUDIT_STREAM_URL is unset."""
+    url = base_url()
+    if url is None:
+        return
+
+    body = {
+        "kind": kind,
+        "source": "data-contract-registry",
+        "payload": payload,
+    }
+    try:
+        response = await client.post(
+            f"{url}/events",
+            json=body,
+            timeout=timeout_s(),
+        )
+        response.raise_for_status()
+    except (httpx.HTTPError, OSError) as err:
+        print(
+            f"audit-stream emit failed (kind={kind}): {type(err).__name__}: {err}",
+            flush=True,
+        )

data_contract_registry/compatibility.py

@@ -0,0 +1,197 @@
+"""
+Compatibility checker — does new schema break consumers of old schema?
+
+Modes follow the Confluent schema registry conventions:
+
+    BACKWARD    new schema can read data produced by the previous schema
+                (consumers can upgrade first)
+    FORWARD     previous schema can read data produced by the new schema
+                (producers can upgrade first)
+    FULL        both
+    NONE        anything goes; first-time onboarding only
+
+For our six-type system the rules are:
+
+    BACKWARD-breaking changes (new schema rejects old data):
+      - removed a field that old data carried
+      - changed a field's type
+      - turned an optional field into required (old data missing it -> reject)
+      - shrunk an enum (old enum value -> reject)
+
+    FORWARD-breaking changes (old schema rejects new data):
+      - added a required field old schema doesn't know about
+        (only matters if old schema rejects unknown fields; we treat additions
+         to enums as forward-compatible since extra values are fine for readers)
+
+This is intentionally smaller than the Avro/Protobuf rule set — the point is
+"can I promote this", not "let me prove every possible serialisation path."
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from .models import (
+    CompatibilityIssue,
+    CompatibilityReport,
+    DataContract,
+)
+
+CompatibilityMode = Literal["backward", "forward", "full", "none"]
+
+
+class CompatibilityChecker:
+    """Stateless. Cheap to construct. Reuse one per process."""
+
+    def check(
+        self,
+        previous: DataContract,
+        proposed: DataContract,
+        *,
+        mode: CompatibilityMode = "backward",
+    ) -> CompatibilityReport:
+        if previous.dataset_id != proposed.dataset_id:
+            raise ValueError(
+                f"dataset_id mismatch: previous={previous.dataset_id!r} proposed={proposed.dataset_id!r}"
+            )
+
+        issues: list[CompatibilityIssue] = []
+        issues.extend(self._version_issues(previous, proposed))
+        issues.extend(self._owner_issues(proposed))
+        issues.extend(self._primary_key_issues(previous, proposed))
+
+        if mode in ("backward", "full"):
+            issues.extend(self._backward_issues(previous, proposed))
+        if mode in ("forward", "full"):
+            issues.extend(self._forward_issues(previous, proposed))
+
+        compatible = not any(i.severity == "error" for i in issues)
+        return CompatibilityReport(compatible=compatible, mode=mode, issues=issues)
+
+    # ---- structural checks (run regardless of mode) ---------------------
+
+    def _version_issues(self, previous: DataContract, proposed: DataContract) -> list[CompatibilityIssue]:
+        prev = _parse_semver(previous.version)
+        new = _parse_semver(proposed.version)
+        if new <= prev:
+            return [
+                CompatibilityIssue(
+                    severity="error",
+                    field=None,
+                    kind="version_not_increasing",
+                    message=(
+                        f"new version {proposed.version!r} must be strictly greater than {previous.version!r}"
+                    ),
+                )
+            ]
+        return []
+
+    def _owner_issues(self, proposed: DataContract) -> list[CompatibilityIssue]:
+        if not proposed.owners:
+            return [
+                CompatibilityIssue(
+                    severity="error",
+                    field=None,
+                    kind="owner_missing",
+                    message="proposed contract must declare at least one owner",
+                )
+            ]
+        return []
+
+    def _primary_key_issues(self, previous: DataContract, proposed: DataContract) -> list[CompatibilityIssue]:
+        if previous.primary_key != proposed.primary_key:
+            return [
+                CompatibilityIssue(
+                    severity="error",
+                    field=None,
+                    kind="primary_key_changed",
+                    message=(f"primary_key changed: {previous.primary_key} -> {proposed.primary_key}"),
+                )
+            ]
+        return []
+
+    # ---- backward / forward checks --------------------------------------
+
+    def _backward_issues(self, previous: DataContract, proposed: DataContract) -> list[CompatibilityIssue]:
+        issues: list[CompatibilityIssue] = []
+
+        prev_fields = {f.name: f for f in previous.fields}
+        new_fields = {f.name: f for f in proposed.fields}
+
+        # Removed fields: a field that was in the old schema and isn't in the new.
+        for name, prev in prev_fields.items():
+            if name not in new_fields:
+                issues.append(
+                    CompatibilityIssue(
+                        severity="error",
+                        field=name,
+                        kind="field_removed",
+                        message=f"field {name!r} was removed; old data will fail validation",
+                    )
+                )
+                continue
+            new = new_fields[name]
+            if new.type != prev.type:
+                issues.append(
+                    CompatibilityIssue(
+                        severity="error",
+                        field=name,
+                        kind="field_type_changed",
+                        message=(
+                            f"field {name!r} type changed: {prev.type} -> {new.type}; "
+                            "values from old schema may not round-trip"
+                        ),
+                    )
+                )
+            if not prev.required and new.required:
+                issues.append(
+                    CompatibilityIssue(
+                        severity="error",
+                        field=name,
+                        kind="field_required_added",
+                        message=(f"field {name!r} was optional, now required; old rows missing it will fail"),
+                    )
+                )
+            if prev.enum and new.enum and set(new.enum) - set(prev.enum) != set(new.enum) - set(prev.enum):
+                # Should never happen; guard kept for clarity.
+                pass
+            if prev.enum and new.enum:
+                shrunk = set(prev.enum) - set(new.enum)
+                if shrunk:
+                    issues.append(
+                        CompatibilityIssue(
+                            severity="error",
+                            field=name,
+                            kind="field_enum_shrunk",
+                            message=(
+                                f"field {name!r} enum shrunk; removed values {sorted(map(str, shrunk))} "
+                                "may appear in old data"
+                            ),
+                        )
+                    )
+        return issues
+
+    def _forward_issues(self, previous: DataContract, proposed: DataContract) -> list[CompatibilityIssue]:
+        issues: list[CompatibilityIssue] = []
+        prev_fields = {f.name: f for f in previous.fields}
+        new_fields = {f.name: f for f in proposed.fields}
+
+        for name, new in new_fields.items():
+            if name not in prev_fields and new.required:
+                issues.append(
+                    CompatibilityIssue(
+                        severity="error",
+                        field=name,
+                        kind="field_required_added",
+                        message=(
+                            f"required field {name!r} added; consumers on the old schema "
+                            "won't know how to populate it"
+                        ),
+                    )
+                )
+        return issues
+
+
+def _parse_semver(version: str) -> tuple[int, int, int]:
+    major, minor, patch = version.split(".")
+    return int(major), int(minor), int(patch)

data_contract_registry/from_decision_card.py

@@ -0,0 +1,49 @@
+"""
+Bridge to AI Procurement Decision Cards.
+
+When a buyer approves a vendor whose data product the team will consume, the
+Decision Card's `buyer.name` + `decision_maker` are *the right answers* to
+"who owns the contract on our side". This helper extracts those fields into
+`Owner` records so a freshly registered contract carries them automatically
+instead of asking the data team to re-type them.
+
+Tiny, but it's the third cross-ecosystem hook in the portfolio.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import Owner
+
+
+def contract_owner_from_decision_card(card: dict[str, Any]) -> list[Owner]:
+    """
+    Pull a credible owner list out of a Kinetic Gain Procurement Decision Card.
+
+    The buyer's team is always owner #0. If the card also declares a
+    `decision_maker.role` we add that as a secondary owner so on-call routing
+    has a name to page.
+    """
+    if "buyer" not in card or not isinstance(card["buyer"], dict):
+        raise ValueError("Decision Card is missing required 'buyer' object")
+    buyer = card["buyer"]
+    name = buyer.get("name")
+    if not name or not isinstance(name, str):
+        raise ValueError("buyer.name is required and must be a non-empty string")
+
+    owners: list[Owner] = [Owner(team=name, contact=buyer.get("contact") or None)]
+
+    decision_maker = card.get("decision_maker") or {}
+    if isinstance(decision_maker, dict):
+        role = decision_maker.get("role")
+        dm_name = decision_maker.get("name")
+        if role:
+            owners.append(
+                Owner(
+                    team=f"{role}" + (f" ({dm_name})" if dm_name else ""),
+                    contact=decision_maker.get("authority") or None,
+                )
+            )
+
+    return owners

data_contract_registry/models.py

@@ -0,0 +1,148 @@
+"""
+Pydantic v2 models for data contracts.
+
+A `DataContract` is the unit of agreement between a data producer and one or
+more consumers. The schema is intentionally small — six field types covering
+~99% of real-world dataset columns — plus the metadata that always matters:
+
+    - owners              who to wake up
+    - freshness SLA       how stale is too stale
+    - status              draft / active / deprecated / archived
+    - deprecation_uri     when status == "deprecated", where the migration plan lives
+
+Versions are full snapshots (not diffs); the registry holds the version history.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+FieldType = Literal["string", "integer", "number", "boolean", "timestamp", "json"]
+"""Six canonical primitives. `json` is the escape hatch for nested payloads."""
+
+ContractStatus = Literal["draft", "active", "deprecated", "archived"]
+
+
+class DataField(StrictModel):
+    """One column / attribute in the contract."""
+
+    name: str = Field(..., min_length=1)
+    type: FieldType
+    required: bool = True
+    description: str | None = None
+    enum: list[str | int | bool] | None = Field(
+        default=None,
+        description="If set, the field value must be one of these.",
+    )
+    deprecated: bool = False
+
+
+class Owner(StrictModel):
+    """One owner of a contract — usually a team."""
+
+    team: str = Field(..., min_length=1)
+    contact: str | None = Field(
+        default=None,
+        description="Slack channel, pager group, or email.",
+    )
+
+
+class FreshnessSLA(StrictModel):
+    """How stale the dataset is allowed to be before it's considered broken."""
+
+    max_lag_seconds: int = Field(..., gt=0)
+    measurement: str = Field(
+        default="event_time",
+        description="Field whose age is measured: 'event_time', 'ingested_at', etc.",
+    )
+
+
+class DataContract(StrictModel):
+    """
+    The whole contract document.
+
+    Stable identity is `(dataset_id, version)`. Versions follow semver:
+
+        MAJOR   incompatible change (removed field, renamed field, type change)
+        MINOR   new optional field, new enum value
+        PATCH   description fix, owner update, no schema change
+    """
+
+    dataset_id: str = Field(..., min_length=1, max_length=128)
+    version: str = Field(..., description="Semver like '1.2.0'.")
+    description: str | None = None
+    fields: list[DataField] = Field(..., min_length=1)
+    owners: list[Owner] = Field(..., min_length=1)
+    freshness_sla: FreshnessSLA | None = None
+    status: ContractStatus = "draft"
+    deprecation_uri: str | None = None
+    primary_key: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_invariants(self) -> DataContract:
+        if not SEMVER_RE.match(self.version):
+            raise ValueError(f"version must match MAJOR.MINOR.PATCH; got {self.version!r}")
+        names = [f.name for f in self.fields]
+        if len(names) != len(set(names)):
+            raise ValueError("field names must be unique within a contract")
+        for key in self.primary_key:
+            if key not in names:
+                raise ValueError(f"primary_key field {key!r} is not declared in fields")
+        if self.status == "deprecated" and not self.deprecation_uri:
+            raise ValueError("status='deprecated' requires deprecation_uri")
+        return self
+
+    def field(self, name: str) -> DataField | None:
+        for f in self.fields:
+            if f.name == name:
+                return f
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Compatibility outputs
+# ---------------------------------------------------------------------------
+
+
+class CompatibilityIssue(StrictModel):
+    """A single problem flagged by the compatibility checker."""
+
+    severity: Literal["error", "warning"]
+    field: str | None = None
+    kind: Literal[
+        "field_removed",
+        "field_renamed",
+        "field_type_changed",
+        "field_required_added",
+        "field_enum_shrunk",
+        "version_not_increasing",
+        "owner_missing",
+        "primary_key_changed",
+    ]
+    message: str
+
+
+class CompatibilityReport(StrictModel):
+    """Result of `CompatibilityChecker.check`."""
+
+    compatible: bool
+    mode: str
+    issues: list[CompatibilityIssue]
+
+    @property
+    def errors(self) -> list[CompatibilityIssue]:
+        return [i for i in self.issues if i.severity == "error"]
+
+    @property
+    def warnings(self) -> list[CompatibilityIssue]:
+        return [i for i in self.issues if i.severity == "warning"]

data_contract_registry/registry.py

@@ -0,0 +1,166 @@
+"""
+In-memory contract registry.
+
+Holds many contracts by `(dataset_id, version)` and exposes the moves data
+teams actually make:
+
+    register      promote a new version after compatibility passes
+    latest        give me the freshest contract for this dataset
+    history       give me every version
+    deprecate     mark a version deprecated with a migration URI
+    archive       remove from active rotation (history preserved)
+
+Concurrency: a single `threading.Lock` around the dict. Real deployments
+would swap this for a SQL backend; the protocol is small enough that doing
+so is mechanical.
+"""
+
+from __future__ import annotations
+
+from threading import Lock
+
+from .compatibility import CompatibilityChecker, CompatibilityMode
+from .models import CompatibilityReport, DataContract
+
+
+class RegistryError(Exception):
+    """Raised by `ContractRegistry` for caller-facing failures."""
+
+
+class ContractRegistry:
+    """Thread-safe in-memory registry. Cheap to share across threads."""
+
+    __slots__ = ("_checker", "_contracts", "_lock")
+
+    def __init__(self, *, checker: CompatibilityChecker | None = None) -> None:
+        self._contracts: dict[str, list[DataContract]] = {}
+        self._checker = checker or CompatibilityChecker()
+        self._lock = Lock()
+
+    # ---- writes ---------------------------------------------------------
+
+    def register(
+        self,
+        contract: DataContract,
+        *,
+        compatibility: CompatibilityMode = "backward",
+    ) -> CompatibilityReport:
+        """
+        Register a new version of a contract.
+
+        If there's no existing version for this `dataset_id`, the contract is
+        accepted unconditionally (a compatible-by-vacuous-truth report is returned).
+
+        If there is, the new version is checked against the most recent active
+        version. The registration only proceeds if the report's `compatible` is
+        True.
+        """
+        with self._lock:
+            history = self._contracts.setdefault(contract.dataset_id, [])
+            existing = next((c for c in reversed(history) if c.status == "active"), None)
+            if existing is None and history:
+                # Fall back to the most recent of any status.
+                existing = history[-1]
+
+            if existing is None:
+                history.append(contract)
+                return CompatibilityReport(compatible=True, mode=compatibility, issues=[])
+
+            if existing.version == contract.version:
+                raise RegistryError(
+                    f"version {contract.version!r} of {contract.dataset_id!r} is already registered"
+                )
+
+            report = self._checker.check(existing, contract, mode=compatibility)
+            if not report.compatible:
+                return report
+
+            history.append(contract)
+            return report
+
+    def deprecate(
+        self,
+        dataset_id: str,
+        version: str,
+        *,
+        deprecation_uri: str,
+    ) -> DataContract:
+        with self._lock:
+            history = self._contracts.get(dataset_id)
+            if not history:
+                raise RegistryError(f"unknown dataset_id: {dataset_id!r}")
+            for i, c in enumerate(history):
+                if c.version == version:
+                    updated = c.model_copy(
+                        update={"status": "deprecated", "deprecation_uri": deprecation_uri}
+                    )
+                    history[i] = updated
+                    return updated
+            raise RegistryError(f"{dataset_id!r} has no version {version!r}")
+
+    def archive(self, dataset_id: str, version: str) -> DataContract:
+        with self._lock:
+            history = self._contracts.get(dataset_id)
+            if not history:
+                raise RegistryError(f"unknown dataset_id: {dataset_id!r}")
+            for i, c in enumerate(history):
+                if c.version == version:
+                    updated = c.model_copy(update={"status": "archived"})
+                    history[i] = updated
+                    return updated
+            raise RegistryError(f"{dataset_id!r} has no version {version!r}")
+
+    # ---- reads ----------------------------------------------------------
+
+    def latest(self, dataset_id: str, *, include_non_active: bool = False) -> DataContract:
+        with self._lock:
+            history = self._contracts.get(dataset_id)
+            if not history:
+                raise RegistryError(f"unknown dataset_id: {dataset_id!r}")
+            if include_non_active:
+                return history[-1]
+            for c in reversed(history):
+                if c.status == "active":
+                    return c
+            raise RegistryError(f"{dataset_id!r} has no active version")
+
+    def get(self, dataset_id: str, version: str) -> DataContract:
+        with self._lock:
+            history = self._contracts.get(dataset_id)
+            if not history:
+                raise RegistryError(f"unknown dataset_id: {dataset_id!r}")
+            for c in history:
+                if c.version == version:
+                    return c
+            raise RegistryError(f"{dataset_id!r} has no version {version!r}")
+
+    def history(self, dataset_id: str) -> list[DataContract]:
+        with self._lock:
+            history = self._contracts.get(dataset_id)
+            if not history:
+                raise RegistryError(f"unknown dataset_id: {dataset_id!r}")
+            return list(history)
+
+    def datasets(self) -> list[str]:
+        with self._lock:
+            return list(self._contracts.keys())
+
+    def __contains__(self, dataset_id: object) -> bool:
+        with self._lock:
+            return dataset_id in self._contracts
+
+    # ---- dry-run --------------------------------------------------------
+
+    def check(
+        self,
+        contract: DataContract,
+        *,
+        compatibility: CompatibilityMode = "backward",
+    ) -> CompatibilityReport:
+        """Check a proposed contract WITHOUT registering it."""
+        with self._lock:
+            history = self._contracts.get(contract.dataset_id)
+            existing = next((c for c in reversed(history or []) if c.status == "active"), None)
+        if existing is None:
+            return CompatibilityReport(compatible=True, mode=compatibility, issues=[])
+        return self._checker.check(existing, contract, mode=compatibility)

data_contract_registry-0.1.1.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: data-contract-registry
+Version: 0.1.1
+Summary: Schema registry for data contracts: semver versioning, compatibility checks (backward/forward/full), ownership, freshness SLAs. The 'you can't promote it without an approved contract' pattern for data pipelines. Optional audit-stream-py integration via AUDIT_STREAM_URL.
+Project-URL: Homepage, https://github.com/mizcausevic-dev/data-contract-registry
+Project-URL: Repository, https://github.com/mizcausevic-dev/data-contract-registry
+Project-URL: Issues, https://github.com/mizcausevic-dev/data-contract-registry/issues
+Project-URL: Author Site, https://kineticgain.com/
+Author-email: Miz Causevic <miz@kineticgain.com>
+License: MIT
+License-File: LICENSE
+Keywords: data-contract,data-quality,fastapi,kinetic-gain,schema-registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# data-contract-registry
+
+[![CI](https://github.com/mizcausevic-dev/data-contract-registry/actions/workflows/ci.yml/badge.svg)](https://github.com/mizcausevic-dev/data-contract-registry/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Schema registry for data contracts.** Semver versioning, compatibility checks (backward / forward / full), declared owners, freshness SLAs. The "you can't promote a new dataset version without an approved contract" pattern, lifted from API governance and aimed at data pipelines.
+
+The headline endpoint is `POST /contracts` — register a new version, get back a deterministic compatibility report or a 422 with every breaking change called out by field name and kind.
+
+---
+
+## Why
+
+The thing that gets data teams paged at 2am isn't a missing test. It's a producer who quietly removed `ltv` because "we never use it anymore" while three downstream dashboards still join on it. Schema registries (Confluent, Buf, etc.) solved this for streaming and gRPC; data pipelines need the same hardness in a shape that fits the things data teams actually argue about:
+
+- **owners** — who do I page when this dataset goes stale
+- **freshness SLA** — when does "stale" become "broken"
+- **primary key** — changing it is a `MAJOR`, not a `MINOR`
+- **enum drift** — adding a value is fine; removing one is a backward-compatibility break
+- **deprecation policy** — flag a version with the URI of the migration plan; don't delete it
+
+This package is the smallest thing that does all of those.
+
+---
+
+## Install
+
+```bash
+pip install data-contract-registry
+# with the FastAPI surface:
+pip install "data-contract-registry[api]"
+```
+
+Python 3.11+. Runtime deps: `pydantic` + `PyYAML`.
+
+---
+
+## Library quickstart
+
+```python
+from data_contract_registry import (
+    ContractRegistry,
+    DataContract,
+    DataField,
+    Owner,
+)
+
+registry = ContractRegistry()
+
+v1 = DataContract(
+    dataset_id="users.daily_active",
+    version="1.0.0",
+    primary_key=["user_id", "active_date"],
+    owners=[Owner(team="growth-platform", contact="#growth-platform")],
+    fields=[
+        DataField(name="user_id",     type="string"),
+        DataField(name="active_date", type="timestamp"),
+        DataField(name="plan",        type="string", enum=["free", "pro", "enterprise"]),
+        DataField(name="ltv",         type="number", required=False),
+    ],
+    status="active",
+)
+registry.register(v1)
+
+# Compatible promotion (added an optional field).
+v1_1 = v1.model_copy(update={
+    "version": "1.1.0",
+    "fields": [*v1.fields, DataField(name="signup_source", type="string", required=False)],
+})
+report = registry.register(v1_1)
+print(report.compatible)   # True
+
+# Incompatible promotion — removing a field breaks backward compatibility.
+v2 = v1.model_copy(update={"version": "2.0.0", "fields": [f for f in v1.fields if f.name != "ltv"]})
+report = registry.register(v2)
+print(report.compatible)               # False
+print(report.errors[0].kind)           # "field_removed"
+print(report.errors[0].message)        # "field 'ltv' was removed; old data will fail validation"
+```
+
+---
+
+## Compatibility modes
+
+| Mode       | Meaning |
+| ---------- | --- |
+| `backward` | New schema can read data produced by the previous schema. **Default.** Consumers upgrade first. |
+| `forward`  | Previous schema can read data produced by the new schema. Producers upgrade first. |
+| `full`     | Both. |
+| `none`     | Anything goes. First-time onboarding only. |
+
+The checks the engine knows how to flag (each carries a structured `kind` so you can build CI gates around specific failures):
+
+| Kind                       | Severity | Mode |
+| -------------------------- | -------- | --- |
+| `field_removed`            | error    | backward |
+| `field_type_changed`       | error    | backward |
+| `field_required_added`     | error    | backward (optional→required) **or** forward (new required field) |
+| `field_enum_shrunk`        | error    | backward |
+| `primary_key_changed`      | error    | always |
+| `version_not_increasing`   | error    | always |
+| `owner_missing`            | error    | always |
+
+---
+
+## FastAPI surface
+
+```bash
+pip install "data-contract-registry[api]"
+uvicorn data_contract_registry.app:app --port 8090
+```
+
+| Method | Path | What it does |
+| --- | --- | --- |
+| GET | `/` | Service info. |
+| GET | `/healthz` | Liveness probe. |
+| GET | `/datasets` | List registered dataset IDs. |
+| POST | `/contracts` | Register / promote a contract. 422 with a structured issue list when incompatible. |
+| POST | `/contracts/check` | Dry-run compatibility check — does **not** register. |
+| GET | `/contracts/{ds}/latest` | Latest **active** contract for a dataset. |
+| GET | `/contracts/{ds}/versions` | Full version history. |
+| GET | `/contracts/{ds}/versions/{v}` | One specific version. |
+| POST | `/contracts/{ds}/versions/{v}/deprecate` | Mark deprecated with a migration URI. |
+| POST | `/contracts/{ds}/versions/{v}/archive` | Archive a version (history preserved). |
+| POST | `/contracts/owners/from-decision-card` | **Cross-ecosystem hook** — pull owners out of a Decision Card. |
+
+Bundles are held in-memory by default. For restart-safe storage, swap `_BundleStore`'s implementation; the protocol is small.
+
+---
+
+## The cross-ecosystem hook
+
+The third hook in the portfolio (after `procurement-decision-api` → `policy-as-code-engine` and the Suite → Decision Intelligence bridge). When a buyer approves a vendor whose data product the team will consume, the Decision Card's `buyer.name` + `decision_maker` are **the right answer** to "who owns the contract on our side":
+
+```bash
+curl -X POST http://localhost:8090/contracts/owners/from-decision-card \
+  -H 'Content-Type: application/json' \
+  -d @decision-card.json
+# -> [
+#   {"team": "Springfield USD",                            "contact": "#data-platform"},
+#   {"team": "Director of Data (Alex Chen)",               "contact": null}
+# ]
+```
+
+Drop that list straight into `DataContract.owners` and the registration carries paging info the team didn't have to re-type.
+
+---
+
+## YAML authoring
+
+```yaml
+# contracts/users-daily-active.yaml
+dataset_id: users.daily_active
+version: "1.0.0"
+owners:
+  - team: growth-platform
+    contact: "#growth-platform"
+freshness_sla:
+  max_lag_seconds: 86400
+fields:
+  - {name: user_id,      type: string}
+  - {name: active_date,  type: timestamp}
+  - {name: plan,         type: string, enum: [free, pro, enterprise]}
+```
+
+Hand-author in YAML, validate in CI, register from Python:
+
+```python
+import yaml
+from pathlib import Path
+from data_contract_registry import ContractRegistry, DataContract
+
+raw = yaml.safe_load(Path("contracts/users-daily-active.yaml").read_text())
+ContractRegistry().register(DataContract.model_validate(raw))
+```
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests && ruff format --check src tests
+mypy src
+pytest -v
+```
+
+CI matrix runs Python 3.11 / 3.12 / 3.13.
+
+---
+
+## Related in this ecosystem
+
+- **[procurement-decision-api](https://github.com/mizcausevic-dev/procurement-decision-api)** — drafts the Decision Cards this registry pulls owners from.
+- **[policy-as-code-engine](https://github.com/mizcausevic-dev/policy-as-code-engine)** — pair with this registry to enforce contracts at request time.
+- **[slo-budget-tracker](https://github.com/mizcausevic-dev/slo-budget-tracker)** — wire your freshness SLA into the same monitoring story.
+- More at [kineticgain.com](https://kineticgain.com/).
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data_contract_registry-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+data_contract_registry/__init__.py,sha256=sC8JdBV5gMy2ectTvjW9ZCRwByvIXzpN4SsOaaD-aL8,1629
+data_contract_registry/app.py,sha256=QCHT_gAoOgewea3fQZa6i0o_UKlA71gYPGU5mvUy8zY,8222
+data_contract_registry/audit_stream.py,sha256=1_7xDUZIA-G9VS07tVJeS2jwy2ubrOA8RjCrUVeebmk,2536
+data_contract_registry/compatibility.py,sha256=ACHl0mmA_j0QQVMU93AUibxGJ-JX72QsqZjWYETtUh0,7762
+data_contract_registry/from_decision_card.py,sha256=gdujAJCSYHutYg0I6sTRgUpQbhRm0qW8YOoZj_gtM74,1757
+data_contract_registry/models.py,sha256=yhEBodqQnF6eYNA37cxmNa9FrOSiV-18L38gTMGLC5A,4781
+data_contract_registry/registry.py,sha256=pYaF6B4TimKitsBgb5AVWyCMJw9BeqRPR-GzUs1oRs4,6358
+data_contract_registry-0.1.1.dist-info/METADATA,sha256=ltoblW673tYxv6RECKRbxN8cqXxwLhEneaJMa3X47tY,9702
+data_contract_registry-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+data_contract_registry-0.1.1.dist-info/licenses/LICENSE,sha256=9REhXrEWXVgwUgFKw9H__Zaboj9yGUNNVJeYTlmqvG8,1084
+data_contract_registry-0.1.1.dist-info/RECORD,,

data_contract_registry-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

data_contract_registry-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miz Causevic / Kinetic Gain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.