reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/plugins/transform/four_state_vector.py

@@ -0,0 +1,62 @@
+"""Four-state logic-intensity measurement vector."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from reader_workbench.plugins.transform._four_state_vector import (
+    build_four_state_vector_plugin_result,
+    log_four_state_vector_plugin_result,
+)
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class FourStateVectorResponseBinding(PluginConfig):
+    logic_channel: str = Field(min_length=1)
+    intensity_channel: str = Field(min_length=1)
+
+
+class FourStateVectorReferenceBinding(PluginConfig):
+    design_id: str = Field(min_length=1)
+    observation_stat: Literal["mean", "median"] = "mean"
+
+
+class FourStateVectorCfg(PluginConfig):
+    response: FourStateVectorResponseBinding
+    design_by: list[str] = Field(default_factory=lambda: ["design_id"])
+    time_column: str = "time"
+    treatment_column: str | None = None
+    time_mode: Literal["nearest", "last_before", "first_after", "exact"] = "nearest"
+    target_time_h: float | None = None
+    time_tolerance_h: float | None = 0.5
+    state_map_ref: str = Field(min_length=1)
+    reference: FourStateVectorReferenceBinding
+    require_all_corners_per_design: bool = True
+    eps_ratio: float = 1e-9
+    eps_range: float = 1e-12
+    eps_ref: float = 1e-9
+    eps_abs: float = 0.0
+    ref_add_alpha: float = 0.0
+    log2_offset_delta: float = 0.0
+    exclude_reference_from_output: bool = True
+    carry_metadata: list[str] = Field(default_factory=lambda: ["sequence", "id"])
+
+
+class FourStateVectorTransform(Plugin):
+    ConfigModel = FourStateVectorCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "plate_reader.annotated.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {"vector": dataframe_output("vector", "logic.four_state_vector.v1")}
+
+    def run(self, ctx, inputs, cfg: FourStateVectorCfg):
+        result = build_four_state_vector_plugin_result(ctx=ctx, df=inputs["df"], cfg=cfg)
+        log_four_state_vector_plugin_result(ctx=ctx, result=result)
+        return {"vector": result.vector}

reader_workbench/plugins/transform/four_state_vector_collection.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from reader_workbench.domains.logic.four_state_vector.collection import (
+    FourStateVectorSource,
+    collect_four_state_vector_sources,
+)
+from reader_workbench.workbench.ports import dataframe_output, record_collection_input
+from reader_workbench.workbench.records import SourceRecordCollection
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class FourStateVectorCollectionCfg(PluginConfig):
+    pass
+
+
+class FourStateVectorCollectionTransform(Plugin):
+    """Collect exact vector revisions; workspace discovery stays in Reader core."""
+
+    ConfigModel = FourStateVectorCollectionCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"sources": record_collection_input("sources", "logic.four_state_vector.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {"vectors": dataframe_output("vectors", "logic.four_state_vector_collection.v1")}
+
+    def run(self, ctx, inputs, cfg):
+        collection: SourceRecordCollection = inputs["sources"]
+        sources = tuple(
+            FourStateVectorSource(
+                resource_id=item.ref.resource_id,
+                experiment_id=item.ref.experiment_id,
+                record_id=item.ref.record_id,
+                revision_digest=item.revision_digest,
+                frame=item.load_dataframe(),
+            )
+            for item in collection
+        )
+        return {"vectors": collect_four_state_vector_sources(sources).frame}

reader_workbench/plugins/transform/logic_symmetry.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class LogicSymmetryPrepCfg(PluginConfig):
+    enable: bool = False
+    mode: Literal["first", "last", "median", "exact", "nearest"] = "last"
+    target_time: float | None = None
+    tolerance: float = Field(0.51, ge=0)
+    align_corners: bool = False
+    case_sensitive_treatments: bool | None = None
+    time_column: str = "time"
+
+
+class LogicSymmetryCfg(PluginConfig):
+    response_channel: str = Field(min_length=1)
+    design_by: list[str] = Field(default_factory=lambda: ["design_id"], min_length=1)
+    batch_col: str = Field("batch", min_length=1)
+    treatment_column: str | None = None
+    state_map_ref: str = Field(min_length=1)
+    observation_stat: Literal["mean", "median"] = "mean"
+    prep: LogicSymmetryPrepCfg = Field(default_factory=LogicSymmetryPrepCfg)
+
+
+class LogicSymmetryTransform(Plugin):
+    """Materialize logic-symmetry metrics as a normal pipeline record."""
+
+    ConfigModel = LogicSymmetryCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "plate_reader.annotated.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return {"table": dataframe_output("table", "logic_symmetry.v1")}
+
+    def run(self, ctx, inputs, cfg: LogicSymmetryCfg):
+        if ctx.experiment is None:
+            raise ValueError("logic_symmetry requires experiment semantics in the run context")
+        state_space = ctx.experiment.annotations.resolve_ordered_state_space(ref=cfg.state_map_ref)
+        if state_space.state_ids != ("00", "10", "01", "11"):
+            raise ValueError("Logic-symmetry state space must declare exactly 00, 10, 01, 11 in that order")
+
+        from reader_workbench.domains.logic.logic_symmetry import summarize_logic_symmetry  # noqa: PLC0415
+
+        prep = cfg.prep.model_dump()
+        if prep["case_sensitive_treatments"] is None:
+            prep["case_sensitive_treatments"] = state_space.case_sensitive
+        table = summarize_logic_symmetry(
+            inputs["df"],
+            response_channel=cfg.response_channel,
+            design_by=cfg.design_by,
+            batch_col=cfg.batch_col,
+            treatment_column=cfg.treatment_column or state_space.column,
+            treatment_map=dict(state_space.source_values),
+            treatment_case_sensitive=state_space.case_sensitive,
+            observation_stat=cfg.observation_stat,
+            prep=prep,
+        )
+        return {"table": table}

reader_workbench/plugins/transform/outlier_filter.py

@@ -0,0 +1,60 @@
+"""Simple z-score filter per (channel, time)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class OutlierCfg(PluginConfig):
+    enable: bool = False
+    z_thresh: float = 4.0
+
+
+class OutlierFilter(Plugin):
+    ConfigModel = OutlierCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return cls.passthrough_output_ports(
+            outputs={"df": dataframe_output("df", "tidy.v1")},
+            passthrough={"df": "df"},
+            promoted_examples={"df": ("plate_reader.annotated.v1",)},
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del cfg
+        return self.inherit_dataframe_output_ports(
+            inputs=inputs,
+            outputs=outputs,
+            passthrough={"df": "df"},
+            where=where,
+        )
+
+    def run(self, ctx, inputs, cfg: OutlierCfg):
+        if not cfg.enable:
+            return {"df": inputs["df"].copy()}
+
+        df = inputs["df"].copy()
+        df["value"] = pd.to_numeric(df["value"], errors="coerce")
+
+        def _f(g: pd.DataFrame) -> pd.DataFrame:
+            s = g["value"].dropna()
+            if s.size <= 1:
+                return g
+            mu = float(s.mean())
+            sd = float(s.std(ddof=1)) if s.size > 1 else 0.0
+            if not np.isfinite(sd) or sd <= 0:
+                return g
+            z = (g["value"] - mu) / sd
+            return g.loc[z.abs() <= float(cfg.z_thresh)]
+
+        out = df.groupby(["channel", "time"], group_keys=False).apply(_f)
+        return {"df": out}

reader_workbench/plugins/transform/overflow.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class OverflowCfg(PluginConfig):
+    action: Literal["max", "drop", "nan", "none"] = "max"
+    clip_quantile: float = 0.999
+    # New: explicit capping strategy
+    cap_strategy: Literal["provided", "infer", "quantile"] = "quantile"
+    per_channel_caps: Mapping[str, float] | None = None
+    # New: how to detect overflow rows
+    flag_column: str = "overflow"
+    treat_inf_as_overflow: bool = True
+
+
+class OverflowHandling(Plugin):
+    ConfigModel = OverflowCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return cls.passthrough_output_ports(
+            outputs={"df": dataframe_output("df", "tidy.v1")},
+            passthrough={"df": "df"},
+            promoted_examples={"df": ("plate_reader.annotated.v1",)},
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del cfg
+        return self.inherit_dataframe_output_ports(
+            inputs=inputs,
+            outputs=outputs,
+            passthrough={"df": "df"},
+            where=where,
+        )
+
+    def run(self, ctx, inputs, cfg: OverflowCfg):
+        df = inputs["df"].copy()
+        df["value"] = pd.to_numeric(df["value"], errors="coerce")
+        act = cfg.action.lower()
+        if act == "none":
+            unexpected_nonfinite = df["value"].isna() | np.isneginf(df["value"])
+            if unexpected_nonfinite.any():
+                raise ValueError("overflow_handling: NaN or negative infinity cannot represent instrument overflow")
+            policy_clipped, prior_overflow, bounds = _incoming_value_provenance(df)
+            flagged = _declared_instrument_overflow(df, flag_column=cfg.flag_column)
+            if cfg.treat_inf_as_overflow:
+                flagged = flagged | np.isposinf(df["value"])
+            elif (~np.isfinite(df["value"]) & ~(flagged | prior_overflow)).any():
+                raise ValueError("overflow_handling: non-finite values must be classified as instrument overflow")
+            instrument_overflow = prior_overflow | flagged
+            bounds = bounds.copy()
+            bounds.loc[flagged] = bounds.loc[flagged].map(_union_lower_bound)
+            df["value_policy_clipped"] = policy_clipped
+            df["value_instrument_overflow"] = instrument_overflow
+            df["value_bound_kind"] = bounds
+            df[cfg.flag_column] = instrument_overflow
+            return {"df": df}
+        if act == "drop":
+            unexpected_nonfinite = df["value"].isna() | np.isneginf(df["value"])
+            if unexpected_nonfinite.any():
+                raise ValueError("overflow_handling: NaN or negative infinity cannot represent instrument overflow")
+            policy_clipped, prior_overflow, bounds = _incoming_value_provenance(df)
+            flagged = _declared_instrument_overflow(df, flag_column=cfg.flag_column)
+            if cfg.treat_inf_as_overflow:
+                flagged = flagged | np.isposinf(df["value"])
+            elif (~np.isfinite(df["value"]) & ~(flagged | prior_overflow)).any():
+                raise ValueError("overflow_handling: non-finite values must be classified as instrument overflow")
+            drop_rows = policy_clipped | prior_overflow | bounds.ne("exact") | flagged
+            out = df.loc[~drop_rows].copy()
+            out["value_policy_clipped"] = False
+            out["value_instrument_overflow"] = False
+            out["value_bound_kind"] = "exact"
+            out[cfg.flag_column] = False
+            return {"df": out}
+        if act == "nan":
+            return {"df": df}
+        if act == "max":
+            # 1) mark which rows are overflowed
+            flagged = _declared_instrument_overflow(df, flag_column=cfg.flag_column)
+            if cfg.treat_inf_as_overflow:
+                flagged = flagged | ~np.isfinite(df["value"])
+            elif (~np.isfinite(df["value"]) & ~flagged).any():
+                raise ValueError("overflow_handling: non-finite values must be classified as instrument overflow")
+
+            # 2) compute per-channel caps explicitly
+            if cfg.cap_strategy == "provided":
+                if not cfg.per_channel_caps:
+                    raise ValueError("overflow_handling: cap_strategy='provided' but per_channel_caps is empty")
+                caps = pd.Series({str(k): float(v) for k, v in cfg.per_channel_caps.items()}, name="__cap__")
+            elif cfg.cap_strategy == "infer":
+                base = df[np.isfinite(df["value"])]
+                if base.empty:
+                    raise ValueError("overflow_handling: cap_strategy='infer' but no finite values available")
+                caps = base.groupby("channel")["value"].max().rename("__cap__")
+            elif cfg.cap_strategy == "quantile":
+                base = df[np.isfinite(df["value"])]
+                if base.empty:
+                    raise ValueError("overflow_handling: cap_strategy='quantile' but no finite values available")
+                caps = base.groupby("channel")["value"].quantile(float(cfg.clip_quantile)).rename("__cap__")
+            else:
+                raise ValueError(f"overflow_handling: unknown cap_strategy {cfg.cap_strategy!r}")
+
+            out = df.join(caps, on="channel")
+            if out["__cap__"].isna().any():
+                missing = sorted(out.loc[out["__cap__"].isna(), "channel"].astype(str).unique())
+                raise ValueError(f"overflow_handling: missing cap for channels: {missing}")
+
+            # 3) preserve why an observation is no longer exact before clamping.
+            # Explicit instrument overflow and finite policy clipping are different
+            # evidence states even though both land on the configured upper cap.
+            policy_clipped = np.isfinite(out["value"]) & out["value"].gt(out["__cap__"]) & ~flagged
+            out["value_policy_clipped"] = policy_clipped.astype(bool)
+            out["value_instrument_overflow"] = flagged.astype(bool)
+            out["value_bound_kind"] = np.where(policy_clipped | flagged, "lower", "exact")
+            out[cfg.flag_column] = flagged.astype(bool)
+
+            # 4) clamp everything to the cap; overflowed rows land exactly on the cap
+            out.loc[flagged, "value"] = np.inf  # ensure clamp hits the cap deterministically
+            out["value"] = np.minimum(out["value"], out["__cap__"])
+
+            # 5) concise log
+            if ctx.logger is not None:
+                policy_counts = policy_clipped.groupby(out["channel"]).sum().astype(int)
+                overflow_counts = flagged.groupby(out["channel"]).sum().astype(int)
+                ctx.logger.info(
+                    "overflow_handling • strategy=%s • policy_clipped_rows=%d • "
+                    "instrument_overflow_rows=%d • policy_by_channel=%s • instrument_by_channel=%s",
+                    cfg.cap_strategy,
+                    int(policy_clipped.sum()),
+                    int(flagged.sum()),
+                    dict(policy_counts[policy_counts > 0]),
+                    dict(overflow_counts[overflow_counts > 0]),
+                )
+
+            return {"df": out.drop(columns="__cap__")}
+        raise ValueError(f"unknown overflow action {cfg.action}")
+
+
+def _incoming_value_provenance(frame: pd.DataFrame) -> tuple[pd.Series, pd.Series, pd.Series]:
+    fields = {"value_policy_clipped", "value_instrument_overflow", "value_bound_kind"}
+    present = fields & set(frame.columns)
+    if present and present != fields:
+        raise ValueError("overflow_handling: value provenance must provide all three fields together")
+    if not present:
+        return (
+            pd.Series(False, index=frame.index, dtype=bool),
+            pd.Series(False, index=frame.index, dtype=bool),
+            pd.Series("exact", index=frame.index, dtype=object),
+        )
+
+    policy_clipped = _strict_provenance_boolean(frame["value_policy_clipped"], field="value_policy_clipped")
+    instrument_overflow = _strict_provenance_boolean(
+        frame["value_instrument_overflow"], field="value_instrument_overflow"
+    )
+    bounds = frame["value_bound_kind"]
+    if bounds.isna().any() or not bounds.map(lambda value: isinstance(value, str)).all():
+        raise ValueError("overflow_handling: value_bound_kind provenance must contain strings without missing values")
+    bounds = bounds.astype(str)
+    allowed = {"exact", "lower", "upper", "indeterminate"}
+    unknown = sorted(set(bounds) - allowed)
+    if unknown:
+        raise ValueError(f"overflow_handling: unsupported value_bound_kind provenance: {unknown}")
+    if not (policy_clipped | instrument_overflow).eq(bounds.ne("exact")).all():
+        raise ValueError("overflow_handling: clipping and overflow provenance disagrees with value_bound_kind")
+    return policy_clipped, instrument_overflow, bounds
+
+
+def _declared_instrument_overflow(frame: pd.DataFrame, *, flag_column: str) -> pd.Series:
+    flagged = pd.Series(False, index=frame.index, dtype=bool)
+    if flag_column not in frame.columns:
+        return flagged
+    raw_flags = frame[flag_column]
+    if raw_flags.isna().any() or not raw_flags.map(lambda value: isinstance(value, (bool, np.bool_))).all():
+        raise ValueError(f"overflow_handling: {flag_column!r} must contain booleans without missing values")
+    return raw_flags.astype(bool)
+
+
+def _strict_provenance_boolean(values: pd.Series, *, field: str) -> pd.Series:
+    if values.isna().any() or not values.map(lambda value: isinstance(value, (bool, np.bool_))).all():
+        raise ValueError(f"overflow_handling: {field} provenance must contain booleans without missing values")
+    return values.astype(bool)
+
+
+def _union_lower_bound(bound: object) -> str:
+    return "lower" if str(bound) in {"exact", "lower"} else "indeterminate"

reader_workbench/plugins/transform/ratio.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from contextlib import suppress
+
+import numpy as np
+import pandas as pd
+from pydantic import Field
+
+from reader_workbench.workbench.ports import dataframe_input, dataframe_output
+from reader_workbench.workbench.registry import Plugin, PluginConfig
+
+
+class RatioCfg(PluginConfig):
+    name: str
+    numerator: str
+    denominator: str
+    align_on: list[str] = Field(default_factory=lambda: ["position", "time"])
+
+
+class RatioTransform(Plugin):
+    ConfigModel = RatioCfg
+
+    @classmethod
+    def input_ports(cls):
+        return {"df": dataframe_input("df", "tidy.v1")}
+
+    @classmethod
+    def output_ports(cls):
+        return cls.passthrough_output_ports(
+            outputs={"df": dataframe_output("df", "tidy.v1")},
+            passthrough={"df": "df"},
+            promoted_examples={"df": ("plate_reader.annotated.v1",)},
+        )
+
+    def resolve_output_ports(self, *, inputs, outputs, cfg, where):
+        del cfg
+        return self.inherit_dataframe_output_ports(
+            inputs=inputs,
+            outputs=outputs,
+            passthrough={"df": "df"},
+            where=where,
+        )
+
+    def run(self, ctx, inputs, cfg: RatioCfg):
+        input_columns = list(inputs["df"].columns)
+        df, emit_value_provenance = _with_value_provenance(inputs["df"])
+
+        # Build alignment key; auto-augment with per-sheet/scope cols if present
+        key = [c for c in cfg.align_on if c in df.columns]
+        for extra in ("sheet_index", "sheet_name", "source"):
+            if extra in df.columns and extra not in key:
+                key.append(extra)
+        if not key:
+            available = sorted(set(df.columns))
+            raise ValueError(
+                "ratio: none of align_on columns are present in the input.\n"
+                f"  align_on: {cfg.align_on}\n"
+                f"  available: {available}"
+            )
+
+        # Partition numerator/denominator; keep ALL metadata on numerator side
+        lhs = (
+            df[df["channel"] == cfg.numerator]
+            .rename(
+                columns={
+                    "value": "__num__",
+                    "value_policy_clipped": "__num_policy_clipped__",
+                    "value_instrument_overflow": "__num_instrument_overflow__",
+                    "value_bound_kind": "__num_bound_kind__",
+                }
+            )
+            .copy()
+        )
+        rhs = (
+            df[df["channel"] == cfg.denominator]
+            .rename(
+                columns={
+                    "value": "__den__",
+                    "value_policy_clipped": "__den_policy_clipped__",
+                    "value_instrument_overflow": "__den_instrument_overflow__",
+                    "value_bound_kind": "__den_bound_kind__",
+                }
+            )
+            .copy()
+        )
+        if lhs.empty or rhs.empty:
+            available = sorted(df["channel"].dropna().astype(str).unique().tolist())
+            missing = []
+            if lhs.empty:
+                missing.append(cfg.numerator)
+            if rhs.empty:
+                missing.append(cfg.denominator)
+            raise ValueError(
+                f"ratio: requested channel(s) missing from input.\n  missing: {missing}\n  available: {available}"
+            )
+
+        # Keep only join keys + denominator on RHS to avoid suffix collisions
+        rhs = rhs[
+            key
+            + [
+                "__den__",
+                "__den_policy_clipped__",
+                "__den_instrument_overflow__",
+                "__den_bound_kind__",
+            ]
+        ]
+
+        # Join (lhs may be many-to-one vs rhs on the key)
+        merged = pd.merge(lhs, rhs, on=key, how="inner", validate="many_to_one")
+
+        # Only declared instrument lower bounds may explain a non-finite operand.
+        merged["__num__"] = pd.to_numeric(merged["__num__"], errors="coerce")
+        merged["__den__"] = pd.to_numeric(merged["__den__"], errors="coerce")
+        finite = np.isfinite(merged["__num__"]) & np.isfinite(merged["__den__"])
+        numerator_overflow = (
+            np.isposinf(merged["__num__"])
+            & merged["__num_instrument_overflow__"]
+            & merged["__num_bound_kind__"].eq("lower")
+        )
+        denominator_overflow = (
+            np.isposinf(merged["__den__"])
+            & merged["__den_instrument_overflow__"]
+            & merged["__den_bound_kind__"].eq("lower")
+        )
+        nonfinite = ~finite
+        omittable = (
+            nonfinite
+            & (np.isfinite(merged["__num__"]) | numerator_overflow)
+            & (np.isfinite(merged["__den__"]) | denominator_overflow)
+        )
+        unexpected_nonfinite = nonfinite & ~omittable
+        if unexpected_nonfinite.any():
+            raise ValueError("ratio: unexpected non-finite operand lacks instrument-overflow lower-bound provenance")
+
+        nonfinite_count = int(omittable.sum())
+        if nonfinite_count:
+            ctx.logger.warning(
+                "[warn]ratio[/warn] • %s: omitted %d aligned pair(s) with non-finite operands",
+                cfg.name,
+                nonfinite_count,
+            )
+
+        invalid = finite & (merged["__den__"] == 0)
+        dropped = int(invalid.sum())
+        if dropped:
+            ctx.logger.warning("[warn]ratio[/warn] • %s: dropped %d row(s) due to zero denominator", cfg.name, dropped)
+
+        merged = merged.loc[~omittable & ~invalid].copy()
+        bounded = merged["__num_bound_kind__"].ne("exact") | merged["__den_bound_kind__"].ne("exact")
+        nonpositive = merged["__num__"].le(0.0) | merged["__den__"].le(0.0)
+        if (bounded & nonpositive).any():
+            raise ValueError("ratio: bounded values require positive operands for directional bound propagation")
+        merged["value"] = merged["__num__"] / merged["__den__"]
+        merged["channel"] = cfg.name
+        merged["value_policy_clipped"] = merged["__num_policy_clipped__"] | merged["__den_policy_clipped__"]
+        merged["value_instrument_overflow"] = (
+            merged["__num_instrument_overflow__"] | merged["__den_instrument_overflow__"]
+        )
+        denominator_bounds = merged["__den_bound_kind__"].map(
+            {"exact": "exact", "lower": "upper", "upper": "lower", "indeterminate": "indeterminate"}
+        )
+        merged["value_bound_kind"] = [
+            _combine_bounds(numerator, denominator)
+            for numerator, denominator in zip(merged["__num_bound_kind__"], denominator_bounds, strict=True)
+        ]
+        if emit_value_provenance and "overflow" in merged.columns:
+            merged["overflow"] = merged["value_instrument_overflow"]
+
+        # Restore original column set in original order (inherits metadata from lhs)
+        derived = merged[df.columns].copy()
+
+        out = pd.concat([df, derived], ignore_index=True)
+        if not emit_value_provenance:
+            # Generic ratios remain usable, but missing provenance is not evidence
+            # that an observation is exact. Four-state event-window ingestion rejects it.
+            out = out.loc[:, input_columns]
+
+        with suppress(Exception):
+            ctx.logger.info(
+                "ratio • [accent]%s[/accent] = %s / %s • +%d row(s) • keys=%s",
+                cfg.name,
+                cfg.numerator,
+                cfg.denominator,
+                len(derived),
+                key,
+            )
+
+        return {"df": out}
+
+
+def _with_value_provenance(frame: pd.DataFrame) -> tuple[pd.DataFrame, bool]:
+    result = frame.copy()
+    explicit_fields = {"value_policy_clipped", "value_instrument_overflow", "value_bound_kind"}
+    present = explicit_fields & set(result.columns)
+    if present and present != explicit_fields:
+        raise ValueError("ratio: value provenance must provide all three explicit fields together")
+    if present:
+        policy_clipped = _strict_boolean(result["value_policy_clipped"], field="value_policy_clipped")
+        instrument_overflow = _strict_boolean(result["value_instrument_overflow"], field="value_instrument_overflow")
+        bounds = result["value_bound_kind"]
+        if bounds.isna().any() or not bounds.map(lambda value: isinstance(value, str)).all():
+            raise ValueError("ratio: value_bound_kind provenance must contain strings without missing values")
+        bounds = bounds.astype(str)
+        allowed = {"exact", "lower", "upper", "indeterminate"}
+        unknown = sorted(set(bounds) - allowed)
+        if unknown:
+            raise ValueError(f"ratio: unsupported value_bound_kind values: {unknown}")
+        affected = policy_clipped | instrument_overflow
+        if not affected.eq(bounds.ne("exact")).all():
+            raise ValueError("ratio: clipping and overflow provenance disagrees with value_bound_kind")
+        if "overflow" in result.columns:
+            observed_overflow = _strict_boolean(result["overflow"], field="overflow")
+            if not observed_overflow.eq(instrument_overflow).all():
+                raise ValueError("ratio: overflow disagrees with explicit instrument-overflow provenance")
+    else:
+        policy_clipped = pd.Series(False, index=result.index, dtype=bool)
+        instrument_overflow = pd.Series(False, index=result.index, dtype=bool)
+        bounds = pd.Series("exact", index=result.index, dtype=object)
+    result["value_policy_clipped"] = policy_clipped
+    result["value_instrument_overflow"] = instrument_overflow
+    result["value_bound_kind"] = bounds
+    return result, bool(present)
+
+
+def _strict_boolean(values: pd.Series, *, field: str) -> pd.Series:
+    if values.isna().any() or not values.map(lambda value: isinstance(value, (bool, np.bool_))).all():
+        raise ValueError(f"ratio: {field} provenance must contain booleans without missing values")
+    return values.astype(bool)
+
+
+def _combine_bounds(left: object, right: object) -> str:
+    bounds = {str(left), str(right)} - {"exact"}
+    if not bounds:
+        return "exact"
+    if len(bounds) == 1:
+        return bounds.pop()
+    return "indeterminate"