250 lines
12 KiB
Python
250 lines
12 KiB
Python
"""Collect explicit boundary evidence without treating equal samples as proof."""
|
|
|
|
from __future__ import annotations
|
|
|
|
from datetime import datetime
|
|
from math import isfinite
|
|
|
|
from .scope import SECOND, collect_scope_outputs, fingerprint, range_limits, stamp, usable
|
|
from .timing import TIMING_OUTPUTS, period_envelopes, 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"),
|
|
"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):
|
|
groups = {}
|
|
for row in candidates:
|
|
output = row["outputs"].get(layer)
|
|
if output is None or not usable(output):
|
|
continue
|
|
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 = []
|
|
if len(groups) > 1:
|
|
differences.append({
|
|
"layer": layer, "relevant": relevant, "reason": "birth_time_sensitive",
|
|
"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 = len(groups) == 1 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 _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"]
|
|
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)
|
|
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")
|
|
return {
|
|
**collected, "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)
|