kiri-cli 1.0.0b3__py3-none-any.whl

kiri_odcs/kiri_fk.py

@@ -0,0 +1,447 @@
+"""Typed foreign-key / relationship metadata — ADR 0125 §1.
+
+A foreign key is a relationship *between two contracts*, so the
+``kiri.relationships`` namespace lives at contract scope (like
+``kiri.dv``), not on a single property. The model is **technique-
+neutral**: it expresses the declared referential model a curated silver
+layer must satisfy regardless of whether the silver shape is ``flat``,
+``kimball_dimensional`` or ``data_vault``. The FK gate (slice 5.1b+)
+probes those declarations on the reconcile/verify path; this module is
+the contract-model half only.
+
+This namespace is **distinct from ADR 0045 lineage**:
+``kiri.lineage.from_columns`` records where a column's *value* came from
+(derivation); ``kiri.relationships`` records what a column must
+*reference at rest* (constraint). Conflating them would corrupt the
+lineage graph, whose edges are data-flow.
+
+The ``mode="after"`` validators enforce the structural invariants so a
+malformed relationship fails at parse time, not at probe time. Each
+raises a clear :class:`ValueError` naming the offending FK by ``name``.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import StrEnum
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+__all__ = [
+    "FkCardinality",
+    "FkKeying",
+    "FkPromotion",
+    "FkRef",
+    "FkTier",
+    "ForeignKey",
+    "KiriRelationshipsMeta",
+]
+
+_FROZEN = ConfigDict(frozen=True, extra="forbid")
+
+#: A foreign-key ``name`` becomes both an emitted constraint name and a
+#: stable finding id, so it must be identifier-shaped (no whitespace, no
+#: quoting surface). Mirrors :meth:`Invariant._name_is_safe` in
+#: ``kiri_ext`` — same defence-in-depth posture against injection into
+#: SQL comments / report cells / audit rows.
+_FK_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+#: Key columns are kept verbatim (the dialect quoter preserves source
+#: casing / diacritics), so an empty identifier must never slip through to
+#: the DDL / probe surface. Every key-column element is constrained
+#: non-empty rather than only the list being non-empty.
+_NonEmptyStr = Annotated[str, Field(min_length=1)]
+
+
+def _contract_identity(contract: str) -> str:
+    """The bare contract token of an ``FkRef.contract``.
+
+    A lineage URN is ``urn:kirimana:<layer>:<contract>::<column>``; a
+    relationship is between *contracts*, so neither the layer/URN scaffold
+    nor the trailing ``::<column>`` is part of a side's contract identity.
+    This reduces both forms to the same comparable token, so a side written
+    as ``urn:kirimana:silver:dim_customer::customer_sk`` and one written as
+    the bare ``dim_customer`` are recognised as the same contract.
+
+    The token is extracted **only** from a value that is a well-formed
+    lineage URN (matches :data:`_LINEAGE_URN_RE`). ``FkRef.contract`` is
+    already grammar-validated at field time, but this function is also
+    called on raw ``natural_key_columns`` dict keys, which are typed only
+    ``str``. Gating on the full grammar means a malformed ``urn:``-ish key
+    (wrong layer, missing ``::column``, too few/many segments) is **not**
+    token-extracted: it degrades to its verbatim value, so it cannot
+    falsely match a bare-name side and the surrogate validator rejects the
+    unmatched side with a clean ``ValidationError``. A bare name has no
+    ``urn:`` prefix and is returned with only a trailing ``::column``
+    stripped.
+    """
+    # Lazy import: ``_LINEAGE_URN_RE`` lives in ``kiri_ext``, which imports
+    # this module — a module-level import would be circular. This runs only
+    # during validation, after both modules are loaded.
+    from kiri_odcs.kiri_ext import _LINEAGE_URN_RE
+
+    if contract.startswith("urn:") and _LINEAGE_URN_RE.match(contract):
+        # urn:kirimana:<layer>:<contract>::<column> → <contract>
+        return contract.split("::", 1)[0].split(":", 3)[3]
+    return contract.split("::", 1)[0]
+
+
+class FkTier(StrEnum):
+    """Graded enforcement posture for one declared foreign key (ADR 0125 §1).
+
+    - ``enforced`` — platform-enforced where the engine supports it.
+    - ``rely``     — ``NOT ENFORCED RELY`` (T1); orphans **FAIL** the gate.
+    - ``norely``   — ``NOT ENFORCED NORELY``; orphans are INFO (e.g. a
+      nullable self-reference).
+    - ``planned``  — logically valid but has orphans today because the
+      parent is only partially loaded; the gate WARNs and records a
+      promotion trigger. Requires ``promotion``.
+    - ``lookup``   — no physical parent: documented as a column comment
+      only, never constraint-emitting and never probed.
+    - ``pit``      — a temporal multi-column join *contract* (business
+      key + effective timestamp + current flag); never a Delta FK.
+    """
+
+    ENFORCED = "enforced"
+    RELY = "rely"
+    NORELY = "norely"
+    PLANNED = "planned"
+    LOOKUP = "lookup"
+    PIT = "pit"
+
+
+class FkKeying(StrEnum):
+    """Which key the FK is validated on (ADR 0125 §1 / §7b).
+
+    - ``natural``   — validate on the verbatim business-key columns.
+    - ``surrogate`` — the FK is declared on an ``_SK`` column, but a
+      recomputed surrogate only holds if both sides recompute it
+      identically; the gate therefore validates on
+      ``natural_key_columns`` instead. Hence ``surrogate`` requires
+      ``natural_key_columns`` for both sides.
+    """
+
+    NATURAL = "natural"
+    SURROGATE = "surrogate"
+
+
+class FkCardinality(StrEnum):
+    """Declared cardinality of the relationship (ADR 0125 §1)."""
+
+    ONE_ONE = "1:1"
+    ONE_N = "1:N"
+    ZERO_ONE_N = "0..1:N"
+    N_M = "N:M"
+
+
+class FkRef(BaseModel):
+    """One side (parent or child) of a relationship (ADR 0125 §1).
+
+    Fields:
+
+    - ``contract``       — the bare contract name (e.g. ``dim_customer``)
+      or the silver URN form. When a URN is given, it is validated
+      against the lineage URN grammar (:data:`_LINEAGE_URN_RE`).
+    - ``columns``        — the composite key columns on this side.
+      Order-significant (paired position-wise with the other side) and
+      kept **verbatim** so the dialect quoter preserves source casing /
+      diacritics.
+    - ``current_filter`` — optional SCD2 ``_current`` projection that the
+      runner turns into a reconcile ``CurrentFilter`` before probing.
+    """
+
+    model_config = _FROZEN
+
+    contract: str = Field(min_length=1)
+    columns: list[_NonEmptyStr] = Field(min_length=1)
+    current_filter: dict[str, Any] | None = None
+
+    @field_validator("contract")
+    @classmethod
+    def _contract_urn_or_name(cls, value: str) -> str:
+        """Accept a bare contract name or a lineage-grammar URN.
+
+        Per ADR 0125 §1 ``FkRef.contract`` reuses the lineage URN
+        grammar *when given in URN form*. A value that begins with
+        ``urn:`` is therefore validated against :data:`_LINEAGE_URN_RE`;
+        anything else is treated as a bare contract name and accepted
+        as-is (resolution against the project happens in the runner,
+        not at parse time).
+        """
+        # Imported lazily: ``_LINEAGE_URN_RE`` lives in ``kiri_ext``, which
+        # in turn imports ``KiriRelationshipsMeta`` from this module — a
+        # module-level import here would be circular. The validator only
+        # runs after both modules are fully loaded.
+        from kiri_odcs.kiri_ext import _LINEAGE_URN_RE
+
+        if value.startswith("urn:") and not _LINEAGE_URN_RE.match(value):
+            raise ValueError(
+                f"FkRef.contract {value!r} looks like a URN but does not "
+                "match the lineage URN grammar "
+                "``urn:kirimana:<source|bronze|silver|gold>:"
+                "<contract>::<column>``. Give a bare contract name or a "
+                "well-formed URN (ADR 0125 §1)."
+            )
+        return value
+
+
+class FkPromotion(BaseModel):
+    """Promotion record for a ``tier=planned`` foreign key (ADR 0125 §1).
+
+    A ``planned`` FK is logically valid but has orphans today because the
+    parent is only partially loaded. The gate WARNs (rather than
+    silently passing or hard-failing) and surfaces these two fields so
+    Kiri can reason about *why* the FK is not yet strong and *when* it
+    should be re-probed.
+    """
+
+    model_config = _FROZEN
+
+    root_cause: str = Field(min_length=1)
+    promotion_trigger: str = Field(min_length=1)
+
+
+class ForeignKey(BaseModel):
+    """One declared foreign key between two contracts (ADR 0125 §1).
+
+    The structural invariants below fail at parse time so a malformed
+    relationship never reaches probe time. See the per-validator
+    docstrings for the exact rule each enforces.
+    """
+
+    model_config = _FROZEN
+
+    name: str
+    parent: FkRef
+    child: FkRef
+    cardinality: FkCardinality
+    tier: FkTier
+    keying: FkKeying = FkKeying.NATURAL
+    bridge_table: bool = False
+    confidence: float | None = None
+    case_insensitive_match: bool = False
+    natural_key_columns: dict[str, list[_NonEmptyStr]] | None = None
+    alternate_keys: list[list[_NonEmptyStr]] | None = None
+    no_cycle: bool = False
+    promotion: FkPromotion | None = None
+
+    @field_validator("name")
+    @classmethod
+    def _name_is_identifier_shaped(cls, value: str) -> str:
+        """``name`` must be identifier-shaped (stable constraint + finding id).
+
+        The name is emitted verbatim as a SQL constraint name and used
+        as a finding id; restricting it to ``[A-Za-z_][A-Za-z0-9_]*``
+        keeps it quoting-safe and stable across the ``--gate`` surface.
+        """
+        if not _FK_NAME_RE.match(value):
+            raise ValueError(
+                f"ForeignKey.name must match {_FK_NAME_RE.pattern} "
+                f"(identifier-shaped, stable constraint + finding id); "
+                f"got {value!r}."
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _planned_requires_promotion(self) -> ForeignKey:
+        """``tier=planned`` requires a ``promotion`` record (ADR 0125 §1, §3).
+
+        A ``planned`` FK downgrades a FAIL to a WARN; that downgrade is
+        only honest when accompanied by a declared root cause and
+        promotion trigger, so the gate is never a silent green.
+        """
+        if self.tier is FkTier.PLANNED and self.promotion is None:
+            raise ValueError(
+                f"ForeignKey {self.name!r}: tier=planned requires a "
+                "``promotion`` ({root_cause, promotion_trigger}) — the "
+                "explicit, recorded reason orphans are tolerated as WARN. "
+                "See ADR 0125 §1."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _lookup_is_comment_only(self) -> ForeignKey:
+        """``tier=lookup`` is column-comment-only — never constraint-emitting.
+
+        A ``lookup`` reference has no resolvable physical parent (ADR
+        0125 §1 / §3: "no physical parent — column comment emitted"). It
+        is never probed and never emits a constraint. We still require
+        well-formed ``parent`` / ``child`` refs (enforced by the field
+        types), but a lookup FK must not carry the markers that only
+        make sense for an enforceable, probed relationship — declaring a
+        ``promotion`` (a probe-tier concept) or surrogate keying on a
+        lookup is operator confusion, so reject it fail-closed.
+        """
+        if self.tier is FkTier.LOOKUP:
+            if self.promotion is not None:
+                raise ValueError(
+                    f"ForeignKey {self.name!r}: tier=lookup carries no "
+                    "enforceable parent and is never probed, so a "
+                    "``promotion`` record is meaningless — remove it or "
+                    "choose tier=planned. See ADR 0125 §1."
+                )
+            if self.keying is FkKeying.SURROGATE:
+                raise ValueError(
+                    f"ForeignKey {self.name!r}: tier=lookup is "
+                    "column-comment-only and never validated, so "
+                    "keying=surrogate (a probe-time key-parity concern) "
+                    "does not apply. See ADR 0125 §1."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _pit_requires_temporal(self) -> ForeignKey:
+        """``tier=pit`` requires temporal columns OR a ``current_filter``.
+
+        A PIT relationship is a temporal join contract (ADR 0125 §1 /
+        §4): it must carry a temporal predicate so the projected
+        relationship can be evaluated as-of. We accept either an
+        explicit ``current_filter`` on at least one side (the
+        ``_current`` projection path) or composite (multi-column) keys
+        that include the effective-timestamp / current-flag columns —
+        i.e. more than the single business-key column a non-temporal FK
+        would carry.
+        """
+        if self.tier is FkTier.PIT:
+            has_current_filter = (
+                self.parent.current_filter is not None or self.child.current_filter is not None
+            )
+            has_temporal_columns = len(self.parent.columns) > 1 and len(self.child.columns) > 1
+            if not (has_current_filter or has_temporal_columns):
+                raise ValueError(
+                    f"ForeignKey {self.name!r}: tier=pit is a temporal "
+                    "join contract and requires either a ``current_filter`` "
+                    "on at least one side or composite temporal columns "
+                    "(business key + effective timestamp / current flag). "
+                    "See ADR 0125 §1, §4."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _surrogate_requires_natural_keys(self) -> ForeignKey:
+        """``keying=surrogate`` requires ``natural_key_columns`` for both sides.
+
+        A recomputed ``_SK`` only holds if both sides recompute it
+        identically (ADR 0125 §1 / §7b), so the gate validates on the
+        natural business key instead. That requires the natural-key
+        columns for *both* the parent and the child side, keyed by their
+        contract identity. A side may be written as a bare name or a
+        column-qualified lineage URN, and the ``natural_key_columns`` keys
+        likewise — they match when their contract identities agree
+        (:func:`_contract_identity`), so an URN-form side resolves against
+        a name-keyed map and vice versa.
+        """
+        if self.keying is FkKeying.SURROGATE:
+            nkc = self.natural_key_columns
+            if not nkc:
+                raise ValueError(
+                    f"ForeignKey {self.name!r}: keying=surrogate requires "
+                    "``natural_key_columns`` for both sides (keyed by "
+                    "contract name) so the gate validates on the business "
+                    "key rather than a recomputed _SK. See ADR 0125 §1, §7b."
+                )
+            by_identity: dict[str, list[str]] = {}
+            for key, key_cols in nkc.items():
+                by_identity.setdefault(_contract_identity(key), key_cols)
+            resolved: dict[str, list[str]] = {}
+            for side_name, side in (("parent", self.parent), ("child", self.child)):
+                side_cols = nkc.get(side.contract) or by_identity.get(
+                    _contract_identity(side.contract)
+                )
+                if not side_cols:
+                    raise ValueError(
+                        f"ForeignKey {self.name!r}: keying=surrogate "
+                        f"requires natural_key_columns for side "
+                        f"{side.contract!r}; got keys {sorted(nkc)!r}. "
+                        "See ADR 0125 §1, §7b."
+                    )
+                resolved[side_name] = side_cols
+            # The surrogate gate joins the two sides' natural keys position-
+            # wise, so they must have equal arity — otherwise the renderer's
+            # paired zip would raise at probe time (a gate crash) instead of
+            # failing closed at parse time here.
+            if len(resolved["parent"]) != len(resolved["child"]):
+                raise ValueError(
+                    f"ForeignKey {self.name!r}: keying=surrogate natural-key "
+                    f"arity mismatch — parent has {len(resolved['parent'])} "
+                    f"column(s) {resolved['parent']!r} but child has "
+                    f"{len(resolved['child'])} column(s) {resolved['child']!r}. "
+                    "The two natural keys join position-wise. See ADR 0125 §1, §7b."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _composite_arity_matches(self) -> ForeignKey:
+        """Parent and child key arity must match, and so must each alternate key.
+
+        A composite FK joins parent columns to child columns position-
+        wise (ADR 0125 §1), so the two column lists must be the same
+        length. Each declared alternate-key path is an alternative
+        composite join on the same pair of tables, so it must have the
+        same arity as the primary key columns.
+        """
+        if len(self.parent.columns) != len(self.child.columns):
+            raise ValueError(
+                f"ForeignKey {self.name!r}: composite arity mismatch — "
+                f"parent has {len(self.parent.columns)} column(s) "
+                f"{self.parent.columns!r} but child has "
+                f"{len(self.child.columns)} column(s) {self.child.columns!r}. "
+                "Parent and child key columns are paired position-wise. "
+                "See ADR 0125 §1."
+            )
+        if self.alternate_keys is not None:
+            expected = len(self.parent.columns)
+            for idx, alt in enumerate(self.alternate_keys):
+                if len(alt) != expected:
+                    raise ValueError(
+                        f"ForeignKey {self.name!r}: alternate_keys[{idx}] "
+                        f"has arity {len(alt)} ({alt!r}) but the primary "
+                        f"key columns have arity {expected}. Each "
+                        "alternate-key path must match the FK's arity. "
+                        "See ADR 0125 §1."
+                    )
+        return self
+
+    @model_validator(mode="after")
+    def _no_cycle_only_on_self_reference(self) -> ForeignKey:
+        """``no_cycle=true`` is meaningful only on a self-reference (ADR 0125 §1).
+
+        The cycle policy guards a self-referential hierarchy (e.g. a
+        manager chain). Setting it when the parent and child are
+        different contracts is operator confusion — there is no cycle to
+        guard — so reject it fail-closed rather than carry a no-op flag.
+
+        The two sides are compared by *contract identity*
+        (:func:`_contract_identity`), so a self-reference expressed with
+        column-qualified URNs — ``urn:…:dim_employee::employee_id`` (parent)
+        vs ``urn:…:dim_employee::manager_id`` (child) — is correctly
+        recognised as the same contract rather than wrongly rejected on
+        the differing ``::column`` segment.
+        """
+        if self.no_cycle and _contract_identity(self.parent.contract) != _contract_identity(
+            self.child.contract
+        ):
+            raise ValueError(
+                f"ForeignKey {self.name!r}: no_cycle=true is meaningful "
+                "only on a self-reference (parent.contract == "
+                f"child.contract); got parent={self.parent.contract!r} "
+                f"child={self.child.contract!r}. Remove no_cycle or point "
+                "both sides at the same contract. See ADR 0125 §1."
+            )
+        return self
+
+
+class KiriRelationshipsMeta(BaseModel):
+    """Aggregate of declared foreign keys for one contract — ADR 0125 §1.
+
+    Promoted from ``kiri.relationships.*`` customProperties (the
+    ``foreign_keys`` list under ``kiri.relationships.foreign_keys``).
+    The default-empty instance is a no-op marker meaning "this contract
+    declares no relationships" — it must stay cheap to construct so it
+    can serve as the default factory on :class:`KiriMeta`.
+    """
+
+    model_config = _FROZEN
+
+    foreign_keys: list[ForeignKey] = Field(default_factory=list)

kiri_odcs/kiri_pit.py

@@ -0,0 +1,121 @@
+"""Typed PIT (point-in-time) entity metadata — ADR 0056 + ADR 0062 §2.
+
+PIT entities live in the silver ``pit`` zone (see :class:`SilverZone`) and
+materialise query-acceleration snapshots over the raw / business vault.
+``KiriPitMeta`` carries the per-contract shape; the silver graph planner
+reads it to emit ANCHOR_HUB edges and to schedule PIT nodes after
+satellites in the topological order.
+
+The namespace is ``kiri.pit.*`` on the ODCS contract; missing keys mean
+"not declared" — the validator only fires when the contract opts into
+PIT semantics by setting ``anchor_hub`` and/or ``snapshot_keys``.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+_FROZEN = ConfigDict(frozen=True, extra="forbid")
+
+
+class PitRefreshKind(StrEnum):
+    """How a PIT snapshot is refreshed each batch (ADR 0062 §2).
+
+    - ``snapshot``      — the default: rebuild the as-of-window from the
+      anchor hub + driving satellites on every run. Cheap on small
+      windows; honest about the window's freshness.
+    - ``incremental``   — append new as-of rows since the last batch
+      without re-reading historical windows. Requires the upstream
+      satellites to be append-only and idempotent on (parent_hk,
+      load_ts).
+    - ``full_refresh``  — drop and rebuild every row. Expensive; used
+      when the policy or the upstream satellites change shape and a
+      clean restate is cheaper than reasoning about deltas.
+    """
+
+    SNAPSHOT = "snapshot"
+    INCREMENTAL = "incremental"
+    FULL_REFRESH = "full_refresh"
+
+
+class SnapshotGrain(StrEnum):
+    """Calendar grain for PIT snapshot rows (ADR 0062 §2).
+
+    ``custom`` lets the operator declare a non-calendar cadence (e.g.
+    'every Monday at 06:00'); the actual cadence is then encoded in the
+    contract's ``kiri.schedule.cadence`` cron expression and the
+    PIT planner just trusts that the upstream scheduler honours it.
+    """
+
+    DAILY = "daily"
+    HOURLY = "hourly"
+    CUSTOM = "custom"
+
+
+class KiriPitMeta(BaseModel):
+    """PIT (point-in-time) entity metadata — ADR 0056 + ADR 0062 §2.
+
+    Promoted from ``kiri.pit.*`` customProperties on a silver contract
+    whose medallion ``silver_zone`` is ``pit``. The validator enforces
+    the minimum shape: a PIT entity must either anchor on a single hub
+    (``anchor_hub`` set) or grain on a list of snapshot keys
+    (``snapshot_keys`` non-empty); a contract that does neither is
+    structurally a no-op and is rejected at parse time.
+
+    Fields:
+
+    - ``snapshot_keys``  — columns whose distinct values define one PIT
+      row per as-of timestamp. Empty when the entity anchors on a single
+      hub instead. Order is preserved for deterministic hashing.
+    - ``anchor_hub``     — silver URN of the hub this PIT pivots around.
+      Used by the graph planner to emit an ``ANCHOR_HUB`` edge so PIT
+      nodes land after their hub + driving satellites.
+    - ``as_of_column``   — timestamp column on the resulting PIT table
+      identifying each snapshot row. Default ``as_of_date`` matches the
+      DataVault4dbt convention; rename per project taste.
+    - ``refresh``        — see :class:`PitRefreshKind`.
+    - ``snapshot_grain`` — see :class:`SnapshotGrain`. ``None`` means
+      "no calendar grain declared" — the planner falls back to the
+      contract's orchestration schedule.
+    """
+
+    model_config = _FROZEN
+
+    snapshot_keys: list[str] = Field(default_factory=list)
+    anchor_hub: str | None = None
+    as_of_column: str = "as_of_date"
+    refresh: PitRefreshKind = PitRefreshKind.SNAPSHOT
+    snapshot_grain: SnapshotGrain | None = None
+
+    @model_validator(mode="after")
+    def _require_anchor_or_snapshot_keys(self) -> KiriPitMeta:
+        """A PIT entity must declare an anchor hub OR at least one snapshot key.
+
+        Without either, the planner has no way to materialise rows. The
+        check is deferred until model construction so that a freshly
+        instantiated ``KiriPitMeta()`` (used as the default factory on
+        ``KiriMeta``) stays a no-op marker — the validator only complains
+        when an author actually opted into PIT shape but forgot the
+        minimum fields.
+
+        Defaulting both to empty / None keeps ``KiriMeta.pit`` cheap to
+        construct for contracts that don't declare a PIT at all.
+        """
+        # Only enforce when at least one PIT-shaped field has been
+        # explicitly set; the default-empty instance is a sentinel
+        # meaning "no PIT declared on this contract" and must remain
+        # constructable so backwards-compat parsing keeps working.
+        explicit_fields = self.model_fields_set
+        opted_in = bool(explicit_fields & {"snapshot_keys", "anchor_hub"})
+        if not opted_in:
+            return self
+        if self.anchor_hub is None and not self.snapshot_keys:
+            raise ValueError(
+                "kiri.pit requires either anchor_hub (URN of the hub the "
+                "PIT pivots around) or snapshot_keys (non-empty list of "
+                "columns defining one snapshot row). Declare at least "
+                "one — see ADR 0062 §2."
+            )
+        return self

kiri_odcs/kiri_ref.py

@@ -0,0 +1,57 @@
+"""Typed reference entity metadata — ADR 0062 §3.
+
+Reference entities carry small, slowly-changing lookup data (country
+codes, product categories, currency tables) consumed by hubs / sats
+in the silver Data Vault. They sit at the top of the graph plan
+(``DvEdgeKind`` zero) so downstream entities can resolve their FKs.
+
+The namespace is ``kiri.ref.*`` on the ODCS contract; missing keys
+mean "not declared". The validator enforces that ``business_keys`` is
+present whenever ``historised=True``, since SCD2 history requires a
+stable identity column to attach the validity window to.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+_FROZEN = ConfigDict(frozen=True, extra="forbid")
+
+
+class KiriRefMeta(BaseModel):
+    """Reference entity metadata — ADR 0062 §3.
+
+    Fields:
+
+    - ``historised``    — when ``False`` (default) the reference is
+      SCD1 (overwrite on update); when ``True`` the renderer emits an
+      SCD2 table with valid_from / valid_to columns.
+    - ``business_keys`` — columns identifying one reference entity.
+      Required when ``historised=True`` because SCD2 needs a stable
+      identity to attach the validity window to. Optional but
+      recommended for SCD1 references too — missing it forces the
+      renderer to dedup on every column.
+    """
+
+    model_config = _FROZEN
+
+    historised: bool = False
+    business_keys: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _historised_requires_business_keys(self) -> KiriRefMeta:
+        """SCD2 references must declare business_keys.
+
+        Without them, the renderer cannot identify which physical row
+        a new version supersedes. SCD1 references can omit business
+        keys (the renderer will dedup on every column) but the lint
+        layer will warn separately — that's not a structural error.
+        """
+        if self.historised and not self.business_keys:
+            raise ValueError(
+                "kiri.ref with historised=true requires business_keys "
+                "(non-empty list of columns identifying one reference "
+                "entity). SCD2 needs a stable identity to attach the "
+                "valid_from / valid_to window to. See ADR 0062 §3."
+            )
+        return self