httk.store.backend.sql.provenance_edges

Store-scoped SQL scanning of StrongLink edges.

Run provenance edges (inputs/artifacts/outputs on Run) are child fields whose element class is an edge record carrying the string fields label, entry_type, and entry_id. Both the database-backed StoreEntryProvider and the durable StoredEntryFederation serve these edges as OPTIMADE relationships in both directions. This module holds the shared discovery and SQL scanning so both serve them identically, and so the declaring family is always discovered from the store’s registered families (never a hardcoded record class).

The forward view projects one run’s own edges. The reverse view is derived, never stored: it filters alt_kind IS NULL (run alternatives are separate lineages that must not emit reverse identifiers) and reduces each run lineage to its latest main row, so a target entry names only the runs whose latest main revision still references it.

Classes

StrongLinkFamily

One store-registered family whose backing declares StrongLink edge fields.

Functions

strong_link_families(store)

Return the store's registered families whose backings declare StrongLink fields.

wire_type_for_internal(store, internal_type)

Return the served (wire) entry-type name for an edge's internal target type.

forward_run_edges(connection, store, family, run_sids)

Return each run's own edges keyed by run sid, in field then row order.

latest_main_run_sids(connection, run_table)

Return each run lineage's latest main row sid (alt_kind IS NULL).

latest_main_condition(run_table, run_alias)

Return the correlated predicate selecting a run lineage's latest main row.

reverse_run_edges(connection, store, family, ...)

Return the reverse edges pointing at each target id, keyed by target id.

Module Contents

class httk.store.backend.sql.provenance_edges.StrongLinkFamily

One store-registered family whose backing declares StrongLink edge fields.

Parameters:

  • internal_type – The family’s internal (unprefixed) entry-type name.

  • wire_type – The family’s served (wire) entry-type name.

  • definition_id – The family’s entry-type definition IRI, whose prefix names the wire relationship keys.

  • backing – The concrete backing record class carrying the edge fields.

  • schema – The backing’s resolved storage schema.

  • markers – The backing’s StrongLink markers keyed by field name.

internal_type: str
wire_type: str
definition_id: str | None
backing: type
schema: httk.store.backend.schema.TableSchema
markers: collections.abc.Mapping[str, httk.core.storage.StrongLink]

Return the store’s registered families whose backings declare StrongLink fields.

Parameters:

store (httk.store.backend.sql.store.SqlStore) – The SQL store whose configured families are inspected.

Returns:

One StrongLinkFamily per StrongLink-declaring backing.

Return type:

list[StrongLinkFamily]

httk.store.backend.sql.provenance_edges.wire_type_for_internal(store, internal_type)

Return the served (wire) entry-type name for an edge’s internal target type.

Resolves via the target family’s served definition — the same EntryTypeDefinition.served_form() source used elsewhere — so a target such as records serves as _httk_records while a standard name (or any unregistered target) passes through unchanged.

Parameters:
Returns:

The served (wire) entry-type name, or internal_type unchanged.

Return type:

str

httk.store.backend.sql.provenance_edges.forward_run_edges(connection, store, family, run_sids)

Return each run’s own edges keyed by run sid, in field then row order.

Parameters:
Returns:

run sid -> [((internal_target_type, target_id, label), marker)].

Return type:

dict[int, list[tuple[tuple[str, str, str], httk.core.storage.StrongLink]]]

httk.store.backend.sql.provenance_edges.latest_main_run_sids(connection, run_table)

Return each run lineage’s latest main row sid (alt_kind IS NULL).

Parameters:

  • connection (Any) – An open read connection.

  • run_table (sqlalchemy.Table) – The run family’s parent table.

Returns:

logical_id -> latest main sid.

Return type:

dict[int, int]

httk.store.backend.sql.provenance_edges.latest_main_condition(run_table, run_alias)

Return the correlated predicate selecting a run lineage’s latest main row.

The SQL-predicate counterpart of latest_main_run_sids() for use inside a correlated EXISTS (e.g. reverse-relationship filtering): run_alias is a main row (alt_kind IS NULL) and no newer main row of the same lineage exists. The same constraint the reverse serving path applies through a Python-side max-sid-per-lineage scan.

Parameters:

  • run_table (sqlalchemy.Table) – The run family’s parent table (used to alias the newer-row probe).

  • run_alias (sqlalchemy.FromClause) – The run parent alias being constrained inside the outer query.

Returns:

The alt_kind IS NULL and latest-of-lineage boolean predicate.

Return type:

sqlalchemy.ColumnElement[bool]

httk.store.backend.sql.provenance_edges.reverse_run_edges(connection, store, family, target_type, target_ids)

Return the reverse edges pointing at each target id, keyed by target id.

Only a run lineage’s latest main row contributes (alt_kind IS NULL, latest sid per lineage); an edge deduped across lineages still yields one reverse identifier per referencing lineage. Because the join back through the child tables has no index, this is a per-page scan of the run edges.

Parameters:
Returns:

target id -> [(run raw id, edge label, marker)], ordered per target by (run raw id, field/marker order, edge row order).

Return type:

dict[str, list[tuple[str, str, httk.core.storage.StrongLink]]]