# Data-mesh governance

> Canonical HTML: https://montygovernance.com/docs/governance

### Overview

Governance lets a superowner delegate administrative capabilities without giving every team full control of the database. Policies bind an owner to a store and can optionally narrow authority by keyspace, storage type, or semantic model. This supports shared and multi-tenant deployments where domain teams operate their own data products while a platform team retains central control.

Governance policies control administrative operations. They complement, rather than replace, the `READ`, `WRITE`, and `ALL` data-access permissions described under Credentials. Holding a governance capability never implies data access. Policy mutations require superowner credentials, and authorization is deny-by-default: an owner can perform only what an explicit grant or its own creator rights allow.

For the architectural view of how this maps onto domain-owned data products, see [Data Mesh](/data-mesh).

### Capabilities

- `provision-keyspace` — Create keyspaces in a store. This is store-scoped.
- `remove-keyspace` — Remove keyspaces within the delegated scope.
- `manage-snapshots` — Manage snapshots. Snapshots are always in-memory.
- `manage-semantic` — Enable, disable, or configure semantic search.
- `manage-schema` — Create, change, preview, or remove schemas.
- `manage-access` — Reserved for delegating data-access permissions. The capability is part of the policy model and can be granted, but it has no runtime enforcement yet.

### Scopes and qualifiers

Every policy identifies an owner, capability, and store. A keyspace narrows applicable capabilities to one data product. The `provision-keyspace` capability is store-scoped because the target keyspace does not exist yet, so its keyspace argument is ignored.

- `types` is optional for provisioning, removal, schema, access, and semantic management.
- `types` is invalid for `manage-snapshots`; snapshots always apply to in-memory keyspaces.
- `models` is optional and valid only for `provision-keyspace` and `manage-semantic`.
- Omitting an optional qualifier grants or denies the capability across all values represented by that qualifier.

### Grants, revocations, and explicit denials

Use `policyGrant` to delegate authority and `policyRevoke` to remove a grant. Use `policyDeny` when an operation must remain prohibited even when a broader grant exists, and `policyRemoveDenial` to remove that explicit denial. Preview grant and revoke operations before changing active policy with `policyPreviewGrant` and `policyPreviewRevoke`.

Not every capability has to be granted. An owner that creates a keyspace automatically receives read and write access to it, snapshot management when the keyspace is in-memory, semantic management limited to the models applicable policy allows, and the right to remove it. An explicit denial suspends any of these creator capabilities for a specific resource, and outranks a broader grant.

```python
from montycat import PolicyCapability, PolicyKeyspaceType, SemanticModel

await connection.policy_grant(
    owner="alice",
    capability=PolicyCapability.PROVISION_KEYSPACE,
    store="catalog",
    types=[PolicyKeyspaceType.IN_MEMORY, PolicyKeyspaceType.PERSISTENT],
    models=[SemanticModel.BGE_SMALL],
)
await connection.policy_grant(
    owner="alice",
    capability=PolicyCapability.MANAGE_SEMANTIC,
    store="catalog",
    keyspace="products",
    types=[PolicyKeyspaceType.IN_MEMORY],
    models=[SemanticModel.BGE_SMALL],
)
await connection.policy_view(owner="alice", store="catalog")
```

```python
from montycat import PolicyCapability, PolicyKeyspaceType

policy = {
    "owner": "alice",
    "capability": PolicyCapability.MANAGE_SCHEMA,
    "store": "catalog",
    "keyspace": "products",
    "types": [PolicyKeyspaceType.PERSISTENT],
}

preview = await connection.policy_preview_revoke(**policy)
await connection.policy_revoke(**policy)
await connection.policy_deny(**policy)
await connection.policy_remove_denial(**policy)
```

### Inspection, explanation, and audit

- `policyView` shows the effective policy, optionally filtered by owner and store.
- `policyExplain` explains whether a specific capability is allowed for an owner and scope.
- `policyHistory` returns policy changes and can be filtered by owner, store, and keyspace.
- `policyExport` exports the active policy as JSON or YAML.

```python
from montycat import PolicyCapability, PolicyKeyspaceType, SemanticModel

effective = await connection.policy_view(owner="alice", store="catalog")
history = await connection.policy_history(
    owner="alice", store="catalog", keyspace="products"
)
decision = await connection.policy_explain(
    capability=PolicyCapability.MANAGE_SEMANTIC,
    store="catalog",
    owner="alice",
    keyspace="products",
    keyspace_type=PolicyKeyspaceType.IN_MEMORY,
    model=SemanticModel.BGE_SMALL,
)
```

### Policy manifests

Policy manifests make governance repeatable and reviewable as infrastructure as code. Use `policyValidate` to check a JSON or YAML document, `policyPlan` to inspect the changes it would make, and `policyApply` to apply it. A safe deployment flow is validate, plan, review, and then apply.

```python
from montycat import PolicyFormat

with open("governance.yaml", encoding="utf-8") as file:
    document = file.read()

validation = await connection.policy_validate(document, format=PolicyFormat.YAML)
plan = await connection.policy_plan(document, format=PolicyFormat.YAML)
# Review the returned plan before applying it.
result = await connection.policy_apply(document, format=PolicyFormat.YAML)
backup = await connection.policy_export(format=PolicyFormat.YAML)
```

### Data-mesh and multi-tenant organization

Treat stores as shared platform boundaries and keyspaces as domain-owned data products. Delegate only the capabilities each domain needs, constrain storage types or semantic models where platform cost and compliance require it, and use explicit denials for protected resources. Review effective policies and history as part of regular access audits.