httk.store.db.layout
====================

.. py:module:: httk.store.db.layout

.. autoapi-nested-parse::

   Versioned physical layout for :class:`httk.store.db.store.SqlStore`.



Attributes
----------

.. autoapisummary::

   httk.store.db.layout.STORAGE_PROTOCOL_VERSION
   httk.store.db.layout.METADATA_TABLE_NAME
   httk.store.db.layout.WRITE_PROFILE_VOCABULARY


Exceptions
----------

.. autoapisummary::

   httk.store.db.layout.StorageLayoutUpgradeRequiredError
   httk.store.db.layout.StoreUnderConstructionError


Classes
-------

.. autoapisummary::

   httk.store.db.layout.EntryFamilyLayout
   httk.store.db.layout.StorageLayout
   httk.store.db.layout.BackendFacts


Functions
---------

.. autoapisummary::

   httk.store.db.layout.declaration_json
   httk.store.db.layout.backend_facts_for_dialect
   httk.store.db.layout.normalize_entry_records
   httk.store.db.layout.expected_metadata
   httk.store.db.layout.metadata_table_for
   httk.store.db.layout.actual_schema_objects
   httk.store.db.layout.actual_table_names
   httk.store.db.layout.read_store_metadata


Module Contents
---------------

.. py:class:: EntryFamilyLayout

   One immutable configured entry family and its concrete records.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: family
      :type:  type


   .. py:attribute:: record_names
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: records
      :type:  tuple[type, Ellipsis]


.. py:class:: StorageLayout

   The immutable normalized entry declaration of an initialized store.


   .. py:attribute:: protocol_version
      :type:  str


   .. py:attribute:: families
      :type:  tuple[EntryFamilyLayout, Ellipsis]


   .. py:property:: entry_records
      :type: collections.abc.Mapping[type, tuple[type, Ellipsis]]


      Configured family classes mapped to their ordered concrete record classes.


   .. py:property:: declaration
      :type: collections.abc.Mapping[str, tuple[str, Ellipsis]]


      Configured stable family names mapped to their ordered stable record names.


.. py:exception:: StorageLayoutUpgradeRequiredError(diff)

   Bases: :py:obj:`RuntimeError`


   A database does not exactly implement the current persisted store layout.

   ``diff`` is immutable and JSON-shaped.  Its top-level keys are stable
   categories (currently ``protocol``, ``declaration`` and ``schema``), so a
   caller can present a precise upgrade diagnostic without parsing
   the human-readable exception message.


   .. py:attribute:: diff
      :type:  collections.abc.Mapping[str, object]


.. py:function:: declaration_json(layout)

   Serialize a normalized declaration in its exact deterministic persisted form.


.. py:data:: STORAGE_PROTOCOL_VERSION
   :type:  Final
   :value: 'v2.4.0'


   The persisted SqlStore layout protocol implemented by this package.

.. py:data:: METADATA_TABLE_NAME
   :type:  Final
   :value: '_httk_store_metadata'


   Reserved key/value table holding the store protocol and entry declaration.

.. py:data:: WRITE_PROFILE_VOCABULARY
   :type:  Final

.. py:exception:: StoreUnderConstructionError

   Bases: :py:obj:`RuntimeError`


   A new open found an interrupted empty-store bulk ingest.

   Crash window for new SQLite/DuckDB opens: before the marker commits the
   old clean state remains accepted; after the marker and through ingest,
   finalize, or before marker clear the store is rejected; after clear it is
   accepted again.  The marker is intentionally not a resume protocol.

   ClickHouse marker residue is fail-closed: the default recovery is to drop
   the database and re-ingest. Clearing the marker is valid only after an
   operator has restored and verified the declared empty-store invariant.


.. py:class:: BackendFacts

   Dialect capabilities used by the SQL storage protocol.


   .. py:attribute:: transactional_ddl
      :type:  bool


   .. py:attribute:: transactional_dml
      :type:  bool


   .. py:attribute:: supports_sequences
      :type:  bool


   .. py:attribute:: atomic_upsert
      :type:  bool


   .. py:attribute:: serial_stage_format
      :type:  Literal['sqlite', 'duckdb-attach', 'parquet']


   .. py:attribute:: parallel_shard_format
      :type:  Literal['sqlite', 'parquet']


   .. py:attribute:: supports_deferred_finalize
      :type:  bool


   .. py:attribute:: supports_degraded
      :type:  bool


   .. py:attribute:: write_profiles
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: metadata_backend
      :type:  Literal['table', 'keepermap']


   .. py:attribute:: supports_incremental_save
      :type:  bool


   .. py:attribute:: system_catalog
      :type:  Literal['sqlite', 'duckdb', 'clickhouse']


   .. py:attribute:: stage_load
      :type:  Literal['attach', 'duckdb-views', 'client-stream']


   .. py:attribute:: finalize_map_maintenance
      :type:  Literal['update', 'swap']


   .. py:attribute:: supports_adhoc_indexes
      :type:  bool


.. py:function:: backend_facts_for_dialect(dialect_name)

   Resolve the hardcoded protocol facts for one supported dialect.


.. py:function:: normalize_entry_records(entry_records)

   Normalize a declaration and apply SQL physical-name validation.


.. py:function:: expected_metadata(layout)

   Return SQLAlchemy metadata for all protocol-owned tables of ``layout``.


.. py:function:: metadata_table_for(metadata)

   Return the reserved protocol key/value table in ``metadata``.


.. py:function:: actual_schema_objects(connection)

   Return application schema-object names mapped to their stable object kinds.

   The DuckDB SQLAlchemy inspector presently routes column inspection through
   a PostgreSQL catalogue relation DuckDB does not expose, so the whole
   layout path intentionally uses the dialect catalogues directly.


.. py:function:: actual_table_names(connection)

   Return application base-table names without SQLAlchemy reflection.


.. py:function:: read_store_metadata(connection)

   Read the marker values, or return ``None`` when no metadata table exists.