Storage¶

zeroth.platform.storage ¶

Storage primitives shared by Zeroth subsystems.

This package provides the database and caching backends that other parts of Zeroth use: SQLite for local persistence, Redis connection configuration, and JSON helpers for serialization.

Postgres support (AsyncPostgresDatabase) is gated behind the [memory-pg] extra and imported lazily so that a base pip install zeroth-core does not require psycopg / psycopg-pool at import time.

The governed-runtime store factory that used to live beside RedisConfig is domain-aware wiring and moved to :mod:zeroth.integrations.persistence.governed_redis; the legacy zeroth.platform.storage paths keep republishing it.

ASYNC_NON_PERSISTENCE_MODULES `module-attribute` ¶

ASYNC_NON_PERSISTENCE_MODULES = frozenset(
    {
        "contracts/templates/registry.py",
        "governance/policy/registry.py",
        "integrations/memory/registry.py",
    }
)

Persistence-shaped modules explicitly classified as in-memory metadata helpers.

ASYNC_PERSISTENCE_MODULES `module-attribute` ¶

ASYNC_PERSISTENCE_MODULES = frozenset(
    {
        "contracts/graph/repository.py",
        "contracts/graph/storage.py",
        "contracts/registry/registry.py",
        "governance/approvals/repository.py",
        "governance/attestations/store.py",
        "governance/audit/coordination.py",
        "governance/audit/repository.py",
        "governance/decisions/repository.py",
        "governance/guardrails/policy.py",
        "governance/retention/audit_log_repository.py",
        "governance/retention/claims.py",
        "governance/retention/cleanup_state_repository.py",
        "governance/retention/coordination.py",
        "governance/retention/legal_hold_repository.py",
        "governance/retention/policy_repository.py",
        "governance/retention/workspace_reader.py",
        "integrations/memory/config_repository.py",
        "integrations/persistence/runs/checkpoint_store.py",
        "integrations/persistence/runs/retention_queries.py",
        "integrations/persistence/runs/run_repository.py",
        "integrations/persistence/runs/thread_repository.py",
        "integrations/persistence/runs/token_snapshot_store.py",
        "platform/artifacts/store.py",
        "platform/secrets/vault.py",
        "runtime/agents/thread_store.py",
        "service/certifications/repository.py",
        "service/deployments/repository.py",
        "service/github/repository.py",
        "service/langgraph_gateway/enforcement_store.py",
        "service/repositories/repository.py",
        "service/webhooks/repository.py",
    }
)

Production persistence modules that must use structured storage gateways.

ECON_MIGRATION_SCOPE_DEFINITIONS `module-attribute` ¶

ECON_MIGRATION_SCOPE_DEFINITIONS = (
    ResourceScopeDefinition(
        resource_name="econ.alembic_version",
        table_name="alembic_version_econ",
        scope=GLOBAL,
        operations=frozenset({READ}),
    ),
    ResourceScopeDefinition(
        resource_name="econ.auth_scope_migration_provenance",
        table_name="_zeroth_20260811_04_auth_scope",
        scope=GLOBAL,
        operations=frozenset({READ}),
    ),
)

Unmapped bookkeeping tables in the econ migration head.

SERVICE_PENDING_DIRECT_OWNERSHIP_TABLES `module-attribute` ¶

SERVICE_PENDING_DIRECT_OWNERSHIP_TABLES = frozenset()

Tenant resources awaiting a direct ownership migration.

SERVICE_SCOPE_DEFINITIONS `module-attribute` ¶

SERVICE_SCOPE_DEFINITIONS = tuple(
    (
        ResourceScopeDefinition(
            resource_name=f"service.{table_name}",
            table_name=table_name,
            workspace_scoped=table_name
            in _SERVICE_WORKSPACE_TABLES,
            direct_scope_ready=table_name
            not in SERVICE_PENDING_DIRECT_OWNERSHIP_TABLES,
            operations=get(
                table_name, frozenset(ResourceOperation)
            ),
        )
    )
    for table_name in _SERVICE_TABLES
) + (
    ResourceScopeDefinition(
        resource_name="service.alembic_version",
        table_name="alembic_version",
        scope=GLOBAL,
        operations=frozenset({READ}),
    ),
    ResourceScopeDefinition(
        resource_name="service.schema_versions",
        table_name="schema_versions",
        scope=GLOBAL,
        operations=frozenset({READ}),
    ),
)

Scope definitions for every physical table in the service migration head.

AsyncSQLiteDatabase ¶

AsyncSQLiteDatabase(
    path: str,
    *,
    encryption_key: str | bytes | None = None,
    coordination_timeout_seconds: float = DEFAULT_COORDINATION_TIMEOUT_SECONDS,
)

AsyncDatabase implementation backed by aiosqlite.

Each call to transaction() opens a fresh connection with connection-local PRAGMAs. WAL mode is initialized once per database instance because it is a persistent, database-wide setting; repeating that pragma on every fresh connection creates an avoidable exclusive-lock race during cold parallel execution.

transaction `async` ¶

transaction(
    *, write_lock: bool = False
) -> AsyncIterator[AsyncSQLiteConnection]

Open a connection, yield it inside a transaction, then commit or rollback.

close `async` ¶

close() -> None

No-op -- connections are per-transaction.

AsyncConnection ¶

Bases: Protocol

Abstraction over a database connection within a transaction.

AsyncDatabase ¶

Bases: Protocol

Abstract async database interface for all repositories.

RedisConfig ¶

Bases: BaseModel

All the settings needed to connect to a Redis instance.

Supports local installs, Docker containers, and remote servers. You can set these values directly or load them from environment variables using from_env().

redis_url ¶

redis_url(
    *,
    require_docker_available: bool = False,
    container_inspector: Callable[[str], bool]
    | None = None,
) -> str

Build and return the full Redis connection URL.

If a URL was set directly, it's returned as-is. Otherwise, the URL is built from the host, port, and authentication settings.

masked_redis_url ¶

masked_redis_url() -> str

Return the Redis URL with any password replaced by '***'.

Safe to use in logs and error messages.

docker_container_available ¶

docker_container_available(
    *,
    container_inspector: Callable[[str], bool]
    | None = None,
) -> bool

Check if the Docker Redis container is currently running.

from_env `classmethod` ¶

from_env(prefix: str = 'ZEROTH_REDIS_') -> RedisConfig

Create a RedisConfig by reading environment variables.

Looks for variables like ZEROTH_REDIS_HOST, ZEROTH_REDIS_PORT, etc. You can change the prefix if needed.

RedisDeploymentMode ¶

Bases: StrEnum

How Redis is being run: on the local machine, inside Docker, or on a remote server.

ScopedResourceDriver ¶

Bases: Protocol

A scope-bound production gateway with immutable operation discovery.

GlobalTable ¶

GlobalTable(
    database: AsyncDatabase,
    registry: ResourceScopeRegistry,
    resource_name: str,
)

Bases: _StructuredTable

A structured gateway reserved for explicitly global reference tables.

Bind the repository or gateway to its validated scope.

ScopedJoin `dataclass` ¶

ScopedJoin(
    table: ScopedTable,
    local_column: str,
    foreign_column: str,
)

A tenant-safe inner join to another scoped table.

__post_init__ ¶

__post_init__() -> None

Validate the immutable scope definition after initialization.

ScopedTable ¶

ScopedTable(
    database: AsyncDatabase,
    registry: ResourceScopeRegistry,
    resource_name: str,
    context: ScopeContext
    | NullWorkspaceScopeContext
    | TenantWideScopeContext
    | CrossTenantMaintenanceScopeContext,
    *,
    _privileged_tenant_wide: bool = False,
    _cross_tenant_maintenance: bool = False,
)

Bases: _StructuredTable

A structured tenant-scoped table bound to one trusted scope context.

Bind the repository or gateway to its validated scope.

for_privileged_tenant_wide `classmethod` ¶

for_privileged_tenant_wide(
    database: AsyncDatabase,
    registry: ResourceScopeRegistry,
    resource_name: str,
    context: TenantWideScopeContext,
) -> Self

Construct the explicit privileged tenant-wide gateway.

for_cross_tenant_maintenance `classmethod` ¶

for_cross_tenant_maintenance(
    database: AsyncDatabase,
    registry: ResourceScopeRegistry,
    resource_name: str,
    context: CrossTenantMaintenanceScopeContext,
) -> Self

Create or resolve for cross tenant maintenance for structurally scoped persistence.

CrossTenantMaintenanceScopeContext `dataclass` ¶

CrossTenantMaintenanceScopeContext()

Exact read/enumerate authority for reviewed retention discovery.

for_scheduled_maintenance `classmethod` ¶

for_scheduled_maintenance() -> (
    CrossTenantMaintenanceScopeContext
)

Create or resolve for scheduled maintenance for structurally scoped persistence.

NullWorkspaceScopeContext `dataclass` ¶

NullWorkspaceScopeContext(tenant_id: str)

A tenant identity explicitly bound to resources outside any workspace.

__post_init__ ¶

__post_init__() -> None

Validate the immutable scope definition after initialization.

for_default_compatibility `classmethod` ¶

for_default_compatibility() -> NullWorkspaceScopeContext

Build the reserved default tenant's null-workspace context.

PersistenceSurface `dataclass` ¶

PersistenceSurface(
    resource_name: str,
    repository_type: type[Any],
    operation_methods: Mapping[
        str, frozenset[ResourceOperation]
    ],
    non_persistence_public_methods: frozenset[
        str
    ] = frozenset(),
    probe: PersistenceProbe | None = None,
)

Production repository class bound to one registered resource.

ResourceOperation ¶

Bases: StrEnum

Persistent operations a resource may expose.

ResourceScope ¶

Bases: StrEnum

Ownership boundary applied to a persistent resource.

ResourceScopeDefinition `dataclass` ¶

ResourceScopeDefinition(
    resource_name: str,
    table_name: str,
    operations: frozenset[ResourceOperation],
    scope: ResourceScope = ResourceScope.TENANT_SCOPED,
    workspace_scoped: bool = False,
    direct_scope_ready: bool = True,
)

The stable scope contract for one persistent resource.

__post_init__ ¶

__post_init__() -> None

Validate the immutable scope definition after initialization.

ResourceScopeRegistry ¶

ResourceScopeRegistry(
    definitions: Iterable[ResourceScopeDefinition] = (),
)

Registry of stable logical resources and their physical tables.

Bind the repository or gateway to its validated scope.

definitions `property` ¶

definitions: tuple[ResourceScopeDefinition, ...]

Return an insertion-ordered immutable snapshot of all definitions.

register ¶

register(definition: ResourceScopeDefinition) -> None

Register a definition, rejecting either kind of duplicate identity.

definition_for_resource ¶

definition_for_resource(
    resource_name: str,
) -> ResourceScopeDefinition

Return the definition for a stable logical resource name.

definition_for_table ¶

definition_for_table(
    table_name: str,
) -> ResourceScopeDefinition

Return the definition for a physical table name.

validate_binding ¶

validate_binding(
    resource_name: str,
    context: ScopeBinding,
    *,
    operation: ResourceOperation | None = None,
) -> ResourceScopeDefinition

Validate an ordinary resource operation and return its definition.

validate_privileged_tenant_wide_binding ¶

validate_privileged_tenant_wide_binding(
    resource_name: str,
    context: TenantWideScopeContext,
    *,
    operation: ResourceOperation | None = None,
) -> ResourceScopeDefinition

Explicitly validate privileged tenant-wide access to a tenant resource.

validate_cross_tenant_maintenance_binding ¶

validate_cross_tenant_maintenance_binding(
    resource_name: str,
    context: CrossTenantMaintenanceScopeContext,
    *,
    operation: ResourceOperation,
) -> ResourceScopeDefinition

Validate a maintenance binding against the registered resource scope.

ScopeContext `dataclass` ¶

ScopeContext(tenant_id: str, workspace_id: str)

A tenant and workspace identity for an ordinary scoped operation.

__post_init__ ¶

__post_init__() -> None

Validate the immutable scope definition after initialization.

for_default_compatibility `classmethod` ¶

for_default_compatibility(
    *, workspace_id: str
) -> ScopeContext

Build the reserved default-tenant context for migrations and tests.

TenantWideScopeContext `dataclass` ¶

TenantWideScopeContext(tenant_id: str)

An explicit privileged context spanning all workspaces in one tenant.

__post_init__ ¶

__post_init__() -> None

Validate the immutable scope definition after initialization.

for_default_compatibility `classmethod` ¶

for_default_compatibility() -> TenantWideScopeContext

Build the reserved default-tenant context for migrations and tests.

EncryptedField ¶

EncryptedField(key: str | bytes)

Symmetric field encryption helper for sensitive JSON columns.

Migration `dataclass` ¶

Migration(version: int, name: str, sql: str)

A single database schema change, identified by a version number.

Migrations run in order (version 1, then 2, etc.) and each one contains a SQL script that creates or alters tables.

SQLiteDatabase ¶

SQLiteDatabase(
    path: str | Path,
    *,
    encryption_key: str | bytes | None = None,
)

A lightweight SQLite wrapper that manages connections and schema versions.

Handles opening connections with good defaults, running transactions, and applying migrations so your database schema stays up to date.

connect ¶

connect() -> sqlite3.Connection

Open a new database connection with recommended settings.

Enables foreign keys, WAL journaling mode, and row-factory access so you can use column names to read results.

transaction ¶

transaction() -> Iterator[sqlite3.Connection]

Open a connection, yield it, then commit or rollback automatically.

Use this as a context manager (with-statement). If your code raises an exception, the transaction is rolled back; otherwise it's committed.

fetch_schema_version ¶

fetch_schema_version(scope: str) -> int

Return the current schema version number for a given scope.

Returns 0 if no migrations have been applied yet.

apply_migrations ¶

apply_migrations(
    scope: str, migrations: Sequence[Migration]
) -> list[Migration]

Run any pending migrations for a scope and return the ones that were applied.

Migrations are applied in version order. Already-applied migrations are skipped. Raises ValueError if migrations have duplicate or non-contiguous version numbers.

execute_script ¶

execute_script(sql: str) -> None

Run a raw SQL script inside a transaction.

AsyncPostgresDatabase ¶

AsyncPostgresDatabase(
    pool: AsyncConnectionPool,
    *,
    coordination_timeout_seconds: float = DEFAULT_COORDINATION_TIMEOUT_SECONDS,
)

AsyncDatabase implementation backed by a psycopg AsyncConnectionPool.

Use the create() classmethod to construct an instance with an opened pool.

create `async` `classmethod` ¶

create(
    dsn: str,
    *,
    min_size: int = 2,
    max_size: int = 10,
    coordination_timeout_seconds: float = DEFAULT_COORDINATION_TIMEOUT_SECONDS,
) -> AsyncPostgresDatabase

Create and open a connection pool, returning an AsyncPostgresDatabase.

transaction `async` ¶

transaction(
    *, write_lock: bool = False
) -> AsyncIterator[PostgresConnection]

Acquire a connection from the pool, run inside a transaction.

close `async` ¶

close() -> None

Close the connection pool.

ensure_and_lock_row `async` ¶

ensure_and_lock_row(
    connection: AsyncConnection,
    *,
    backend: Literal["sqlite", "postgres"],
    table: str,
    key_column: str,
    key: str,
) -> dict[str, object] | None

Create one approved coordination row and lock it on PostgreSQL.

Identifiers are selected only after exact allow-list validation; values remain bound parameters on both supported backends.

create_database `async` ¶

create_database(settings: ZerothSettings) -> AsyncDatabase

Create and return the appropriate async database backend.

Reads settings.database.backend to decide: - "postgres" -> AsyncPostgresDatabase with connection pool - anything else -> AsyncSQLiteDatabase (default)

docker_container_running ¶

docker_container_running(
    container_name: str, *, docker_binary: str = "docker"
) -> bool

Check if a Docker container with the given name is currently running.

Calls docker inspect under the hood. Returns False if Docker isn't installed or the container doesn't exist.

discover_persistence_surfaces ¶

discover_persistence_surfaces() -> tuple[
    PersistenceSurface, ...
]

Rebuild surfaces by introspecting decorated production repository classes.

named_isolation_probe ¶

named_isolation_probe(probe_name: str) -> PersistenceProbe

Create a lazy probe reference that avoids repository import cycles.

persistence_operation ¶

persistence_operation(
    *operations: ResourceOperation,
) -> Callable[[_CallableT], _CallableT]

Attach immutable, explicit persistence semantics to a public method.

persistence_resource_operations ¶

persistence_resource_operations(
    resource_name: str, *operations: ResourceOperation
) -> Callable[[_CallableT], _CallableT]

Bind one multi-resource repository method to a resource's operations.

persistence_surface ¶

persistence_surface(
    resource_name: str,
    *,
    probe: PersistenceProbe | None = None,
    non_persistence_public_methods: frozenset[
        str
    ] = frozenset(),
    method_names: frozenset[str] | None = None,
) -> Callable[[type[Any]], type[Any]]

Declare a production repository surface adjacent to its implementation.

persistence_surfaces ¶

persistence_surfaces() -> tuple[PersistenceSurface, ...]

Return registered production repository surfaces in stable order.

register_persistence_surface ¶

register_persistence_surface(
    resource_name: str,
    repository_type: type[Any],
    *,
    operation_methods: Mapping[
        str, frozenset[ResourceOperation]
    ],
    non_persistence_public_methods: frozenset[
        str
    ] = frozenset(),
) -> PersistenceSurface

Register reviewed production method metadata and fail on drift.

validate_persistence_surface ¶

validate_persistence_surface(
    surface: PersistenceSurface,
    definition: ResourceScopeDefinition | None = None,
) -> None

Reject undecorated public methods and empty or unexpected declarations.

getattr ¶

__getattr__(name: str) -> Any

Lazily import Postgres-backed symbols (require [memory-pg] extra).

Storage¶

zeroth.platform.storage ¶

ASYNC_NON_PERSISTENCE_MODULES module-attribute ¶

ASYNC_PERSISTENCE_MODULES module-attribute ¶

ECON_MIGRATION_SCOPE_DEFINITIONS module-attribute ¶

SERVICE_PENDING_DIRECT_OWNERSHIP_TABLES module-attribute ¶

SERVICE_SCOPE_DEFINITIONS module-attribute ¶

AsyncSQLiteDatabase ¶

transaction async ¶

close async ¶

AsyncConnection ¶

AsyncDatabase ¶

RedisConfig ¶

redis_url ¶

masked_redis_url ¶

docker_container_available ¶

from_env classmethod ¶

RedisDeploymentMode ¶

ScopedResourceDriver ¶

GlobalTable ¶

ScopedJoin dataclass ¶

__post_init__ ¶

ScopedTable ¶

for_privileged_tenant_wide classmethod ¶

for_cross_tenant_maintenance classmethod ¶

CrossTenantMaintenanceScopeContext dataclass ¶

for_scheduled_maintenance classmethod ¶

NullWorkspaceScopeContext dataclass ¶

__post_init__ ¶

for_default_compatibility classmethod ¶

PersistenceSurface dataclass ¶

ResourceOperation ¶

ResourceScope ¶

ResourceScopeDefinition dataclass ¶

__post_init__ ¶

ResourceScopeRegistry ¶

definitions property ¶

register ¶

definition_for_resource ¶

definition_for_table ¶

validate_binding ¶

validate_privileged_tenant_wide_binding ¶

validate_cross_tenant_maintenance_binding ¶

ScopeContext dataclass ¶

__post_init__ ¶

for_default_compatibility classmethod ¶

TenantWideScopeContext dataclass ¶

__post_init__ ¶

for_default_compatibility classmethod ¶

EncryptedField ¶

Migration dataclass ¶

SQLiteDatabase ¶

connect ¶

transaction ¶

fetch_schema_version ¶

apply_migrations ¶

execute_script ¶

AsyncPostgresDatabase ¶

create async classmethod ¶

transaction async ¶

close async ¶

ensure_and_lock_row async ¶

create_database async ¶

docker_container_running ¶

discover_persistence_surfaces ¶

named_isolation_probe ¶

persistence_operation ¶

persistence_resource_operations ¶

persistence_surface ¶

persistence_surfaces ¶

register_persistence_surface ¶

validate_persistence_surface ¶

__getattr__ ¶

ASYNC_NON_PERSISTENCE_MODULES `module-attribute` ¶

ASYNC_PERSISTENCE_MODULES `module-attribute` ¶

ECON_MIGRATION_SCOPE_DEFINITIONS `module-attribute` ¶

SERVICE_PENDING_DIRECT_OWNERSHIP_TABLES `module-attribute` ¶

SERVICE_SCOPE_DEFINITIONS `module-attribute` ¶

transaction `async` ¶

close `async` ¶

from_env `classmethod` ¶

ScopedJoin `dataclass` ¶

for_privileged_tenant_wide `classmethod` ¶

for_cross_tenant_maintenance `classmethod` ¶

CrossTenantMaintenanceScopeContext `dataclass` ¶

for_scheduled_maintenance `classmethod` ¶

NullWorkspaceScopeContext `dataclass` ¶

for_default_compatibility `classmethod` ¶

PersistenceSurface `dataclass` ¶

ResourceScopeDefinition `dataclass` ¶

definitions `property` ¶

ScopeContext `dataclass` ¶

for_default_compatibility `classmethod` ¶

TenantWideScopeContext `dataclass` ¶

for_default_compatibility `classmethod` ¶

Migration `dataclass` ¶

create `async` `classmethod` ¶

transaction `async` ¶

close `async` ¶

ensure_and_lock_row `async` ¶

create_database `async` ¶

getattr ¶