vgi-python 0.48.0__py3-none-any.whl → 0.48.1__py3-none-any.whl

vgi/_test_fixtures/catalog.py

@@ -528,7 +528,10 @@ class InMemoryCatalog(CatalogInterface):
     ) -> None:
         """Create a new table."""
         if constraint_definitions:
-            raise NotImplementedError("this metadata-only catalog does not enforce canonical constraints")
+            raise NotImplementedError(
+                "CREATE TABLE with NOT NULL/PRIMARY KEY/UNIQUE/CHECK/FOREIGN KEY constraints is unsupported: "
+                "this metadata-only catalog stores no rows, so it cannot enforce them on writes"
+            )
         if any(value is not None for value in (comment, tags, options, layout)):
             raise NotImplementedError("table creation metadata/options/layout profiles are not supported")
 

vgi/_test_fixtures/worker.py

@@ -329,7 +329,6 @@ from vgi.catalog import (
     AttachOpaqueData,
     Catalog,
     Index,
-    IndexConstraintType,
     Macro,
     MacroType,
     ReadOnlyCatalogInterface,
@@ -346,10 +345,7 @@ from vgi.catalog import (
     View,
 )
 from vgi.catalog.capabilities import (
-    CONSTRAINT_RECORDS_READ,
-    INDEX_DEFINITION_READ,
     ROW_SCALAR_EXPRESSION,
-    CatalogCapabilities,
 )
 from vgi.catalog.catalog_interface import _validate_at_params
 from vgi.catalog.constraints import ConstraintDefinition, ConstraintInfo, ConstraintKind, ForeignKeyDefinition
@@ -357,11 +353,9 @@ from vgi.catalog.dependencies import CatalogObjectRef
 from vgi.catalog.descriptors import ColumnStatisticsInput
 from vgi.catalog.duckdb_statistics import statistics_from_duckdb
 from vgi.catalog.evaluation_context import QueryEvaluationContext
-from vgi.catalog.indexes import IndexDefinition, IndexKey
-from vgi.catalog.options import OptionState
+from vgi.catalog.indexes import index_definition
 from vgi.catalog.sql import SqlExpression as CanonicalSqlExpression
 from vgi.schema_utils import schema
-from vgi.typed_values import TypedValueBatch
 from vgi.worker import Worker
 
 # Shared scratch dir for native-branch fixtures (read_parquet / read_csv arms).
@@ -1598,14 +1592,7 @@ _EXAMPLE_CATALOG = Catalog(
             indexes=[
                 Index(
                     name=name,
-                    definition=IndexDefinition(
-                        table=CatalogObjectRef(kind="table", schema_path=["data"], name="numbers"),
-                        algorithm="fixture.metadata",
-                        keys=[IndexKey(column_path=["value"]).serialize_to_bytes()],
-                        options=TypedValueBatch.empty(),
-                        constraint_type=IndexConstraintType.NONE,
-                    ),
-                    options=OptionState(values=TypedValueBatch.empty()),
+                    definition=index_definition(["data"], "numbers", [["value"]], algorithm="fixture.metadata"),
                     comment="Metadata-only index teaching fixture; no physical index or enforcement",
                 )
                 for name in ("idx_numbers_value", "idx_numbers_value_unique")
@@ -1625,10 +1612,6 @@ class ExampleCatalog(ReadOnlyCatalogInterface):
 
     catalog = _EXAMPLE_CATALOG
 
-    def catalog_capabilities(self, *, attach_opaque_data: AttachOpaqueData) -> CatalogCapabilities:
-        """Expose validated immutable facts; this catalog has no mutation path."""
-        return CatalogCapabilities(read=sorted([CONSTRAINT_RECORDS_READ, ROW_SCALAR_EXPRESSION, INDEX_DEFINITION_READ]))
-
     def table_get(
         self,
         *,

vgi/catalog/__init__.py

@@ -39,6 +39,7 @@ from vgi.catalog.catalog_interface import (
     TableInfo,
     TransactionOpaqueData,
     ViewInfo,
+    catalog_capabilities_for,
     deserialize_column_statistics,
     serialize_column_statistics,
 )
@@ -60,11 +61,16 @@ from vgi.catalog.constraints import (
     ConstraintValidation,
     ForeignKeyDefinition,
     ForeignKeyMatch,
+    ReferencedKey,
     ReferentialAction,
+    constraint_record,
+    served_table_schema,
+    validate_constraint_records,
+    validate_foreign_key_targets,
 )
 from vgi.catalog.dependencies import CatalogObjectRef, DependencySnapshot, ObjectDependency
 from vgi.catalog.descriptors import Catalog, ForeignKeyDef, Index, Macro, Schema, Sql, Table, View
-from vgi.catalog.indexes import IndexDefinition, IndexKey
+from vgi.catalog.indexes import IndexDefinition, IndexKey, index_definition
 from vgi.catalog.macros import MacroOverload, MacroParameter
 from vgi.catalog.metadata_changes import CatalogMetadataChanges
 from vgi.catalog.query import (
@@ -77,8 +83,16 @@ from vgi.catalog.query import (
 )
 from vgi.catalog.secret_type import SecretTypeSpec
 from vgi.catalog.setting import Setting, SettingSpec
-from vgi.catalog.sql import ColumnExpressions, SqlStatement, column_expressions, with_column_expressions
+from vgi.catalog.sql import (
+    ColumnExpressions,
+    SqlStatement,
+    canonical_generated_columns,
+    column_expressions,
+    validate_generated_columns,
+    with_column_expressions,
+)
 from vgi.catalog.storage import CatalogStorage, CatalogStorageSqlite
+from vgi.column_path import RequiredFilterPaths
 from vgi.write_results import WriteOperation, WriteResultMode, write_changes_batch, write_result_schema
 
 __all__ = [
@@ -88,6 +102,12 @@ __all__ = [
     "with_column_metadata",
     "IndexDefinition",
     "IndexKey",
+    "index_definition",
+    "catalog_capabilities_for",
+    "served_table_schema",
+    "validate_foreign_key_targets",
+    "canonical_generated_columns",
+    "validate_generated_columns",
     "ConstraintChange",
     "ConstraintDefinition",
     "ConstraintEnforcement",
@@ -99,7 +119,11 @@ __all__ = [
     "ConstraintValidation",
     "ForeignKeyDefinition",
     "ForeignKeyMatch",
+    "ReferencedKey",
     "ReferentialAction",
+    "constraint_record",
+    "validate_constraint_records",
+    "RequiredFilterPaths",
     "ColumnExpressions",
     "SqlStatement",
     "column_expressions",

vgi/catalog/_dispatch.py

@@ -0,0 +1,179 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Call catalog overrides written against the pre-v3 ``CatalogInterface`` signatures.
+
+vgi.v3 added keyword arguments to several ``CatalogInterface`` methods
+(``catalog_attach(client_capabilities=)``, ``schema_create(options=)``,
+``view_create(aliases=, security=, ...)``, ...) and renamed ``column_name`` to
+``column_path``. The worker always passes them, so an override with explicit
+parameters and no ``**kwargs`` would raise TypeError on every call.
+
+[`call_catalog`][] inspects the override's signature and passes only what it
+accepts. A new argument is dropped only when its value carries no meaning the
+old override could have honoured (``None``, empty, a top-level path); then a
+DeprecationWarning (and one log line) asks for the new signature. A meaningful
+value (a barrier view, a nested column path, schema options) is never silently
+dropped: the call fails with an error naming the parameter.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import threading
+import warnings
+from collections.abc import Callable, Mapping
+from typing import Any
+
+_logger = logging.getLogger("vgi.catalog")
+
+
+def _always(value: object) -> bool:
+    del value
+    return True
+
+
+def _empty(value: object) -> bool:
+    return value is None or (isinstance(value, (list, tuple, dict, set)) and not value)
+
+
+def _top_level(value: object) -> bool:
+    return isinstance(value, list) and len(value) == 1
+
+
+#: method -> added keyword -> predicate: may this value be dropped for an old override?
+_ADDED: dict[str, dict[str, Callable[[Any], bool]]] = {
+    # The worker selects profiles against the client's offer after attach, so
+    # an override that ignores the offer loses nothing.
+    "catalog_attach": {"client_capabilities": _always},
+    "schema_create": {"options": _empty},
+    "view_create": {
+        "aliases": _empty,
+        "security": lambda value: value == "regular",
+        "comment": _empty,
+        "tags": _empty,
+        "column_comments": _empty,
+    },
+    "table_create": {
+        "constraint_definitions": _empty,
+        "comment": _empty,
+        "tags": _empty,
+        "options": _empty,
+        "layout": _empty,
+    },
+    "table_column_add": {"column_path": _top_level},
+    "table_column_type_change": {"column_path": _top_level},
+}
+
+#: Methods whose ``column_name`` became ``column_path``.
+_RENAMED_COLUMN = frozenset(
+    {
+        "table_column_comment_set",
+        "table_column_drop",
+        "table_column_rename",
+        "table_column_default_set",
+        "table_column_default_drop",
+        "table_not_null_drop",
+        "table_not_null_set",
+    }
+)
+
+#: Removed parameters an old override may still require; passed empty when the
+#: replacement is empty.
+_REMOVED_EMPTY: dict[str, dict[str, Callable[[], Any]]] = {
+    "table_create": {
+        name: list
+        for name in (
+            "not_null_constraints",
+            "unique_constraints",
+            "check_constraints",
+            "primary_key_constraints",
+            "foreign_key_constraints",
+        )
+    },
+}
+
+_signatures: dict[tuple[type, str], frozenset[str] | None] = {}
+_warned: set[tuple[type, str, str]] = set()
+_lock = threading.Lock()
+
+
+def _accepted(catalog: object, name: str) -> frozenset[str] | None:
+    """Keyword names the override accepts, or ``None`` when it takes ``**kwargs``."""
+    key = (type(catalog), name)
+    with _lock:
+        if key in _signatures:
+            return _signatures[key]
+    try:
+        parameters = inspect.signature(getattr(catalog, name)).parameters.values()
+    except (TypeError, ValueError):
+        result = None
+    else:
+        result = (
+            None
+            if any(p.kind == inspect.Parameter.VAR_KEYWORD for p in parameters)
+            else frozenset(p.name for p in parameters if p.kind != inspect.Parameter.VAR_POSITIONAL)
+        )
+    with _lock:
+        _signatures[key] = result
+    return result
+
+
+def _deprecated(catalog: object, name: str, message: str) -> None:
+    owner = type(catalog)
+    text = f"{owner.__qualname__}.{name}(): {message}; update the override to the vgi.v3 CatalogInterface signature"
+    warnings.warn(text, DeprecationWarning, stacklevel=3)
+    key = (owner, name, message)
+    with _lock:
+        first = key not in _warned
+        _warned.add(key)
+    if first:
+        _logger.warning(text)
+
+
+def call_catalog(catalog: object, name: str, /, **kwargs: Any) -> Any:
+    """Call ``catalog.<name>(**kwargs)``, tolerating a pre-v3 override signature.
+
+    Args:
+        catalog: The catalog interface instance.
+        name: The ``CatalogInterface`` method name.
+        **kwargs: The vgi.v3 keyword arguments.
+
+    Returns:
+        Whatever the catalog method returns.
+
+    Raises:
+        NotImplementedError: A new argument carries a value the override
+            cannot receive (it would otherwise be silently ignored).
+    """
+    method = getattr(catalog, name)
+    accepted = _accepted(catalog, name)
+    if accepted is None:
+        return method(**kwargs)
+    call: dict[str, Any] = {}
+    added: Mapping[str, Callable[[Any], bool]] = _ADDED.get(name, {})
+    for key, value in kwargs.items():
+        if key in accepted:
+            call[key] = value
+        elif key in added:
+            if not added[key](value):
+                raise NotImplementedError(
+                    f"{type(catalog).__qualname__}.{name}() has no {key!r} parameter, so it cannot honour "
+                    f"{key}={value!r}; update the override to the vgi.v3 CatalogInterface signature"
+                )
+            _deprecated(catalog, name, f"does not accept {key}=, which was dropped")
+        elif key == "column_path" and name in _RENAMED_COLUMN and "column_name" in accepted:
+            if not _top_level(value):
+                raise NotImplementedError(
+                    f"{type(catalog).__qualname__}.{name}() takes column_name, so it cannot address nested "
+                    f"column path {value!r}; update the override to take column_path"
+                )
+            call["column_name"] = value[0]
+            _deprecated(catalog, name, "takes column_name; pass column_path instead")
+        else:
+            call[key] = value
+    for legacy, empty in _REMOVED_EMPTY.get(name, {}).items():
+        if legacy in accepted and legacy not in call:
+            call[legacy] = empty()
+            _deprecated(catalog, name, f"still takes the removed {legacy} parameter")
+    return method(**call)

vgi/catalog/_expression_grammar.py

@@ -0,0 +1,243 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""The DuckDB extension's accepted CHECK and generated-column SQL grammars.
+
+The extension parses canonical SQL with DuckDB's parser and accepts only a
+small deterministic subset (``ParseNumericCheck`` in
+``vgi_constraint_contract.cpp`` and ``Scalar`` in
+``vgi_column_expression.cpp``). This module mirrors both walks over the same
+parser's AST, obtained from ``json_serialize_sql`` on the locally installed
+engine (haybarn or duckdb).
+
+vgi does not hard-depend on an engine. Without one these checks are skipped
+(the extension still rejects at ATTACH); with one, an author's own tests see
+the extension's verdict before deployment.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any
+
+import pyarrow as pa
+
+_NUMERIC_TYPES = frozenset(
+    {
+        "TINYINT",
+        "SMALLINT",
+        "INTEGER",
+        "BIGINT",
+        "HUGEINT",
+        "UTINYINT",
+        "USMALLINT",
+        "UINTEGER",
+        "UBIGINT",
+        "UHUGEINT",
+        "FLOAT",
+        "DOUBLE",
+        "DECIMAL",
+    }
+)
+_PRIMITIVE = frozenset({"NULL", "BOOLEAN", "TINYINT", "SMALLINT", "INTEGER", "BIGINT", "FLOAT", "DOUBLE"})
+_PRIMITIVE |= {"DECIMAL", "VARCHAR"}
+_GENERATED_PRIMITIVE = frozenset({"NULL", "BOOLEAN", "TINYINT", "SMALLINT", "INTEGER", "BIGINT", "VARCHAR"})
+_COMPARISONS = frozenset(
+    {
+        "COMPARE_EQUAL",
+        "COMPARE_NOTEQUAL",
+        "COMPARE_LESSTHAN",
+        "COMPARE_GREATERTHAN",
+        "COMPARE_LESSTHANOREQUALTO",
+        "COMPARE_GREATERTHANOREQUALTO",
+    }
+)
+_OPERATORS = frozenset({"OPERATOR_COALESCE", "OPERATOR_IS_NULL", "OPERATOR_IS_NOT_NULL", "OPERATOR_NOT"})
+_FUNCTIONS = frozenset({"+", "-", "*", "%", "abs", "lower", "upper"})
+_CHECK_COLUMN_TYPES = (
+    pa.types.is_int8,
+    pa.types.is_int16,
+    pa.types.is_int32,
+    pa.types.is_int64,
+    pa.types.is_float32,
+    pa.types.is_float64,
+)
+
+_lock = threading.Lock()
+_connection: Any = None
+_unavailable = False
+
+
+def _parse(sql: str) -> dict[str, Any] | None:
+    """Return ``json_serialize_sql`` output, or ``None`` when no engine is installed."""
+    global _connection, _unavailable
+    with _lock:
+        if _unavailable:
+            return None
+        if _connection is None:
+            try:
+                from vgi._duckdb import connect
+
+                _connection = connect()
+            except ImportError:
+                _unavailable = True
+                return None
+        row = _connection.execute("SELECT json_serialize_sql(?)", [sql]).fetchone()
+    assert row is not None
+    result: dict[str, Any] = json.loads(row[0])
+    return result
+
+
+def _single_expression(sql: str, wrapped: str, error: str) -> dict[str, Any] | None:
+    """Parse ``wrapped`` and return its only select-list expression (extension ``Parse``)."""
+    if not sql or "\0" in sql or len(sql.encode()) > 1024 * 1024:
+        raise ValueError("invalid SQL size or text")
+    parsed = _parse(wrapped)
+    if parsed is None:
+        return None
+    if parsed.get("error"):
+        raise ValueError(f"{error}: {parsed.get('error_message', 'parse error')}")
+    statements = parsed.get("statements", [])
+    if len(statements) != 1 or statements[0]["node"].get("type") != "SELECT_NODE":
+        raise ValueError(f"{error}: expected exactly one scalar expression")
+    node = statements[0]["node"]
+    if (
+        len(node["select_list"]) != 1
+        or (node.get("from_table") or {}).get("type") != "EMPTY"
+        or node.get("modifiers")
+        or (node.get("cte_map") or {}).get("map")
+        or node.get("where_clause") is not None
+        or node.get("group_expressions")
+        or node.get("group_sets")
+        or node.get("having") is not None
+        or node.get("qualify") is not None
+        or node.get("sample") is not None
+    ):
+        raise ValueError(f"{error}: query clauses are unsupported")
+    expression: dict[str, Any] = node["select_list"][0]
+    return expression
+
+
+def _children(expression: dict[str, Any]) -> list[dict[str, Any]]:
+    """Mirror ``ParsedExpressionIterator::EnumerateChildren`` for the accepted classes."""
+    kind = expression["class"]
+    if kind == "CAST":
+        return [expression["child"]]
+    if kind == "COMPARISON":
+        return [expression["left"], expression["right"]]
+    if kind in {"CONJUNCTION", "OPERATOR", "FUNCTION"}:
+        return list(expression.get("children", []))
+    return []
+
+
+def validate_check_sql(sql: str, schema: pa.Schema, row_id_column: int | None = None) -> None:
+    """Accept exactly what ``ParseNumericCheck`` accepts for this table.
+
+    A CHECK must be one comparison between unqualified columns of a signed
+    integer or floating-point type and non-NULL numeric constants.
+
+    Args:
+        sql: The CHECK expression text.
+        schema: The table's Arrow schema.
+        row_id_column: Index of the ``is_row_id`` column, if any.
+
+    Raises:
+        ValueError: The extension would reject this CHECK at ATTACH.
+    """
+    expression = _single_expression(sql, "SELECT " + sql, "CHECK requires exactly one scalar expression")
+    if expression is None:
+        return
+    if expression.get("alias") or expression["class"] != "COMPARISON":
+        raise ValueError("the DuckDB extension reads only Boolean numeric comparisons as CHECK constraints")
+    if expression["type"] not in _COMPARISONS:
+        raise ValueError(f"unsupported CHECK comparison {expression['type']}")
+    for operand in (expression["left"], expression["right"]):
+        if operand.get("alias"):
+            raise ValueError("CHECK expressions cannot have aliases")
+        if operand["class"] == "CONSTANT":
+            value = operand["value"]
+            if value.get("is_null") or value["type"]["id"] not in _NUMERIC_TYPES:
+                raise ValueError("CHECK requires numeric operands")
+            continue
+        if operand["class"] != "COLUMN_REF":
+            raise ValueError("CHECK supports only comparisons between numeric columns and constants")
+        names = operand["column_names"]
+        if len(names) != 1:
+            raise ValueError("CHECK requires unqualified column references")
+        matches = [index for index, field in enumerate(schema) if field.name.lower() == names[0].lower()]
+        if len(matches) > 1:
+            raise ValueError(f"ambiguous CHECK column reference {names[0]!r}")
+        if not matches or matches[0] == row_id_column:
+            raise ValueError(f"CHECK references a missing or synthetic column {names[0]!r}")
+        field = schema.field(matches[0])
+        if b"ARROW:extension:name" in (field.metadata or {}) or isinstance(field.type, pa.BaseExtensionType):
+            raise ValueError(f"CHECK column {field.name!r} has an extension type, which is unsupported")
+        if not any(predicate(field.type) for predicate in _CHECK_COLUMN_TYPES):
+            raise ValueError(
+                f"CHECK column {field.name!r} is {field.type}; CHECK requires int8/16/32/64, float32 or float64"
+            )
+
+
+def validate_generated_sql(sql: str) -> None:
+    """Accept exactly what the extension's generated-column ``Scalar`` walk accepts.
+
+    Args:
+        sql: The generated expression text.
+
+    Raises:
+        ValueError: The extension would reject this generated expression.
+    """
+    expression = _single_expression(sql, "SELECT (" + sql + ")", "generated column expression")
+    if expression is None:
+        return
+    nodes = 0
+
+    def visit(node: dict[str, Any], depth: int) -> None:
+        nonlocal nodes
+        nodes += 1
+        if depth > 64 or nodes > 4096:
+            raise ValueError("generated expression is too complex")
+        if node.get("alias"):
+            raise ValueError("generated expression aliases are unsupported")
+        kind, kind_type = node["class"], node["type"]
+        if kind == "CONSTANT":
+            if node["value"]["type"]["id"] not in _GENERATED_PRIMITIVE:
+                raise ValueError(
+                    f"unsupported generated literal type {node['value']['type']['id']}; "
+                    "use Boolean, signed integer, VARCHAR or NULL literals"
+                )
+        elif kind == "COLUMN_REF":
+            if len(node["column_names"]) != 1:
+                raise ValueError("generated expressions require unqualified column references")
+        elif kind == "CAST":
+            if node.get("try_cast") or node["cast_type"]["id"] not in _GENERATED_PRIMITIVE:
+                raise ValueError("generated expressions support only CAST to Boolean, signed integer or VARCHAR")
+        elif kind == "COMPARISON":
+            if kind_type not in _COMPARISONS:
+                raise ValueError(f"unsupported comparison {kind_type}")
+        elif kind == "CONJUNCTION":
+            if kind_type not in {"CONJUNCTION_AND", "CONJUNCTION_OR"}:
+                raise ValueError(f"unsupported conjunction {kind_type}")
+        elif kind == "OPERATOR":
+            if kind_type not in _OPERATORS:
+                raise ValueError(f"unsupported operator {kind_type}")
+        elif kind == "FUNCTION":
+            name = node["function_name"]
+            if (
+                node.get("schema")
+                or node.get("catalog")
+                or node.get("distinct")
+                or node.get("filter") is not None
+                or node.get("export_state")
+                or (node.get("order_bys") or {}).get("orders")
+                or not (name.lower() in _FUNCTIONS or name == "||")
+            ):
+                raise ValueError(
+                    f"unsupported function {name!r}; generated expressions allow + - * % || abs lower upper"
+                )
+        else:
+            raise ValueError("expression is outside the supported deterministic generated-column grammar")
+        for child in _children(node):
+            visit(child, depth + 1)
+
+    visit(expression, 0)

vgi/catalog/_legacy.py

@@ -0,0 +1,46 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Clear errors for constructor arguments removed by the vgi.v3 protocol.
+
+A removed dataclass field otherwise fails with Python's generic "unexpected
+keyword argument". These shims keep the generated ``__init__`` (and its
+signature, via ``functools.wraps``) and only replace that error with one
+naming the replacement.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar
+
+T = TypeVar("T", bound=type)
+
+
+def reject_removed_arguments(removed: Mapping[str, str], *, positional: str | None = None) -> Callable[[T], T]:
+    """Wrap a dataclass ``__init__`` so removed arguments raise a guiding TypeError.
+
+    Args:
+        removed: Removed keyword name to the message naming its replacement.
+        positional: When set, any positional argument raises this message
+            (for keyword-only records that used to accept positional values).
+
+    Returns:
+        A class decorator.
+    """
+
+    def decorate(cls: T) -> T:
+        generated: Callable[..., None] = cls.__init__  # type: ignore[misc]
+
+        @functools.wraps(generated)
+        def __init__(self: Any, *args: Any, **kwargs: Any) -> None:
+            if args and positional is not None:
+                raise TypeError(f"{cls.__name__}: {positional}")
+            for name in kwargs.keys() & removed.keys():
+                raise TypeError(f"{cls.__name__}({name}=...) was removed in vgi.v3: {removed[name]}")
+            generated(self, *args, **kwargs)
+
+        cls.__init__ = __init__  # type: ignore[misc]
+        return cls
+
+    return decorate

vgi/catalog/capabilities.py

@@ -172,6 +172,22 @@ class CatalogCapabilities(ArrowSerializableDataclass):
             selected = {category: names - removed for category, names in selected.items()}
         return CatalogCapabilities(**{category: sorted(names) for category, names in selected.items()})
 
+    def union(self, *others: CatalogCapabilities) -> CatalogCapabilities:
+        """Combine advertisements, e.g. a subclass extending its base's profiles.
+
+        Args:
+            *others: Advertisements to merge into this one.
+
+        Returns:
+            The canonical (sorted, de-duplicated) union.
+        """
+        return CatalogCapabilities(
+            **{
+                category: sorted(set(getattr(self, category)).union(*(getattr(o, category) for o in others)))
+                for category in self._known
+            }
+        )
+
     def validate_selected(self) -> None:
         """Reject malformed, unknown or incomplete attachment agreements."""
         if self.select(self) != self: