"""Collect explicit boundary evidence without treating equal samples as proof.""" from __future__ import annotations from collections import defaultdict from datetime import datetime from math import isfinite from . import LEGACY_POLICY_VERSION, POLICY_VERSION from .scope import SECOND, collect_scope_outputs, fingerprint, range_limits, stamp, usable from .timing import TIMING_OUTPUTS, period_change_witnesses, period_envelopes, period_observation, period_signature COVERAGE = {"policy_covered", "sampled_only", "incomplete"} class ScanBudgetExhausted(RuntimeError): pass class BoundaryMethodUnavailable(RuntimeError): pass def _receipt(item: dict, layer: str, details: dict, bounds: list[datetime]) -> dict: state = details["state"] resolution = details["resolution_seconds"] gap = details["max_unchecked_gap_seconds"] error = details["boundary_error_seconds"] if (state not in COVERAGE or not isinstance(resolution, int) or resolution < 1 or not isinstance(gap, (int, float)) or not isfinite(gap) or gap < 0 or not isinstance(error, (int, float)) or not isfinite(error) or error < 0 or not isinstance(details["method_id"], str) or not details["method_id"]): raise ValueError("invalid_boundary_provider_receipt") if state == "policy_covered" and (resolution > 1 or error > 1): state = "sampled_only" start, end = range_limits(item) return { "layer": layer, "range_id": item["range_id"], "branch_id": item["branch_id"], "state": state, "method_id": details["method_id"], "boundary_times": [at.isoformat() for at in bounds], "resolution_seconds": resolution, "max_unchecked_gap_seconds": gap, "boundary_error_seconds": error, "stop_tolerance_seconds": 1, "reason": details.get("reason"), **({"basis": details["basis"]} if state == "policy_covered" and details.get("basis") else {}), "uncovered": [] if state == "policy_covered" else [{"start": start.isoformat(), "end": end.isoformat()}], } def _fallback(item: dict, layer: str, reason: str, *, incomplete: bool = False) -> dict: start, end = range_limits(item) return _receipt(item, layer, { "state": "incomplete" if incomplete else "sampled_only", "method_id": "endpoints_only", "resolution_seconds": 1, "max_unchecked_gap_seconds": int((end - start).total_seconds()), "boundary_error_seconds": 0, "reason": reason, }, []) def _scan_range(item: dict, required: list[str], providers: dict, sample) -> list[dict]: start, end = range_limits(item) branch = item["branch_id"] receipts = [] try: sample(start, branch) sample(end, branch) except ScanBudgetExhausted: return [_fallback(item, layer, "scan_incomplete", incomplete=True) for layer in required] for layer in required: provider = providers.get(layer) if provider is None: receipts.append(_fallback(item, layer, "scan_incomplete")) continue try: details = provider(item, sample) bounds = sorted({stamp(at) for at in details["boundaries"]}) if any(at.microsecond or not start < at <= end for at in bounds): raise ValueError("provider_boundary_outside_range_or_precision") for at in bounds: sample(at - SECOND, branch) sample(at, branch) receipts.append(_receipt(item, layer, details, bounds)) except ScanBudgetExhausted: receipts.append(_fallback(item, layer, "scan_incomplete", incomplete=True)) except BoundaryMethodUnavailable: receipts.append(_fallback(item, layer, "method_unresolved")) except (ArithmeticError, RuntimeError): receipts.append(_fallback(item, layer, "calculation_failure", incomplete=True)) return receipts def _segments(ranges: list[dict], receipts: list[dict], candidates: list[dict]) -> list[dict]: """Partition each range at known boundaries while retaining unresolved ranges.""" segments = [] for item in ranges: start, end = range_limits(item) related = [receipt for receipt in receipts if receipt["range_id"] == item["range_id"]] bounds = sorted({stamp(at) for receipt in related for at in receipt["boundary_times"]}) points = (start, *bounds, end + SECOND) for left, after in zip(points, points[1:]): right = after - SECOND samples = [row for row in candidates if item["range_id"] in row["range_ids"] and left <= stamp(row["candidate_at"]) <= right] segments.append({ "range_id": item["range_id"], "branch_id": item["branch_id"], "range": {"start": left.isoformat(), "end": right.isoformat(), "closed_start": True, "closed_end": True, "duration_seconds": int((right - left).total_seconds())}, "sample_count": len(samples), "representative_at": samples[0]["candidate_at"] if samples else None, "representative_is_birth_truth": False, "support": "policy_covered" if all(row["state"] == "policy_covered" for row in related) else "observed_only", "computed_payload_refs": [row["candidate_id"] for row in samples], }) return segments def _layer_value(layer: str, output: dict, forecast: dict | None, granularity: str): if layer not in TIMING_OUTPUTS: return output["value"] if forecast is None: return None return period_signature(output, forecast, granularity) or None def _classify_layer(layer, candidates, required, covered, forecast, granularity, policy_version): groups = {} observations = [] timed_v2 = policy_version == POLICY_VERSION and layer in TIMING_OUTPUTS and forecast is not None for row in candidates: output = row["outputs"].get(layer) if output is None or not usable(output): continue if timed_v2: observation = period_observation(output, forecast, granularity) observations.append((row["candidate_at"], observation)) value = observation[0] else: value = _layer_value(layer, output, forecast, granularity) if value is not None: groups.setdefault(fingerprint(value), []).append((row, output, value)) supported_count = sum(map(len, groups.values())) fully_supported = covered and len(candidates) == supported_count and supported_count > 0 relevant = layer in required differences = [] claims = [] witnesses = period_change_witnesses(observations, granularity) if timed_v2 else {} material = bool(witnesses) if timed_v2 else len(groups) > 1 if material: differences.append({ "layer": layer, "relevant": relevant, "reason": "birth_time_sensitive", **({"witnesses": witnesses} if timed_v2 else {}), "by_value": [ {"value": rows[0][2], "candidate_ids": [row["candidate_id"] for row, _, _ in rows], "branch_ids": sorted({row["branch_id"] for row, _, _ in rows})} for rows in groups.values() ], }) reasons = { output.get("reason") or ("calculation_failure" if output["status"] == "error" else "method_unresolved") for row in candidates if (output := row["outputs"].get(layer)) is not None and not usable(output) } if relevant: for key, rows in groups.items(): is_stable = not material and fully_supported claims.append({ "claim_id": f"{layer}:{key[:16]}", "layer": layer, "value": rows[0][2], "support": "all_candidates" if is_stable else "observed_candidates_only", "candidate_ids": [row["candidate_id"] for row, _, _ in rows], "branch_ids": sorted({row["branch_id"] for row, _, _ in rows}), "range_ids": sorted({range_id for row, _, _ in rows for range_id in row["range_ids"]}), "dependencies": sorted({dep for _, output, _ in rows for dep in output["dependencies"]}), "result_refs": [output["result_ref"] for _, output, _ in rows], }) coverage = "executed_complete" if fully_supported else "partial" if groups else "blocked" return coverage, differences, claims, reasons def _claim_group_results(policy, coverage, receipts, differences, limitations, claims): rows_by_layer = defaultdict(list) reasons_by_layer = defaultdict(set) groups_by_layer = defaultdict(list) changes_by_layer = {row["layer"]: row for row in differences} for row in receipts: rows_by_layer[row["layer"]].append(row) for row in limitations: reasons_by_layer[row["layer"]].add(row["reason"]) results = [] for group in policy["claim_groups"]: group_id = group["group_id"] layers, limited_by = [], [] if group["needs_input"]: limited_by.append({"reason": "event_class_required", "layer": None}) incomplete = changed = conditional = False for layer in group["layers"]: groups_by_layer[layer].append(group_id) related = rows_by_layer[layer] reasons = reasons_by_layer[layer] state = ("incomplete" if any(r["state"] == "incomplete" for r in related) else "policy_covered" if related and all(r["state"] == "policy_covered" for r in related) else "sampled_only") change = changes_by_layer.get(layer) layers.append({"layer": layer, "coverage": state, "execution_coverage": coverage[layer], "changed": change is not None}) if change: changed = True times = sorted({at for row in related for at in row["boundary_times"]}) observed_at = sorted({key.rsplit("@", 1)[-1] for value in change["by_value"] for key in value["candidate_ids"][:1]}) limited_by.append({"layer": layer, "reason": change["reason"], "boundary_times": times, "observed_at": observed_at}) for kind, witnesses in sorted(change.get("witnesses", {}).items()): limited_by.append({"layer": layer, "reason": kind, "observed_at": witnesses}) failures = any(r["state"] == "incomplete" and r["reason"] != "method_unresolved" for r in related) or "calculation_failure" in reasons insufficient = state != "policy_covered" or coverage[layer] != "executed_complete" if failures or insufficient: incomplete |= failures conditional |= insufficient for reason in sorted(reasons or {state if state != "policy_covered" else "method_unresolved"}): limited_by.append({"layer": layer, "reason": reason}) status = ("needs_input" if group["needs_input"] else "insufficient_evidence" if incomplete else "needs_refinement" if changed else "conditional" if conditional else "scope_ready") results.append({"group_id": group_id, "domain": group["domain"], "status": status, "layers": layers, "limited_by": limited_by}) grouped_claims = [ {**claim, "group_id": group_id, "claim_id": f"{group_id}:{claim['claim_id']}"} for claim in claims for group_id in groups_by_layer[claim["layer"]] ] return results, grouped_claims def _assessment(collected: dict, scope: dict, receipts: list[dict], failures: set, sample_count: int, budget: int) -> dict: required, candidates = collected["required_layers"], collected["candidates"] layer_names = set(required) | {key for row in candidates for key in row["outputs"]} forecast = scope["purpose_scope"]["forecast_window"] granularity = scope["purpose_scope"]["granularity"] policy = scope["policy"] policy_version = policy.get("id", LEGACY_POLICY_VERSION) differences, claims, envelopes, limitations = [], [], {}, [] coverage = {} for layer in sorted(layer_names): related = [row for row in receipts if row["layer"] == layer] bounded = not failures and bool(related) and all(row["state"] == "policy_covered" for row in related) state, changes, facts, reasons = _classify_layer( layer, candidates, required, bounded, forecast, granularity, policy_version, ) differences.extend(changes) claims.extend(facts) reasons.update(row["reason"] for row in related if row["reason"]) limitations.extend({"layer": layer, "reason": reason} for reason in sorted(reasons)) if layer in required: coverage[layer] = state if layer in TIMING_OUTPUTS: envelopes[layer] = period_envelopes(candidates, layer, state == "executed_complete") states = {row["state"] for row in receipts} scan_state = ("incomplete" if failures or "incomplete" in states else "policy_covered" if states == {"policy_covered"} else "sampled_only") material = any(row["relevant"] for row in differences) domain_complete = not failures and (collected["domain_complete"] or scan_state == "policy_covered") branch_ids = {item["branch_id"] for item in scope["plausible_ranges"]} all_layers = all(state == "executed_complete" for state in coverage.values()) branch_state = ("unresolved_material" if len(branch_ids) > 1 and material else "resolved" if len(branch_ids) == 1 and scan_state != "incomplete" else "bounded_equivalent" if scan_state == "policy_covered" and all_layers else "not_evaluated") group_fields = {} if policy_version == POLICY_VERSION: groups, claims = _claim_group_results(policy, coverage, receipts, differences, limitations, claims) group_fields = {"claim_groups": groups, "unmapped_route_layers": policy["unmapped_route_layers"], "missing_domains": policy["missing_domains"]} return { **collected, **group_fields, "layer_coverage": coverage, "domain_complete": domain_complete, "scan_state": scan_state, "branch_state": branch_state, "per_layer_scan_receipts": receipts, "output_envelopes": envelopes, "material_change": material, "material_differences": [row for row in differences if row["relevant"]], "observed_differences": differences, "limitations": limitations, "claims": claims, "stable_claim_ids": [row["claim_id"] for row in claims if row["support"] == "all_candidates"], "conditional_claim_ids": [row["claim_id"] for row in claims if row["support"] != "all_candidates"], "interval_results": _segments(scope["plausible_ranges"], receipts, candidates), "budget": {"candidate_limit": budget, "candidates_computed": sample_count, "exhausted": any(row["state"] == "incomplete" and row["reason"] == "scan_incomplete" for row in receipts)}, } def scan_scope(scope_request: dict, compute_at, boundary_providers: dict, *, budget: int = 4000) -> dict: """Scan every branch; provider and result sampling share one computation budget. A provider receives (range, sample) and returns explicit coverage with the native resolution and discovery method. Unsupported layers stay sampled. """ if not isinstance(budget, int) or isinstance(budget, bool) or budget < 0: raise ValueError("scan_budget_invalid") profiles = scope_request["profiles"] required = scope_request["policy"]["required_layers"] allowed = [(item["branch_id"], *range_limits(item)) for item in scope_request["plausible_ranges"]] rows = {} failures = set() def sample(at: datetime, branch: str) -> dict: at = stamp(at) if at.microsecond or not any(branch == name and start <= at <= end for name, start, end in allowed): raise ValueError("scan_sample_outside_scope_or_precision") key = (branch, at) if key in rows: return rows[key] if len(rows) >= budget: raise ScanBudgetExhausted try: row = compute_at(at, branch) except (ArithmeticError, RuntimeError, ValueError): failures.add(key) row = {"candidate_at": at.isoformat(), "branch_id": branch, "profile": profiles[branch], "outputs": {layer: {"status": "error", "reason": "calculation_failure"} for layer in required}} if stamp(row["candidate_at"]) != at or row["branch_id"] != branch or row["profile"] != profiles[branch]: raise ValueError("native_result_does_not_match_sample") rows[key] = row return row receipts = [ receipt for item in scope_request["plausible_ranges"] for receipt in _scan_range(item, required, boundary_providers, sample) ] collected = collect_scope_outputs(scope_request, list(rows.values())) return _assessment(collected, scope_request, receipts, failures, len(rows), budget)