Module adcp.reporting.inline_storage

Borrowed-pool PostgreSQL storage for inline objects and committed replay seals.

Create either store with an open psycopg_pool.AsyncConnectionPool and call create_schema() before use; both stores share the same additive migration. check_ready() audits required catalog objects without changing the schema. Operations also audit it within their short transaction. Pools, credentials, timeouts, database durability, backups and retention remain adopter-owned. Install adcp[pg] to construct a store. Importing this module needs no driver. Catalog fingerprints are qualified on PostgreSQL 16. Other server majors are unqualified; catalog formatting differences may require separate qualification.

An authenticated caller supplies account_id. A reference is not a credential; source_scope does not add authorization. Staging deduplicates exact bytes within an account, independently of execution key or ordinal. Objects are capped at 16 MiB (a constructor may lower that cap), manifests at the source contract's 1 MiB cap. No garbage collector or destructive retention operation is supplied. Payload hashing yields between chunks of at most 1 MiB; it starts no threads.

Staging and seal insertion are separate commits. A committed seal enables exact replay after process restart, but a crash before the seal commits can refetch, even if an object already committed. These stores do not reserve requests before dispatch, recover a lost provider answer, bind unseen request/routing facts, own source leases, or compose a production service. The producer's conformance check still validates a replay against its complete frozen request. Seal validation does not establish that referenced objects exist or share this storage backend. A seal write has no lease token and does not fence a stale source owner.

Private connection participants accept detached backend preparations and return tentative references or a neutral SealedSlice. Their caller owns the same-task READ COMMITTED transaction, table locks and schema audit, account-lock ordering, cancellation/error boundary, commit/rollback and connection return. They acquire no connection, start no task/transaction, and provide no grant or commit proof.

Cancellation settles the borrowed connection before propagating a fresh, redacted CancelledError. Cancellation or a resource error may follow a committed write; resume with the same account/key or content identity to discover its outcome. An active AnyIO cancellation scope retains only a fixed framework marker so its timeout/containment semantics survive; caller text and exception chains do not. The read cancellation event is checked before and after the transaction; cancel the task to interrupt a pending database operation. An object above a store's lower configured read cap fails closed with INTEGRITY_FAILED.

Classes

class InlineStorageError (code: _Code)
Expand source code
class InlineStorageError(RuntimeError):
    """Closed diagnostic; resource failures can have an unknown commit outcome."""

    def __init__(self, code: _Code) -> None:
        self.code = code
        super().__init__(_MESSAGES[code])

Closed diagnostic; resource failures can have an unknown commit outcome.

Ancestors

  • builtins.RuntimeError
  • builtins.Exception
  • builtins.BaseException