mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/visual_run/observations.py

@@ -0,0 +1,874 @@
+"""Bounded, data-only observations derived from deterministic graph tables."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, date, datetime, timedelta
+from decimal import Decimal
+from typing import Any
+from urllib.parse import parse_qsl, unquote, urlsplit
+
+from mostlyright.data_harness.canonical import canonical_json_bytes
+from mostlyright.data_harness.plan_graph import GraphTable, NodeAudit
+
+OBSERVATION_SCHEMA_VERSION = "stage-observation.v2"
+LEGACY_OBSERVATION_SCHEMA_VERSION = "stage-observation.v1"
+MAX_SAMPLE_ROWS = 20
+MAX_PROFILE_ROWS = 1_000
+MAX_COLUMNS = 512
+MAX_INPUTS = 32
+MAX_LINEAGE_SOURCES = 64
+MAX_FINDINGS = 128
+MAX_PARAMETERS_BYTES = 64 * 1024
+MAX_OBSERVATION_BYTES = 512 * 1024
+MAX_TEXT_CHARS = 4_096
+MAX_NESTING = 8
+DISPLAY_DISPOSITIONS = frozenset({"full", "redacted", "aggregate_only", "schema_only"})
+_SECRET_ASSIGNMENT = re.compile(
+    r"(?i)(?:api[_-]?key|account[_-]?key|private[_-]?key|access[_-]?token|authorization|"
+    r"bearer|client[_-]?secret|password|passwd|secret|signature|credential|"
+    r"session[_-]?token|sas[_-]?token|sharedaccesssignature)\s*[:=]"
+)
+_BEARER = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]{8,}")
+_SECRET_QUERY_NAME = re.compile(
+    r"(?i)^(?:"
+    r"x-amz-(?:credential|signature|security-token)|"
+    r"x-goog-(?:credential|signature)|googleaccessid|awsaccesskeyid|"
+    r"sig|signature|token|access[_-]?token|api[_-]?key|authorization|auth|"
+    r"password|passwd|secret|credential|client[_-]?secret|session[_-]?token|sas[_-]?token|"
+    r"account[_-]?key|private[_-]?key|sharedaccesssignature"
+    r")$"
+)
+_SECRET_NAME_PART = re.compile(
+    r"(?i)(?:^|[_-])(?:api[_-]?key|account[_-]?key|private[_-]?key|access[_-]?token|"
+    r"authorization|password|passwd|secret|signature|credential|session[_-]?token|"
+    r"sas[_-]?token|sharedaccesssignature|sig|token)(?:$|[_-])"
+)
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_LOGICAL_TYPES = frozenset(
+    {
+        "null",
+        "boolean",
+        "int64",
+        "float64",
+        "decimal",
+        "date",
+        "timestamp",
+        "timestamp_utc",
+        "string",
+        "mixed",
+    }
+)
+V2_FIELDS = frozenset(
+    {
+        "schema_version",
+        "node_id",
+        "operation",
+        "operation_version",
+        "inputs",
+        "source_coordinates",
+        "operation_parameters",
+        "audit",
+        "input_rows",
+        "output_rows",
+        "input_schemas",
+        "output_schema",
+        "columns",
+        "lineage",
+        "temporal",
+        "coverage",
+        "quality",
+        "profiles",
+        "findings",
+        "sample",
+        "rejected_rows",
+        "duplicate_rows",
+        "output_digest",
+        "display",
+        "truncated",
+    }
+)
+LEGACY_FIELDS = frozenset(
+    {
+        "schema_version",
+        "node_id",
+        "operation",
+        "operation_version",
+        "input_rows",
+        "output_rows",
+        "columns",
+        "sample",
+        "rejected_rows",
+        "duplicate_rows",
+        "output_digest",
+        "display",
+        "truncated",
+    }
+)
+
+
+def _decoded(value: str) -> str:
+    current = value
+    for _ in range(3):
+        decoded = unquote(current)
+        if decoded == current:
+            break
+        current = decoded
+    return current
+
+
+def _sensitive_name(value: str) -> bool:
+    decoded = _decoded(value).strip()
+    return (
+        _SECRET_QUERY_NAME.fullmatch(decoded) is not None
+        or _SECRET_NAME_PART.search(decoded) is not None
+    )
+
+
+def safe_column_for_display(value: str) -> bool:
+    """Return whether a column coordinate is safe to reveal at a row-query boundary."""
+
+    return isinstance(value, str) and not _sensitive_name(value)
+
+
+def safe_for_display(value: Any) -> bool:
+    """Fail closed for plain or percent-encoded credential-bearing strings."""
+
+    if not isinstance(value, str):
+        return True
+    decoded = _decoded(value)
+    if _SECRET_ASSIGNMENT.search(decoded) is not None or _BEARER.search(decoded) is not None:
+        return False
+    try:
+        parsed = urlsplit(decoded)
+    except ValueError:
+        return False
+    if parsed.scheme and (parsed.username is not None or parsed.password is not None):
+        return False
+    query = _decoded(parsed.query)
+    for name, _ in parse_qsl(query, keep_blank_values=True):
+        if _sensitive_name(name):
+            return False
+    # Encoded separators can leave a credential assignment outside parse_qsl's view.
+    for item in re.split(r"[&;]", query):
+        name = _decoded(item.partition("=")[0]).strip()
+        if _sensitive_name(name):
+            return False
+    return True
+
+
+def _bounded_text(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value or len(value) > MAX_TEXT_CHARS:
+        raise ValueError(f"observation {name} is not bounded text")
+    return value
+
+
+def _integer(value: Any, name: str, *, maximum: int = 2**63 - 1) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not 0 <= value <= maximum:
+        raise ValueError(f"observation {name} is not a bounded integer")
+    return value
+
+
+def _json_value(value: Any, *, depth: int = 0) -> Any:
+    if depth > MAX_NESTING:
+        raise ValueError("observation parameters exceed the nesting bound")
+    if value is None or type(value) in {bool, int, str}:
+        if isinstance(value, str) and len(value) > MAX_TEXT_CHARS:
+            raise ValueError("observation parameter text exceeds its bound")
+        return value
+    if isinstance(value, float):
+        raise ValueError("observation parameters must not contain binary floats")
+    if isinstance(value, Decimal):
+        return format(value, "f")
+    if isinstance(value, (date, datetime)):
+        return value.isoformat().replace("+00:00", "Z")
+    if isinstance(value, (list, tuple)):
+        return [_json_value(item, depth=depth + 1) for item in value]
+    if isinstance(value, dict):
+        if any(not isinstance(key, str) or not key or len(key) > MAX_TEXT_CHARS for key in value):
+            raise ValueError("observation parameter keys must be bounded text")
+        return {key: _json_value(value[key], depth=depth + 1) for key in sorted(value)}
+    raise ValueError("observation parameters contain an unsupported value")
+
+
+def _artifact_value(value: Any, *, depth: int = 0) -> Any:
+    """Normalize typed table values into canonical observation JSON."""
+
+    if depth > MAX_NESTING:
+        raise ValueError("observation value exceeds the nesting bound")
+    if value is None or type(value) in {bool, int, str}:
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("observation values must be finite")
+        return {"$float": value.hex()}
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError("observation decimal values must be finite")
+        return {"$decimal": format(value, "f")}
+    if isinstance(value, datetime):
+        return {"$timestamp": value.isoformat().replace("+00:00", "Z")}
+    if isinstance(value, date):
+        return {"$date": value.isoformat()}
+    if isinstance(value, (list, tuple)):
+        return [_artifact_value(item, depth=depth + 1) for item in value]
+    if isinstance(value, dict):
+        return {
+            str(key): _artifact_value(item, depth=depth + 1)
+            for key, item in sorted(value.items(), key=lambda item: str(item[0]))
+        }
+    raise ValueError("observation contains an unsupported table value")
+
+
+def _scrub(value: Any) -> tuple[Any, bool]:
+    """Remove secret values before they can enter an observation artifact."""
+
+    if isinstance(value, str):
+        return (value, False) if safe_for_display(value) else ("[redacted]", True)
+    if isinstance(value, list):
+        items = [_scrub(item) for item in value]
+        return [item for item, _ in items], any(changed for _, changed in items)
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        changed = False
+        for key, item in value.items():
+            if _sensitive_name(key):
+                result[key] = "[redacted]"
+                changed = True
+            else:
+                result[key], item_changed = _scrub(item)
+                changed = changed or item_changed
+        return result, changed
+    return value, False
+
+
+def scrub_for_display(value: Any) -> tuple[Any, bool]:
+    """Return a deterministic recursively redacted display value."""
+
+    return _scrub(value)
+
+
+def validate_stage_observation(value: Any) -> dict[str, Any]:
+    """Validate the closed artifact envelope and its strict global bounds."""
+
+    if not isinstance(value, dict):
+        raise ValueError("stage observation must be an object")
+    schema_version = value.get("schema_version")
+    expected = V2_FIELDS if schema_version == OBSERVATION_SCHEMA_VERSION else LEGACY_FIELDS
+    if schema_version not in {OBSERVATION_SCHEMA_VERSION, LEGACY_OBSERVATION_SCHEMA_VERSION}:
+        raise ValueError("stage observation schema version is unsupported")
+    if set(value) != expected:
+        raise ValueError("stage observation has unknown or missing fields")
+    encoded = canonical_json_bytes(value)
+    if len(encoded) > MAX_OBSERVATION_BYTES:
+        raise ValueError("stage observation exceeds its byte bound")
+    _bounded_text(value["node_id"], "node_id")
+    _bounded_text(value["operation"], "operation")
+    _bounded_text(value["operation_version"], "operation_version")
+    _integer(value["input_rows"], "input_rows")
+    _integer(value["output_rows"], "output_rows")
+    _integer(value["rejected_rows"], "rejected_rows")
+    _integer(value["duplicate_rows"], "duplicate_rows")
+    if _DIGEST.fullmatch(str(value["output_digest"])) is None:
+        raise ValueError("stage observation output digest is invalid")
+    if value["display"] not in DISPLAY_DISPOSITIONS or not isinstance(value["truncated"], bool):
+        raise ValueError("stage observation display fields are invalid")
+    columns = value["columns"]
+    sample = value["sample"]
+    if not isinstance(columns, list) or len(columns) > MAX_COLUMNS:
+        raise ValueError("stage observation columns exceed their bound")
+    if not isinstance(sample, list) or len(sample) > MAX_SAMPLE_ROWS:
+        raise ValueError("stage observation sample exceeds its bound")
+    for column in columns:
+        _bounded_text(column, "column")
+    if value["display"] in {"aggregate_only", "schema_only"} and sample:
+        raise ValueError("stage observation display policy forbids sampled values")
+    for row in sample:
+        if not isinstance(row, dict) or list(row) != columns:
+            raise ValueError("stage observation sample differs from its ordered columns")
+        _artifact_value(row)
+    if schema_version == LEGACY_OBSERVATION_SCHEMA_VERSION:
+        return value
+    if not isinstance(value["operation_parameters"], dict):
+        raise ValueError("stage observation parameters must be an object")
+    _json_value(value["operation_parameters"])
+    if len(canonical_json_bytes(value["operation_parameters"])) > MAX_PARAMETERS_BYTES:
+        raise ValueError("stage observation parameters exceed their byte bound")
+    if not isinstance(value["inputs"], list) or len(value["inputs"]) > MAX_INPUTS:
+        raise ValueError("stage observation inputs exceed their bound")
+    for item in value["inputs"]:
+        if not isinstance(item, dict) or set(item) != {"coordinate", "digest", "row_count"}:
+            raise ValueError("stage observation input is invalid")
+        _bounded_text(item["coordinate"], "input coordinate")
+        if _DIGEST.fullmatch(str(item["digest"])) is None:
+            raise ValueError("stage observation input digest is invalid")
+        if item["row_count"] is not None:
+            _integer(item["row_count"], "input row_count")
+    if (
+        not isinstance(value["source_coordinates"], list)
+        or len(value["source_coordinates"]) > MAX_INPUTS
+    ):
+        raise ValueError("stage observation source coordinates exceed their bound")
+    for coordinate in value["source_coordinates"]:
+        _bounded_text(coordinate, "source coordinate")
+    audit = value["audit"]
+    audit_fields = {
+        "parameter_digest",
+        "input_digests",
+        "output_digest",
+        "order_contract",
+        "engine",
+        "input_bytes",
+        "output_bytes",
+        "retained_bytes",
+    }
+    if not isinstance(audit, dict) or set(audit) != audit_fields:
+        raise ValueError("stage observation audit is invalid")
+    if not isinstance(audit["input_digests"], list) or len(audit["input_digests"]) > MAX_INPUTS:
+        raise ValueError("stage observation audit input digests are invalid")
+    for digest in [audit["parameter_digest"], audit["output_digest"], *audit["input_digests"]]:
+        if _DIGEST.fullmatch(str(digest)) is None:
+            raise ValueError("stage observation audit digest is invalid")
+    _bounded_text(audit["order_contract"], "order contract")
+    _bounded_text(audit["engine"], "engine")
+    for name in ("input_bytes", "output_bytes", "retained_bytes"):
+        _integer(audit[name], name)
+    for schema_group in (value["input_schemas"],):
+        if not isinstance(schema_group, list) or len(schema_group) > MAX_INPUTS:
+            raise ValueError("stage observation input schemas exceed their bound")
+        for item in schema_group:
+            if not isinstance(item, dict) or set(item) != {"coordinate", "columns"}:
+                raise ValueError("stage observation input schema is invalid")
+            _bounded_text(item["coordinate"], "schema coordinate")
+            _validate_columns(item["columns"])
+    _validate_columns(value["output_schema"])
+    lineage = value["lineage"]
+    if not isinstance(lineage, list) or len(lineage) > MAX_COLUMNS:
+        raise ValueError("stage observation lineage exceeds its bound")
+    for item in lineage:
+        if not isinstance(item, dict) or set(item) != {
+            "column",
+            "sources",
+            "operations",
+            "truncated",
+        }:
+            raise ValueError("stage observation lineage item is invalid")
+        _bounded_text(item["column"], "lineage column")
+        if (
+            not isinstance(item["truncated"], bool)
+            or not isinstance(item["sources"], list)
+            or len(item["sources"]) > MAX_LINEAGE_SOURCES
+        ):
+            raise ValueError("stage observation lineage sources are invalid")
+        for source in item["sources"]:
+            if not isinstance(source, dict) or set(source) != {"coordinate", "column"}:
+                raise ValueError("stage observation lineage source is invalid")
+            _bounded_text(source["coordinate"], "lineage coordinate")
+            _bounded_text(source["column"], "lineage source column")
+        if (
+            not isinstance(item["operations"], list)
+            or len(item["operations"]) > MAX_LINEAGE_SOURCES
+        ):
+            raise ValueError("stage observation lineage operations are invalid")
+        for operation in item["operations"]:
+            _bounded_text(operation, "lineage operation")
+    _validate_facts(value)
+    return value
+
+
+def _validate_columns(value: Any) -> None:
+    if not isinstance(value, list) or len(value) > MAX_COLUMNS:
+        raise ValueError("stage observation schema columns exceed their bound")
+    for column in value:
+        if not isinstance(column, dict) or set(column) != {"name", "logical_type", "nullable"}:
+            raise ValueError("stage observation schema column is invalid")
+        _bounded_text(column["name"], "schema column")
+        if column["logical_type"] not in _LOGICAL_TYPES or (
+            column["nullable"] is not None and not isinstance(column["nullable"], bool)
+        ):
+            raise ValueError("stage observation schema type is invalid")
+
+
+def _validate_facts(value: dict[str, Any]) -> None:
+    temporal = value["temporal"]
+    temporal_fields = {"time_column", "timezone", "window_start", "window_end", "granularity"}
+    if temporal is not None:
+        if not isinstance(temporal, dict) or set(temporal) != temporal_fields:
+            raise ValueError("stage observation temporal facts are invalid")
+        for item in temporal.values():
+            if item is not None:
+                _bounded_text(item, "temporal fact")
+    coverage = value["coverage"]
+    coverage_fields = {"expected_rows", "observed_rows", "complete"}
+    if not isinstance(coverage, dict) or frozenset(coverage) not in {
+        frozenset(coverage_fields),
+        frozenset((*coverage_fields, "representative_window")),
+    }:
+        raise ValueError("stage observation coverage facts are invalid")
+    for name in ("expected_rows", "observed_rows"):
+        if coverage[name] is not None:
+            _integer(coverage[name], f"coverage {name}")
+    if coverage["complete"] is not None and not isinstance(coverage["complete"], bool):
+        raise ValueError("stage observation coverage completeness is invalid")
+    representative = coverage.get("representative_window")
+    if representative is not None:
+        if not isinstance(representative, dict) or set(representative) != {
+            "start",
+            "end",
+            "output",
+            "inputs",
+            "truncated",
+        }:
+            raise ValueError("stage observation representative window is invalid")
+        _bounded_text(representative["start"], "representative window start")
+        _bounded_text(representative["end"], "representative window end")
+        if not isinstance(representative["output"], dict):
+            raise ValueError("stage observation representative output is invalid")
+        if not isinstance(representative["truncated"], bool):
+            raise ValueError("stage observation representative truncation is invalid")
+        inputs = representative["inputs"]
+        if not isinstance(inputs, list) or len(inputs) > MAX_INPUTS:
+            raise ValueError("stage observation representative inputs are invalid")
+        for item in inputs:
+            if not isinstance(item, dict) or set(item) != {"coordinate", "rows"}:
+                raise ValueError("stage observation representative input is invalid")
+            _bounded_text(item["coordinate"], "representative input coordinate")
+            if not isinstance(item["rows"], list) or len(item["rows"]) > MAX_SAMPLE_ROWS:
+                raise ValueError("stage observation representative input rows are invalid")
+            if any(not isinstance(row, dict) for row in item["rows"]):
+                raise ValueError("stage observation representative input row is invalid")
+        if value["display"] != "full" and (
+            representative["output"] or any(item["rows"] for item in representative["inputs"])
+        ):
+            raise ValueError("stage observation display policy forbids representative row values")
+    quality = value["quality"]
+    quality_fields = {"checks_passed", "checks_total", "rejected_rows", "duplicate_rows"}
+    if not isinstance(quality, dict) or set(quality) != quality_fields:
+        raise ValueError("stage observation quality facts are invalid")
+    for name, item in quality.items():
+        if item is not None:
+            _integer(item, f"quality {name}")
+    profiles = value["profiles"]
+    if not isinstance(profiles, list) or len(profiles) > MAX_COLUMNS:
+        raise ValueError("stage observation profiles exceed their bound")
+    for profile in profiles:
+        if not isinstance(profile, dict) or set(profile) != {
+            "column",
+            "rows_examined",
+            "null_count",
+            "distinct_count",
+        }:
+            raise ValueError("stage observation profile is invalid")
+        _bounded_text(profile["column"], "profile column")
+        for name in ("rows_examined", "null_count", "distinct_count"):
+            _integer(profile[name], f"profile {name}", maximum=MAX_PROFILE_ROWS)
+    findings = value["findings"]
+    if not isinstance(findings, list) or len(findings) > MAX_FINDINGS:
+        raise ValueError("stage observation findings exceed their bound")
+    for finding in findings:
+        if not isinstance(finding, dict) or set(finding) != {
+            "severity",
+            "code",
+            "message",
+            "column",
+        }:
+            raise ValueError("stage observation finding is invalid")
+        if finding["severity"] not in {"info", "warning", "error"}:
+            raise ValueError("stage observation finding severity is invalid")
+        _bounded_text(finding["code"], "finding code")
+        _bounded_text(finding["message"], "finding message")
+        if finding["column"] is not None:
+            _bounded_text(finding["column"], "finding column")
+
+
+def _schema(table: GraphTable) -> tuple[dict[str, Any], ...]:
+    if len(table.columns) > MAX_COLUMNS:
+        raise ValueError("observation schema exceeds its column bound")
+    nullable = [False] * len(table.columns)
+    for row in table.rows:
+        for index, value in enumerate(row):
+            nullable[index] = nullable[index] or value is None
+    result = []
+    for index, column in enumerate(table.columns):
+        _bounded_text(column, "column")
+        result.append(
+            {
+                "name": column,
+                "logical_type": table.schema[column],
+                "nullable": nullable[index],
+            }
+        )
+    return tuple(result)
+
+
+def _profiles(table: GraphTable) -> tuple[dict[str, Any], ...]:
+    retained = table.rows[:MAX_PROFILE_ROWS]
+    result = []
+    for index, column in enumerate(table.columns):
+        values = tuple(row[index] for row in retained)
+        distinct = {
+            json.dumps(
+                _artifact_value(value), sort_keys=True, ensure_ascii=False, separators=(",", ":")
+            )
+            for value in values
+            if value is not None
+        }
+        result.append(
+            {
+                "column": column,
+                "rows_examined": len(values),
+                "null_count": sum(value is None for value in values),
+                "distinct_count": len(distinct),
+            }
+        )
+    return tuple(result)
+
+
+@dataclass(frozen=True)
+class StageObservation:
+    node_id: str
+    operation: str
+    operation_version: str
+    inputs: tuple[dict[str, Any], ...]
+    source_coordinates: tuple[str, ...]
+    operation_parameters: dict[str, Any]
+    audit: dict[str, Any]
+    input_rows: int
+    output_rows: int
+    input_schemas: tuple[dict[str, Any], ...]
+    output_schema: tuple[dict[str, Any], ...]
+    columns: tuple[str, ...]
+    lineage: tuple[dict[str, Any], ...]
+    temporal: dict[str, Any] | None
+    coverage: dict[str, Any]
+    quality: dict[str, Any]
+    profiles: tuple[dict[str, Any], ...]
+    findings: tuple[dict[str, Any], ...]
+    sample: tuple[dict[str, Any], ...]
+    rejected_rows: int
+    duplicate_rows: int
+    output_digest: str
+    display: str
+    truncated: bool
+
+    def __post_init__(self) -> None:
+        _bounded_text(self.node_id, "node_id")
+        _bounded_text(self.operation, "operation")
+        _bounded_text(self.operation_version, "operation_version")
+        if self.display not in DISPLAY_DISPOSITIONS:
+            raise ValueError("observation display disposition is invalid")
+        if len(self.inputs) > MAX_INPUTS or len(self.input_schemas) > MAX_INPUTS:
+            raise ValueError("observation exceeds its input bound")
+        if len(self.sample) > MAX_SAMPLE_ROWS:
+            raise ValueError("observation sample exceeds its row bound")
+        if len(self.profiles) > MAX_COLUMNS or len(self.findings) > MAX_FINDINGS:
+            raise ValueError("observation evidence exceeds its bound")
+        if self.display in {"aggregate_only", "schema_only"} and self.sample:
+            raise ValueError("display policy forbids sampled values")
+        if _DIGEST.fullmatch(self.output_digest) is None:
+            raise ValueError("observation output digest is invalid")
+        if len(canonical_json_bytes(self.operation_parameters)) > MAX_PARAMETERS_BYTES:
+            raise ValueError("observation parameters exceed their byte bound")
+
+    def to_dict(self) -> dict[str, Any]:
+        value = {
+            "schema_version": OBSERVATION_SCHEMA_VERSION,
+            "node_id": self.node_id,
+            "operation": self.operation,
+            "operation_version": self.operation_version,
+            "inputs": list(self.inputs),
+            "source_coordinates": list(self.source_coordinates),
+            "operation_parameters": self.operation_parameters,
+            "audit": self.audit,
+            "input_rows": self.input_rows,
+            "output_rows": self.output_rows,
+            "input_schemas": list(self.input_schemas),
+            "output_schema": list(self.output_schema),
+            "columns": list(self.columns),
+            "lineage": list(self.lineage),
+            "temporal": self.temporal,
+            "coverage": self.coverage,
+            "quality": self.quality,
+            "profiles": list(self.profiles),
+            "findings": list(self.findings),
+            "sample": list(self.sample),
+            "rejected_rows": self.rejected_rows,
+            "duplicate_rows": self.duplicate_rows,
+            "output_digest": self.output_digest,
+            "display": self.display,
+            "truncated": self.truncated,
+        }
+        if len(canonical_json_bytes(value)) > MAX_OBSERVATION_BYTES:
+            raise ValueError("stage observation exceeds its byte bound")
+        return value
+
+
+def observe_table(
+    audit: NodeAudit,
+    table: GraphTable,
+    *,
+    display: str,
+    sample_rows: int = 5,
+    input_tables: dict[str, GraphTable] | None = None,
+    source_coordinates: tuple[str, ...] = (),
+    operation_parameters: dict[str, Any] | None = None,
+    temporal: dict[str, Any] | None = None,
+    coverage: dict[str, Any] | None = None,
+    quality: dict[str, Any] | None = None,
+    findings: tuple[dict[str, Any], ...] = (),
+) -> StageObservation:
+    """Derive the closed v2 observation; optional context is supplied by the graph owner."""
+
+    if (
+        isinstance(sample_rows, bool)
+        or not isinstance(sample_rows, int)
+        or not 0 <= sample_rows <= MAX_SAMPLE_ROWS
+    ):
+        raise ValueError("sample row bound is invalid")
+    if display not in DISPLAY_DISPOSITIONS:
+        raise ValueError("observation display disposition is invalid")
+    if len(audit.inputs) != len(audit.input_digests):
+        raise ValueError("observation audit input coordinates and digests differ")
+    input_tables = input_tables or {}
+    if set(input_tables) - set(audit.inputs):
+        raise ValueError("observation input tables name an unknown coordinate")
+    parameters = _json_value(operation_parameters or {})
+    assert isinstance(parameters, dict)
+    parameters, parameters_redacted = _scrub(parameters)
+    assert isinstance(parameters, dict)
+    source_values = tuple(_bounded_text(item, "source coordinate") for item in source_coordinates)
+    scrubbed_sources, sources_redacted = _scrub(list(source_values))
+    source_values = tuple(scrubbed_sources)
+    retained = table.rows[:sample_rows] if display in {"full", "redacted"} else ()
+    unsafe_sample = any(_sensitive_name(column) for column in table.columns) or any(
+        not safe_for_display(value) for row in retained for value in row
+    )
+    if display == "full" and (unsafe_sample or parameters_redacted or sources_redacted):
+        display = "schema_only"
+        retained = ()
+    sample = []
+    for row in retained:
+        values = {
+            column: _artifact_value(value) for column, value in zip(table.columns, row, strict=True)
+        }
+        if display == "redacted":
+            values = {
+                column: None if value is None else "[redacted]" for column, value in values.items()
+            }
+        sample.append(values)
+    inputs = tuple(
+        {
+            "coordinate": coordinate,
+            "digest": digest,
+            "row_count": len(input_tables[coordinate].rows) if coordinate in input_tables else None,
+        }
+        for coordinate, digest in zip(audit.inputs, audit.input_digests, strict=True)
+    )
+    input_schemas = []
+    for index, coordinate in enumerate(audit.inputs):
+        if coordinate in input_tables:
+            columns = list(_schema(input_tables[coordinate]))
+        elif index < len(audit.input_schemas):
+            columns = [
+                {"name": name, "logical_type": logical_type, "nullable": None}
+                for name, logical_type in audit.input_schemas[index]
+            ]
+        else:
+            columns = []
+        input_schemas.append({"coordinate": coordinate, "columns": columns})
+    lineage = []
+    for column in table.columns:
+        column_lineage = table.lineage.get(column)
+        sources = () if column_lineage is None else tuple(column_lineage)
+        operations = () if column_lineage is None else column_lineage.operations
+        lineage.append(
+            {
+                "column": column,
+                "sources": [
+                    {"coordinate": coordinate, "column": source_column}
+                    for coordinate, source_column in sources[:MAX_LINEAGE_SOURCES]
+                ],
+                "operations": list(operations[:MAX_LINEAGE_SOURCES]),
+                "truncated": max(len(sources), len(operations)) > MAX_LINEAGE_SOURCES,
+            }
+        )
+    normalized_temporal = None if temporal is None else _json_value(temporal)
+    normalized_temporal, temporal_redacted = _scrub(normalized_temporal)
+    normalized_coverage = _json_value(
+        coverage
+        or {
+            "expected_rows": None,
+            "observed_rows": audit.output_rows,
+            "complete": None,
+            "representative_window": None,
+        }
+    )
+    normalized_coverage, coverage_redacted = _scrub(normalized_coverage)
+    normalized_quality = _json_value(
+        quality
+        or {
+            "checks_passed": None,
+            "checks_total": None,
+            "rejected_rows": audit.rejected_rows,
+            "duplicate_rows": audit.duplicate_rows,
+        }
+    )
+    normalized_findings = _json_value(list(findings))
+    if not isinstance(normalized_findings, list) or len(normalized_findings) > MAX_FINDINGS:
+        raise ValueError("observation findings exceed their bound")
+    normalized_findings, findings_redacted = _scrub(normalized_findings)
+    if display == "full" and (findings_redacted or temporal_redacted or coverage_redacted):
+        display = "schema_only"
+        sample = []
+        if isinstance(normalized_coverage, dict):
+            normalized_coverage["representative_window"] = None
+    observation = StageObservation(
+        node_id=audit.node_id,
+        operation=audit.operation,
+        operation_version=audit.operation_version,
+        inputs=inputs,
+        source_coordinates=source_values,
+        operation_parameters=parameters,
+        audit={
+            "parameter_digest": audit.parameter_digest,
+            "input_digests": list(audit.input_digests),
+            "output_digest": audit.output_digest,
+            "order_contract": audit.order_contract,
+            "engine": audit.engine,
+            "input_bytes": audit.input_bytes,
+            "output_bytes": audit.output_bytes,
+            "retained_bytes": audit.retained_bytes,
+        },
+        input_rows=audit.input_rows,
+        output_rows=audit.output_rows,
+        input_schemas=tuple(input_schemas),
+        output_schema=_schema(table),
+        columns=table.columns,
+        lineage=tuple(lineage),
+        temporal=normalized_temporal,
+        coverage=normalized_coverage,
+        quality=normalized_quality,
+        profiles=_profiles(table),
+        findings=tuple(normalized_findings),
+        sample=tuple(sample),
+        rejected_rows=audit.rejected_rows,
+        duplicate_rows=audit.duplicate_rows,
+        output_digest=audit.output_digest,
+        display=display,
+        truncated=len(table.rows) > len(sample),
+    )
+    validate_stage_observation(observation.to_dict())
+    return observation
+
+
+def resample_window_evidence(
+    table: GraphTable,
+    input_tables: Mapping[str, GraphTable],
+    parameters: Mapping[str, Any],
+    *,
+    include_rows: bool,
+) -> dict[str, Any] | None:
+    """Bind one deterministic resample output window to bounded contributing rows."""
+
+    if not table.rows:
+        return None
+    event_time = parameters.get("event_time")
+    duration = parameters.get("duration_seconds")
+    group_by = parameters.get("group_by")
+    if (
+        not isinstance(event_time, str)
+        or isinstance(duration, bool)
+        or not isinstance(duration, int)
+        or duration <= 0
+        or not isinstance(group_by, list)
+        or any(not isinstance(item, str) for item in group_by)
+    ):
+        raise ValueError("resample parameters cannot produce representative evidence")
+    bucket_column = f"{event_time}_bucket"
+    if bucket_column not in table.columns:
+        raise ValueError("resample output omits its bucket column")
+    output_index = {column: index for index, column in enumerate(table.columns)}
+    output_row = table.rows[0]
+    start_value = output_row[output_index[bucket_column]]
+    if isinstance(start_value, str) and start_value.endswith("Z"):
+        start = datetime.fromisoformat(start_value.replace("Z", "+00:00"))
+    elif isinstance(start_value, datetime):
+        start = start_value
+    else:
+        raise ValueError("resample output bucket is not a UTC timestamp")
+    if start.tzinfo is None or start.utcoffset() is None:
+        raise ValueError("resample output bucket is not timezone-aware")
+    start = start.astimezone(UTC)
+    end = start + timedelta(seconds=duration)
+    group_values = {column: output_row[output_index[column]] for column in group_by}
+    representative_inputs: list[dict[str, Any]] = []
+    total_matches = 0
+    retained_matches = 0
+    if include_rows:
+        for coordinate, input_table in sorted(input_tables.items()):
+            input_index = {column: index for index, column in enumerate(input_table.columns)}
+            if event_time not in input_index or any(
+                column not in input_index for column in group_by
+            ):
+                continue
+            retained: list[dict[str, Any]] = []
+            for row in input_table.rows:
+                if any(
+                    row[input_index[column]] != expected
+                    for column, expected in group_values.items()
+                ):
+                    continue
+                raw_time = row[input_index[event_time]]
+                if isinstance(raw_time, str) and raw_time.endswith("Z"):
+                    observed = datetime.fromisoformat(raw_time.replace("Z", "+00:00"))
+                elif isinstance(raw_time, datetime):
+                    observed = raw_time
+                else:
+                    continue
+                if observed.tzinfo is None or observed.utcoffset() is None:
+                    continue
+                if not start <= observed.astimezone(UTC) < end:
+                    continue
+                total_matches += 1
+                if retained_matches < MAX_SAMPLE_ROWS:
+                    retained.append(
+                        {
+                            column: _artifact_value(value)
+                            for column, value in zip(input_table.columns, row, strict=True)
+                        }
+                    )
+                    retained_matches += 1
+            if retained:
+                representative_inputs.append({"coordinate": coordinate, "rows": retained})
+    return {
+        "start": start.isoformat().replace("+00:00", "Z"),
+        "end": end.isoformat().replace("+00:00", "Z"),
+        "output": (
+            {
+                column: _artifact_value(value)
+                for column, value in zip(table.columns, output_row, strict=True)
+            }
+            if include_rows
+            else {}
+        ),
+        "inputs": representative_inputs,
+        "truncated": total_matches > retained_matches,
+    }
+
+
+__all__ = [
+    "DISPLAY_DISPOSITIONS",
+    "LEGACY_OBSERVATION_SCHEMA_VERSION",
+    "MAX_SAMPLE_ROWS",
+    "OBSERVATION_SCHEMA_VERSION",
+    "StageObservation",
+    "observe_table",
+    "resample_window_evidence",
+    "safe_for_display",
+    "scrub_for_display",
+    "validate_stage_observation",
+]