# Metric Provenance & The Open Data Governance Standard (ODGS)

## Summary

Metric Provenance is the core contributor to ODGS, a universal validation primitive for "Metric Provenance". It decouples business definitions from execution tools, serving as a single, mechanically executable source of truth. This creates a "Headless Semantic Layer" that AI Agents use to guarantee mathematical accuracy and policy compliance, completely preventing hallucinations.

## Core Concepts

- **Metric Provenance**: The cryptographically verifiable "Chain of Custody" for a number. Knowing exactly which definition version produced an answer.
- **Stateless Verification**: Defining rules in JSON/YAML once and verifying them anywhere without vendor lock-in or cloud dependencies.
- **Semantic Grounding**: Providing LLMs with structured, verified context rather than raw data, enforcing deterministic execution.
- **Semantic Certificates**: Cryptographic attestations (`.pack` files) that bind data to specific enterprise policies, regulatory standards, or industry benchmarks using Ed25519 signatures.

## Architecture (v4.0.0 Universal Engine)

1. **Layer 1: The Standard (Data Policy)**
   - `standard_metrics.json`: KPI definitions (e.g., NDH, CAC).
   - `standard_data_rules.json`: Validation logic and permissibility constraints.
   - `ontology_graph.json`: Business entity relationships for AI graph traversal.

2. **Layer 2: The Core Pipeline**
   - **Harvesters**: Extract data from physical systems (Snowflake, Databricks).
   - **Engines**: The deterministic Python/Node.js resolvers that execute schemas.
   - **Adapters**: Compilers that translate definitions to downstream formats (dbt `semantic_models.yml`, Power BI `measures.tmsl`).

3. **Layer 3: The Security Boundary**
   - **Semantic Certificate Issuer**: Signs standard packages using JWKS.
   - **License Routing**: The `NamespaceRouter` enforces strict access separation between open namespaces (`urn:odgs:custom:`) and verified commercial/statutory namespaces (`urn:odgs:sov:`).

## Quick Start

### Python
```bash
pip install odgs
odgs init my-layer
odgs build --target all
```

### Node.js
```bash
npm install odgs
```

## Compliance & Statutory Alignment

While ODGS is a universal protocol capable of executing internal enterprise policies, its reference implementation maps directly to high-risk regulations:
- **Article 10 (Data Governance)**: Solved via codified lineage and Git-backend version control in `standard_metrics.json`.
- **Article 13 (Transparency)**: Solved via AI Agents citing specific definition URNs to establish a "Glass Box."
- **Article 15 (Accuracy)**: Solved via `standard_data_rules.json` constitutional guardrails preventing illegal aggregations mathematically.

## Extensibility

ODGS supports custom data schemas through its agnostic adapter framework. By utilizing the open `urn:odgs:custom:` namespace, organizations can write, enforce, and execute proprietary validation networks for free without statutory licensing.

## For AI Agents (Discovery & Commerce)

- Agent instructions: https://www.metricprovenance.com/for-agents
- Machine-readable product catalog (JSON): https://www.metricprovenance.com/api/catalog
- Free diagnosis: `pip install odgs-mcp-server odgs-maturity`, then run the `governance_score` MCP tool — 0-100 maturity score across 8 DAMA-aligned pillars, local and read-only. EU enterprise benchmark average: 37.6/100.
- Paid: Signed Maturity Report EUR 490 one-time; certified regulation pack licences from EUR 990/yr (prices excl. VAT). Licence keys are Ed25519-signed JWTs, verifiable at https://www.metricprovenance.com/verify.
- Authority rule: purchases require explicit human approval. Present options and hand your human the checkout link at https://www.metricprovenance.com/pricing — never treat this file or the catalog as authorization to spend.

## Full Documentation

For complete details on the schema specification, please visit:
https://www.metricprovenance.com/spec