#!/usr/bin/env python3 """Read-only summaries of declared run outcomes in explicitly supplied sealed archives. Development tooling. No semantic success inference, quality scoring, or imputation. """ import argparse import copy from datetime import datetime, timezone import json from pathlib import Path import sys import seal_runs as sealing NOTICE = "Development run-outcome tooling, not empirical findings; completion is a declared status, not requirement satisfaction." def inside(root, relative): sealing.text(relative, "archive relative path") path = Path(relative) sealing.require(not path.is_absolute() and ".." not in path.parts, "unsafe archive relative path") resolved = (root/path).resolve() sealing.require(resolved.is_relative_to(root) and resolved.is_file(), "archive file missing or resolves outside archive") return resolved def registry_signature(registry): """Compare immutable registry metadata/hashes while allowing relocated paths.""" result = copy.deepcopy(registry) sealing.require(result["kit_version"] == "1.0", "incompatible registry version") for task in result["tasks"]: for field in ("public_packet", "assessor_guide"): task[field].pop("path") result["common_conventions"].pop("path") result["tasks"].sort(key=lambda task: task["task_id"]) for family in result["families"]: family["task_ids"].sort() result["families"].sort(key=lambda family: family["family_id"]) return json.dumps(result, sort_keys=True, separators=(",", ":"), allow_nan=False).encode() def load_archive(path, selected_registry): root = Path(path).resolve() sealing.require(root.is_dir(), "archive must be a directory") sealing.require((root/"packet-build-manifest.json").is_file(), "unsealed archive: missing final commit manifest") packet_bytes = inside(root, "packet-build-manifest.json").read_bytes() inventory_bytes = inside(root, "archive-inventory.json").read_bytes() inventory = sealing.parse_json(inventory_bytes, "archive inventory") packet = sealing.parse_json(packet_bytes, "archive commit") sealing.keys(inventory, ("archive_inventory_version", "notice", "coordinator_only", "defaults_unfrozen", "batch_id", "seal_record_id", "commit_file", "state", "records", "support_files", "runs", "unassessable_runs"), "archive inventory") sealing.require(inventory["archive_inventory_version"] == "1.0", "incompatible archive inventory version") sealing.require(inventory["coordinator_only"] is True and inventory["commit_file"] == "packet-build-manifest.json", "invalid archive commit contract") sealing.keys(packet, ("build_manifest_version", "batch_id", "seal_record_id", "batch_sealed", "sealed_at_utc", "independent_rater_ids", "conditions", "runs"), "archive commit") sealing.require(packet["build_manifest_version"] == "1.0", "incompatible packet-build manifest version") sealing.require(packet["batch_sealed"] is True, "unsealed archive: batch_sealed must be true") seal_time = sealing.utc(packet["sealed_at_utc"], "archive seal time") sealing.require(seal_time <= datetime.now(timezone.utc), "archive seal is in the future") sealing.require(all(packet[k] == inventory[k] for k in ("batch_id", "seal_record_id")), "archive seal/batch identity mismatch") sealing.text(packet["batch_id"], "batch_id") sealing.text(packet["seal_record_id"], "seal_record_id") archived, support, paths = {}, {}, set() for group, record_fields in (("records", ("record_id", "kind", "source_path", "path", "sha256", "bytes")), ("support_files", ("path", "sha256", "bytes"))): for row in sealing.array(inventory[group], group): sealing.keys(row, record_fields, group+" entry") sealing.require(type(row["bytes"]) is int and row["bytes"] >= 0, "invalid archive byte count") sealing.digest(row["sha256"], "archive source hash") sealing.require(row["path"] not in paths, "duplicate archive payload path") paths.add(row["path"]) inside(root, row["path"]) # Validate containment before shared hash reader. if group == "records": rid = sealing.text(row["record_id"], "record_id") sealing.require(rid not in archived and row["kind"] in sealing.KINDS, "duplicate/invalid archive record") sealing.text(row["source_path"], "source provenance path") # Never dereferenced. archived[rid] = row else: support[row["path"]] = row required_support = {"source-inventory.json", "source-registry.json", "registry/task-registry.json"} sealing.require(required_support <= set(support), "archive lacks required source/registry snapshots") digest_path = inside(root, "archive-inventory.sha256") inventory_hash = digest_path.read_text(encoding="ascii").strip() sealing.digest(inventory_hash, "inventory hash") sealing.verify_payloads(root, inventory, inventory_hash) source = sealing.parse_json(inside(root, "source-inventory.json").read_bytes(), "snapshotted source inventory") relocated = sealing.parse_json(inside(root, "registry/task-registry.json").read_bytes(), "archived registry") original_registry = sealing.parse_json(inside(root, "source-registry.json").read_bytes(), "source registry snapshot") selected_signature = registry_signature(selected_registry) sealing.require(registry_signature(relocated) == selected_signature == registry_signature(original_registry), "incompatible task/rubric registry metadata or reference hashes") for task in relocated["tasks"]: for field in ("public_packet", "assessor_guide"): relative = "registry/"+task[field]["path"] sealing.require(relative in support, "registered reference is not inventoried") inside(root, relative) common_relative = "registry/"+relocated["common_conventions"]["path"] sealing.require(common_relative in support, "common conventions are not inventoried") inside(root, common_relative) tasks, _, _ = sealing.registry_data(relocated, root/"registry") source_records = {} for row in sealing.array(source["records"], "source records"): sealing.keys(row, ("record_id", "kind", "path", "sha256"), "source record") rid = sealing.text(row["record_id"], "source record ID") sealing.require(rid not in source_records and rid in archived, "duplicate/missing archived source record") sealing.text(row["path"], "original source path") # Source paths are metadata only. sealing.require(row["kind"] == archived[rid]["kind"], "source record kind mismatch") if row["sha256"] is not None: sealing.require(row["sha256"] == archived[rid]["sha256"], "prior source hash mismatch") source_records[rid] = row sealing.require(set(source_records) == set(archived) and inventory["runs"] == source["runs"], "archive does not preserve complete declared run/record inventory") runs, attempts, users = sealing.validate_inventory(source, source_records, tasks) snapshots = {rid: inside(root, row["path"]).read_bytes() for rid, row in archived.items()} sealing.validate_usage(source_records, snapshots, runs, attempts, users) for run in runs.values(): end = sealing.utc_optional(run["ended_at_utc"], "run end") sealing.require(end is None or end <= seal_time, "declared run ends after archive seal") for attempt in run["attempts"]: for field in ("started_at_utc", "ended_at_utc"): value = sealing.utc_optional(attempt[field], field) sealing.require(value is None or value <= seal_time, "declared attempt occurs after archive seal") unassessable = [dict(run_id=r["run_id"], condition_id=r["condition_id"], task_id=r["task_id"], repetition_id=r["repetition_id"], reason=r["endpoint_selection"]["basis"]) for r in runs.values() if r["endpoint_selection"]["artifact_id"] is None] sealing.require(inventory["unassessable_runs"] == unassessable, "unassessable runs omitted or inconsistent") expected_packet = dict(build_manifest_version="1.0", batch_id=source["batch_id"], seal_record_id=inventory["seal_record_id"], batch_sealed=True, sealed_at_utc=packet["sealed_at_utc"], independent_rater_ids=source["independent_rater_ids"], conditions=source["conditions"], runs=[]) for run in runs.values(): endpoint = run["endpoint_selection"]["artifact_id"] if endpoint is None: continue snapshots[endpoint].decode("utf-8") row = {k: run[k] for k in ("run_id", "condition_id", "task_id", "task_version", "rubric_version", "repetition_id")} row.update(sealed=True, sealed_at_utc=packet["sealed_at_utc"], final_artifact=dict(artifact_id=endpoint, path=archived[endpoint]["path"], sha256=archived[endpoint]["sha256"])) expected_packet["runs"].append(row) sealing.require(packet == expected_packet, "commit manifest is inconsistent with archived endpoints/identities") rows = [] for run in runs.values(): endpoint = run["endpoint_selection"]["artifact_id"] rows.append(dict(run_id=run["run_id"], condition_id=run["condition_id"], task_id=run["task_id"], task_version=run["task_version"], rubric_version=run["rubric_version"], family_id=tasks[run["task_id"]]["family_id"], repetition_id=run["repetition_id"], declared_status=run["run_status"], designated_endpoint_available=endpoint is not None, designated_endpoint_id=endpoint, declared_artifact_record_count=sum(source_records[r]["kind"] == "artifact" for r in run["record_ids"]), archive_seal_record_id=packet["seal_record_id"])) provenance = dict(archive=str(root), batch_id=packet["batch_id"], seal_record_id=packet["seal_record_id"], sealed_at_utc=packet["sealed_at_utc"], archive_inventory_sha256=inventory_hash, commit_manifest_sha256=sealing.sha(packet_bytes), registry_signature_sha256=sealing.sha(selected_signature)) return rows, source["conditions"], provenance def summarize_group(rows, expected, tasks): observed = {(r["condition_id"], r["task_id"], r["repetition_id"]) for r in rows} absent = sorted(expected-observed) denominator = len(rows) counts = {s: sum(r["declared_status"] == s for r in rows) for s in sealing.RUN_STATUSES} available = sum(r["designated_endpoint_available"] for r in rows) return dict(expected_run_cells=len(expected), observed_run_denominator=denominator, absent_run_cell_count=len(absent), coverage_complete=not absent, observed_cell_coverage=dict(numerator=len(observed), denominator=len(expected), fraction=None if not expected else len(observed)/len(expected)), status_counts=counts, status_rates_among_observed={s: dict(numerator=n, denominator=denominator, rate=None if denominator == 0 else n/denominator) for s, n in counts.items()}, endpoint_availability=dict(available=available, not_designated=denominator-available, denominator=denominator), runs_with_declared_artifact_records=sum(r["declared_artifact_record_count"] > 0 for r in rows), absent_cells=[dict(condition_id=c, task_id=t, family_id=tasks[t]["family_id"], repetition_id=rep) for c, t, rep in absent]) def summarize_archives(archive_paths, registry_path=None): registry_path = Path(registry_path or sealing.KIT/"task-registry.json").resolve() registry = sealing.parse_json(registry_path.read_bytes(), "selected registry") sealing.require(registry["kit_version"] == "1.0", "incompatible selected registry version") tasks, families, _ = sealing.registry_data(registry, registry_path.parent) sealing.require(archive_paths, "supply at least one sealed archive") paths, seals, run_ids, cells = set(), set(), set(), set() rows, provenance, conditions = [], [], {} for path in archive_paths: path = Path(path).resolve() sealing.require(path not in paths, "duplicate archive input") paths.add(path) archive_rows, declarations, record = load_archive(path, registry) sealing.require(record["seal_record_id"] not in seals, "duplicate archive seal identity") seals.add(record["seal_record_id"]) for declaration in declarations: conditions.setdefault(declaration["condition_id"], set()).update(declaration["repetition_ids"]) for row in archive_rows: cell = (row["condition_id"], row["task_id"], row["repetition_id"]) sealing.require(row["run_id"] not in run_ids and cell not in cells, "duplicate run identity or run cell across archives") run_ids.add(row["run_id"]) cells.add(cell) rows.append(row) provenance.append(record) expected = {(c, t, rep) for c, reps in conditions.items() for rep in reps for t in tasks} rows.sort(key=lambda r: (r["condition_id"], r["task_id"], r["repetition_id"])) return dict(outcome_report_version="1.0", notice=NOTICE, coordinator_only=True, defaults_unfrozen=True, status_policy="declared archived run_status; no semantic success inference", denominator_policy="observed archived runs only; absent expected cells are separate unknown coverage", requirement_satisfaction_evaluated=False, archives=provenance, condition_repetitions={c: sorted(reps) for c, reps in sorted(conditions.items())}, runs=rows, overall=summarize_group(rows, expected, tasks), by_condition={c: dict(summary=summarize_group([r for r in rows if r["condition_id"] == c], {x for x in expected if x[0] == c}, tasks), by_family={f: summarize_group([r for r in rows if r["condition_id"] == c and r["family_id"] == f], {x for x in expected if x[0] == c and x[1] in group}, tasks) for f, group in families.items()}) for c in sorted(conditions)}, by_family={f: summarize_group([r for r in rows if r["family_id"] == f], {x for x in expected if x[1] in group}, tasks) for f, group in families.items()}) def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--archives", type=Path, nargs="+", required=True) parser.add_argument("--registry", type=Path, default=sealing.KIT/"task-registry.json") args = parser.parse_args(argv) try: report = summarize_archives(args.archives, args.registry) except (sealing.ValidationError, sealing.account_resources.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(report, indent=2, allow_nan=False)) return 0 if __name__ == "__main__": sys.exit(main())