328 lines
17 KiB
Python
328 lines
17 KiB
Python
"""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)
|