feather-cdc-postgres 0.1.0__py3-none-any.whl

feather_cdc_postgres/discovery.py

@@ -0,0 +1,216 @@
+"""Read-only PostgreSQL catalog discovery (#3079 D4/D6/D7).
+
+Constraints:
+  - every relation carries (schema, table) together — two schemas may hold the same table name
+    and the runtime must never collapse them (D2).
+  - nothing here writes, locks, or sets a session GUC; `plan` is provably non-mutating because
+    this module has no DDL/DML in it.
+  - the WAL fuse is READ from the server (`max_slot_wal_keep_size`), never declared (Deviation D-7).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence, Tuple
+
+import psycopg
+
+SYSTEM_SCHEMAS = ("pg_catalog", "information_schema", "pg_toast")
+
+
+@dataclass(frozen=True)
+class SourceColumn:
+    name: str
+    attnum: int
+    type_oid: int
+    typmod: int
+    not_null: bool
+    type_name: str
+    is_array: bool = False
+    elem_oid: int = 0
+
+
+@dataclass(frozen=True)
+class UniqueIndex:
+    name: str
+    columns: Tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class SourceRelation:
+    schema: str
+    table: str
+    oid: int
+    columns: List[SourceColumn] = field(default_factory=list)
+    primary_key: Tuple[str, ...] = ()
+    unique_indexes: Tuple[UniqueIndex, ...] = ()
+    replica_identity: str = "d"  # d default | n nothing | f full | i index
+    row_estimate: float = 0.0
+    kind: str = "r"              # relkind: r plain/leaf table | p partitioned parent
+    parent: Optional[str] = None  # "schema.table" of the partitioned parent, for a leaf
+
+    @property
+    def qualified(self) -> str:
+        return f"{self.schema}.{self.table}"
+
+    def column(self, name: str) -> Optional[SourceColumn]:
+        for c in self.columns:
+            if c.name == name:
+                return c
+        return None
+
+
+_REL_SQL = """
+select c.oid, n.nspname, c.relname, c.relreplident, c.reltuples, c.relkind,
+       pn.nspname || '.' || pc.relname as parent
+from pg_class c
+join pg_namespace n on n.oid = c.relnamespace
+left join pg_inherits i on i.inhrelid = c.oid
+left join pg_class pc on pc.oid = i.inhparent and pc.relkind = 'p'
+left join pg_namespace pn on pn.oid = pc.relnamespace
+where c.relkind in ('r', 'p')
+  and n.nspname not in ('pg_catalog', 'information_schema', 'pg_toast')
+  and n.nspname not like 'pg\\_temp%%' and n.nspname not like 'pg\\_toast%%'
+order by n.nspname, c.relname
+"""
+
+_COL_SQL = """
+select a.attrelid, a.attname, a.attnum, a.atttypid, a.atttypmod, a.attnotnull,
+       t.typname, t.typcategory = 'A' as is_array, t.typelem
+from pg_attribute a
+join pg_class c on c.oid = a.attrelid
+join pg_namespace n on n.oid = c.relnamespace
+join pg_type t on t.oid = a.atttypid
+where a.attnum > 0 and not a.attisdropped
+  and c.relkind in ('r', 'p')
+  and n.nspname not in ('pg_catalog', 'information_schema', 'pg_toast')
+order by a.attrelid, a.attnum
+"""
+
+# Non-partial (indpred is null) and non-expression (indexprs is null): a partial unique index
+# does not guarantee global uniqueness, so it is not a merge key. `k.ord <= i.indnkeyatts` drops
+# INCLUDE columns: they sit in indkey but carry no uniqueness, and merging on one turns every
+# UPDATE of it into a duplicate row.
+_IDX_SQL = """
+select i.indrelid, ic.relname, i.indisprimary, k.ord, a.attname
+from pg_index i
+join pg_class ic on ic.oid = i.indexrelid
+join pg_class c on c.oid = i.indrelid
+join pg_namespace n on n.oid = c.relnamespace
+cross join lateral unnest(i.indkey::smallint[]) with ordinality as k(attnum, ord)
+join pg_attribute a on a.attrelid = i.indrelid and a.attnum = k.attnum
+where i.indisunique and i.indisvalid and i.indislive
+  and i.indpred is null and i.indexprs is null
+  and k.ord <= i.indnkeyatts
+  and c.relkind in ('r', 'p')
+  and n.nspname not in ('pg_catalog', 'information_schema', 'pg_toast')
+order by i.indrelid, ic.relname, k.ord
+"""
+
+
+def discover(dsn: str, *, connect_timeout: int = 10) -> List[SourceRelation]:
+    """Every user table in the source, schema-qualified, with columns, keys and identity."""
+    with psycopg.connect(dsn, connect_timeout=connect_timeout) as conn:
+        conn.read_only = True
+        rels = conn.execute(_REL_SQL).fetchall()
+        cols = conn.execute(_COL_SQL).fetchall()
+        idx = conn.execute(_IDX_SQL).fetchall()
+
+    by_oid: Dict[int, List[SourceColumn]] = {}
+    for attrelid, name, attnum, type_oid, typmod, not_null, type_name, is_array, elem in cols:
+        by_oid.setdefault(attrelid, []).append(
+            SourceColumn(
+                name=name,
+                attnum=attnum,
+                type_oid=type_oid,
+                typmod=typmod,
+                not_null=bool(not_null),
+                type_name=type_name,
+                is_array=bool(is_array),
+                elem_oid=elem or 0,
+            )
+        )
+
+    pk: Dict[int, List[str]] = {}
+    uniq: Dict[int, Dict[str, List[str]]] = {}
+    for indrelid, indname, is_primary, _ord, attname in idx:
+        if is_primary:
+            pk.setdefault(indrelid, []).append(attname)
+        else:
+            uniq.setdefault(indrelid, {}).setdefault(indname, []).append(attname)
+
+    out: List[SourceRelation] = []
+    for oid, schema, table, relreplident, reltuples, relkind, parent in rels:
+        out.append(
+            SourceRelation(
+                schema=schema,
+                table=table,
+                oid=oid,
+                columns=by_oid.get(oid, []),
+                primary_key=tuple(pk.get(oid, ())),
+                unique_indexes=tuple(
+                    UniqueIndex(name=n, columns=tuple(c)) for n, c in sorted(uniq.get(oid, {}).items())
+                ),
+                replica_identity=relreplident,
+                row_estimate=float(reltuples or 0.0),
+                kind=relkind,
+                parent=parent,
+            )
+        )
+    return sorted(out, key=lambda r: (r.schema, r.table))
+
+
+def publication_relations(dsn: str, publication: str, *, connect_timeout: int = 10) -> Optional[set]:
+    """{(schema, table)} currently published, or None when the publication does not exist yet
+    (a first run — distinct from an existing but empty publication)."""
+    with psycopg.connect(dsn, connect_timeout=connect_timeout) as conn:
+        conn.read_only = True
+        exists = conn.execute("select 1 from pg_publication where pubname = %s", (publication,)).fetchone()
+        if exists is None:
+            return None
+        rows = conn.execute(
+            "select schemaname, tablename from pg_publication_tables where pubname = %s", (publication,)
+        ).fetchall()
+    return {(s, t) for s, t in rows}
+
+
+def slot_state(dsn: str, slot: str, *, connect_timeout: int = 10) -> Dict[str, object]:
+    """Slot telemetry plus the server's own WAL retention fuse.
+
+    `max_slot_wal_keep_size` is read, not declared: a manifest number that disagrees with the
+    server is a false invariant (Deviation D-7). -1 on the server means unlimited → None here.
+    """
+    with psycopg.connect(dsn, connect_timeout=connect_timeout) as conn:
+        conn.read_only = True
+        row = conn.execute(
+            """
+            select active, wal_status, restart_lsn::text, confirmed_flush_lsn::text,
+                   pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)::bigint
+            from pg_replication_slots where slot_name = %s
+            """,
+            (slot,),
+        ).fetchone()
+        keep = conn.execute(
+            "select setting, unit from pg_settings where name = 'max_slot_wal_keep_size'"
+        ).fetchone()
+
+    fuse: Optional[int] = None
+    if keep is not None:
+        setting, unit = int(keep[0]), (keep[1] or "")
+        if setting >= 0:
+            mult = {"B": 1, "kB": 1024, "MB": 1024**2, "GB": 1024**3, "8kB": 8192}.get(unit, 1)
+            fuse = setting * mult
+
+    state: Dict[str, object] = {"slot": slot, "exists": row is not None, "max_slot_wal_keep_size_bytes": fuse}
+    if row is not None:
+        state.update(
+            active=row[0],
+            wal_status=row[1],
+            restart_lsn=row[2],
+            confirmed_flush_lsn=row[3],
+            lag_bytes=row[4],
+        )
+    return state
+
+
+def relation_map(relations: Sequence[SourceRelation]) -> Dict[str, SourceRelation]:
+    return {r.qualified: r for r in relations}

feather_cdc_postgres/drift.py

@@ -0,0 +1,207 @@
+"""Per-run schema registry + drift policy (#3079 D7, plan Deviation D-3).
+
+Constraints:
+  - a key_change deliberately does NOT refresh the stored signature, so every later run
+    re-detects it and keeps the table out of the publication until `resnapshot` refreshes it;
+  - breaking non-key drift never stops the drain — one ordered slot cannot skip one relation,
+    and dlt's evolution is additive, so continuing is non-destructive;
+  - a `text_fallback` mapping is always an event, never a silent cast.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Sequence
+
+from control_plane import status as cp_status
+
+from . import discovery, publication
+from .lifecycle import (
+    DISCOVERED, DRIFT_REVIEW, RESNAPSHOT_REQUIRED, RETIRED, SNAPSHOTTING, Lifecycle,
+)
+from .schema_registry import (
+    TEXT_FALLBACK, classify_drift, compile_relation, project, project_signature, signature,
+)
+
+KEY_CHANGE = "key_change"
+# Reported and marked, but the table keeps loading (Appendix C: dlt never destroys a column).
+BREAKING_KINDS = frozenset({"drop_column", "rename_column", "type_incompatible"})
+# A column the reviewed signature does not name (#4346): on a table with denied columns it is
+# withheld until an operator decides — it may be the secret renamed.
+NEW_COLUMN_KINDS = frozenset({"add_nullable_column", "add_not_null_column", "rename_column"})
+# States whose next step this tick is a full baseline (runner._adopt_streaming routes a
+# re-selected RETIRED or DISCOVERED relation to SNAPSHOTTING; an unpublished one is added and
+# baselined).
+BASELINE_PENDING = frozenset({SNAPSHOTTING, RETIRED, DISCOVERED})
+
+
+def remedy(manifest_path: str, qualified: str) -> str:
+    return f"python -m feather_cdc_postgres resnapshot {manifest_path} --tables {qualified} --yes"
+
+
+@dataclass
+class DriftOutcome:
+    """`blocked` is out of the publication for this run and every run until a resnapshot."""
+
+    blocked: set = field(default_factory=set)
+    review: set = field(default_factory=set)
+    drifts: dict = field(default_factory=dict)
+
+    def active(self, relations: Sequence) -> list:
+        return [r for r in relations if (r.schema, r.table) not in self.blocked]
+
+
+def _sources(cfg) -> dict:
+    return discovery.relation_map(discovery.discover(cfg.source_dsn))
+
+
+def _compile_all(cfg, relations, *, run, sources) -> tuple[list[dict], dict]:
+    """Registry rows + fresh signature per relation; every text_fallback column is an event."""
+    rows: list[dict] = []
+    sigs: dict = {}
+    for rel in relations:
+        src = sources.get(rel.qualified)
+        if src is None:
+            run.event(entity=rel.qualified, status=cp_status.EV_ERROR, unit="schema_drift",
+                      error_detail="selected relation does not exist at the source")
+            continue
+        key = tuple(rel.key)
+        denied = _denied(cfg, rel, src)
+        src = project(src, denied)   # #4346: a denied column is not part of what lands
+        cols, _problems = compile_relation(src, key)
+        rows += [{"registration": cfg.registration, "schema": rel.schema, "table": rel.table,
+                  "column": c.name, "type_oid": c.type_oid, "typmod": c.typmod,
+                  "not_null": c.not_null, "key_role": c.key_role,
+                  "dest_type": c.compiled.dest_type, "mapping": c.compiled.mapping}
+                 for c in cols]
+        fallback = [c.name for c in cols if c.compiled.mapping == TEXT_FALLBACK]
+        if fallback:
+            run.event(entity=rel.qualified, status=cp_status.EV_OK, unit="schema_registry",
+                      extra={"text_fallback_columns": fallback,
+                             "detail": "no declared OID mapping — landing as text"})
+        sigs[(rel.schema, rel.table)] = signature(src, key)
+    return rows, sigs
+
+
+def _denied(cfg, rel, src=None) -> tuple:
+    """The relation's column deny-list (#4346): the compiled Relation's plus the manifest map
+    the runtime carries (both come from `source.deny.columns`; a relation built outside the
+    compiler carries none of its own) — plus, given the catalogue relation `src`, every column
+    whose attnum is a denied one: a denied column renamed after the run resolved its names
+    must not be recorded as a reviewed, approved column (Codex round 12)."""
+    own = set(getattr(rel, "deny_columns", ()) or ())
+    own |= set((getattr(cfg, "deny_columns", None) or {}).get((rel.schema, rel.table), ()))
+    if src is not None:
+        attnums = set((getattr(cfg, "deny_attnums", None) or {}).get(src.oid, ()))
+        own |= {c.name for c in src.columns if c.attnum in attnums}
+    return tuple(sorted(own))
+
+
+def record_all(cfg, relations, *, run) -> dict:
+    """Registry + signatures with NO diff — what a full (re-)snapshot leaves behind."""
+    cfg.destination.ensure_runtime_tables()
+    rows, sigs = _compile_all(cfg, relations, run=run, sources=_sources(cfg))
+    cfg.destination.write_registry_rows(rows)
+    for (schema, table), sig in sigs.items():
+        cfg.destination.write_signature(cfg.registration, schema, table, sig)
+    return sigs
+
+
+def record_signature(cfg, rel, *, run=None) -> dict | None:
+    """Refresh ONE relation's signature — what `resnapshot` calls to clear a key_change."""
+    src = _sources(cfg).get(rel.qualified)
+    if src is None:
+        return None
+    sig = signature(src, tuple(rel.key), _denied(cfg, rel, src))
+    cfg.destination.write_signature(cfg.registration, rel.schema, rel.table, sig)
+    return sig
+
+
+def scan(cfg, relations, *, run, lc: Lifecycle, owner,
+         manifest_path: str = "<manifest>") -> DriftOutcome:
+    """Compile every desired relation, persist the registry, and act on the diff vs last run."""
+    cfg.destination.ensure_runtime_tables()
+    stored = cfg.destination.read_signatures(cfg.registration)
+    sources = _sources(cfg)
+    rows, sigs = _compile_all(cfg, relations, run=run, sources=sources)
+    cfg.destination.write_registry_rows(rows)
+    out = DriftOutcome()
+
+    for rel in relations:
+        pair = (rel.schema, rel.table)
+        new_sig = sigs.get(pair)
+        if new_sig is None:
+            continue
+        # Projected like the new one: a signature stored before a deny was added still names the
+        # column, and must not read as a breaking `drop_column` (#4346).
+        old_sig = project_signature(stored.get(pair),
+                                    _denied(cfg, rel, sources.get(rel.qualified)))
+        drifts = classify_drift(old_sig, new_sig) if old_sig is not None else []
+        if not drifts:
+            # Identical → nothing to write: each write is a MotherDuck round trip, and fifty of
+            # them every tick for a schema that did not move is the cost of an idle registration.
+            if stored.get(pair) != new_sig:
+                cfg.destination.write_signature(cfg.registration, rel.schema, rel.table, new_sig)
+            continue
+
+        out.drifts[pair] = drifts
+        kinds = {d.kind for d in drifts}
+        payload = [{"kind": d.kind, "column": d.column, "severity": d.severity,
+                    "detail": d.detail} for d in drifts]
+
+        if lc.state_of(rel.schema, rel.table) in BASELINE_PENDING:
+            # A full baseline is already due this tick (#4338: a re-selected retired table, a
+            # table renamed at the source, an interrupted snapshot): it rebuilds the copy in the
+            # new shape, which IS the remedy. Blocking or reviewing it would also need a
+            # lifecycle edge `snapshotting` does not have, and abort the whole tick.
+            cfg.destination.write_signature(cfg.registration, rel.schema, rel.table, new_sig)
+            run.event(entity=rel.qualified, status=cp_status.EV_OK, unit="schema_drift",
+                      extra={"drifts": payload, "action": "superseded_by_baseline"})
+            continue
+
+        if KEY_CHANGE in kinds:
+            # The OLD signature stands: the block has to survive a restart, and the only thing
+            # that clears it is a resnapshot rebuilding the table under the new key.
+            out.blocked.add(pair)
+            run.event(entity=rel.qualified, status=cp_status.EV_ERROR, unit="schema_drift",
+                      error_detail="merge key changed — removed from the publication",
+                      extra={"drifts": payload, "action": "publication_removed",
+                             "remedy": remedy(manifest_path, rel.qualified)})
+            lc.ensure(rel.schema, rel.table, RESNAPSHOT_REQUIRED, "key change")
+            continue
+
+        added = kinds & NEW_COLUMN_KINDS
+        if added and _denied(cfg, rel, sources.get(rel.qualified)):
+            # Fail closed on a table that carries a deny (#4346, Sonnet F1): a new or renamed
+            # column may be the secret under another name. The OLD signature stands — it is the
+            # reviewed shape the decoder withholds everything else against — until an operator
+            # denies the column or resnapshots to approve it.
+            new_cols = sorted(d.column for d in drifts if d.kind in NEW_COLUMN_KINDS and d.column)
+            out.review.add(pair)
+            # unit `deny_columns`, every tick until resolved: the daily-loading privacy alarm
+            # reads that unit, and must stay red while the review is pending (Codex round 12).
+            run.event(entity=rel.qualified, status=cp_status.EV_ERROR, unit="deny_columns",
+                      error_detail=(f"new or renamed column(s) {', '.join(new_cols)} on a table "
+                                    "with denied columns — withheld until reviewed"),
+                      extra={"drifts": payload, "action": "withheld_pending_review",
+                             "remedy": "add the column(s) to source.deny.columns, or "
+                                       + remedy(manifest_path, rel.qualified) + " to approve"})
+            lc.ensure(rel.schema, rel.table, DRIFT_REVIEW, "new column on a denied table")
+            continue
+        cfg.destination.write_signature(cfg.registration, rel.schema, rel.table, new_sig)
+        breaking = kinds & BREAKING_KINDS
+        if breaking:
+            out.review.add(pair)
+            run.event(entity=rel.qualified, status=cp_status.EV_ERROR, unit="schema_drift",
+                      error_detail=f"breaking drift: {', '.join(sorted(breaking))}",
+                      extra={"drifts": payload, "action": "kept_loading"})
+            lc.ensure(rel.schema, rel.table, DRIFT_REVIEW, ", ".join(sorted(breaking)))
+        else:
+            run.event(entity=rel.qualified, status=cp_status.EV_OK, unit="schema_drift",
+                      extra={"drifts": payload, "action": "auto_evolved"})
+
+    if out.blocked:
+        owner.assert_held()
+        publication.reconcile(cfg.source_dsn, cfg.publication,
+                              [(r.schema, r.table) for r in relations
+                               if (r.schema, r.table) not in out.blocked])
+    return out

feather_cdc_postgres/generate_dbt.py

@@ -0,0 +1,106 @@
+"""Generate dbt source declarations from a compiled plan (#3079 D3, supersedes
+the retired scripts/generate_featherbase_sources.py, deleted in #3079).
+
+Constraints:
+  - the dbt source NAME is the destination database when the plan lands in one target schema —
+    existing models say `source('bronze_featherbase', 'comment')` and must keep resolving.
+  - descriptions come from the source's own metadata when it has any, so regeneration never
+    clobbers hand-written prose (#2209 constraint 3).
+  - `_dlt_loads` carries the only freshness check: warn-only at 24h. Minutes-grade liveness is
+    the control plane's job — a dead sync must not be its own only alarm.
+"""
+from __future__ import annotations
+
+import pathlib
+from typing import Dict, List, Optional
+
+from .manifest import Manifest
+from .selectors import CompiledPlan, Relation, table_class
+
+HEADER = "# GENERATED by `python -m feather_cdc_postgres generate-dbt` (#3079) — do not hand-edit."
+DLT_LOADS_DESC = "dlt load ledger — one row per landed load package (liveness backstop)."
+
+
+def _prose_name(source_id: str) -> str:
+    return source_id.replace("_", " ").title()
+
+
+def _default_description(m: Manifest, r: Relation) -> str:
+    who = _prose_name(m.source_id)
+    if r.module:
+        return f"{who} native table (module: {r.module})."
+    return f"{who} source table ({r.schema}.{r.table})."
+
+
+def _q(text: str) -> str:
+    return '"' + text.replace('"', "'") + '"'
+
+
+def source_name(m: Manifest, target_schemas: List[str]) -> Dict[str, str]:
+    """Target schema → dbt source name. One schema keeps the bare database name (existing
+    `source()` calls); several disambiguate, because two dbt sources cannot share a name."""
+    if len(target_schemas) == 1:
+        return {target_schemas[0]: m.destination.database}
+    return {s: f"{m.destination.database}__{s}" for s in target_schemas}
+
+
+def render(m: Manifest, compiled: CompiledPlan, descriptions: Optional[Dict[str, str]] = None) -> str:
+    """YAML text. `descriptions` (keyed 'schema.table') overrides whatever the adapter supplied."""
+    descriptions = descriptions or {}
+    by_schema: Dict[str, List[Relation]] = {}
+    for r in compiled.relations:
+        by_schema.setdefault(r.target_schema or r.schema, []).append(r)
+    schemas = sorted(by_schema)
+    names = source_name(m, schemas)
+
+    lines: List[str] = [
+        HEADER,
+        f"# Registration: {m.source_id}.yml · selection {compiled.selection_hash[:12]}",
+        "version: 2",
+        "",
+        "sources:",
+    ]
+    for schema in schemas:
+        lines += [
+            f"  - name: {names[schema]}",
+            f"    database: {m.destination.database}",
+            f"    schema: {schema}",
+            "    description: "
+            + _q(
+                f"CDC mirror of {m.source_id} ({schema}); slot-based logical replication, "
+                "minutes-fresh (#3079/#2839). Bronze doctrine: verbatim rows, silver fixes DQ."
+            ),
+            "    tables:",
+        ]
+        for r in sorted(by_schema[schema], key=lambda x: x.table):
+            desc = descriptions.get(r.qualified) or r.description or _default_description(m, r)
+            lines += [
+                f"      - name: {r.table}",
+                f"        description: {_q(desc)}",
+                "        meta:",
+                f"          table_class: {r.table_class}",
+                f"          source_module: {r.module if r.module else 'null'}",
+                f"          source_schema: {r.schema}",
+                f"          source_table: {r.table}",
+            ]
+        # Liveness backstop. 24h warn is deliberate: the drain only loads when something
+        # changed, so a tight window false-warns on a quiet day.
+        lines += [
+            "      - name: _dlt_loads",
+            f"        description: {_q(DLT_LOADS_DESC)}",
+            "        meta:",
+            f"          table_class: {table_class(m, schema, '_dlt_loads')}",
+            "          source_module: null",
+            f"          source_schema: {schema}",
+            "          source_table: _dlt_loads",
+            "        loaded_at_field: inserted_at",
+            "        freshness:",
+            "          warn_after: {count: 24, period: hour}",
+        ]
+    return "\n".join(lines) + "\n"
+
+
+def write(m: Manifest, compiled: CompiledPlan, out: pathlib.Path, descriptions=None) -> pathlib.Path:
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(render(m, compiled, descriptions), encoding="utf-8")
+    return out

feather_cdc_postgres/lifecycle.py

@@ -0,0 +1,79 @@
+"""Per-relation lifecycle state machine (#3079 D5).
+
+States are the ONLY record of why a table is not streaming, so every move is validated and
+mirrored to `control.event` (unit='lifecycle'). Slot loss is never a silent empty stream: it
+lands as `resnapshot_required` before any re-snapshot begins.
+`drift_review` has NO edge back to `streaming`: a run that merely sees no further drift must
+not clear a reported break, so the only way out is `resnapshot` (which passes through
+resnapshot_required → snapshotting → streaming) or retirement. The state machine enforces
+that rather than a convention (#3079 D7).
+"""
+from __future__ import annotations
+
+from control_plane import status as cp_status
+
+DISCOVERED = "discovered"
+SNAPSHOTTING = "snapshotting"
+CATCHING_UP = "catching_up"
+STREAMING = "streaming"
+DRIFT_REVIEW = "drift_review"
+RESNAPSHOT_REQUIRED = "resnapshot_required"
+RETIRED = "retired"
+
+STATES = frozenset({DISCOVERED, SNAPSHOTTING, CATCHING_UP, STREAMING,
+                    DRIFT_REVIEW, RESNAPSHOT_REQUIRED, RETIRED})
+
+ALLOWED: dict[str | None, frozenset[str]] = {
+    # STREAMING from nothing is ADOPTION only (runner._adopt_streaming): a slot that already
+    # exists is proof a previous drainer baselined the table; inventing a snapshot it never ran
+    # would be the bigger lie.
+    None: frozenset({DISCOVERED, SNAPSHOTTING, STREAMING}),
+    DISCOVERED: frozenset({SNAPSHOTTING, CATCHING_UP, RETIRED}),
+    SNAPSHOTTING: frozenset({CATCHING_UP, STREAMING, RESNAPSHOT_REQUIRED, RETIRED}),
+    CATCHING_UP: frozenset({STREAMING, DRIFT_REVIEW, RESNAPSHOT_REQUIRED, RETIRED}),
+    STREAMING: frozenset({CATCHING_UP, DRIFT_REVIEW, RESNAPSHOT_REQUIRED, RETIRED}),
+    DRIFT_REVIEW: frozenset({RESNAPSHOT_REQUIRED, RETIRED}),
+    RESNAPSHOT_REQUIRED: frozenset({SNAPSHOTTING, RETIRED}),
+    RETIRED: frozenset({DISCOVERED}),   # re-widening the selection re-admits the table
+}
+
+
+class IllegalTransition(ValueError):
+    pass
+
+
+class Lifecycle:
+    def __init__(self, destination, registration: str, run=None) -> None:
+        self.destination = destination
+        self.registration = registration
+        self.run = run
+        self._states: dict[tuple[str, str], str] = destination.read_lifecycle(registration)
+
+    def state_of(self, schema: str, table: str) -> str | None:
+        return self._states.get((schema, table))
+
+    def known(self) -> dict[tuple[str, str], str]:
+        """Every relation this registration has a row for, with its state (a copy)."""
+        return dict(self._states)
+
+    def transition(self, schema: str, table: str, new_state: str,
+                   detail: str | None = None) -> str:
+        if new_state not in STATES:
+            raise IllegalTransition(f"unknown lifecycle state {new_state!r}")
+        current = self._states.get((schema, table))
+        if new_state not in ALLOWED[current]:
+            raise IllegalTransition(
+                f"{schema}.{table}: {current or 'new'} → {new_state} is not an allowed transition"
+            )
+        self.destination.write_lifecycle(self.registration, schema, table, new_state, detail)
+        self._states[(schema, table)] = new_state
+        if self.run is not None:
+            self.run.event(entity=f"{schema}.{table}", status=cp_status.EV_OK, unit="lifecycle",
+                           extra={"from": current, "to": new_state, "detail": detail})
+        return new_state
+
+    def ensure(self, schema: str, table: str, new_state: str, detail: str | None = None) -> str:
+        """Idempotent: already in `new_state` is a no-op, not an error."""
+        if self._states.get((schema, table)) == new_state:
+            return new_state
+        return self.transition(schema, table, new_state, detail)