#!/usr/bin/env python3 """Offline retrospective quality at caller-declared common adaptation-spend caps. Development tooling: chronology/cost select snapshots, never quality rankings. """ import argparse from decimal import Decimal, localcontext import json import os from pathlib import Path import re import sys import tempfile BASE = Path(__file__).resolve().parent sys.path.insert(0, str(BASE.parent/"cost-to-quality")) import analyze_cost_threshold as boundary_helpers progress, shared = boundary_helpers.progress, boundary_helpers.shared archived, sealing, packets, accounting = boundary_helpers.archived, boundary_helpers.sealing, boundary_helpers.packets, boundary_helpers.accounting NOTICE = "Development retrospective equal-cost tooling, not empirical evidence; defaults unfrozen; no prospective stopping or adaptation feedback." def load_analysis(manifest_path, registry_path=None): manifest_path = Path(manifest_path).resolve() content = manifest_path.read_bytes() manifest = sealing.parse_json(content, "equal-cost manifest", decimal=True) sealing.keys(manifest, ("equal_cost_manifest_version", "analysis_id", "common_caps", "progress_manifest", "ledgers", "run_accounting"), "equal-cost manifest") sealing.require(manifest["equal_cost_manifest_version"] == "1.0", "incompatible equal-cost manifest version") sealing.text(manifest["analysis_id"], "analysis ID") caps = {} for row in sealing.array(manifest["common_caps"], "common caps"): sealing.keys(row, ("currency", "amounts"), "currency cap panel") currency = row["currency"] sealing.require(isinstance(currency, str) and re.fullmatch(r"[A-Z]{3}", currency) is not None and currency not in caps, "invalid/duplicate currency panel") amounts = [accounting.decimal_value(value, "spend cap") for value in sealing.array(row["amounts"], "cap amounts")] sealing.require(amounts and all(a < b for a, b in zip(amounts, amounts[1:])), "caps must be nonempty, unique and strictly increasing") caps[currency] = amounts sealing.require(caps, "declare at least one currency cap panel") # Reuse the existing complete request-boundary validator without changing it. # Its required threshold field is inert validation scaffolding; no threshold # event/statistic is calculated or used for snapshot selection here. def absolute_descriptor(descriptor, extra=()): sealing.keys(descriptor, ("path", "sha256", *extra), "source descriptor") return dict(descriptor, path=str((manifest_path.parent/sealing.text(descriptor["path"], "source path")).resolve())) adapter = dict(threshold_manifest_version="1.0", analysis_id=manifest["analysis_id"], quality_threshold=0, progress_manifest=absolute_descriptor(manifest["progress_manifest"]), ledgers=[absolute_descriptor(row, ("ledger_id",)) for row in sealing.array(manifest["ledgers"], "ledgers")], run_accounting=manifest["run_accounting"]) with tempfile.TemporaryDirectory(prefix="equal-cost-boundary-validation-") as temporary: path = Path(temporary)/"boundary-validation.json" path.write_bytes(sealing.json_bytes(adapter)) validated = boundary_helpers.load_analysis(path, registry_path) return dict(manifest=manifest, manifest_hash=sealing.sha(content), caps=caps, validated=validated) def money_difference(cap, spend): scale = max(0, -cap.as_tuple().exponent, -spend.as_tuple().exponent) with localcontext() as context: context.prec = max(1, cap.adjusted()+1, spend.adjusted()+1)+scale+2 return format(cap-spend, "f") def prepare_budgets(analysis): validated = analysis["validated"] quality = validated["quality"] budgets = {} for run in quality["manifest"]["runs"]: rid = run["run_id"] source = validated["accounting_runs"][rid] delivered = {s["turn"]: s for s in run["snapshots"]} turns = [] for turn in range(1, quality["manifest"]["turn_count"]+1): boundary = source["boundaries"].get(turn) count = None if boundary is None else boundary["cumulative_request_count"] cost = boundary_helpers.cumulative_cost(validated, rid, count) turns.append(dict(turn=turn, delivered=turn in delivered, artifact=None if turn not in delivered else delivered[turn]["artifact"], cumulative_adaptation=cost)) lid = source["source"]["ledger_id"] final_assessment = None if lid is not None: ledger = validated["ledgers"][lid] final_assessment = accounting.summarize_group([r for r in ledger["requests"] if r["run_id"] == rid and r["phase"] == "final_assessment"], ledger["runs"][rid]["phase_log_complete"]["final_assessment"]) budgets[rid] = dict(turns=turns, final_assessment_resources_separate=final_assessment, full_declared_adaptation=boundary_helpers.cumulative_cost(validated, rid, len(source["order"]))) return budgets def classify(point, currency, cap): cost = point["cumulative_adaptation"] result = dict(turn=point["turn"], artifact=point["artifact"], cumulative_adaptation=cost, state="unresolved", reason=None, actual_spend=None, matching_currency_known_subtotal=None) if not point["delivered"]: result["reason"] = "missing_snapshot" return result resources = cost["resources"] if resources is not None: metric = resources["billing"]["by_currency"].get(currency) subtotal = None if metric is None else metric["known_subtotal"] result["matching_currency_known_subtotal"] = subtotal if subtotal is not None and Decimal(subtotal) > cap: result.update(state="over_cap", reason="known_nonnegative_currency_subtotal_exceeds_cap") return result if not cost["coverage_complete"]: result["reason"] = "unknown_accounting" return result vector = cost["cost_by_currency"] if not vector: # A genuinely known empty request prefix, not missing billing. result.update(state="eligible", reason="known_empty_request_prefix", actual_spend="0") elif set(vector) == {currency}: spend = Decimal(vector[currency]) result.update(state="eligible" if spend <= cap else "over_cap", reason="known_matching_currency_spend", actual_spend=vector[currency]) else: result["reason"] = "incomparable_currency_vector" return result def select_snapshot(budget, currency, cap): audit, crossed = [], False for point in budget["turns"]: decision = classify(point, currency, cap) if crossed: sealing.require(decision["state"] != "eligible", "cumulative spending contradicts an earlier established over-cap bound") if decision["state"] == "unresolved": decision.update(state="over_cap", reason="after_established_over_cap_prefix") if decision["state"] == "over_cap": crossed = True audit.append(decision) candidates = [p for p in audit if p["state"] == "eligible"] candidate = candidates[-1] if candidates else None blockers = [p for p in audit if p["state"] == "unresolved" and (candidate is None or p["turn"] > candidate["turn"])] if blockers: return dict(selection_state="indeterminate", selected=None, latest_known_eligible_candidate_not_selected=None if candidate is None else candidate["turn"], blocking_turns=[p["turn"] for p in blockers], indeterminacy_reasons=sorted({p["reason"] for p in blockers}), eligibility_audit=audit) return dict(selection_state="selected" if candidate is not None else "no_snapshot_within_cap", selected=candidate, latest_known_eligible_candidate_not_selected=None, blocking_turns=[], indeterminacy_reasons=[], eligibility_audit=audit) def run_result(row, budget, currency, cap): if budget is None: selection = dict(selection_state="indeterminate", selected=None, latest_known_eligible_candidate_not_selected=None, blocking_turns=[], indeterminacy_reasons=["missing_run"], eligibility_audit=[]) else: selection = select_snapshot(budget, currency, cap) chosen = selection.pop("selected") selected = None if chosen is not None: source = row["turns"][chosen["turn"]-1] spend = Decimal(chosen["actual_spend"]) selected = dict(turn=chosen["turn"], artifact=chosen["artifact"], observed_quality=source["normalized_requirement_satisfaction"], assessment_binding=source["assessment_binding"], assessment_record=source["assessment_record"], actual_spend=chosen["actual_spend"], unused_cap=money_difference(cap, spend), currency=currency, actual_billed_cost_vector=chosen["cumulative_adaptation"]["cost_by_currency"], cumulative_adaptation=chosen["cumulative_adaptation"]) state = ("observed_quality" if selected["observed_quality"] is not None else "missing_selected_assessment") if selected is not None else selection["selection_state"] return dict(run_id=row["run_id"], task_id=row["task_id"], family_id=row["family_id"], repetition_id=row["repetition_id"], prescribed_endpoint=row["prescribed_endpoint"], comparison_state=state, selected_snapshot=selected, **selection, all_snapshot_accounting_known=False if budget is None else all(p["cumulative_adaptation"]["coverage_complete"] for p in budget["turns"]), full_declared_adaptation=None if budget is None else budget["full_declared_adaptation"], final_assessment_resources_separate=None if budget is None else budget["final_assessment_resources_separate"]) def series_result(source, analysis, budgets): result = {} quality = analysis["validated"]["quality"] for currency, caps in analysis["caps"].items(): panels = [] for cap in caps: conditions = {} for condition, group in source["by_condition"].items(): rows = [run_result(row, budgets.get(row["run_id"]), currency, cap) for row in group["runs"]] values = {(r["task_id"], r["repetition_id"]): None if r["selected_snapshot"] is None else r["selected_snapshot"]["observed_quality"] for r in rows} summary = progress.aggregate(values, condition, quality) states = {state: sum(r["comparison_state"] == state for r in rows) for state in ("observed_quality", "missing_selected_assessment", "no_snapshot_within_cap", "indeterminate")} conditions[condition] = dict(quality_summary=summary, expected_run_denominator=len(rows), observed_run_count=sum(r["run_id"] is not None for r in rows), selection_determined_count=sum(r["selection_state"] != "indeterminate" for r in rows), selected_snapshot_count=sum(r["selected_snapshot"] is not None for r in rows), comparison_state_counts=states, selection_coverage_complete=all(r["selection_state"] != "indeterminate" for r in rows), quality_coverage_complete=summary["coverage_complete"], runs=rows) complete = all(c["quality_coverage_complete"] for c in conditions.values()) panels.append(dict(cap_amount=format(cap, "f"), by_condition=conditions, complete_cohort_comparison=complete, complete_condition_quality_means={c: v["quality_summary"]["mean"] for c, v in conditions.items()} if complete else None)) result[currency] = dict(caps=panels) return dict(by_currency=result) def analyze_equal_cost(manifest_path, registry_path=None): analysis = load_analysis(manifest_path, registry_path) validated = analysis["validated"] quality = validated["quality"] budgets = prepare_budgets(analysis) return dict(equal_cost_report_version="1.0", notice=NOTICE, coordinator_only=True, defaults_unfrozen=True, analysis_id=analysis["manifest"]["analysis_id"], source_manifest_sha256=analysis["manifest_hash"], progress_manifest_sha256=quality["manifest_hash"], registry_sha256=quality["registry_hash"], selection_policy="latest chronologically delivered snapshot with known whole-prefix actual spend in cap currency <= cap; never quality-ranked; later unresolved eligibility blocks selection", budget_logic="nonnegative charges and nondecreasing request prefixes can establish over-cap lower bounds; no monotonic quality assumption", interpretation="retrospective snapshot view, not a prospectively cap-stopped run or causal improvement; unused cap is slack at selected snapshot, not saved whole-run expenditure", archives=quality["archives"], ledger_provenance=validated["ledger_provenance"], unused_ledger_run_ids=validated["unused_ledger_run_ids"], unselected_archived_run_ids=quality["unselected_archived_run_ids"], unused_assessment_assignments=quality["unused_assessment_assignments"], source_assessments={sid: {k: s[k] for k in ("source_batch_id", "source_seal_record_id", "rater_mapping", "provenance")} for sid, s in quality["sets"].items()}, independent={r: series_result(progress.series_result(quality, r), analysis, budgets) for r in quality["manifest"]["independent_rater_ids"]}, adjudicated=series_result(progress.series_result(quality), analysis, budgets)) def write_report(manifest_path, output_path, registry_path=None): output = packets.output_path(output_path) report = analyze_equal_cost(manifest_path, registry_path) sealing.require(all(output != Path(a["archive"]) and Path(a["archive"]) not in output.parents for a in report["archives"]), "report destination must stay outside sealed archives") content, pending = sealing.json_bytes(report), None try: with tempfile.NamedTemporaryFile(prefix=".pending-equal-cost-", dir=output.parent, delete=False) as handle: pending = Path(handle.name) handle.write(content) handle.flush() os.fsync(handle.fileno()) sealing.require(pending.read_bytes() == content, "report staging byte validation failed") os.link(pending, output) finally: if pending is not None: try: pending.unlink(missing_ok=True) except OSError: pass return dict(notice=NOTICE, coordinator_only=True, defaults_unfrozen=True, output=str(output), sha256=sealing.sha(content)) def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--manifest", type=Path, required=True) parser.add_argument("--registry", type=Path) parser.add_argument("--output", type=Path, required=True) args = parser.parse_args(argv) try: result = write_report(args.manifest, args.output, args.registry) except (sealing.ValidationError, accounting.LedgerError, OSError, KeyError, TypeError, ValueError, ArithmeticError) as exc: print(json.dumps(dict(error=str(exc), notice=NOTICE)), file=sys.stderr) return 2 print(json.dumps(result, indent=2, allow_nan=False)) return 0 if __name__ == "__main__": sys.exit(main())