#!/usr/bin/env python3 """Offline blinded-packet preparation for explicitly declared sealed text artifacts. Development tooling. No model calls, rating generation, or semantic redaction. """ import argparse import copy from datetime import datetime, timezone import hashlib import json import os from pathlib import Path import random import sys import uuid from score_forms import (ValidationError, array, digest, keys, manifest_data, read_json, registry_data, require, strings, text, utc) BASE = Path(__file__).resolve().parent NOTICE = "Development packet-preparation tooling; packet creation is not assessment or experimental evidence." INSTRUCTIONS = """# Independent manual assessment Development packet-preparation tooling; no ratings are prefilled. The coordinator declares this batch sealed. Assess only the assigned artifact, its public packet, assessor guide, and common conventions. Read packet-index.json in its supplied presentation order and complete only your rating-form.json copy. Rate independently; do not consult another rater before both forms are locked. Criterion Cn maps to public Rn: use integer 1 only when the whole requirement is satisfied, otherwise integer 0. Accept supported alternatives, not just guide examples. Record precise artifact/public locations and a reason. Leave a genuinely unresolved ambiguity null with a note; do not add hidden requirements. Never treat missing ratings as zero. All judgments, evidence, times, and scores start blank. Do not open coordinator keys, prompts, memory, resource logs, or prior ratings. Do not return assessment feedback to adaptation. Report packet or blinding issues to the coordinator without editing the artifact. Artifact bytes are unchanged: intrinsic method disclosures in the text have NOT been removed. Folder separation and file names do NOT enforce confidentiality or demonstrate successful blinding. """ def hashed_bytes(path, expected): digest(expected, "source sha256") content = Path(path).read_bytes() require(hashlib.sha256(content).hexdigest() == expected, f"source hash mismatch: {path}") return content def blank_templates(path, tasks, mapping): form = read_json(path) keys(form, ("form_version", "form_type", "asset_status", "task_registry", "form_id", "batch_id", "seal_record_id", "rater_id", "locked_at_utc", "ratings"), "blank rating template") require(form["form_version"] == "1.0" and form["form_type"] == "independent_rating_batch" and form["asset_status"] == "untested_development_template", "incompatible blank rating template") require(all(form[k] is None for k in ("form_id", "batch_id", "seal_record_id", "rater_id", "locked_at_utc")), "rating template must be blank") result = {} for row in array(form["ratings"], "template ratings"): keys(row, ("rating_record_id", "blinded_artifact_id", "blinded_artifact_sha256", "task_id", "task_version", "rubric_version", "family_id", "assessment_status", "assessment_issue", "completed_at_utc", "criteria", "scores"), "blank rating record") tid = row["task_id"] require(tid in tasks and tid not in result, "unknown/duplicate template task") require(all(row[k] == tasks[tid][k] for k in ("task_version", "rubric_version", "family_id")), "template version/family mismatch") require(all(row[k] is None for k in ("rating_record_id", "blinded_artifact_id", "blinded_artifact_sha256", "assessment_status", "assessment_issue", "completed_at_utc")), "template record not blank") criteria = array(row["criteria"], "template criteria") require([(c["criterion_id"], c["public_requirement_id"]) for c in criteria] == mapping, "template criterion mapping mismatch") for criterion in criteria: keys(criterion, ("criterion_id", "public_requirement_id", "satisfaction", "artifact_evidence_locations", "public_basis_locations", "reason", "ambiguity_note"), "blank criterion") require(all(criterion[k] is None for k in ("satisfaction", "reason", "ambiguity_note")) and criterion["artifact_evidence_locations"] == [] and criterion["public_basis_locations"] == [], "criterion template must contain no observations") require(row["scores"] == dict(criterion_count=12, satisfied_criteria=None, requirement_satisfaction_score=None), "template scores not blank") result[tid] = row require(set(result) == set(tasks), "blank template must cover registry tasks") return form, result def output_path(path): path = Path(path).absolute() require(not os.path.lexists(path), f"refusing existing output: {path}") require(path.parent.is_dir(), f"output parent must already exist: {path.parent}") return path.resolve() def disjoint(left, right): return left != right and left not in right.parents and right not in left.parents def write_bytes(path, content): path.parent.mkdir(parents=True, exist_ok=True) with path.open("xb") as handle: handle.write(content) def write_json(path, value): write_bytes(path, (json.dumps(value, indent=2, allow_nan=False)+"\n").encode("utf-8")) def build_packets(manifest_path, packets_dir, coordinator_dir, registry_path=None, seed=0): require(type(seed) is int, "shuffle seed must be an integer") manifest_path = Path(manifest_path).resolve() registry_path = Path(registry_path or BASE/"task-registry.json").resolve() packets = output_path(packets_dir) coordinator = output_path(coordinator_dir) require(disjoint(packets, coordinator), "coordinator output must be outside and disjoint from rater output") manifest = read_json(manifest_path) keys(manifest, ("build_manifest_version", "batch_id", "seal_record_id", "batch_sealed", "sealed_at_utc", "independent_rater_ids", "conditions", "runs"), "build manifest") require(manifest["build_manifest_version"] == "1.0", "unsupported build manifest version") require(manifest["batch_sealed"] is True, "batch must be explicitly declared sealed") batch_time = utc(manifest["sealed_at_utc"], "batch sealed_at_utc") require(batch_time <= datetime.now(timezone.utc), "batch seal timestamp cannot be in the future") text(manifest["batch_id"], "batch_id") text(manifest["seal_record_id"], "seal_record_id") raters = manifest["independent_rater_ids"] strings(raters, "independent_rater_ids") require(len(raters) == len(set(raters)) == 2, "declare two distinct independent raters") registry = read_json(registry_path) require(registry["kit_version"] == "1.0", "unsupported registry version") tasks, _, mapping = registry_data(registry, registry_path.parent) form_template, templates = blank_templates(BASE/"rating-form.json", tasks, mapping) # Validate condition/repetition declarations using the existing coordinator # contract, before any outputs exist. Empty assignments intentionally allow # an explicitly sealed subset; downstream scoring still reports full coverage. contract = dict(manifest_version="1.0", batch_id=manifest["batch_id"], seal_record_id=manifest["seal_record_id"], independent_rater_ids=raters, conditions=manifest["conditions"], assignments=[]) _, conditions, _, _ = manifest_data(contract, tasks) source_runs = array(manifest["runs"], "runs") require(source_runs, "declare at least one sealed run") seen_runs, seen_artifacts, seen_paths, seen_cells = set(), set(), set(), set() loaded = [] for row in source_runs: keys(row, ("run_id", "condition_id", "task_id", "task_version", "rubric_version", "repetition_id", "sealed", "sealed_at_utc", "final_artifact"), "sealed run") rid = text(row["run_id"], "run_id") require(rid not in seen_runs, "duplicate run identity") require(row["sealed"] is True, "every declared run must be sealed") require(utc(row["sealed_at_utc"], "run sealed_at_utc") <= batch_time, "run sealed after declared batch seal") require(row["task_id"] in tasks, "unknown task") task = tasks[row["task_id"]] require(all(row[k] == task[k] for k in ("task_version", "rubric_version")), "task/rubric version mismatch") cid, rep = row["condition_id"], row["repetition_id"] require(cid in conditions and rep in conditions[cid], "undeclared condition/repetition") cell = (cid, row["task_id"], rep) require(cell not in seen_cells, "duplicate condition/task/repetition identity") source = row["final_artifact"] keys(source, ("artifact_id", "path", "sha256"), "final_artifact") aid = text(source["artifact_id"], "source artifact_id") source_path = (manifest_path.parent/text(source["path"], "artifact path")).resolve() require(aid not in seen_artifacts and source_path not in seen_paths, "duplicate source artifact identity/path") content = hashed_bytes(source_path, source["sha256"]) try: content.decode("utf-8") except UnicodeDecodeError as exc: raise ValidationError("final artifact must be UTF-8 text; bytes are never transcoded") from exc seen_runs.add(rid) seen_artifacts.add(aid) seen_paths.add(source_path) seen_cells.add(cell) loaded.append(dict(source=row, source_path=str(source_path), content=content)) # Snapshot and verify each copied reference's bytes during preflight. references = {} conventions = registry["common_conventions"] references["assessor-only/README.md"] = hashed_bytes(registry_path.parent/conventions["path"], conventions["sha256"]) task_paths = {} for tid in sorted({r["source"]["task_id"] for r in loaded}): task_paths[tid] = {} for field, directory in (("public_packet", "public"), ("assessor_guide", "assessor-only")): asset = tasks[tid][field] relative = directory+"/"+Path(asset["path"]).name content = hashed_bytes(registry_path.parent/asset["path"], asset["sha256"]) require(relative not in references or references[relative] == content, "reference output name collision") references[relative] = content task_paths[tid][field] = relative issued = set() def opaque(prefix): value = prefix+"-"+uuid.uuid4().hex require(value not in issued, "opaque ID collision") issued.add(value) return value batch_id, seal_id = opaque("batch"), opaque("seal") rater_map = {r: opaque("rater") for r in raters} scoring_manifest = dict(manifest_version="1.0", batch_id=batch_id, seal_record_id=seal_id, independent_rater_ids=list(rater_map.values()), conditions=copy.deepcopy(manifest["conditions"]), assignments=[]) key = dict(packet_builder_version="1.0", notice=NOTICE, source_batch_id=manifest["batch_id"], source_seal_record_id=manifest["seal_record_id"], source_sealed_at_utc=manifest["sealed_at_utc"], batch_id=batch_id, seal_record_id=seal_id, source_manifest_sha256=hashlib.sha256(manifest_path.read_bytes()).hexdigest(), source_registry_sha256=hashlib.sha256(registry_path.read_bytes()).hexdigest(), shuffle_seed=seed, defaults_unfrozen=True, rater_aliases=rater_map, artifacts=[], presentations={}) # Canonical source identity order makes the source-artifact presentation # permutation reproducible with a seed; UUID aliases themselves are not seeded. loaded.sort(key=lambda r: r["source"]["final_artifact"]["artifact_id"]) for item in loaded: source = item["source"] tid = source["task_id"] item["blinded_id"] = opaque("artifact") assignment = dict(blinded_artifact_id=item["blinded_id"], blinded_artifact_sha256=source["final_artifact"]["sha256"], task_id=tid, task_version=tasks[tid]["task_version"], rubric_version=tasks[tid]["rubric_version"], family_id=tasks[tid]["family_id"], condition_id=source["condition_id"], repetition_id=source["repetition_id"]) scoring_manifest["assignments"].append(assignment) key["artifacts"].append(dict(source_artifact_id=source["final_artifact"]["artifact_id"], run_id=source["run_id"], source_path=item["source_path"], **assignment)) manifest_data(scoring_manifest, tasks) rng = random.Random(seed) bundles = [] for source_rater in raters: alias = rater_map[source_rater] ordered = list(loaded) rng.shuffle(ordered) form = copy.deepcopy(form_template) form.update(form_id=opaque("form"), batch_id=batch_id, seal_record_id=seal_id, rater_id=alias, task_registry="packet-index.json", ratings=[]) index = dict(packet_version="1.0", notice=NOTICE, batch_id=batch_id, seal_record_id=seal_id, rater_id=alias, form_id=form["form_id"], artifacts=[]) for item in ordered: source = item["source"] tid, blind = source["task_id"], item["blinded_id"] row = copy.deepcopy(templates[tid]) row.update(rating_record_id=opaque("rating"), blinded_artifact_id=blind, blinded_artifact_sha256=source["final_artifact"]["sha256"]) form["ratings"].append(row) index["artifacts"].append(dict(blinded_artifact_id=blind, sha256=source["final_artifact"]["sha256"], task_id=tid, task_version=row["task_version"], rubric_version=row["rubric_version"], family_id=row["family_id"], artifact_path="artifacts/"+blind+".txt", public_packet_path=task_paths[tid]["public_packet"], assessor_guide_path=task_paths[tid]["assessor_guide"], conventions_path="assessor-only/README.md")) key["presentations"][alias] = dict(form_id=form["form_id"], artifact_order=[i["blinded_id"] for i in ordered], rating_record_ids=[r["rating_record_id"] for r in form["ratings"]]) bundles.append((alias, form, index, ordered)) # No output is created until every declared seal, identity, hash, source, # template and generated scoring assignment has passed preflight. mkdir/open # are exclusive: never merge into or overwrite an existing destination. packets.mkdir() coordinator.mkdir() for alias, form, index, ordered in bundles: root = packets/alias root.mkdir() for relative, content in references.items(): write_bytes(root/relative, content) for item in ordered: write_bytes(root/"artifacts"/(item["blinded_id"]+".txt"), item["content"]) write_json(root/"rating-form.json", form) write_json(root/"packet-index.json", index) write_bytes(root/"RATER-INSTRUCTIONS.md", INSTRUCTIONS.encode("utf-8")) write_json(coordinator/"coordinator-manifest.json", scoring_manifest) write_json(coordinator/"packet-key.json", key) write_bytes(coordinator/"BUILD_COMPLETE", (NOTICE+"\n").encode()) write_bytes(packets/"BUILD_COMPLETE", (NOTICE+"\n").encode()) return dict(packet_builder_version="1.0", notice=NOTICE, rater_packets_dir=str(packets), coordinator_dir=str(coordinator), artifact_count=len(loaded), rater_bundle_count=len(bundles)) def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--manifest", type=Path, required=True) parser.add_argument("--packets-dir", type=Path, required=True) parser.add_argument("--coordinator-dir", type=Path, required=True) parser.add_argument("--registry", type=Path, default=BASE/"task-registry.json") parser.add_argument("--seed", type=int, default=0) args = parser.parse_args(argv) try: result = build_packets(args.manifest, args.packets_dir, args.coordinator_dir, args.registry, args.seed) except (ValidationError, OSError, KeyError, TypeError, ValueError) as exc: print(json.dumps(dict(error=str(exc), notice=NOTICE)), file=sys.stderr) return 2 print(json.dumps(result, indent=2)) return 0 if __name__ == "__main__": sys.exit(main())