User Guide

Data-mesh 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.

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.

Grant policies

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")

Preview, revoke, deny, and remove a denial

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.

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.

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.