# V0 Runtime-Served Contract View Schema

## Purpose

The runtime-served contract view is the agent- and runtime-facing JSON projection of an approved Git-authored data product contract.

It is not a second source of truth. It is a promoted, denormalized, runtime-enriched view derived from an approved authored contract revision.

Machine-readable schema:

```text
schemas/data-product-contract.runtime-view.v0.schema.json
```

## Design Goals

The runtime view should be:

- Fast for agents and platform clients to consume
- Explicit about current product status
- Rich enough for discovery, query, explanation, and action decisions
- Linked to deeper registries instead of embedding every heavy detail
- Provenance-preserving back to Git
- Versioned independently from authored contract files

## Snapshot, Not Warehouse

The runtime-served view is a denormalized snapshot. It includes summaries and stable references to deeper systems:

- Full lineage graph
- Full policy documents
- Full run logs
- Full test history
- Full docs pages
- Full audit logs

Agents should be able to answer "Can I use this product for this task right now?" from the snapshot, then follow links for deeper explanation.

## Required Top-Level Fields

- `view_schema_version`
- `served_at`
- `product`
- `authored_contract`
- `status`
- `assets`
- `schema`
- `semantics`
- `freshness`
- `tests`
- `lineage`
- `governance`
- `agent_permissions`
- `observability`
- `compatibility`
- `links`

## Runtime-Only Fields

These fields are runtime facts and should not be authored directly in Git:

- `served_at`
- `status.current`
- `freshness.current`
- `tests.current`
- `lineage.effective`
- `governance.effective`
- `agent_permissions.effective`
- `observability.run_history`
- `observability.incidents`
- `observability.metrics`
- `authored_contract.provenance`

## Product Status

The runtime view has one top-level product status:

- `healthy`
- `degraded`
- `blocked`
- `deprecated`
- `retired`
- `unknown`

Status is computed from contract tests, freshness state, governance validity, compatibility state, and platform health signals.

Agents must respect status. For example, an agent should not use a degraded service product for authoritative reporting unless the user explicitly accepts that risk.

## Current Test State

Runtime test state is summarized by severity:

- `blocking`
- `degrading`
- `informational`
- `experimental`

Each test result includes the latest observed result, severity, last run time, and an optional link to full history.

## Effective Governance

The runtime view exposes effective governance, not only declared governance intent.

Effective governance includes:

- Classifications
- Inherited classifications
- Access decision summary
- Masking summary
- Retention policy summary
- Audit requirements
- Policy references
- Links to detailed policy evaluation results

The v0 starter classification mapping is defined in `docs/design/v0-governance-classifications.md`.

## Effective Agent Permissions

The runtime view exposes effective agent permissions after resolving authored intent, governance policy, domain ownership, product status, and runtime constraints.

Agent permissions include:

- Default decision
- Grants
- Denials
- Maximum risk tier
- Allowed actions
- Approval-required actions
- Constraints
- Links to policy reasoning

## Provenance

Every runtime-served view must point back to Git:

- Repository
- Path
- Commit SHA
- Authored contract version
- Authored schema version
- Promotion time
- Promoter
- Validation result

## Example

```json
{
  "view_schema_version": "0.1.0",
  "served_at": "2026-05-25T04:00:00Z",
  "product": {
    "id": "revenue.monthly_recurring_revenue",
    "name": "Monthly Recurring Revenue",
    "version": "0.1.0",
    "layer": "curated",
    "owner": {
      "type": "team",
      "name": "revenue-analytics"
    },
    "domain": {
      "name": "revenue"
    },
    "purpose": "Provides governed monthly recurring revenue measures."
  },
  "authored_contract": {
    "schema_version": "0.1.0",
    "provenance": {
      "repository": "git@github.com:example/lakehouse-contracts.git",
      "path": "contracts/revenue/monthly_recurring_revenue/contract.yaml",
      "commit_sha": "0123456789abcdef0123456789abcdef01234567",
      "promoted_at": "2026-05-25T03:55:00Z",
      "promoter": "contract-engine",
      "validation": {
        "status": "passed"
      }
    }
  },
  "status": {
    "current": "healthy",
    "reason": "All blocking tests passed and freshness is within expectation."
  },
  "assets": [
    {
      "id": "mrr_by_account_month",
      "kind": "table",
      "ref": "analytics.revenue.mrr_by_account_month",
      "status": "available"
    }
  ],
  "schema": {
    "kind": "relational",
    "observed_at": "2026-05-25T03:45:00Z",
    "columns": [
      {
        "name": "account_id",
        "type": "string",
        "nullable": false
      },
      {
        "name": "month",
        "type": "date",
        "nullable": false
      },
      {
        "name": "mrr_usd",
        "type": "decimal(18,2)",
        "nullable": false
      }
    ]
  },
  "semantics": {
    "metrics": [
      {
        "name": "mrr",
        "expression": "sum(mrr_usd)",
        "description": "Monthly recurring revenue in USD."
      }
    ]
  },
  "freshness": {
    "expectation": {
      "max_age": "PT24H"
    },
    "current": {
      "status": "fresh",
      "observed_at": "2026-05-25T03:45:00Z",
      "age": "PT15M"
    }
  },
  "tests": {
    "summary": {
      "status": "passed",
      "blocking": { "passed": 1, "failed": 0 },
      "degrading": { "passed": 0, "failed": 0 },
      "informational": { "passed": 0, "failed": 0 },
      "experimental": { "passed": 0, "failed": 0 }
    },
    "current": [
      {
        "id": "mrr_non_negative",
        "severity": "blocking",
        "status": "passed",
        "last_run_at": "2026-05-25T03:45:00Z"
      }
    ]
  },
  "lineage": {
    "effective": {
      "upstreams": [
        {
          "kind": "data_product",
          "ref": "billing.invoices",
          "status": "available"
        }
      ],
      "downstreams": []
    }
  },
  "governance": {
    "effective": {
      "classifications": ["internal"],
      "access": {
        "default": "restricted",
        "allowed_roles": ["finance_analyst", "revenue_agent"]
      },
      "audit": {
        "required": true,
        "events": ["query", "export"]
      }
    }
  },
  "agent_permissions": {
    "effective": {
      "default": "deny",
      "grants": [
        {
          "principal": "revenue-analysis-agent",
          "max_risk_tier": "controlled_operational",
          "allowed_actions": ["discover", "query", "explain", "create_ticket"]
        }
      ]
    }
  },
  "observability": {
    "docs": {
      "url": "https://example.local/docs/products/revenue.monthly_recurring_revenue"
    },
    "run_history": {
      "latest_run": {
        "id": "run-123",
        "status": "succeeded",
        "started_at": "2026-05-25T03:40:00Z",
        "ended_at": "2026-05-25T03:45:00Z"
      }
    }
  },
  "compatibility": {
    "change_policy": "semver",
    "deprecation_window": "P90D"
  },
  "links": {
    "self": "/api/v0/products/revenue.monthly_recurring_revenue/contract-view",
    "authored_contract": "https://github.com/example/lakehouse-contracts/blob/0123456789abcdef0123456789abcdef01234567/contracts/revenue/monthly_recurring_revenue/contract.yaml",
    "lineage": "/api/v0/products/revenue.monthly_recurring_revenue/lineage",
    "runs": "/api/v0/products/revenue.monthly_recurring_revenue/runs",
    "policies": "/api/v0/products/revenue.monthly_recurring_revenue/policies",
    "tests": "/api/v0/products/revenue.monthly_recurring_revenue/tests"
  }
}
```