# ODGS: Open Data Governance Standard
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18564270.svg)](https://doi.org/10.5281/zenodo.18564270) ![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg) ![Version](https://img.shields.io/badge/Version-3.0.0-green.svg)

> **Current Status:** Candidate Reference Implementation for NEN Standards Committee 381 525 (Data, Cloud & Edge).
> **Architecture:** 5-Plane Sovereign Sidecar.

## 1. Abstract
The Open Data Governance Standard (ODGS) is a vendor-neutral protocol for **Administrative Safety** in High-Risk AI Systems.

It resolves the "Definition-Execution Gap" by strictly enforcing **Configuration as Law**:
*   The **Legislative Plane** (JSON) defines the policy.
*   The **Judiciary Plane** (Code) enforces it via a "Hard Stop" mechanism.

---

## 2. Repository Structure (Separation of Concerns)

This repository serves as both the **Standard Definition** and a **Reference Implementation**.

```text
odgs-protocol-main/
├── specifications/             <-- THE STANDARD (The Law)
│   ├── 00-architecture-5-plane.md
│   ├── 01-metrics-schema.json  (Legislative Plane)
│   ├── 02-rules-schema.json    (Judiciary Plane)
│   └── 03-ontology-schema.json (Semantic Plane)
│
├── docs/                       <-- THE EVIDENCE (Technical Annex)
│   ├── ODGS_Technical_Annex.md
│   └── compliance_report_iso_42001.md
│
├── src/odgs/                   <-- THE REFERENCE IMPLEMENTATION (Python Engine)
│   ├── executive/interceptor.py (The Enforcer)
│   └── system/cli.py           (The Interface)
│
└── lib/                        <-- THE CLIENT ADAPTER (Node.js SDK)
```

> **Note on Polyglot Architecture:**
> ODGS provides a **Python Engine** for heavy data engineering (dbt/Snowflake) and a **Node.js Client** for lightweight application sidecars. Both implementations adhere strictly to the schemas in `/specifications`.

---

## 3. The 5-Plane Architecture
ODGS v3.0.0 enforces the **Separation of Powers** required by sovereign data ecosystems.

| Plane | Role | Function | Artifact |
| :--- | :--- | :--- | :--- |
| **🏛️ Legislative** | **The Definition** | Defines *WHAT* must be governed. | `specifications/01-metrics-schema.json` |
| **⚖️ Judiciary** | **The Enforcer** | Defines *HOW* to validate it. | `specifications/02-rules-schema.json` |
| **⚔️ Executive** | **The Context** | Defines *WHERE* it applies. | `src/odgs/executive/interceptor.py` |
| **🔌 System** | **The Interface** | Manages API I/O. | `src/odgs/system/api.py` |
| **📝 Audit** | **The Record** | Proves compliance (Art. 12). | `git-log-adapter` |

[Read the Architecture Overview](docs/architecture_overview.md)

---

## 4. Key Capabilities

### 🔮 Dynamic Rule Engine
No more hardcoded logic. Rules are defined in `specifications/02-rules-schema.json` using secure expressions (e.g., `value > 0`). The Interceptor executes these rules dynamically.

### 🛡️ Tri-Partite Binding
Every audit log entry cryptographically binds three elements to ensure non-repudiation (Article 12):
1.  **Input Data Hash:** `SHA-256(Payload)`
2.  **Definition Hash:** `SHA-256(Project State)`
3.  **Configuration Hash:** `SHA-256(System Configuration)`

### 🔒 Git-as-Backend (Data Sovereignty)
We do not send your data to the cloud. ODGS uses your own filesystem as the database.
*   **Zero-Trust Logging:** Audit logs are written locally.
*   **Immutable History:** Logs are immediately committed to your local **Git Repository**, creating a forensic chain of custody that YOU own.

---

## 5. Quick Start (Reference Implementation)

### Installation
```bash
pip install odgs
# Requires: simpleeval, GitPython
```

### Usage (The Interceptor)

```python
from odgs import OdgsInterceptor, ProcessBlockedException

# Initialize Sovereign Sidecar
guard = OdgsInterceptor()

try:
    # The Sovereign Handshake
    guard.intercept(
        process_urn="urn:odgs:process:O2C_S03", 
        required_integrity_hash="sha256:7f9a2b90cc...", 
        data_context={"container_id": "INVALID 123"}
    )
except ProcessBlockedException as e:
    print(f"⛔ HARD STOP: {e}")
    # Log has been committed to local git repo automatically
    sys.exit(1)
```

---

## ⚠️ Legal Disclaimer
**ODGS provides the technical capability for Article 10 & 12 compliance; it does not guarantee legal immunity.**
The Organization (User) remains the sole Liability Holder. ODGS is the mechanism (The Lock); the Organization is responsible for the policy (The Key).

---

## License
Apache License 2.0 - see [LICENSE](LICENSE) for details.

**Copyright © 2026 [Metric Provenance](https://github.com/MetricProvenance)**
