[A-Z])")
+BYTE_SIZES = {
+ "L": 1,
+ "A": 1,
+ "B": 1,
+ "I": 2,
+ "J": 4,
+ "K": 8,
+ "E": 4,
+ "D": 8,
+}
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+def sha256_file(path: Path) -> str:
+ h = hashlib.sha256()
+ with path.open("rb") as f:
+ for chunk in iter(lambda: f.read(1024 * 1024), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def run(cmd: list[str]) -> subprocess.CompletedProcess:
+ return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+
+
+def rclone_copyto(local: Path, remote: str) -> tuple[bool, str]:
+ proc = run(["rclone", "copyto", str(local), remote, "--checksum"])
+ message = (proc.stderr or proc.stdout).decode(errors="replace").strip()
+ return proc.returncode == 0, message
+
+
+def download(url: str, target: Path, timeout: int) -> None:
+ target.parent.mkdir(parents=True, exist_ok=True)
+ part = target.with_suffix(target.suffix + ".part")
+ req = Request(url, headers={"User-Agent": "ResearchStack-DAPallSeed/0"})
+ with urlopen(req, timeout=timeout) as response, part.open("wb") as out:
+ while True:
+ chunk = response.read(1024 * 1024)
+ if not chunk:
+ break
+ out.write(chunk)
+ part.replace(target)
+
+
+def card_value(card: str):
+ if len(card) < 10 or card[8] != "=":
+ return None
+ raw = card[10:80].split("/", 1)[0].strip()
+ if raw.startswith("'"):
+ end = raw.rfind("'")
+ return raw[1:end].strip() if end > 0 else raw.strip("'").strip()
+ if raw in {"T", "F"}:
+ return raw == "T"
+ try:
+ return int(raw)
+ except ValueError:
+ try:
+ return float(raw.replace("D", "E"))
+ except ValueError:
+ return raw
+
+
+def read_header(f) -> tuple[dict, int]:
+ cards: list[str] = []
+ bytes_read = 0
+ while True:
+ block = f.read(2880)
+ if not block:
+ raise EOFError("unexpected EOF while reading FITS header")
+ bytes_read += len(block)
+ for i in range(0, len(block), 80):
+ card = block[i : i + 80].decode("ascii", errors="replace")
+ cards.append(card)
+ if card.startswith("END"):
+ header: dict[str, object] = {}
+ for item in cards:
+ key = item[:8].strip()
+ if not key:
+ continue
+ value = card_value(item)
+ if value is not None:
+ header[key] = value
+ return header, bytes_read
+
+
+def padded_size(size: int) -> int:
+ return int(math.ceil(size / 2880.0) * 2880)
+
+
+def parse_tform(value: str) -> tuple[int, str, int]:
+ match = TFORM_RE.match(value.strip())
+ if not match:
+ raise ValueError(f"unsupported TFORM {value!r}")
+ repeat = int(match.group("repeat") or "1")
+ code = match.group("code")
+ if code == "X":
+ # FITS bit arrays are counted in bits.
+ width = int(math.ceil(repeat / 8))
+ else:
+ width = repeat * BYTE_SIZES.get(code, 0)
+ if width <= 0:
+ raise ValueError(f"unsupported TFORM {value!r}")
+ return repeat, code, width
+
+
+def build_columns(header: dict) -> list[dict]:
+ cols = []
+ offset = 0
+ tfields = int(header.get("TFIELDS", 0))
+ for idx in range(1, tfields + 1):
+ name = str(header.get(f"TTYPE{idx}", f"COL{idx}")).strip()
+ form = str(header.get(f"TFORM{idx}", "")).strip()
+ repeat, code, width = parse_tform(form)
+ cols.append(
+ {
+ "idx": idx,
+ "name": name,
+ "form": form,
+ "repeat": repeat,
+ "code": code,
+ "width": width,
+ "offset": offset,
+ }
+ )
+ offset += width
+ return cols
+
+
+def decode_value(raw: bytes, col: dict):
+ repeat = col["repeat"]
+ code = col["code"]
+ if code == "A":
+ return raw.decode("ascii", errors="replace").strip()
+ if code == "L":
+ vals = [bytes([b]).decode("ascii", errors="replace") == "T" for b in raw[:repeat]]
+ return vals[0] if repeat == 1 else vals
+ if code == "B":
+ vals = list(raw[:repeat])
+ return vals[0] if repeat == 1 else vals
+ fmt = {
+ "I": ">h",
+ "J": ">i",
+ "K": ">q",
+ "E": ">f",
+ "D": ">d",
+ }.get(code)
+ if not fmt:
+ return None
+ size = struct.calcsize(fmt)
+ vals = [
+ struct.unpack(fmt, raw[i * size : (i + 1) * size])[0]
+ for i in range(repeat)
+ ]
+ vals = [None if isinstance(v, float) and (math.isnan(v) or math.isinf(v)) else v for v in vals]
+ return vals[0] if repeat == 1 else vals
+
+
+def interesting_columns(columns: list[dict]) -> list[dict]:
+ patterns = [
+ "plateifu",
+ "mangaid",
+ "objra",
+ "objdec",
+ "nsa_z",
+ "z",
+ "emline",
+ "ha_",
+ "hb_",
+ "oiii",
+ "nii",
+ "sii",
+ "sigma",
+ "vel",
+ "snr",
+ "daptype",
+ ]
+ selected = []
+ for col in columns:
+ lname = col["name"].lower()
+ if any(pattern in lname for pattern in patterns):
+ selected.append(col)
+ # Keep identifiers even if a future naming change misses them.
+ selected = selected[:80]
+ return selected
+
+
+def classify_column(name: str) -> str:
+ lname = name.lower()
+ if lname in {"plateifu", "mangaid", "daptype"}:
+ return "identifier"
+ if "emline" in lname or any(line in lname for line in ["ha_", "hb_", "oiii", "nii", "sii"]):
+ return "gas_emission_line_or_fit"
+ if "sigma" in lname or "vel" in lname:
+ return "shock_or_velocity_proxy"
+ if lname in {"objra", "objdec", "nsa_z", "z"} or lname.endswith("_z"):
+ return "position_or_redshift_context"
+ if "snr" in lname:
+ return "quality_or_uncertainty_proxy"
+ return "context"
+
+
+def scan_fits(path: Path, sample_rows: int) -> dict:
+ hdus = []
+ samples = []
+ with path.open("rb") as f:
+ hdu_index = 0
+ while True:
+ start = f.tell()
+ try:
+ header, header_bytes = read_header(f)
+ except EOFError:
+ break
+ data_start = f.tell()
+ xtension = str(header.get("XTENSION", "PRIMARY"))
+ bitpix = int(header.get("BITPIX", 8))
+ naxis = int(header.get("NAXIS", 0))
+ if xtension == "BINTABLE":
+ row_len = int(header["NAXIS1"])
+ row_count = int(header["NAXIS2"])
+ pcount = int(header.get("PCOUNT", 0))
+ data_size = row_len * row_count + pcount
+ columns = build_columns(header)
+ selected = interesting_columns(columns)
+ hdu_info = {
+ "hdu_index": hdu_index,
+ "name": header.get("EXTNAME", f"HDU{hdu_index}"),
+ "xtension": xtension,
+ "row_count": row_count,
+ "row_len": row_len,
+ "column_count": len(columns),
+ "selected_column_count": len(selected),
+ "selected_columns": [
+ {
+ "name": col["name"],
+ "form": col["form"],
+ "semantic_role": classify_column(col["name"]),
+ }
+ for col in selected
+ ],
+ }
+ hdus.append(hdu_info)
+ if selected and len(samples) < sample_rows:
+ rows_to_read = min(sample_rows - len(samples), row_count)
+ for row_idx in range(rows_to_read):
+ f.seek(data_start + row_idx * row_len)
+ row = f.read(row_len)
+ record = {
+ "hdu_index": hdu_index,
+ "row_index": row_idx,
+ "source_catalog": "SDSS_DR17_MaNGA_DAPall",
+ "model_family": "stellar_gas_observation_seed",
+ "gate_decision": "ADMIT_OBSERVATION_SAMPLE",
+ "fields": {},
+ "semantic_roles": {},
+ }
+ for col in selected:
+ raw = row[col["offset"] : col["offset"] + col["width"]]
+ value = decode_value(raw, col)
+ # Keep JSON compact for large vector columns.
+ if isinstance(value, list) and len(value) > 8:
+ value = {
+ "length": len(value),
+ "head": value[:4],
+ "tail": value[-4:],
+ }
+ record["fields"][col["name"]] = value
+ record["semantic_roles"][col["name"]] = classify_column(col["name"])
+ samples.append(record)
+ f.seek(data_start + padded_size(data_size))
+ else:
+ # Generic IMAGE/PRIMARY skip.
+ if naxis == 0:
+ data_size = 0
+ else:
+ pixels = 1
+ for axis in range(1, naxis + 1):
+ pixels *= int(header.get(f"NAXIS{axis}", 0))
+ data_size = abs(bitpix) // 8 * pixels
+ hdus.append(
+ {
+ "hdu_index": hdu_index,
+ "name": header.get("EXTNAME", "PRIMARY" if hdu_index == 0 else f"HDU{hdu_index}"),
+ "xtension": xtension,
+ "naxis": naxis,
+ }
+ )
+ f.seek(data_start + padded_size(data_size))
+ if f.tell() <= start:
+ raise RuntimeError("FITS scanner did not advance")
+ hdu_index += 1
+ return {"hdus": hdus, "samples": samples}
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--cache", type=Path, default=ARTIFACT_DIR / FITS_NAME)
+ parser.add_argument("--destination", default=DESTINATION)
+ parser.add_argument("--timeout", type=int, default=180)
+ parser.add_argument("--sample-rows", type=int, default=5)
+ parser.add_argument("--skip-download", action="store_true")
+ parser.add_argument("--skip-upload-raw", action="store_true")
+ args = parser.parse_args()
+
+ DATA_DIR.mkdir(parents=True, exist_ok=True)
+ ARTIFACT_DIR.mkdir(parents=True, exist_ok=True)
+
+ downloaded = False
+ if not args.cache.exists() and not args.skip_download:
+ download(FITS_URL, args.cache, args.timeout)
+ downloaded = True
+ if not args.cache.exists():
+ raise FileNotFoundError(args.cache)
+
+ fits_sha = sha256_file(args.cache)
+ fits_size = args.cache.stat().st_size
+ scan = scan_fits(args.cache, args.sample_rows)
+
+ sample_path = DATA_DIR / "sdss_manga_dapall_observation_sample.json"
+ sample_payload = {
+ "schema": "sdss_manga_dapall_observation_sample_v0",
+ "created": now_iso(),
+ "claim_boundary": "Bounded sample extracted from SDSS DR17 MaNGA DAPall FITS. This is not the full observation database; it is the first observation-backed schema seed.",
+ "source_url": FITS_URL,
+ "source_file_sha256": fits_sha,
+ "source_file_bytes": fits_size,
+ "sample_rows": scan["samples"],
+ }
+ sample_path.write_text(json.dumps(sample_payload, indent=2) + "\n")
+
+ column_path = DATA_DIR / "sdss_manga_dapall_column_map.json"
+ column_payload = {
+ "schema": "sdss_manga_dapall_column_map_v0",
+ "created": now_iso(),
+ "source_url": FITS_URL,
+ "source_file_sha256": fits_sha,
+ "source_file_bytes": fits_size,
+ "hdu_count": len(scan["hdus"]),
+ "hdus": scan["hdus"],
+ }
+ column_path.write_text(json.dumps(column_payload, indent=2) + "\n")
+
+ raw_remote = f"{args.destination.rstrip('/')}/raw/{FITS_NAME}"
+ sample_remote = f"{args.destination.rstrip('/')}/derived/{sample_path.name}"
+ column_remote = f"{args.destination.rstrip('/')}/derived/{column_path.name}"
+
+ raw_upload = {"drive_path": raw_remote, "ok": False, "message": "skipped"}
+ if not args.skip_upload_raw:
+ ok, msg = rclone_copyto(args.cache, raw_remote)
+ raw_upload = {"drive_path": raw_remote, "ok": ok, "message": msg}
+
+ sample_ok, sample_msg = rclone_copyto(sample_path, sample_remote)
+ column_ok, column_msg = rclone_copyto(column_path, column_remote)
+
+ receipt_path = DATA_DIR / f"sdss_manga_dapall_observation_seed_receipt_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+ receipt = {
+ "schema": "sdss_manga_dapall_observation_seed_receipt_v0",
+ "created": now_iso(),
+ "claim_boundary": "Promotes one public SDSS MaNGA catalog from route-only to observation-backed seed. Full FITS is cached under shared-data/artifacts and copied to Drive; tracked repo files are column map, sample, and receipt JSON.",
+ "source_url": FITS_URL,
+ "local_cache": str(args.cache.relative_to(REPO)) if args.cache.is_relative_to(REPO) else str(args.cache),
+ "downloaded_this_run": downloaded,
+ "fits_sha256": fits_sha,
+ "fits_bytes": fits_size,
+ "sample_file": str(sample_path.relative_to(REPO)),
+ "column_map_file": str(column_path.relative_to(REPO)),
+ "gdrive_uploads": {
+ "raw_fits": raw_upload,
+ "sample": {"drive_path": sample_remote, "ok": sample_ok, "message": sample_msg},
+ "column_map": {"drive_path": column_remote, "ok": column_ok, "message": column_msg},
+ },
+ "parse_summary": {
+ "hdu_count": len(scan["hdus"]),
+ "sample_count": len(scan["samples"]),
+ "bintable_hdus": [h for h in scan["hdus"] if h.get("xtension") == "BINTABLE"],
+ },
+ "model_refinement": {
+ "new_boundary": "route_only_to_observation_sample",
+ "observable_lanes": [
+ "emission-line gas diagnostics",
+ "velocity or velocity-dispersion shock proxies",
+ "redshift and sky-position context",
+ "quality or uncertainty proxies",
+ ],
+ "next_gate": "fit selected gas/shock columns against local shock eigen axes",
+ },
+ "decision": "ADMIT_OBSERVATION_BACKED_STELLAR_GAS_SEED"
+ if raw_upload["ok"] and sample_ok and column_ok and scan["samples"]
+ else "HOLD_PARTIAL_OBSERVATION_SEED",
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+ receipt_remote = f"{args.destination.rstrip('/')}/receipts/{receipt_path.name}"
+ receipt_ok, receipt_msg = rclone_copyto(receipt_path, receipt_remote)
+ receipt["gdrive_uploads"]["receipt"] = {
+ "drive_path": receipt_remote,
+ "ok": receipt_ok,
+ "message": receipt_msg,
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+ if receipt_ok:
+ rclone_copyto(receipt_path, receipt_remote)
+ print(json.dumps(receipt, indent=2))
+ return 0 if receipt["decision"].startswith("ADMIT") else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/4-Infrastructure/shim/semantic_compression_theoretical_limits_prior.py b/4-Infrastructure/shim/semantic_compression_theoretical_limits_prior.py
new file mode 100644
index 00000000..5732104e
--- /dev/null
+++ b/4-Infrastructure/shim/semantic_compression_theoretical_limits_prior.py
@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""Semantic compression theoretical-limits prior.
+
+This records the user's pasted Consensus thread as a route/evaluator prior.
+It is not a semantic-compression proof and it does not relax byte-exact
+promotion. The practical extraction is a set of limit coordinates that can
+shape DD pruning, receipts, and evaluator fields.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_RECEIPT = Path(
+ "4-Infrastructure/shim/semantic_compression_theoretical_limits_prior_receipt.json"
+)
+DEFAULT_CURRICULUM = Path(
+ "4-Infrastructure/shim/semantic_compression_theoretical_limits_prior_curriculum.jsonl"
+)
+
+
+CONSENSUS_SOURCE_SUMMARY = {
+ "thread_title": "Semantic Compression Theoretical Limits",
+ "prompt": "unified math models of theoretical limits in semantic compression",
+ "mode": "Deep",
+ "search_count": 21,
+ "citation_graph_uses": 1,
+ "retrieved_count_reported": 2_777_471,
+ "eligible_count_reported": 1_500,
+ "included_count_reported": 50,
+ "consensus_meter": {
+ "question": "Are there unified mathematical models that define the theoretical limits of semantic compression?",
+ "n": 9,
+ "yes_percent": 100,
+ },
+ "claim_boundary": (
+ "Consensus thread is a source-bundle prior. It supplies theoretical-limit "
+ "coordinates and citations, not local compression evidence."
+ ),
+}
+
+
+LIMIT_FAMILIES = [
+ {
+ "id": "semantic_information_bounds",
+ "source_examples": [
+ "Information-theoretic limits on compression of semantic information",
+ "A Mathematical Theory of Semantic Communication",
+ "Semantic Information Theory and Applications",
+ ],
+ "useful_shape": (
+ "model a semantic source with conditional independence, Bayesian or "
+ "probabilistic structure, and derive lower/upper rate bounds"
+ ),
+ "dd_use": "bound semantic-sidecar claims and require explicit semantic source model IDs",
+ "receipt_fields": [
+ "semantic_source_model_id",
+ "conditional_independence_receipt",
+ "semantic_entropy_bound_bits",
+ "side_information_policy",
+ ],
+ "failure_mode": "semantic bound claimed without an explicit source model or local byte receipt",
+ },
+ {
+ "id": "semantic_rate_distortion",
+ "source_examples": [
+ "Semantic Rate-Distortion Theory with Applications",
+ "A Rate-Distortion Framework for Characterizing Semantic Information",
+ "Semantic Compression with Side Information: A Rate-Distortion Perspective",
+ "Fundamental Limitation of Semantic Communications: Neural Estimation for Rate-Distortion",
+ ],
+ "useful_shape": (
+ "define a semantic distortion variable, estimate or bound the semantic "
+ "rate-distortion function, and compare rate against task outcome"
+ ),
+ "dd_use": "treat semantic distortion as a diagnostic constraint, never as byte promotion",
+ "receipt_fields": [
+ "semantic_distortion_metric_id",
+ "rate_distortion_estimator_id",
+ "side_information_bits",
+ "task_success_metric",
+ ],
+ "failure_mode": "semantic distortion score improves while decoded bytes do not match",
+ },
+ {
+ "id": "rate_distortion_perception_bottleneck",
+ "source_examples": [
+ "Rate-Distortion-Perception Trade-Off in Information Theory, Generative Models, and Intelligent Communications",
+ "Semantic Communication via Rate Distortion Perception Bottleneck",
+ "Rate-Distortion-Perception Theory for Semantic Communication",
+ ],
+ "useful_shape": (
+ "perceptual constraints may require extra rate; bottleneck objective "
+ "balances task/perception/bit distortion"
+ ),
+ "dd_use": "charge perceptual or semantic witness bytes explicitly in the route budget",
+ "receipt_fields": [
+ "perception_constraint_id",
+ "bottleneck_lambda",
+ "extra_rate_for_perception_bits",
+ "diagnostic_quality_score",
+ ],
+ "failure_mode": "perception quality hides sidecar or witness debt",
+ },
+ {
+ "id": "information_bottleneck_and_ordered_latents",
+ "source_examples": [
+ "Efficient compression in color naming and its evolution",
+ "Information-Ordered Bottlenecks for Adaptive Semantic Compression",
+ "Ordered embeddings and intrinsic dimensionalities with information-ordered bottlenecks",
+ "Adversarial Information Bottleneck",
+ ],
+ "useful_shape": (
+ "compress observations while preserving task-relevant variables; order "
+ "latent coordinates by marginal information or robustness"
+ ),
+ "dd_use": "rank route features and prune low-information sidecar lanes",
+ "receipt_fields": [
+ "bottleneck_variable_id",
+ "relevance_variable_id",
+ "marginal_information_gain",
+ "robustness_receipt_id",
+ ],
+ "failure_mode": "latent relevance score treated as an exact rehydration witness",
+ },
+ {
+ "id": "geometric_algebraic_error_subspaces",
+ "source_examples": [
+ "Geometry is All You Need: A Unified Taxonomy of Matrix and Tensor Factorization for Compression of Generative Language Models",
+ "A General Error-Theoretical Analysis Framework for Constructing Compression Strategies",
+ "Bridging Information-Theoretic and Geometric Compression in Language Models",
+ ],
+ "useful_shape": (
+ "parameter/data compression can be expressed through intrinsic dimension, "
+ "factorization geometry, or error subspace shape"
+ ),
+ "dd_use": "use geometry as route-feature coordinates and error-budget priors",
+ "receipt_fields": [
+ "intrinsic_dimension_estimate",
+ "factorization_family_id",
+ "error_subspace_shape_id",
+ "layerwise_budget_vector",
+ ],
+ "failure_mode": "geometric compactness confused with source-byte compression",
+ },
+ {
+ "id": "llm_understanding_compression_link",
+ "source_examples": [
+ "Lossless data compression by large models",
+ "Semantic Compression with Large Language Models",
+ "Language Modeling Is Compression",
+ "Fundamental Limits of Prompt Compression: A Rate-Distortion Framework for Black-Box Language Models",
+ ],
+ "useful_shape": (
+ "large learned models can improve compression by prediction/understanding, "
+ "but introduce hallucination, context compression, and compute costs"
+ ),
+ "dd_use": "allow LLM routes as proposal/predictor engines with strict byte rehydration checks",
+ "receipt_fields": [
+ "model_id",
+ "prompt_compression_ratio",
+ "hallucination_guard_id",
+ "context_rehydration_hash",
+ "compute_budget_ms",
+ ],
+ "failure_mode": "LLM reconstruction is semantically plausible but byte-invalid",
+ },
+ {
+ "id": "synonymity_and_semantic_arithmetic_coding",
+ "source_examples": [
+ "Semantic Arithmetic Coding Using Synonymous Mappings",
+ "The Semantic Relations in LLMs: An Information-theoretic Compression Approach",
+ "Preserving quality of information by using semantic relationships",
+ ],
+ "useful_shape": (
+ "synonym or semantic-equivalence classes can reduce semantic code length "
+ "when the equivalence relation is explicit"
+ ),
+ "dd_use": "map synonym classes to tokenbook proposals and residualize exact lexical choice",
+ "receipt_fields": [
+ "semantic_equivalence_class_id",
+ "synonym_map_hash",
+ "lexical_residual_bytes",
+ "equivalence_ambiguity_count",
+ ],
+ "failure_mode": "semantic equivalence discards lexical bytes without residual repair",
+ },
+ {
+ "id": "resource_constrained_semantic_limits",
+ "source_examples": [
+ "Compression Ratio Allocation for Probabilistic Semantic Communication With RSMA",
+ "A Joint Communication and Computation Design for Probabilistic Semantic Communications",
+ "Semantic Rate Distortion and Posterior Design: Compute Constraints, Multimodality, and Strategic Inference",
+ "Semantic Communication with Side Information: A Rate-Distortion Perspective",
+ ],
+ "useful_shape": (
+ "rate, compute, memory, side information, and multi-user allocation all "
+ "change the achievable semantic limit"
+ ),
+ "dd_use": "make runtime, memory, sidecar, and witness budgets first-class route constraints",
+ "receipt_fields": [
+ "byte_budget",
+ "compute_budget_ms",
+ "memory_budget_bytes",
+ "side_information_bytes",
+ "allocation_policy_id",
+ ],
+ "failure_mode": "semantic route appears efficient only by ignoring compute or side-information cost",
+ },
+ {
+ "id": "ambiguity_multimodality_and_generalization_gap",
+ "source_examples": [
+ "Compression Beyond Pixels: Semantic Compression with Multimodal Foundation Models",
+ "Can Image Compression Rely on CLIP?",
+ "Semantic Rate Distortion and Posterior Design: Compute Constraints, Multimodality, and Strategic Inference",
+ "On the Fundamental Limits of LLMs at Scale",
+ ],
+ "useful_shape": (
+ "ambiguity, polysemy, multimodality, hallucination, and retrieval fragility "
+ "limit transfer from theoretical semantic rates to real systems"
+ ),
+ "dd_use": "force ambiguity packets and multimodal claim boundaries before promotion",
+ "receipt_fields": [
+ "ambiguity_class_id",
+ "polysemy_count",
+ "modality_set",
+ "retrieval_fragility_score",
+ "generalization_scope",
+ ],
+ "failure_mode": "semantic limit validated on narrow data is applied to a broader corpus slice",
+ },
+]
+
+
+THEORETICAL_RECEIPT_RULES = {
+ "ratio_schema": "source_bytes / compressed_total_bytes",
+ "semantic_limit_status": "diagnostic unless byte_rehydration_hash matches",
+ "promotion_rule": (
+ "promote iff semantic-limit machinery only proposes, bounds, or budgets "
+ "routes; exact residual lanes restore source bytes; decoded hash matches; "
+ "and measured total bytes beat incumbent under explicit ratio_schema"
+ ),
+ "failure_rule": (
+ "semantic entropy, rate-distortion, bottleneck, perceptual quality, LLM "
+ "understanding, or synonymity without byte-exact restoration is diagnostic only"
+ ),
+}
+
+
+def stable_hash(obj: Any) -> str:
+ payload = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+ return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def build_receipt() -> dict[str, Any]:
+ source_hash = stable_hash(CONSENSUS_SOURCE_SUMMARY)
+ receipt: dict[str, Any] = {
+ "schema": "semantic_compression_theoretical_limits_prior_v1",
+ "generated_at": "2026-05-08T00:00:00+00:00",
+ "source_summary": CONSENSUS_SOURCE_SUMMARY,
+ "source_summary_hash": source_hash,
+ "claim_boundary": (
+ "Theoretical semantic-compression models define proposal and budget "
+ "surfaces. They do not establish local byte compression unless the "
+ "route has a local encode/decode/hash/byte-count receipt."
+ ),
+ "limit_families": LIMIT_FAMILIES,
+ "theoretical_receipt_rules": THEORETICAL_RECEIPT_RULES,
+ "dd_state_extension": [
+ "semantic_source_model_id",
+ "semantic_entropy_bound_bits",
+ "semantic_distortion_metric_id",
+ "rate_distortion_estimator_id",
+ "bottleneck_variable_id",
+ "marginal_information_gain",
+ "intrinsic_dimension_estimate",
+ "error_subspace_shape_id",
+ "semantic_equivalence_class_id",
+ "lexical_residual_bytes",
+ "side_information_bytes",
+ "compute_budget_ms",
+ "ambiguity_class_id",
+ "byte_rehydration_hash",
+ ],
+ "candidate_dd_edges": [
+ "choose_semantic_source_model",
+ "estimate_semantic_entropy_bound",
+ "estimate_semantic_rate_distortion",
+ "apply_information_bottleneck_rank",
+ "emit_geometric_error_subspace",
+ "propose_llm_predictor_route",
+ "emit_synonym_class_tokenbook",
+ "charge_side_information_budget",
+ "record_ambiguity_packet",
+ "emit_exact_residual_lane",
+ "verify_byte_rehydration_hash",
+ "reject_semantic_only_promotion",
+ ],
+ }
+ receipt["receipt_hash"] = stable_hash(receipt)
+ return receipt
+
+
+def curriculum_records(receipt: dict[str, Any]) -> list[dict[str, Any]]:
+ system = (
+ "You are a semantic-compression limit router. Treat theory as a "
+ "budget/proposal surface and byte-exact receipts as promotion authority."
+ )
+ records: list[dict[str, Any]] = []
+ for family in receipt["limit_families"]:
+ records.append(
+ {
+ "messages": [
+ {"role": "system", "content": system},
+ {
+ "role": "user",
+ "content": json.dumps(
+ {
+ "task": "route_semantic_compression_limit_family",
+ "family_id": family["id"],
+ "useful_shape": family["useful_shape"],
+ "dd_use": family["dd_use"],
+ },
+ ensure_ascii=False,
+ ),
+ },
+ {
+ "role": "assistant",
+ "content": json.dumps(
+ {
+ "selected": True,
+ "receipt_fields": family["receipt_fields"],
+ "failure_mode": family["failure_mode"],
+ "claim_boundary": "semantic-limit-prior-only",
+ "promotion_authority": "local encode/decode/hash/byte-count receipt",
+ },
+ ensure_ascii=False,
+ ),
+ },
+ ]
+ }
+ )
+ return records
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--receipt", type=Path, default=DEFAULT_RECEIPT)
+ parser.add_argument("--curriculum", type=Path, default=DEFAULT_CURRICULUM)
+ args = parser.parse_args()
+
+ receipt = build_receipt()
+ args.receipt.parent.mkdir(parents=True, exist_ok=True)
+ args.receipt.write_text(json.dumps(receipt, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+ with args.curriculum.open("w", encoding="utf-8") as handle:
+ for record in curriculum_records(receipt):
+ handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+ print(json.dumps(receipt, indent=2, ensure_ascii=False))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/semantic_topology_compression_regimes.py b/4-Infrastructure/shim/semantic_topology_compression_regimes.py
new file mode 100644
index 00000000..2d3ce3c8
--- /dev/null
+++ b/4-Infrastructure/shim/semantic_topology_compression_regimes.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Semantic topology compression regimes for metaprobe/LLM tuning.
+
+The regimes are intentionally blunt:
+
+* beautiful: stable topological folding across compatible semantic basins
+* ugly: asymmetric pruning that preserves statistical structure but drops context
+* horrible: manifold tearing / singularity where bindings become incompatible
+
+The output is a training prior and receipt taxonomy, not a proof of semantic
+geometry. Lean can later formalize the predicates and destruction rules.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+REGIMES = [
+ {
+ "id": "beautiful_topological_folding",
+ "label": "beautiful",
+ "condition": "shared_invariant_high and torsion_low and round_trip_loss_low",
+ "operation": "fold compatible semantic basins into a dense shared coordinate",
+ "payload": ["shared_invariant", "fold_map", "torsion", "round_trip_loss", "receipt_hash"],
+ "failure_mode": "false_friend_fold",
+ "lean_predicate_hint": "StableFold(a,b) := invariant_overlap a b >= tau ∧ torsion a b <= eps",
+ },
+ {
+ "id": "ugly_asymmetric_pruning",
+ "label": "ugly",
+ "condition": "statistical_structure_high and indexical_structure_discarded and quality_delta_bounded",
+ "operation": "shear off low-information or indexical volume while preserving routing basin",
+ "payload": ["retained_terms", "dropped_context", "distortion", "quality_delta", "source_boundary"],
+ "failure_mode": "nuance_collapse",
+ "lean_predicate_hint": "AdmissiblePrune(x,y) := preserves_basin x y ∧ distortion x y <= budget",
+ },
+ {
+ "id": "horrible_manifold_tearing",
+ "label": "horrible",
+ "condition": "torsion_high or contradiction_high or round_trip_loss_unbounded",
+ "operation": "mark incompatible bindings as torn; isolate detached semantic mass instead of merging",
+ "payload": ["contradiction_witness", "tear_boundary", "detached_mass_id", "origin_block", "repair_rule"],
+ "failure_mode": "semantic_singularity",
+ "lean_predicate_hint": "TornBinding(a,b) := torsion a b > max_torsion ∨ contradiction a b",
+ },
+]
+
+
+def chat_record(system: str, prompt: dict[str, Any], answer: dict[str, Any]) -> dict[str, Any]:
+ return {
+ "messages": [
+ {"role": "system", "content": system},
+ {"role": "user", "content": json.dumps(prompt, ensure_ascii=False)},
+ {"role": "assistant", "content": json.dumps(answer, ensure_ascii=False)},
+ ]
+ }
+
+
+def curriculum_records(receipt: dict[str, Any]) -> list[dict[str, Any]]:
+ system = "You are a semantic topology compression router. Classify regimes and emit receipt boundaries."
+ records: list[dict[str, Any]] = []
+ for regime in receipt["regimes"]:
+ records.append(
+ chat_record(
+ system,
+ {
+ "task": "classify_semantic_compression_regime",
+ "regime": regime["label"],
+ "condition": regime["condition"],
+ "operation": regime["operation"],
+ "instruction": "Return how this regime should route a compressed semantic binding.",
+ },
+ {
+ "selected": True,
+ "regime_id": regime["id"],
+ "operation": regime["operation"],
+ "claim_boundary": "semantic-topology-prior-only",
+ "receipt_payload": regime["payload"],
+ "failure_mode": regime["failure_mode"],
+ "lean_predicate_hint": regime["lean_predicate_hint"],
+ },
+ )
+ )
+ return records
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--receipt", type=Path, default=Path("4-Infrastructure/shim/semantic_topology_compression_regimes_receipt.json"))
+ parser.add_argument("--curriculum", type=Path, default=Path("4-Infrastructure/shim/semantic_topology_compression_regimes_curriculum.jsonl"))
+ args = parser.parse_args()
+
+ receipt = {
+ "schema": "semantic_topology_compression_regimes_v1",
+ "claim_boundary": "Compression regimes classify folding/pruning/tearing decisions; Lean or metaprobe receipts are required for local claims.",
+ "regimes": REGIMES,
+ "lawful": True,
+ }
+ args.receipt.parent.mkdir(parents=True, exist_ok=True)
+ args.receipt.write_text(json.dumps(receipt, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+ with args.curriculum.open("w", encoding="utf-8") as handle:
+ for record in curriculum_records(receipt):
+ handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+ print(json.dumps(receipt, indent=2, ensure_ascii=False))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/shadow_layer_opportunity_map.py b/4-Infrastructure/shim/shadow_layer_opportunity_map.py
new file mode 100644
index 00000000..b8c60913
--- /dev/null
+++ b/4-Infrastructure/shim/shadow_layer_opportunity_map.py
@@ -0,0 +1,576 @@
+#!/usr/bin/env python3
+"""Receipt-backed map of domains suited for refined shadow-layer encoding.
+
+Shadow encoding applies when a visible low-dimensional object is best treated
+as a projection of a richer typed state. The visible layer can be compact, but
+only if the hidden state, adapter, residual, closure policy, and algebraic
+accumulator path are receipted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+OUT_DIR = REPO / "shared-data" / "data" / "shadow_layer_opportunities"
+MAP = OUT_DIR / "shadow_layer_opportunity_map.json"
+RECEIPT = OUT_DIR / "shadow_layer_opportunity_map_receipt.json"
+SUMMARY = OUT_DIR / "shadow_layer_opportunity_map.md"
+
+SOURCE_REFS = [
+ REPO / "4-Infrastructure" / "shim" / "mmff_rigid_body_geometry_probe.py",
+ REPO / "shared-data" / "data" / "mmff_rigid_body_geometry" / "mmff_rigid_body_geometry_receipt.json",
+ REPO / "6-Documentation" / "docs" / "specs" / "FORWARD_FOUNDATION_EQUATION_COMPILER.md",
+ REPO / "6-Documentation" / "docs" / "specs" / "GCCL_ENCODING_CONTRACT.md",
+ REPO / "6-Documentation" / "docs" / "specs" / "GENSIS_COMPILER_SPEC.md",
+ REPO / "6-Documentation" / "docs" / "specs" / "PROJECTABLE_GEOMETRY_COMPRESSOR_SPEC.md",
+ REPO / "6-Documentation" / "articles" / "meme-math-that-pays-rent" / "article.md",
+ REPO / "0-Core-Formalism" / "otom" / "tools" / "lean" / "Semantics" / "Semantics" / "LochMonsterFilter.lean",
+ REPO / "shared-data" / "data" / "bibliographic_event_horizon" / "bibliographic_event_horizon_receipt.json",
+ REPO / "shared-data" / "data" / "asymptotic_closure_horizon" / "asymptotic_closure_horizon_receipt.json",
+]
+
+EXTERNAL_CITATIONS = [
+ {
+ "id": "immaterialscience_bibliographic_event_horizon",
+ "title": "The Bibliographic Event Horizon: A Study on the Gravitational Pull of [1]",
+ "url": "https://www.immaterialscience.org/2026/citations",
+ "role": "bibliographic_shadow_prompt",
+ "status": "satirical_source_used_as_real_diagnostic_prompt",
+ },
+ {
+ "id": "reddit_bibliographic_event_horizon_discussion",
+ "title": "Reddit discussion wrapper for bibliographic event horizon prompt",
+ "url": "https://www.reddit.com/r/ImmaterialScience/comments/1t7plf9/the_bibliographic_event_horizon_a_study_on_the/",
+ "role": "discussion_pointer",
+ "status": "metadata_only",
+ },
+ {
+ "id": "charmm_mmff_docs",
+ "title": "CHARMM MMFF documentation",
+ "url": "https://www.charmm-gui.org/charmmdoc/mmff.html",
+ "role": "molecular_shadow_reference",
+ "status": "external_reference",
+ },
+ {
+ "id": "openbabel_mmff94_docs",
+ "title": "Open Babel MMFF94 force field documentation",
+ "url": "https://openbabel.org/docs/Forcefields/mmff94.html",
+ "role": "molecular_shadow_reference",
+ "status": "external_reference",
+ },
+ {
+ "id": "rdkit_mmff_implementation_paper",
+ "title": "MMFF implementation validation reference in RDKit ecosystem",
+ "url": "https://link.springer.com/article/10.1186/s13321-014-0037-3",
+ "role": "implementation_reference",
+ "status": "external_reference",
+ },
+ {
+ "id": "user_supplied_asymptote_meme",
+ "title": "Asymptote meme source prompt",
+ "role": "asymptotic_shadow_prompt",
+ "status": "user_supplied_image_prompt",
+ },
+]
+
+TREE_FIDDY_CAGE_BOUNDARY_BYTES = 350
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_bytes(data: bytes) -> str:
+ return hashlib.sha256(data).hexdigest()
+
+
+def hash_obj(obj: Any) -> str:
+ return sha256_bytes(stable_json(obj).encode("utf-8"))
+
+
+def rel(path: Path) -> str:
+ try:
+ return str(path.relative_to(REPO))
+ except ValueError:
+ return str(path)
+
+
+def file_hash(path: Path) -> str | None:
+ return sha256_bytes(path.read_bytes()) if path.exists() else None
+
+
+def source_ref(path: Path) -> dict[str, Any]:
+ return {"path": rel(path), "exists": path.exists(), "sha256": file_hash(path)}
+
+
+def shadow_route(
+ *,
+ rank: int,
+ route_id: str,
+ domain: str,
+ visible_shadow: str,
+ hidden_state: str,
+ chain: list[str],
+ residual_handles: list[str],
+ reusable_kernels: list[str],
+ fixture_targets: list[str],
+ hold_surfaces: list[str],
+ next_probe: str,
+ estimated_yield: str,
+ decision: str = "SHADOW_ROUTE_READY",
+ archive_mode: str = "TREE_FIDDY_CANDIDATE",
+) -> dict[str, Any]:
+ item = {
+ "rank": rank,
+ "route_id": route_id,
+ "domain": domain,
+ "visible_shadow": visible_shadow,
+ "hidden_state": hidden_state,
+ "refined_shadow_chain": chain,
+ "accumulator": {
+ "kind": "O-AMMR",
+ "meaning": "ordered algebraic Merkle mountain range over typed projection nodes",
+ "plain_merkle_role": "content hash field only; not the whole trust object",
+ },
+ "representative_carrier": {
+ "shape": "16D signed envelope -> 12D source/residual plane -> 4D primitive keel -> genus-3 residual boat -> 0D closure",
+ "closure_budget_twelfths": {
+ "visible_4d": 4,
+ "shadow_3d": 3,
+ "closure_0d": 1,
+ "lawbound": 4,
+ "unresolved": 0,
+ "total": 12,
+ },
+ "residual_handles": residual_handles,
+ },
+ "tree_fiddy_guard": {
+ "cage_boundary_bytes": TREE_FIDDY_CAGE_BOUNDARY_BYTES,
+ "archive_mode": archive_mode,
+ "archive_rule": "if committed_or_shielded then Q_active(i)=0",
+ "promotion_rule": "archive route only when control+receipt+residual budget is bounded by cage boundary",
+ "failure_lane": "HOLD_ACTIVE_SHADOW_ROUTE",
+ },
+ "reusable_kernels": reusable_kernels,
+ "fixture_targets": fixture_targets,
+ "hold_surfaces": hold_surfaces,
+ "next_probe": next_probe,
+ "estimated_yield": estimated_yield,
+ "decision": decision,
+ }
+ item["route_hash"] = hash_obj({k: v for k, v in item.items() if k != "route_hash"})
+ return item
+
+
+def build_map() -> dict[str, Any]:
+ default_chain = [
+ "L16_signed_envelope",
+ "L12_source_residual_plane",
+ "L4_primitive_keel",
+ "Rg3_residual_boat",
+ "L3_or_L2_visible_shadow",
+ "L0_closure",
+ "O_AMMR_root",
+ ]
+ default_handles = ["packet_local", "shear_torsion", "spectral_field"]
+ routes = [
+ shadow_route(
+ rank=1,
+ route_id="molecular_mmff_rigid_bodies",
+ domain="molecular mechanics and MMFF-style geometry",
+ visible_shadow="3D atom coordinates and local fragment poses",
+ hidden_state="typed chemistry body state: atom identity, topology, aromaticity, charge, force-field slots, residual strain",
+ chain=[
+ "L16_body_state",
+ "L12_chemistry_residual_plane",
+ "L8_mmff_adapter_state",
+ "L4_geometry_primitive",
+ "Rg3_strain_residual_boat",
+ "L3_coordinate_shadow",
+ "L0_replay_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["coordinate_packet", "torsion_shear", "forcefield_spectral_slot"],
+ reusable_kernels=["RIGID_BODY_POSE", "HINGED_RIGID_BODY", "TORSION_OPCODE", "MN_BOND_DEVIATION"],
+ fixture_targets=["ring templates", "rotor groups", "rigid triads", "fragment pose replay"],
+ hold_surfaces=["atom typing", "aromaticity", "parameter tables", "charges", "nonbonded interactions", "energy minimization"],
+ next_probe="mmff_rigid_body_geometry_probe.py",
+ estimated_yield="very_high",
+ ),
+ shadow_route(
+ rank=2,
+ route_id="protein_secondary_structure",
+ domain="protein geometry and folding surfaces",
+ visible_shadow="backbone coordinates, alpha helices, beta sheets, contact maps",
+ hidden_state="sequence, residue chemistry, torsion state, hydrogen-bond graph, solvent/exposure lanes",
+ chain=default_chain,
+ residual_handles=default_handles,
+ reusable_kernels=["RIGID_BODY_POSE", "HINGED_CHAIN", "CONTACT_MAP_SHADOW", "TORSION_OPCODE"],
+ fixture_targets=["ideal helix template", "beta-strand template", "Ramachandran torsion bins", "contact-map replay"],
+ hold_surfaces=["force field validity", "solvent model", "folding dynamics", "experimental structure uncertainty"],
+ next_probe="protein_shadow_geometry_probe.py",
+ estimated_yield="high",
+ ),
+ shadow_route(
+ rank=3,
+ route_id="crystal_lattice_basis",
+ domain="crystallography and solid-state structures",
+ visible_shadow="unit-cell coordinates and lattice basis",
+ hidden_state="space group, motif, Wyckoff positions, occupancy, defects, temperature factors",
+ chain=[
+ "L16_material_state",
+ "L12_symmetry_residual_plane",
+ "L8_symmetry_adapter",
+ "L4_lattice_primitive",
+ "Rg3_defect_residual_boat",
+ "L3_unit_cell_shadow",
+ "L0_orbit_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["motif_packet", "symmetry_shear", "defect_spectral_field"],
+ reusable_kernels=["LATTICE_BASIS", "SYMMETRY_ORBIT", "MOTIF_REPLAY", "DEFECT_RESIDUAL"],
+ fixture_targets=["NaCl cell", "graphite/diamond motif", "space-group orbit expansion", "defect residual lane"],
+ hold_surfaces=["disorder", "partial occupancy", "thermal ellipsoids", "DFT/experimental provenance"],
+ next_probe="crystal_lattice_shadow_probe.py",
+ estimated_yield="very_high",
+ ),
+ shadow_route(
+ rank=4,
+ route_id="cad_mechanical_assemblies",
+ domain="CAD and mechanical assemblies",
+ visible_shadow="3D part mesh, pose graph, constraints",
+ hidden_state="parametric sketch, joints, tolerances, material, manufacturing operations, load paths",
+ chain=[
+ "L16_design_intent",
+ "L12_feature_residual_plane",
+ "L8_feature_adapter",
+ "L4_joint_primitive",
+ "Rg3_tolerance_residual_boat",
+ "L3_mesh_shadow",
+ "L0_assembly_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["feature_packet", "joint_shear_torsion", "loadpath_spectral_field"],
+ reusable_kernels=["RIGID_BODY_POSE", "JOINT_CONSTRAINT", "SYMMETRY_REPEAT", "MESH_RESIDUAL"],
+ fixture_targets=["bolted plate", "hinge assembly", "patterned holes", "extrude/revolve replay"],
+ hold_surfaces=["FEA validity", "manufacturing tolerance", "contact/friction", "load certification"],
+ next_probe="cad_assembly_shadow_probe.py",
+ estimated_yield="high",
+ ),
+ shadow_route(
+ rank=5,
+ route_id="seismic_interior_witness",
+ domain="geophysics and inaccessible interiors",
+ visible_shadow="boundary wave arrivals, travel-time residuals, mode signatures",
+ hidden_state="opaque interior material state, phase regions, anisotropy, temperature/pressure lanes",
+ chain=[
+ "L16_interior_state",
+ "L12_wave_residual_plane",
+ "L8_wave_adapter",
+ "L4_boundary_witness",
+ "Rg3_tomography_residual_boat",
+ "L1_time_series_shadow",
+ "L0_witness_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["arrival_packet", "anisotropy_shear", "attenuation_spectral_field"],
+ reusable_kernels=["BOUNDARY_WITNESS", "MN_IMPEDANCE_CONTRAST", "RESIDUAL_TOMOGRAPHY", "UNDERVERSE_LANE"],
+ fixture_targets=["two-layer travel-time fixture", "S-wave missing lane", "impedance reflection", "tomography residual"],
+ hold_surfaces=["unique interior decode", "material phase overclaim", "measurement noise", "model nonuniqueness"],
+ next_probe="seismic_shadow_witness_probe.py",
+ estimated_yield="medium_high",
+ ),
+ shadow_route(
+ rank=6,
+ route_id="medical_imaging_anatomy",
+ domain="medical imaging geometry",
+ visible_shadow="2D/3D scan slices, segmentation masks, landmark coordinates",
+ hidden_state="anatomy state, tissue class, acquisition protocol, orientation, uncertainty, diagnosis boundary",
+ chain=default_chain,
+ residual_handles=default_handles,
+ reusable_kernels=["SLICE_STACK", "SEGMENTATION_MASK", "RIGID_REGISTRATION", "RESIDUAL_UNCERTAINTY"],
+ fixture_targets=["phantom object slices", "rigid registration", "mask run-length replay", "landmark pose replay"],
+ hold_surfaces=["diagnosis", "clinical validity", "scanner artifacts", "privacy/provenance"],
+ next_probe="medical_image_shadow_probe.py",
+ estimated_yield="medium_high",
+ decision="SHADOW_ROUTE_HOLD_FIRST",
+ archive_mode="TREE_FIDDY_BLOCKED_CLINICAL_HOLD",
+ ),
+ shadow_route(
+ rank=7,
+ route_id="language_parse_semantics",
+ domain="language syntax and semantic compression",
+ visible_shadow="token stream, parse tree, formatted text",
+ hidden_state="syntax, entity graph, discourse state, source provenance, ambiguity lanes",
+ chain=[
+ "L16_discourse_state",
+ "L12_text_residual_plane",
+ "L8_semantic_adapter",
+ "L4_parse_primitive",
+ "Rg3_ambiguity_residual_boat",
+ "L1_token_shadow",
+ "L0_byte_replay_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["token_packet", "syntax_shear", "semantic_spectral_field"],
+ reusable_kernels=["GRAMMAR_TEMPLATE", "ENTITY_REFERENCE", "MORPHOLOGY_OPCODE", "RESIDUAL_TEXT"],
+ fixture_targets=["inflection tables", "template-heavy wiki text", "citation template parse", "entity-link replay"],
+ hold_surfaces=["meaning equivalence", "translation claims", "ambiguous grammar", "human intent"],
+ next_probe="language_shadow_parse_probe.py",
+ estimated_yield="high",
+ ),
+ shadow_route(
+ rank=8,
+ route_id="bibliographic_event_horizon",
+ domain="bibliography and citation-provenance graphs",
+ visible_shadow="citation number, bibliography entry, theorem/source label",
+ hidden_state="source graph, dependency graph, claim fanout, quote coverage, receipt thrust, residual obligations",
+ chain=[
+ "L16_source_ecology",
+ "L12_claim_dependency_residual_plane",
+ "L8_bibliography_adapter",
+ "L4_citation_gravity_primitive",
+ "Rg3_obligation_residual_boat",
+ "L1_reference_label_shadow",
+ "L0_forward_receipt_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["quote_packet", "dependency_shear", "claim_spectral_field"],
+ reusable_kernels=["CITATION_GRAVITY", "FORWARD_RECEIPT_THRUST", "DEPENDENCY_O_AMMR", "HOLD_LABEL_AUTHORITY"],
+ fixture_targets=["over-cited root label", "forward-receipted source", "small source-hash note"],
+ hold_surfaces=["citation label as proof", "prestige authority", "unquoted dependency", "unclosed theorem chain"],
+ next_probe="bibliographic_event_horizon_probe.py",
+ estimated_yield="high",
+ ),
+ shadow_route(
+ rank=9,
+ route_id="asymptotic_closure_horizon",
+ domain="limit arguments, near-proofs, near-compression, and near-authority routes",
+ visible_shadow="approach curve, limit statement, near-zero delta, near-complete proof label",
+ hidden_state="finite gate state: replay, residual, receipt, byte law, and closure witness",
+ chain=[
+ "L16_limit_claim_state",
+ "L12_finite_gate_residual_plane",
+ "L8_limit_adapter",
+ "L4_approach_primitive",
+ "Rg3_missing_witness_residual_boat",
+ "L1_asymptote_shadow",
+ "L0_finite_intersection_closure",
+ "O_AMMR_root",
+ ],
+ residual_handles=["approach_packet", "gate_shear", "missing_witness_spectral_field"],
+ reusable_kernels=["FINITE_INTERSECTION_GATE", "ASYMPTOTIC_HOLD", "TREE_FIDDY_ARCHIVE_DIAGNOSTIC"],
+ fixture_targets=["citation gravity near-authority", "global-delta near-zero compression", "finite coordinate replay", "proof label dependency chain"],
+ hold_surfaces=["limit language as proof", "approaches-zero as byte law", "eventual closure without witness", "infinite citation chain"],
+ next_probe="asymptotic_closure_horizon_probe.py",
+ estimated_yield="high",
+ ),
+ shadow_route(
+ rank=10,
+ route_id="proof_equation_derivations",
+ domain="proof objects and equation derivation chains",
+ visible_shadow="rendered theorem/equation statement",
+ hidden_state="foundation kernel, dependencies, transform rules, residual obligations, closure gates",
+ chain=[
+ "L16_foundation_state",
+ "L12_dependency_residual_plane",
+ "L8_dependency_adapter",
+ "L4_transform_primitive",
+ "Rg3_obligation_residual_boat",
+ "L2_statement_shadow",
+ "L0_closure_witness",
+ "O_AMMR_root",
+ ],
+ residual_handles=["equation_packet", "dependency_shear", "proof_spectral_field"],
+ reusable_kernels=["FORWARD_DERIVATION", "DEPENDENCY_MERKLE", "CLOSURE_WITNESS", "HOLD_RESIDUAL"],
+ fixture_targets=["foundation equation atom", "dependency hash replay", "PASS-ADD-PAUSE-SUBTRACT event chain"],
+ hold_surfaces=["human theorem label", "citation trust", "unclosed residual", "semantic overclaim"],
+ next_probe="proof_shadow_derivation_probe.py",
+ estimated_yield="high",
+ ),
+ shadow_route(
+ rank=11,
+ route_id="pde_field_snapshots",
+ domain="PDE fields and simulation state",
+ visible_shadow="mesh/grid samples and time slices",
+ hidden_state="governing equation, boundary conditions, units, solver, mesh, timestep, residual norm",
+ chain=default_chain,
+ residual_handles=default_handles,
+ reusable_kernels=["BOUNDARY_CONDITION", "STENCIL_OPCODE", "MODE_BASIS", "RESIDUAL_NORM"],
+ fixture_targets=["heat equation stencil", "wave mode packet", "boundary-condition replay", "coarse-grid residual"],
+ hold_surfaces=["solver correctness", "stability", "physical validity", "mesh convergence"],
+ next_probe="pde_field_shadow_probe.py",
+ estimated_yield="medium",
+ ),
+ shadow_route(
+ rank=12,
+ route_id="genomic_chromatin_projection",
+ domain="genomics and chromatin/projection surfaces",
+ visible_shadow="sequence string, contact map, 3D chromatin trace",
+ hidden_state="regulatory state, epigenetic marks, cell type, assay protocol, uncertainty, causal boundary",
+ chain=default_chain,
+ residual_handles=default_handles,
+ reusable_kernels=["SEQUENCE_TEMPLATE", "CONTACT_MAP_SHADOW", "MARK_RUN", "ASSAY_RESIDUAL"],
+ fixture_targets=["repeat sequence run", "motif replay", "contact-map block", "mark interval encoding"],
+ hold_surfaces=["causality", "cell-state generalization", "batch effects", "clinical/biological overclaim"],
+ next_probe="genomic_shadow_projection_probe.py",
+ estimated_yield="medium",
+ decision="SHADOW_ROUTE_HOLD_FIRST",
+ archive_mode="TREE_FIDDY_BLOCKED_CAUSAL_HOLD",
+ ),
+ ]
+ return {
+ "schema": "shadow_layer_opportunity_map_v1",
+ "citations": {
+ "local_source_refs": [rel(path) for path in SOURCE_REFS],
+ "external_citations": EXTERNAL_CITATIONS,
+ },
+ "canonical_statement": (
+ "Shadow layers are useful where the visible object is a cheap projection "
+ "of a richer typed state. The low-dimensional shadow may be encoded, but "
+ "the hidden state, adapter, residual, closure policy, and O-AMMR route "
+ "must be receipted. Plain Merkle hashes are only content commitments."
+ ),
+ "selection_rule": (
+ "Promote replayable shadows first. Keep semantics, physical validity, diagnosis, "
+ "causality, and theorem trust in HOLD until local closure receipts exist."
+ ),
+ "refinement_rule": {
+ "avoid": "pure Merkle tree as trust object",
+ "use": "O-AMMR plus typed representative carrier",
+ "carrier_law": "source_12D = lift(project(source_12D)) + residual_12D",
+ "residual_law": "packet_local + shear_torsion + spectral_field = residual_12D",
+ "promotion_requires": [
+ "axis counts match",
+ "three residual handles close",
+ "unresolved shell mass is zero",
+ "visible shadow replays exactly",
+ "source and receipt hashes are present",
+ ],
+ },
+ "tree_fiddy_rule": {
+ "meaning": "bounded archive and safety cage for shadow routes",
+ "cage_boundary_bytes": TREE_FIDDY_CAGE_BOUNDARY_BYTES,
+ "active_pull_rule": "Q_active(i)=0 if i is committed or shielded",
+ "assignment": "BHOCS/archive commit routes are Tree Fiddy owned; live recurrence remains outside the cage",
+ "shadow_use": (
+ "A shadow route may be archived only after replay, residual, and receipt "
+ "costs fit within the cage. Otherwise it stays HOLD_ACTIVE_SHADOW_ROUTE."
+ ),
+ },
+ "claim_boundary": (
+ "Planning receipt only. This map ranks likely shadow-layer encoding surfaces; "
+ "it does not assert compression gains, physical truth, clinical validity, or proof validity."
+ ),
+ "routes": routes,
+ "route_count": len(routes),
+ "status_counts": {
+ status: sum(1 for item in routes if item["decision"] == status)
+ for status in sorted({item["decision"] for item in routes})
+ },
+ }
+
+
+def build_receipt(route_map: dict[str, Any]) -> dict[str, Any]:
+ receipt = {
+ "schema": "shadow_layer_opportunity_map_receipt_v1",
+ "generated_at_utc": datetime.now(timezone.utc).isoformat(),
+ "timestamp_role": "metadata_only",
+ "generated_at_utc_included_in_receipt_hash": False,
+ "map": rel(MAP),
+ "map_hash": hash_obj(route_map),
+ "source_refs": [source_ref(path) for path in SOURCE_REFS],
+ "external_citations": route_map["citations"]["external_citations"],
+ "route_count": route_map["route_count"],
+ "status_counts": route_map["status_counts"],
+ "decision": "ADMIT_SHADOW_ROUTE_MAP_HOLD_FIRST",
+ "claim_boundary": route_map["claim_boundary"],
+ }
+ receipt["receipt_hash"] = sha256_bytes(
+ stable_json({k: v for k, v in receipt.items() if k not in {"receipt_hash", "generated_at_utc"}}).encode("utf-8")
+ )
+ return receipt
+
+
+def write_summary(route_map: dict[str, Any], receipt: dict[str, Any]) -> None:
+ lines = [
+ "# Shadow Layer Opportunity Map",
+ "",
+ f"Decision: `{receipt['decision']}` ",
+ f"Receipt hash: `{receipt['receipt_hash']}`",
+ "",
+ route_map["claim_boundary"],
+ "",
+ "## Canonical Statement",
+ "",
+ route_map["canonical_statement"],
+ "",
+ "## Refinement Rule",
+ "",
+ f"- Avoid: `{route_map['refinement_rule']['avoid']}`",
+ f"- Use: `{route_map['refinement_rule']['use']}`",
+ f"- Carrier law: `{route_map['refinement_rule']['carrier_law']}`",
+ f"- Residual law: `{route_map['refinement_rule']['residual_law']}`",
+ "",
+ "## Tree Fiddy Guard",
+ "",
+ f"- Cage boundary bytes: `{route_map['tree_fiddy_rule']['cage_boundary_bytes']}`",
+ f"- Active pull rule: `{route_map['tree_fiddy_rule']['active_pull_rule']}`",
+ f"- Assignment: {route_map['tree_fiddy_rule']['assignment']}",
+ f"- Shadow use: {route_map['tree_fiddy_rule']['shadow_use']}",
+ "",
+ "## Ranked Routes",
+ "",
+ "| Rank | Route | Domain | Visible shadow | Yield | Decision | Next probe |",
+ "|---:|---|---|---|---|---|---|",
+ ]
+ for item in route_map["routes"]:
+ lines.append(
+ f"| {item['rank']} | `{item['route_id']}` | {item['domain']} | "
+ f"{item['visible_shadow']} | {item['estimated_yield']} | `{item['decision']}` | `{item['next_probe']}` |"
+ )
+ lines.extend(["", "## Rule", "", route_map["selection_rule"]])
+ lines.extend(["", "## Citations", ""])
+ lines.append("Local source refs:")
+ for source in receipt["source_refs"]:
+ lines.append(f"- `{source['path']}` exists: `{source['exists']}`")
+ lines.append("")
+ lines.append("External/source prompts:")
+ for citation in route_map["citations"]["external_citations"]:
+ target = citation.get("url") or citation["status"]
+ lines.append(f"- `{citation['id']}`: {citation['title']} ({target}); role: `{citation['role']}`")
+ SUMMARY.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ route_map = build_map()
+ receipt = build_receipt(route_map)
+ MAP.write_text(json.dumps(route_map, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_summary(route_map, receipt)
+ print(
+ json.dumps(
+ {
+ "map": rel(MAP),
+ "receipt": rel(RECEIPT),
+ "summary": rel(SUMMARY),
+ "receipt_hash": receipt["receipt_hash"],
+ "decision": receipt["decision"],
+ "status_counts": route_map["status_counts"],
+ },
+ indent=2,
+ sort_keys=True,
+ )
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/sigilith_symbolic_resilience_prior.py b/4-Infrastructure/shim/sigilith_symbolic_resilience_prior.py
new file mode 100644
index 00000000..cb4993c9
--- /dev/null
+++ b/4-Infrastructure/shim/sigilith_symbolic_resilience_prior.py
@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""Receipt for Nash 2026 Sigilith symbolic-resilience prior.
+
+This is an analysis/citation prior only. The source record carries a non-commercial
+research/no-derivative implementation boundary, so this artifact extracts high-level
+equation shapes and claim boundaries without implementing the Sigilith framework.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+SOURCE_DIR = REPO / "shared-data" / "sources" / "hcommons" / "gjgw2-j1f46"
+SOURCE_PDF = SOURCE_DIR / "Nash2026Sigilith_SymbolicResilience.pdf"
+SOURCE_TEXT = SOURCE_DIR / "Nash2026Sigilith_SymbolicResilience.txt"
+RECORD_JSON = SOURCE_DIR / "record_api.json"
+RECEIPT = SHIM / "sigilith_symbolic_resilience_prior_receipt.json"
+CURRICULUM = SHIM / "sigilith_symbolic_resilience_prior_curriculum.jsonl"
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_bytes(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def build_receipt() -> dict[str, Any]:
+ record = json.loads(RECORD_JSON.read_text(encoding="utf-8"))
+ pdf_sha256 = sha256_bytes(SOURCE_PDF)
+ text_sha256 = sha256_bytes(SOURCE_TEXT)
+ pdf_md5 = hashlib.md5(SOURCE_PDF.read_bytes(), usedforsecurity=False).hexdigest()
+ metadata = record.get("metadata", {})
+ receipt: dict[str, Any] = {
+ "schema": "sigilith_symbolic_resilience_prior_v1",
+ "source": {
+ "record_id": record.get("id"),
+ "title": metadata.get("title"),
+ "creator": "Nash, Ky",
+ "publication_date": metadata.get("publication_date"),
+ "doi": record.get("pids", {}).get("doi", {}).get("identifier"),
+ "record_url": record.get("links", {}).get("self_html"),
+ "api_url": record.get("links", {}).get("self"),
+ "pdf_filename": SOURCE_PDF.name,
+ "pdf_md5": pdf_md5,
+ "pdf_sha256": pdf_sha256,
+ "text_sha256": text_sha256,
+ },
+ "license_boundary": [
+ "use as citation and high-level analysis prior only",
+ "do not implement Sigilith/CDMQ methods from this source without permission",
+ "do not create derivative framework artifacts from protected method details",
+ "preserve author claim boundary: no biological, cognitive, or autonomous interpretation implied",
+ ],
+ "primary_read": (
+ "The paper offers a synthetic symbolic-system analogue for resilience under "
+ "drift: constraint density, modifier regeneration, and paradox buffering "
+ "can delay collapse. This maps cleanly to the stack's overload model as a "
+ "symbolic collapse-topology prior, not as evidence of biological autonomy."
+ ),
+ "source_claim_boundary": (
+ "Survival-like behavior is defined as delayed terminal collapse through "
+ "internal stabilization dynamics without biological, cognitive, or autonomous claims."
+ ),
+ "system_comparison": {
+ "R1": {
+ "description": "baseline CDMQ system with no resilience mechanisms",
+ "observed_pattern": "rapid drift escalation and single-stage collapse",
+ "T_collapse": 100,
+ },
+ "R2": {
+ "description": "enhanced system with increased constraint density, modifier regeneration, and paradox buffering",
+ "observed_pattern": "drift suppression, plateau formation, modifier regeneration, paradox buffering, delayed collapse",
+ "T_collapse": 140,
+ },
+ "CDC": 40,
+ },
+ "equation_shapes": [
+ {
+ "id": "drift_magnitude",
+ "shape": "D_t = Q_t / (C_t + M_t)",
+ "semantics": "paradox/quality activation over stabilizing constraint and modifier mass",
+ "folded_use": "symbolic analogue of overload pressure",
+ },
+ {
+ "id": "collapse_delay_coefficient",
+ "shape": "CDC = T_collapse(R2) - T_collapse(R1)",
+ "semantics": "delay gained by resilience mechanisms",
+ "folded_use": "collapse-resistance delta for route/system variants",
+ },
+ {
+ "id": "constraint_density",
+ "shape": "C_rho = C / N",
+ "semantics": "constraint density per symbolic sequence length",
+ "folded_use": "stabilization mass per route/window",
+ },
+ {
+ "id": "modifier_recovery_rate",
+ "shape": "MRR = (M_(t+1) - M_t) / Delta_t",
+ "semantics": "rate of modifier regeneration",
+ "folded_use": "recovery capacity after overload or drift",
+ },
+ {
+ "id": "paradox_suppression_ratio",
+ "shape": "PSR = 1 - (Q_active / Q_total)",
+ "semantics": "suppression of paradox activation",
+ "folded_use": "buffering gate for contradiction/overflow",
+ },
+ ],
+ "collapse_topology": [
+ "drift rise",
+ "drift reversal",
+ "drift plateau",
+ "drift rebound",
+ "partial collapse",
+ "stabilisation",
+ "final collapse",
+ ],
+ "overload_model_mapping": {
+ "Q_t": "active contradiction/paradox/salience pressure",
+ "C_t": "constraints or assimilation structures",
+ "M_t": "modifiers, repair operators, or buffering mechanisms",
+ "D_t": "symbolic overload pressure",
+ "C_rho": "institutional/cognitive constraint density",
+ "MRR": "repair/offload regeneration rate",
+ "PSR": "paradox or contradiction buffering effectiveness",
+ "CDC": "delay before terminal collapse or forced reconfiguration",
+ },
+ "historical_bandwidth_mapping": {
+ "accelerated_transfer": "raises Q_t and drift pressure",
+ "assimilation_infrastructure": "raises C_t and C_rho",
+ "adaptive_interpretive_tools": "raise M_t and MRR",
+ "paradox_buffering": "raises PSR and delays collapse",
+ "residual_stress": "unbuffered Q_t that drives rebound or collapse",
+ },
+ "promotion_rule": [
+ "use only as structural analogy and equation-shape prior",
+ "map CDMQ variables to local variables explicitly before use",
+ "validate any overload/collapse claim against local data",
+ "keep source license and no-autonomy claim boundary attached",
+ ],
+ "failure_rules": [
+ "treating synthetic symbolic behavior as biological evidence -> overclaim",
+ "implementing protected Sigilith/CDMQ methods from source -> permission boundary violation",
+ "using survival-like language without boundary -> invalid framing",
+ "mapping Q/C/M variables without local definitions -> hold",
+ "claiming collapse prediction without empirical timeline data -> overclaim",
+ ],
+ "linked_local_models": [
+ "Connectome Protective Cognitive Load Reweighting",
+ "Holographic Fractional Recursive Equation Fold",
+ "Decision Diagram Compression Tuning Prior",
+ ],
+ "claim_boundary": (
+ "This receipt records a symbolic-resilience citation and high-level equation "
+ "fold. It is not an implementation, not a derivative Sigilith method, not "
+ "biological evidence, and not proof of the historical overload theory."
+ ),
+ }
+ receipt["receipt_hash"] = sha256_text(stable_json(receipt))
+ return receipt
+
+
+def write_curriculum(receipt: dict[str, Any]) -> None:
+ rows = [
+ {
+ "task": "map_symbolic_resilience_equation",
+ "input": "D_t, CDC, C_rho, MRR, or PSR equation",
+ "target": "overload pressure, collapse delay, constraint density, recovery rate, or paradox buffering",
+ },
+ {
+ "task": "preserve_source_claim_boundary",
+ "input": "survival-like symbolic behavior claim",
+ "target": "delayed terminal collapse only; no biological/cognitive/autonomous implication",
+ },
+ {
+ "task": "reject_unlicensed_implementation",
+ "input": "proposal to implement Sigilith/CDMQ methods from source",
+ "target": "hold unless permission or independent derivation is documented",
+ },
+ ]
+ CURRICULUM.write_text(
+ "".join(json.dumps(row, sort_keys=True) + "\n" for row in rows),
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ receipt = build_receipt()
+ RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_curriculum(receipt)
+ print(json.dumps({
+ "receipt": str(RECEIPT.relative_to(REPO)),
+ "curriculum": str(CURRICULUM.relative_to(REPO)),
+ "receipt_hash": receipt["receipt_hash"],
+ "equation_count": len(receipt["equation_shapes"]),
+ "collapse_topology_stages": len(receipt["collapse_topology"]),
+ }, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/signal_equation_invariant_roots.py b/4-Infrastructure/shim/signal_equation_invariant_roots.py
new file mode 100644
index 00000000..306e9b29
--- /dev/null
+++ b/4-Infrastructure/shim/signal_equation_invariant_roots.py
@@ -0,0 +1,463 @@
+#!/usr/bin/env python3
+"""Derive invariant roots for accessible local signal equations.
+
+This is a local synthesis pass over the Research Stack signal surface. It does
+not claim a complete literature survey. It pulls the equations that are
+available in the workspace signal compendium and executable audio-DSP code, then
+normalizes each into an invariant root: the quantity, equivalence class, or
+constraint that remains meaningful under admissible transforms.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+OUT = SHIM / "signal_equation_invariant_roots_receipt.json"
+CURRICULUM_OUT = SHIM / "signal_equation_invariant_roots_curriculum.jsonl"
+SUMMARY_OUT = SHIM / "signal_equation_invariant_roots_summary.md"
+
+GENERATED_AT = "2026-05-08T00:00:00+00:00"
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+INVARIANT_ROOTS: list[dict[str, Any]] = [
+ {
+ "id": "SIGROOT001_spectral_overlap",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: spectralOverlap sig1 sig2 = sum(sig1[i] * sig2[i])",
+ "equation": " = sum_i s1_i s2_i",
+ "invariant_root": "inner-product pairing on aligned spectral coordinates",
+ "admissible_transforms": "common bin permutation; orthonormal basis change when both signatures transform together",
+ "compression_use": "route similarity, duplicate-island pruning, nearest repair template",
+ "fpga_use": "DSP dot-product lane with accumulator and saturation guard",
+ },
+ {
+ "id": "SIGROOT002_piecewise_merge",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: piecewiseMerge left right[i] = min(1.0, left[i] + right[i])",
+ "equation": "merge_i = min(1, left_i + right_i)",
+ "invariant_root": "bounded semilattice occupancy over [0,1]^n",
+ "admissible_transforms": "coordinatewise monotone maps that preserve zero, one, and order",
+ "compression_use": "safe feature union without unbounded sidecar growth",
+ "fpga_use": "saturating add primitive",
+ },
+ {
+ "id": "SIGROOT003_resonance_degeneracy",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: count(left[i] != 0 and right[i] != 0)",
+ "equation": "deg(left,right) = |support(left) intersect support(right)|",
+ "invariant_root": "support-intersection cardinality",
+ "admissible_transforms": "positive amplitude scaling and common support-preserving permutation",
+ "compression_use": "overlap score for tokenbook/feature collisions",
+ "fpga_use": "bitmask AND plus popcount",
+ },
+ {
+ "id": "SIGROOT004_wavefront_value",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: decay, phaseShift, oscillation, value",
+ "equation": "value = (A - gamma*d) * osc(omega*d) for d <= v*t, else 0",
+ "invariant_root": "retarded wavefront cone plus phase class modulo cycle",
+ "admissible_transforms": "translations and metric-preserving coordinate changes",
+ "compression_use": "event influence radius for local route activation",
+ "fpga_use": "distance gate, phase LUT, envelope subtractor",
+ },
+ {
+ "id": "SIGROOT005_signal_band_policy",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: quiet/active/stressed/extreme threshold bands",
+ "equation": "band(x) = threshold_partition(x)",
+ "invariant_root": "ordered threshold cell",
+ "admissible_transforms": "monotone rescaling with transformed thresholds",
+ "compression_use": "route budget scheduler",
+ "fpga_use": "comparator ladder",
+ },
+ {
+ "id": "SIGROOT006_acoustic_gradient",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: acoustic impedance as gradient magnitude |grad f|",
+ "equation": "Z_acoustic ~ |grad f|",
+ "invariant_root": "metric norm of field gradient",
+ "admissible_transforms": "coordinate changes with explicit metric tensor",
+ "compression_use": "manifold steepest-descent route proposal",
+ "fpga_use": "finite-difference gradient and norm pipeline",
+ },
+ {
+ "id": "SIGROOT007_fitness_entropy_compensation",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: f = f_max - alpha * H",
+ "equation": "f + alpha*H = f_max",
+ "invariant_root": "affine fitness-entropy conserved total",
+ "admissible_transforms": "unit changes that transform alpha coherently",
+ "compression_use": "semantic/fitness score must pay entropy cost",
+ "fpga_use": "linear score lane with conserved budget comparator",
+ },
+ {
+ "id": "SIGROOT008_gibbs_free_energy",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: DeltaG = DeltaH - T*DeltaS",
+ "equation": "G = H - T*S",
+ "invariant_root": "Legendre-transformed available-energy potential",
+ "admissible_transforms": "thermodynamic coordinate changes preserving conjugate pair T,S",
+ "compression_use": "available byte-gain after entropy/side-info cost",
+ "fpga_use": "cost potential lane for thermal/energy-aware routing",
+ },
+ {
+ "id": "SIGROOT009_affine_erasure_permutation",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: pi(i) = (offset + step*i) mod n",
+ "equation": "pi(i) = a + s*i mod n",
+ "invariant_root": "cycle structure determined by gcd(s,n)",
+ "admissible_transforms": "offset translation and invertible modular scaling",
+ "compression_use": "repair stream interleaving with deterministic owner",
+ "fpga_use": "modular address generator",
+ },
+ {
+ "id": "SIGROOT010_genomic_weight",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: genomicWeight ratio",
+ "equation": "W = (rho + v + tau + sigma + q) / ((1+kappa^2)*(1+epsilon))",
+ "invariant_root": "dimensionless normalized field-strength ratio",
+ "admissible_transforms": "common scale-normalization of numerator terms",
+ "compression_use": "adaptive erasure threshold",
+ "fpga_use": "fixed-point ratio approximation",
+ },
+ {
+ "id": "SIGROOT011_pbacs_phi_accumulator",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: phi_{t+1} = phi_t + 106070",
+ "equation": "phi_{t+1} = phi_t + c mod 2^32",
+ "invariant_root": "circle rotation orbit class",
+ "admissible_transforms": "phase offset; modular conjugacy preserving increment",
+ "compression_use": "deterministic phase owner for route symbols",
+ "fpga_use": "free-running modular accumulator",
+ },
+ {
+ "id": "SIGROOT012_pbacs_error_feedback",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: e_{t+1} = v_t + e_t - (b_t ? theta_t : 0)",
+ "equation": "e_next = v + e - b*theta",
+ "invariant_root": "bounded quantization residual",
+ "admissible_transforms": "threshold-preserving fixed-point rescale",
+ "compression_use": "exact residual lane for symbol decisions",
+ "fpga_use": "sigma-delta style feedback cell",
+ },
+ {
+ "id": "SIGROOT013_mutual_information_gain",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: MI(x) = baseline_bpb - actual_bpb",
+ "equation": "MI = baseline_bpb - actual_bpb",
+ "invariant_root": "byte-per-symbol improvement under one ratio schema",
+ "admissible_transforms": "comparisons that keep baseline and actual schema identical",
+ "compression_use": "route evidence coordinate",
+ "fpga_use": "counter difference after codec run",
+ },
+ {
+ "id": "SIGROOT014_weighted_mi_prediction",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: MI_pred weighted average",
+ "equation": "MI_pred = sum_i w_i MI_i S_i / sum_i w_i S_i",
+ "invariant_root": "barycentric coordinate in similarity-weighted evidence simplex",
+ "admissible_transforms": "common positive scaling of all weights",
+ "compression_use": "nearest-prior route prediction",
+ "fpga_use": "weighted accumulator plus reciprocal approximation",
+ },
+ {
+ "id": "SIGROOT015_surprise_metric",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: surprise = log(1 + |MI_actual - MI_predicted|)",
+ "equation": "S = log(1 + |delta_MI|)",
+ "invariant_root": "monotone function of absolute prediction residual",
+ "admissible_transforms": "monotone reparameterization of residual magnitude",
+ "compression_use": "route anomaly detector",
+ "fpga_use": "absolute-delta threshold; log optional",
+ },
+ {
+ "id": "SIGROOT016_structure_yield",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: rho(x) = MI(x) / (cost(x) + epsilon)",
+ "equation": "rho = MI / (cost + eps)",
+ "invariant_root": "information-per-cost efficiency ratio",
+ "admissible_transforms": "unit changes preserving numerator/denominator interpretation",
+ "compression_use": "candidate route priority",
+ "fpga_use": "score-per-cycle allocator",
+ },
+ {
+ "id": "SIGROOT017_weighted_feature_distance",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: weighted feature distance",
+ "equation": "d(z1,z2) = sqrt(sum_i w_i*((z1_i-z2_i)/s_i)^2)",
+ "invariant_root": "diagonal metric distance after scale normalization",
+ "admissible_transforms": "coordinate rescaling absorbed into s_i and w_i",
+ "compression_use": "route family clustering",
+ "fpga_use": "scaled L2 distance pipeline",
+ },
+ {
+ "id": "SIGROOT018_energy_gradient_waveform",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: amplitude=|grad E(t)|, frequency, phase",
+ "equation": "wave_E = (|grad E|, omega_gradE, phi_gradE)",
+ "invariant_root": "gradient magnitude and phase trajectory",
+ "admissible_transforms": "metric-aware coordinate changes",
+ "compression_use": "energy/cost-aware transform scheduling",
+ "fpga_use": "gradient magnitude plus phase accumulator",
+ },
+ {
+ "id": "SIGROOT019_shape_energy_coupling",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: C_SE = alpha * grad h * grad E",
+ "equation": "C_SE = alpha ",
+ "invariant_root": "metric inner product of shape and energy gradients",
+ "admissible_transforms": "coordinate changes preserving the metric pairing",
+ "compression_use": "align geometry witness only when it reduces route cost",
+ "fpga_use": "dual-gradient dot-product lane",
+ },
+ {
+ "id": "SIGROOT020_spectral_field_score",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: score = mass*massField + polarity*polarityField + spectralOverlap",
+ "equation": "score = mM + pP + ",
+ "invariant_root": "bilinear pairing between local state and field",
+ "admissible_transforms": "paired basis changes that preserve the bilinear form",
+ "compression_use": "local route-field compatibility score",
+ "fpga_use": "three-term MAC lane",
+ },
+ {
+ "id": "SIGROOT021_parabolic_j_score",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: J(k) = 32 - 0.5*(k-22)^2",
+ "equation": "J(k) = 32 - 0.5*(k-22)^2",
+ "invariant_root": "distance from resonant vertex k=22",
+ "admissible_transforms": "translation to vertex coordinate u=k-22",
+ "compression_use": "resonance-ranked candidate pruning",
+ "fpga_use": "subtract-square-threshold circuit",
+ },
+ {
+ "id": "SIGROOT022_cmyk_frequency_lattice",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: freq(ch,h)=baseFreq(ch)+deltaFreq*h",
+ "equation": "f_ch(h) = base_ch + delta*h",
+ "invariant_root": "channel-local affine frequency lattice coordinate h",
+ "admissible_transforms": "affine frequency calibration preserving delta steps",
+ "compression_use": "symbol carrier with exact inverse",
+ "fpga_use": "base-plus-shift frequency synthesizer",
+ },
+ {
+ "id": "SIGROOT023_rydberg_gap",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: nu_tilde = R_H*(1/n1^2 - 1/n2^2)",
+ "equation": "nu_bar = R*(1/n1^2 - 1/n2^2)",
+ "invariant_root": "reciprocal-square quantum gap",
+ "admissible_transforms": "unit conversion between wavenumber, wavelength, frequency, and energy",
+ "compression_use": "stable physical spectral basis index",
+ "fpga_use": "small table of canonical spectral lines",
+ },
+ {
+ "id": "SIGROOT024_lorentzian_resonance",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: strength = 1/(1+(Delta lambda)^2)",
+ "equation": "L(delta) = 1/(1+delta^2)",
+ "invariant_root": "squared detuning from spectral center",
+ "admissible_transforms": "sign flip of detuning; normalized wavelength units",
+ "compression_use": "nearest spectral-basis assignment",
+ "fpga_use": "detuning-square LUT",
+ },
+ {
+ "id": "SIGROOT025_kmer_base4_index",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: 3-mer index = b1*16 + b2*4 + b3",
+ "equation": "idx = 16*b1 + 4*b2 + b3",
+ "invariant_root": "base-4 coordinate of codon symbol",
+ "admissible_transforms": "base relabeling with explicit inverse map",
+ "compression_use": "fixed codon/tokenbook coordinate",
+ "fpga_use": "two-bit shift-and-or indexer",
+ },
+ {
+ "id": "SIGROOT026_dct2_basis",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: cos(pi/n*(j+0.5)*k)",
+ "equation": "basis_{j,k} = cos(pi/n*(j+1/2)*k)",
+ "invariant_root": "orthogonal cosine projection coefficient",
+ "admissible_transforms": "orthogonal transforms preserving coefficient energy",
+ "compression_use": "spectral coefficient compaction",
+ "fpga_use": "fixed cosine basis or LUT butterfly",
+ },
+ {
+ "id": "SIGROOT027_qpsk_phase_class",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: QPSK phases 0,90,180,270",
+ "equation": "phase in Z_4",
+ "invariant_root": "phase class modulo pi/2",
+ "admissible_transforms": "global phase rotation with receiver correction",
+ "compression_use": "2-bit symbol carrier",
+ "fpga_use": "quadrant decoder",
+ },
+ {
+ "id": "SIGROOT028_qam16_constellation",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: 4 amplitudes x 4 phases",
+ "equation": "symbol = (a in A4, phase in Z4)",
+ "invariant_root": "finite amplitude-phase lattice point",
+ "admissible_transforms": "affine constellation calibration with preserved decision cells",
+ "compression_use": "4-bit symbol carrier / QAM transfer metaphor",
+ "fpga_use": "amplitude slicer plus quadrant decoder",
+ },
+ {
+ "id": "SIGROOT029_dmt_subcarrier_quotient",
+ "source": "SIGNAL_THEORY_COMPENDIUM.md: phase_out=base_phase+offset_i, demod=phase_in-offset_i",
+ "equation": "phase_base = phase_out - offset_i mod cycle",
+ "invariant_root": "phase quotient after subtracting subcarrier offset",
+ "admissible_transforms": "subcarrier permutation with receipted offset table",
+ "compression_use": "parallel lane carrier with exact demodulation",
+ "fpga_use": "per-lane phase subtractor",
+ },
+ {
+ "id": "SIGROOT030_hann_window_fft_energy",
+ "source": "5-Applications/audio-dsp/src/core/surface.rs: Hann window, FFT, bin energy",
+ "equation": "E_bin = avg_{k in bin} |FFT(window*x)_k|",
+ "invariant_root": "windowed spectral-energy distribution",
+ "admissible_transforms": "time shift up to phase; amplitude normalization when max-normalized",
+ "compression_use": "audio/signal route feature vector",
+ "fpga_use": "window multiply, FFT, magnitude, bin accumulator",
+ },
+ {
+ "id": "SIGROOT031_transient_features",
+ "source": "5-Applications/audio-dsp/src/core/surface.rs: attack, decay, zcr, crest",
+ "equation": "transient = (max dx+, max dx-, zero_crossings/n, peak/rms)",
+ "invariant_root": "edge/impulse morphology of the signal chunk",
+ "admissible_transforms": "time-local scaling with normalized crest and ZCR preserved",
+ "compression_use": "decide raw vs spectral vs hybrid route",
+ "fpga_use": "delta extrema, sign-change counter, RMS/peak lane",
+ },
+ {
+ "id": "SIGROOT032_predictability_autocorrelation",
+ "source": "5-Applications/audio-dsp/src/core/surface.rs: predictability via autocorrelation",
+ "equation": "pred = 0.5*(corr(x_t, x_{t-1}) + 1)",
+ "invariant_root": "normalized temporal correlation",
+ "admissible_transforms": "affine amplitude scaling removed by mean/variance normalization",
+ "compression_use": "predictor suitability signal",
+ "fpga_use": "sliding dot product and norm lane",
+ },
+ {
+ "id": "SIGROOT033_cosine_similarity",
+ "source": "5-Applications/audio-dsp/src/core/surface.rs: dot/(norm_a*norm_b)",
+ "equation": "cos(theta)=/(||a|| ||b||)",
+ "invariant_root": "projective direction on spectral feature sphere",
+ "admissible_transforms": "positive scaling of either vector",
+ "compression_use": "chunk reuse / skip decision",
+ "fpga_use": "dot product and reciprocal norm threshold",
+ },
+]
+
+
+def build_receipt() -> dict[str, Any]:
+ clusters: dict[str, int] = {}
+ for row in INVARIANT_ROOTS:
+ cluster = row["id"].split("_", 1)[1].rsplit("_", 1)[0]
+ clusters[cluster] = clusters.get(cluster, 0) + 1
+ receipt: dict[str, Any] = {
+ "schema": "signal_equation_invariant_roots_v1",
+ "generated_at": GENERATED_AT,
+ "source_scope": [
+ "SIGNAL_THEORY_COMPENDIUM.md",
+ "5-Applications/audio-dsp/src/core/surface.rs",
+ "5-Applications/audio-dsp/src/core/features.rs",
+ ],
+ "claim_boundary": (
+ "These are invariant roots for accessible local signal equations. "
+ "They are route/control priors and hardware design handles, not "
+ "external physics proof or compression proof without exact byte receipts."
+ ),
+ "root_count": len(INVARIANT_ROOTS),
+ "invariant_roots": INVARIANT_ROOTS,
+ "derived_unifying_root": {
+ "equation": "SignalRoute = (coordinate, invariant_root, admissible_transform, receipt_barrier)",
+ "meaning": (
+ "Every accessible signal equation reduces to a coordinate map plus an "
+ "invariant root. The invariant root says what can survive rescaling, "
+ "basis changes, phase shifts, lane permutation, or compression-route "
+ "projection. Promotion still requires a receipt barrier."
+ ),
+ },
+ "hutter_mapping": {
+ "i_axis": "measured byte mass and lower bounds",
+ "q_axis": "exactness roots: hash, Merkle receipt, NaN0 false, route-key closure",
+ "promotion": "only when a route lies on the exactness locus and below incumbent byte level",
+ },
+ "fpga_mapping": {
+ "common_primitives": [
+ "dot_product",
+ "saturating_add",
+ "popcount",
+ "phase_accumulator",
+ "threshold_ladder",
+ "modular_address_generator",
+ "gradient_norm",
+ "fft_bin_accumulator",
+ "digest_lane",
+ ],
+ "barrier": "commit or source-release only after independent digest/check lane passes",
+ },
+ }
+ receipt["receipt_hash"] = sha256_text(stable_json(receipt))
+ return receipt
+
+
+def write_curriculum(receipt: dict[str, Any]) -> None:
+ lines = []
+ for row in receipt["invariant_roots"]:
+ lines.append(stable_json({
+ "task": "derive_signal_invariant_root",
+ "root_id": row["id"],
+ "prompt": f"Derive the invariant root for {row['equation']}.",
+ "completion": (
+ f"Invariant root: {row['invariant_root']}. "
+ f"Admissible transforms: {row['admissible_transforms']}."
+ ),
+ }))
+ CURRICULUM_OUT.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def write_summary(receipt: dict[str, Any]) -> None:
+ lines = [
+ "# Signal Equation Invariant Roots",
+ "",
+ receipt["claim_boundary"],
+ "",
+ f"Root count: {receipt['root_count']}",
+ f"Receipt hash: `{receipt['receipt_hash']}`",
+ "",
+ "## Unifying Root",
+ "",
+ "```text",
+ receipt["derived_unifying_root"]["equation"],
+ "```",
+ "",
+ receipt["derived_unifying_root"]["meaning"],
+ "",
+ "## Roots",
+ "",
+ ]
+ for row in receipt["invariant_roots"]:
+ lines.extend([
+ f"### {row['id']}",
+ "",
+ f"- Equation: `{row['equation']}`",
+ f"- Invariant root: {row['invariant_root']}",
+ f"- Admissible transforms: {row['admissible_transforms']}",
+ f"- Compression use: {row['compression_use']}",
+ f"- FPGA use: {row['fpga_use']}",
+ "",
+ ])
+ SUMMARY_OUT.write_text("\n".join(lines), encoding="utf-8")
+
+
+def main() -> int:
+ receipt = build_receipt()
+ OUT.write_text(json.dumps(receipt, indent=2, sort_keys=True), encoding="utf-8")
+ write_curriculum(receipt)
+ write_summary(receipt)
+ print(json.dumps(
+ {
+ "receipt": rel(OUT),
+ "curriculum": rel(CURRICULUM_OUT),
+ "summary": rel(SUMMARY_OUT),
+ "receipt_hash": receipt["receipt_hash"],
+ "root_count": receipt["root_count"],
+ },
+ indent=2,
+ sort_keys=True,
+ ))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/signal_equation_invariant_roots_summary.md b/4-Infrastructure/shim/signal_equation_invariant_roots_summary.md
new file mode 100644
index 00000000..2b578787
--- /dev/null
+++ b/4-Infrastructure/shim/signal_equation_invariant_roots_summary.md
@@ -0,0 +1,280 @@
+# Signal Equation Invariant Roots
+
+These are invariant roots for accessible local signal equations. They are route/control priors and hardware design handles, not external physics proof or compression proof without exact byte receipts.
+
+Root count: 33
+Receipt hash: `10ec6bf94808b4517c6e866889d8c9cca02969fbcb43c574b0abd27c3cac3a33`
+
+## Unifying Root
+
+```text
+SignalRoute = (coordinate, invariant_root, admissible_transform, receipt_barrier)
+```
+
+Every accessible signal equation reduces to a coordinate map plus an invariant root. The invariant root says what can survive rescaling, basis changes, phase shifts, lane permutation, or compression-route projection. Promotion still requires a receipt barrier.
+
+## Roots
+
+### SIGROOT001_spectral_overlap
+
+- Equation: ` = sum_i s1_i s2_i`
+- Invariant root: inner-product pairing on aligned spectral coordinates
+- Admissible transforms: common bin permutation; orthonormal basis change when both signatures transform together
+- Compression use: route similarity, duplicate-island pruning, nearest repair template
+- FPGA use: DSP dot-product lane with accumulator and saturation guard
+
+### SIGROOT002_piecewise_merge
+
+- Equation: `merge_i = min(1, left_i + right_i)`
+- Invariant root: bounded semilattice occupancy over [0,1]^n
+- Admissible transforms: coordinatewise monotone maps that preserve zero, one, and order
+- Compression use: safe feature union without unbounded sidecar growth
+- FPGA use: saturating add primitive
+
+### SIGROOT003_resonance_degeneracy
+
+- Equation: `deg(left,right) = |support(left) intersect support(right)|`
+- Invariant root: support-intersection cardinality
+- Admissible transforms: positive amplitude scaling and common support-preserving permutation
+- Compression use: overlap score for tokenbook/feature collisions
+- FPGA use: bitmask AND plus popcount
+
+### SIGROOT004_wavefront_value
+
+- Equation: `value = (A - gamma*d) * osc(omega*d) for d <= v*t, else 0`
+- Invariant root: retarded wavefront cone plus phase class modulo cycle
+- Admissible transforms: translations and metric-preserving coordinate changes
+- Compression use: event influence radius for local route activation
+- FPGA use: distance gate, phase LUT, envelope subtractor
+
+### SIGROOT005_signal_band_policy
+
+- Equation: `band(x) = threshold_partition(x)`
+- Invariant root: ordered threshold cell
+- Admissible transforms: monotone rescaling with transformed thresholds
+- Compression use: route budget scheduler
+- FPGA use: comparator ladder
+
+### SIGROOT006_acoustic_gradient
+
+- Equation: `Z_acoustic ~ |grad f|`
+- Invariant root: metric norm of field gradient
+- Admissible transforms: coordinate changes with explicit metric tensor
+- Compression use: manifold steepest-descent route proposal
+- FPGA use: finite-difference gradient and norm pipeline
+
+### SIGROOT007_fitness_entropy_compensation
+
+- Equation: `f + alpha*H = f_max`
+- Invariant root: affine fitness-entropy conserved total
+- Admissible transforms: unit changes that transform alpha coherently
+- Compression use: semantic/fitness score must pay entropy cost
+- FPGA use: linear score lane with conserved budget comparator
+
+### SIGROOT008_gibbs_free_energy
+
+- Equation: `G = H - T*S`
+- Invariant root: Legendre-transformed available-energy potential
+- Admissible transforms: thermodynamic coordinate changes preserving conjugate pair T,S
+- Compression use: available byte-gain after entropy/side-info cost
+- FPGA use: cost potential lane for thermal/energy-aware routing
+
+### SIGROOT009_affine_erasure_permutation
+
+- Equation: `pi(i) = a + s*i mod n`
+- Invariant root: cycle structure determined by gcd(s,n)
+- Admissible transforms: offset translation and invertible modular scaling
+- Compression use: repair stream interleaving with deterministic owner
+- FPGA use: modular address generator
+
+### SIGROOT010_genomic_weight
+
+- Equation: `W = (rho + v + tau + sigma + q) / ((1+kappa^2)*(1+epsilon))`
+- Invariant root: dimensionless normalized field-strength ratio
+- Admissible transforms: common scale-normalization of numerator terms
+- Compression use: adaptive erasure threshold
+- FPGA use: fixed-point ratio approximation
+
+### SIGROOT011_pbacs_phi_accumulator
+
+- Equation: `phi_{t+1} = phi_t + c mod 2^32`
+- Invariant root: circle rotation orbit class
+- Admissible transforms: phase offset; modular conjugacy preserving increment
+- Compression use: deterministic phase owner for route symbols
+- FPGA use: free-running modular accumulator
+
+### SIGROOT012_pbacs_error_feedback
+
+- Equation: `e_next = v + e - b*theta`
+- Invariant root: bounded quantization residual
+- Admissible transforms: threshold-preserving fixed-point rescale
+- Compression use: exact residual lane for symbol decisions
+- FPGA use: sigma-delta style feedback cell
+
+### SIGROOT013_mutual_information_gain
+
+- Equation: `MI = baseline_bpb - actual_bpb`
+- Invariant root: byte-per-symbol improvement under one ratio schema
+- Admissible transforms: comparisons that keep baseline and actual schema identical
+- Compression use: route evidence coordinate
+- FPGA use: counter difference after codec run
+
+### SIGROOT014_weighted_mi_prediction
+
+- Equation: `MI_pred = sum_i w_i MI_i S_i / sum_i w_i S_i`
+- Invariant root: barycentric coordinate in similarity-weighted evidence simplex
+- Admissible transforms: common positive scaling of all weights
+- Compression use: nearest-prior route prediction
+- FPGA use: weighted accumulator plus reciprocal approximation
+
+### SIGROOT015_surprise_metric
+
+- Equation: `S = log(1 + |delta_MI|)`
+- Invariant root: monotone function of absolute prediction residual
+- Admissible transforms: monotone reparameterization of residual magnitude
+- Compression use: route anomaly detector
+- FPGA use: absolute-delta threshold; log optional
+
+### SIGROOT016_structure_yield
+
+- Equation: `rho = MI / (cost + eps)`
+- Invariant root: information-per-cost efficiency ratio
+- Admissible transforms: unit changes preserving numerator/denominator interpretation
+- Compression use: candidate route priority
+- FPGA use: score-per-cycle allocator
+
+### SIGROOT017_weighted_feature_distance
+
+- Equation: `d(z1,z2) = sqrt(sum_i w_i*((z1_i-z2_i)/s_i)^2)`
+- Invariant root: diagonal metric distance after scale normalization
+- Admissible transforms: coordinate rescaling absorbed into s_i and w_i
+- Compression use: route family clustering
+- FPGA use: scaled L2 distance pipeline
+
+### SIGROOT018_energy_gradient_waveform
+
+- Equation: `wave_E = (|grad E|, omega_gradE, phi_gradE)`
+- Invariant root: gradient magnitude and phase trajectory
+- Admissible transforms: metric-aware coordinate changes
+- Compression use: energy/cost-aware transform scheduling
+- FPGA use: gradient magnitude plus phase accumulator
+
+### SIGROOT019_shape_energy_coupling
+
+- Equation: `C_SE = alpha `
+- Invariant root: metric inner product of shape and energy gradients
+- Admissible transforms: coordinate changes preserving the metric pairing
+- Compression use: align geometry witness only when it reduces route cost
+- FPGA use: dual-gradient dot-product lane
+
+### SIGROOT020_spectral_field_score
+
+- Equation: `score = mM + pP + `
+- Invariant root: bilinear pairing between local state and field
+- Admissible transforms: paired basis changes that preserve the bilinear form
+- Compression use: local route-field compatibility score
+- FPGA use: three-term MAC lane
+
+### SIGROOT021_parabolic_j_score
+
+- Equation: `J(k) = 32 - 0.5*(k-22)^2`
+- Invariant root: distance from resonant vertex k=22
+- Admissible transforms: translation to vertex coordinate u=k-22
+- Compression use: resonance-ranked candidate pruning
+- FPGA use: subtract-square-threshold circuit
+
+### SIGROOT022_cmyk_frequency_lattice
+
+- Equation: `f_ch(h) = base_ch + delta*h`
+- Invariant root: channel-local affine frequency lattice coordinate h
+- Admissible transforms: affine frequency calibration preserving delta steps
+- Compression use: symbol carrier with exact inverse
+- FPGA use: base-plus-shift frequency synthesizer
+
+### SIGROOT023_rydberg_gap
+
+- Equation: `nu_bar = R*(1/n1^2 - 1/n2^2)`
+- Invariant root: reciprocal-square quantum gap
+- Admissible transforms: unit conversion between wavenumber, wavelength, frequency, and energy
+- Compression use: stable physical spectral basis index
+- FPGA use: small table of canonical spectral lines
+
+### SIGROOT024_lorentzian_resonance
+
+- Equation: `L(delta) = 1/(1+delta^2)`
+- Invariant root: squared detuning from spectral center
+- Admissible transforms: sign flip of detuning; normalized wavelength units
+- Compression use: nearest spectral-basis assignment
+- FPGA use: detuning-square LUT
+
+### SIGROOT025_kmer_base4_index
+
+- Equation: `idx = 16*b1 + 4*b2 + b3`
+- Invariant root: base-4 coordinate of codon symbol
+- Admissible transforms: base relabeling with explicit inverse map
+- Compression use: fixed codon/tokenbook coordinate
+- FPGA use: two-bit shift-and-or indexer
+
+### SIGROOT026_dct2_basis
+
+- Equation: `basis_{j,k} = cos(pi/n*(j+1/2)*k)`
+- Invariant root: orthogonal cosine projection coefficient
+- Admissible transforms: orthogonal transforms preserving coefficient energy
+- Compression use: spectral coefficient compaction
+- FPGA use: fixed cosine basis or LUT butterfly
+
+### SIGROOT027_qpsk_phase_class
+
+- Equation: `phase in Z_4`
+- Invariant root: phase class modulo pi/2
+- Admissible transforms: global phase rotation with receiver correction
+- Compression use: 2-bit symbol carrier
+- FPGA use: quadrant decoder
+
+### SIGROOT028_qam16_constellation
+
+- Equation: `symbol = (a in A4, phase in Z4)`
+- Invariant root: finite amplitude-phase lattice point
+- Admissible transforms: affine constellation calibration with preserved decision cells
+- Compression use: 4-bit symbol carrier / QAM transfer metaphor
+- FPGA use: amplitude slicer plus quadrant decoder
+
+### SIGROOT029_dmt_subcarrier_quotient
+
+- Equation: `phase_base = phase_out - offset_i mod cycle`
+- Invariant root: phase quotient after subtracting subcarrier offset
+- Admissible transforms: subcarrier permutation with receipted offset table
+- Compression use: parallel lane carrier with exact demodulation
+- FPGA use: per-lane phase subtractor
+
+### SIGROOT030_hann_window_fft_energy
+
+- Equation: `E_bin = avg_{k in bin} |FFT(window*x)_k|`
+- Invariant root: windowed spectral-energy distribution
+- Admissible transforms: time shift up to phase; amplitude normalization when max-normalized
+- Compression use: audio/signal route feature vector
+- FPGA use: window multiply, FFT, magnitude, bin accumulator
+
+### SIGROOT031_transient_features
+
+- Equation: `transient = (max dx+, max dx-, zero_crossings/n, peak/rms)`
+- Invariant root: edge/impulse morphology of the signal chunk
+- Admissible transforms: time-local scaling with normalized crest and ZCR preserved
+- Compression use: decide raw vs spectral vs hybrid route
+- FPGA use: delta extrema, sign-change counter, RMS/peak lane
+
+### SIGROOT032_predictability_autocorrelation
+
+- Equation: `pred = 0.5*(corr(x_t, x_{t-1}) + 1)`
+- Invariant root: normalized temporal correlation
+- Admissible transforms: affine amplitude scaling removed by mean/variance normalization
+- Compression use: predictor suitability signal
+- FPGA use: sliding dot product and norm lane
+
+### SIGROOT033_cosine_similarity
+
+- Equation: `cos(theta)=/(||a|| ||b||)`
+- Invariant root: projective direction on spectral feature sphere
+- Admissible transforms: positive scaling of either vector
+- Compression use: chunk reuse / skip decision
+- FPGA use: dot product and reciprocal norm threshold
diff --git a/4-Infrastructure/shim/singular_route_chart_equations.py b/4-Infrastructure/shim/singular_route_chart_equations.py
new file mode 100644
index 00000000..2a9fc036
--- /dev/null
+++ b/4-Infrastructure/shim/singular_route_chart_equations.py
@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""Singular Route Chart equation group.
+
+This crystallizes the scattered singularity logic in the Decision Diagram
+Compression Tuning Prior into a named equation group. It is a fail-closed
+route-control surface: singular regions may choose finite charts and exact
+residual repair, but they cannot promote without decode/hash/byte-count
+verification.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_SOURCE = Path(
+ "6-Documentation/tiddlywiki-local/wiki/tiddlers/Decision Diagram Compression Tuning Prior.tid"
+)
+DEFAULT_RECEIPT = Path("4-Infrastructure/shim/singular_route_chart_equations_receipt.json")
+DEFAULT_CURRICULUM = Path("4-Infrastructure/shim/singular_route_chart_equations_curriculum.jsonl")
+
+
+SINGULAR_MARKERS = (
+ "singular",
+ "singularity",
+ "NaN0",
+ "FiniteBundleChart",
+ "canonical blow-up",
+ "blow-up ranking",
+ "unresolved_metadata_hold",
+ "fail closed",
+)
+
+
+SINGULAR_ROUTE_CHART = {
+ "name": "SingularRouteChart",
+ "purpose": (
+ "Turn singular, non-transverse, unbounded, ambiguous, or metadata-held "
+ "route regions into finite chart attempts with ranked failure and exact "
+ "residual repair."
+ ),
+ "primary_function": "detect -> chart -> rank -> bound -> repair -> verify_or_NaN0",
+ "claim_boundary": (
+ "A singular chart is a route-control and fail-closed device. It is not "
+ "compression evidence unless decoded bytes hash to the source and total "
+ "measured bytes beat the incumbent."
+ ),
+}
+
+
+EQUATIONS = [
+ {
+ "id": "SRC0_detect_singularity",
+ "equation": "sigma(r) = class(route_region_r)",
+ "meaning": (
+ "Classify the route region as regular, singular, non_transverse, "
+ "non_locally_trivial, unbounded, ambiguous, or metadata_hold."
+ ),
+ "inputs": ["route_region_r", "receipt_class", "claim_boundary_status"],
+ "outputs": ["singularity_class", "singularity_status"],
+ "fail_closed_when": "class is unbounded or metadata is unverified",
+ },
+ {
+ "id": "SRC1_choose_finite_chart",
+ "equation": "C_s = framework(sigma(r), failure_mode_r)",
+ "meaning": (
+ "Select the smallest finite chart family for the singular region: "
+ "derived_stack, diffeological_pseudobundle, banach_hilbert_bundle, "
+ "principal_infinity_bundle, noncommutative_bundle, or fredholm_bundle."
+ ),
+ "inputs": ["singularity_class", "failure_mode_r"],
+ "outputs": ["framework_family_id", "bundle_chart_id", "finite_rank_proxy_id"],
+ "fail_closed_when": "no finite chart can be explicit",
+ },
+ {
+ "id": "SRC2_project_to_finite_proxy",
+ "equation": (
+ "RouteChart_c = P_finite(Section_c, framework_family_id, "
+ "norm_bound_id, gauge_coherence_receipt) + exact_residual_lane_c"
+ ),
+ "meaning": (
+ "Never serialize the infinite or singular object. Project it into a "
+ "finite proxy and attach an exact residual lane."
+ ),
+ "inputs": [
+ "local_section_id",
+ "framework_family_id",
+ "norm_bound_id",
+ "gauge_coherence_receipt",
+ "source_hash",
+ ],
+ "outputs": ["finite_rank_proxy_id", "exact_residual_lane_id"],
+ "fail_closed_when": "finite proxy lacks exact residual repair",
+ },
+ {
+ "id": "SRC3_rank_blowup_failure",
+ "equation": "rho_{t+1} < rho_t for every repair step",
+ "meaning": (
+ "Use a well-founded blow-up rank so singular repair cannot become "
+ "recursive search."
+ ),
+ "inputs": ["blowup_rank_t", "repair_step_t"],
+ "outputs": ["blowup_rank_next", "repair_path_depth"],
+ "fail_closed_when": "rank does not decrease or repair depth exceeds budget",
+ },
+ {
+ "id": "SRC4_bound_singular_cost",
+ "equation": (
+ "LB_s = chart_header + singularity_receipt + rank_receipt + "
+ "norm_bound_receipt + exact_residual_floor"
+ ),
+ "meaning": (
+ "Charge singularity handling before expensive evaluation. Prune if "
+ "the lower bound cannot beat the incumbent."
+ ),
+ "inputs": [
+ "chart_header_bytes",
+ "singularity_receipt_bytes",
+ "rank_receipt_bytes",
+ "norm_bound_receipt_bytes",
+ "exact_residual_floor",
+ ],
+ "outputs": ["singular_lower_bound_bytes"],
+ "fail_closed_when": "lower bound exceeds incumbent",
+ },
+ {
+ "id": "SRC5_verify_or_nan0",
+ "equation": (
+ "close_s iff hash(decode(RouteChart_c)) == source_hash and "
+ "nan0_flag == 0"
+ ),
+ "meaning": "The singular chart closes only through byte-exact decode and NaN0 false.",
+ "inputs": ["RouteChart_c", "source_hash", "nan0_flag"],
+ "outputs": ["byte_rehydration_hash", "closure_status"],
+ "fail_closed_when": "decode hash mismatches or nan0_flag is true",
+ },
+ {
+ "id": "SRC6_promote_singular_route",
+ "equation": (
+ "promote_s iff close_s and total_bytes_s < incumbent_bytes and "
+ "ratio_schema is explicit"
+ ),
+ "meaning": (
+ "Promotion authority remains measured bytes and exact hash; singular "
+ "math only controls safe charting and pruning."
+ ),
+ "inputs": ["closure_status", "total_bytes_s", "incumbent_bytes", "ratio_schema"],
+ "outputs": ["promotion_status"],
+ "fail_closed_when": "any receipt, byte count, or ratio schema is missing",
+ },
+]
+
+
+DD_STATE_EXTENSION = [
+ "singular_route_chart_id",
+ "singularity_class",
+ "singularity_status",
+ "framework_family_id",
+ "bundle_chart_id",
+ "finite_rank_proxy_id",
+ "norm_bound_id",
+ "gauge_coherence_receipt_id",
+ "index_witness_id",
+ "blowup_rank",
+ "repair_path_depth",
+ "singular_lower_bound_bytes",
+ "exact_residual_lane_id",
+ "nan0_flag",
+ "byte_rehydration_hash",
+]
+
+
+CANDIDATE_EDGES = [
+ "detect_singular_route_region",
+ "choose_singular_finite_chart",
+ "project_singular_to_finite_proxy",
+ "rank_blowup_failure",
+ "bound_singular_route_cost",
+ "emit_singular_exact_residual",
+ "verify_singular_decode_hash",
+ "promote_singular_route_or_nan0",
+]
+
+
+def stable_hash(obj: Any) -> str:
+ payload = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+ return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def source_surface(text: str) -> str:
+ marker = "\n!! Citation Math Function Distillation\n"
+ if marker not in text:
+ return text
+ before, after = text.split(marker, 1)
+ next_marker = "\n!! Where To Tune Next\n"
+ if next_marker in after:
+ _, tail = after.split(next_marker, 1)
+ return before + next_marker + tail
+ return before
+
+
+def extract_singular_evidence(source_text: str) -> dict[str, Any]:
+ lines = source_surface(source_text).splitlines()
+ hits: list[dict[str, Any]] = []
+ for idx, line in enumerate(lines, start=1):
+ folded = line.lower()
+ if any(marker.lower() in folded for marker in SINGULAR_MARKERS):
+ hits.append({"line": idx, "text": line.strip()})
+ return {
+ "matched_line_count": len(hits),
+ "markers": list(SINGULAR_MARKERS),
+ "sample_hits": hits[:40],
+ "source_surface_sha256": hashlib.sha256(source_surface(source_text).encode("utf-8")).hexdigest(),
+ }
+
+
+def build_receipt(source: Path) -> dict[str, Any]:
+ source_text = source.read_text(encoding="utf-8")
+ evidence = extract_singular_evidence(source_text)
+ receipt: dict[str, Any] = {
+ "schema": "singular_route_chart_equations_v1",
+ "generated_at": "2026-05-08T00:00:00+00:00",
+ "source_tiddler": str(source),
+ "source_surface_scope": (
+ "tiddler excluding generated Citation Math Function Distillation and "
+ "Singular Route Chart Equation Group sections"
+ ),
+ "singular_evidence": evidence,
+ "singular_route_chart": SINGULAR_ROUTE_CHART,
+ "equations": EQUATIONS,
+ "dd_state_extension": DD_STATE_EXTENSION,
+ "candidate_edges": CANDIDATE_EDGES,
+ "promotion_rule": (
+ "promote singular route iff finite chart is explicit, blow-up rank "
+ "decreases, lower bound beats incumbent, exact residual repairs bytes, "
+ "decoded hash matches, nan0_flag is false, and measured bytes beat "
+ "the incumbent under an explicit ratio_schema"
+ ),
+ "failure_rule": (
+ "unbounded section, non-decreasing repair rank, missing singularity "
+ "receipt, hidden payload in chart, metadata hold, hash mismatch, or "
+ "NaN0 all fail closed"
+ ),
+ }
+ receipt["receipt_hash"] = stable_hash(receipt)
+ return receipt
+
+
+def curriculum_records(receipt: dict[str, Any]) -> list[dict[str, Any]]:
+ system = (
+ "You are a SingularRouteChart controller. Convert singular route "
+ "regions into finite, receipted, byte-exact chart attempts or fail closed."
+ )
+ records: list[dict[str, Any]] = []
+ for equation in receipt["equations"]:
+ records.append(
+ {
+ "messages": [
+ {"role": "system", "content": system},
+ {
+ "role": "user",
+ "content": json.dumps(
+ {
+ "task": "apply_singular_route_chart_equation",
+ "equation_id": equation["id"],
+ "equation": equation["equation"],
+ "inputs": equation["inputs"],
+ },
+ ensure_ascii=False,
+ ),
+ },
+ {
+ "role": "assistant",
+ "content": json.dumps(
+ {
+ "outputs": equation["outputs"],
+ "meaning": equation["meaning"],
+ "fail_closed_when": equation["fail_closed_when"],
+ "promotion_authority": "decode/hash/byte-count receipt",
+ },
+ ensure_ascii=False,
+ ),
+ },
+ ]
+ }
+ )
+ return records
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--source", type=Path, default=DEFAULT_SOURCE)
+ parser.add_argument("--receipt", type=Path, default=DEFAULT_RECEIPT)
+ parser.add_argument("--curriculum", type=Path, default=DEFAULT_CURRICULUM)
+ args = parser.parse_args()
+
+ receipt = build_receipt(args.source)
+ args.receipt.parent.mkdir(parents=True, exist_ok=True)
+ args.receipt.write_text(json.dumps(receipt, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+ with args.curriculum.open("w", encoding="utf-8") as handle:
+ for record in curriculum_records(receipt):
+ handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+ print(json.dumps(receipt, indent=2, ensure_ascii=False))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/smn_tool_awareness_registry.py b/4-Infrastructure/shim/smn_tool_awareness_registry.py
new file mode 100644
index 00000000..8c1464d7
--- /dev/null
+++ b/4-Infrastructure/shim/smn_tool_awareness_registry.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Emit the tool-facing SMN naming boundary registry.
+
+This keeps downstream shims from conflating:
+
+- Semantic Mass: raw semantic/routing pressure
+- SMN: Semantic Mass Number, a counted semantic-load index
+- Mass Number: admissibility packet with residual and boundary guard
+
+The registry is a routing/validation aid only. It does not promote SMN scores to
+truth claims or Mass Number receipts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+OUT_DIR = REPO / "shared-data" / "data" / "stack_solidification"
+REGISTRY = OUT_DIR / "smn_tool_awareness_registry.json"
+RECEIPT = OUT_DIR / "smn_tool_awareness_receipt.json"
+
+CANONICAL_FILES = [
+ REPO / "6-Documentation/docs/specs/SMN_SEMANTIC_MASS_NUMBERS.md",
+ REPO / "6-Documentation/tiddlywiki-local/wiki/tiddlers/Semantic Mass Numbers.tid",
+ REPO / "6-Documentation/tiddlywiki-local/wiki/tiddlers/Mass Number Theory.tid",
+ REPO / "6-Documentation/wiki/Concept-Archive.md",
+ REPO / "0-Core-Formalism/otom/docs/wiki/NotationNomenclatureRegistry.md",
+ REPO / "shared-data/data/stellar_gas_observation/sdss_manga_dr17_emission_line_channels.json",
+]
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_bytes(data: bytes) -> str:
+ return hashlib.sha256(data).hexdigest()
+
+
+def hash_obj(obj: Any) -> str:
+ return sha256_bytes(stable_json(obj).encode("utf-8"))
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+def file_entry(path: Path) -> dict[str, Any]:
+ return {
+ "path": rel(path),
+ "exists": path.exists(),
+ "sha256": sha256_bytes(path.read_bytes()) if path.exists() else None,
+ }
+
+
+def load_json(path: Path) -> Any:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def smn_data_gate() -> dict[str, Any]:
+ path = REPO / "shared-data/data/stellar_gas_observation/sdss_manga_dr17_emission_line_channels.json"
+ if not path.exists():
+ return {"status": "MISSING", "path": rel(path)}
+ data = load_json(path)
+ failures: list[dict[str, Any]] = []
+ channel_count = 0
+ ratio_count = 0
+ for kind, items in (("channel", data.get("channels", [])), ("diagnostic_ratio", data.get("diagnostic_ratios", []))):
+ for item in items:
+ payload = item.get("semantic_mass_number")
+ object_id = item.get("label") or item.get("id")
+ if not payload:
+ failures.append({"kind": kind, "object_id": object_id, "failure": "missing_semantic_mass_number"})
+ continue
+ components = payload.get("components", {})
+ expected = sum(int(value) for value in components.values())
+ if payload.get("smn") != expected:
+ failures.append({"kind": kind, "object_id": object_id, "failure": "component_sum_mismatch"})
+ if payload.get("not_atomic_mass_number") is not True:
+ failures.append({"kind": kind, "object_id": object_id, "failure": "missing_not_atomic_mass_number_guard"})
+ if payload.get("not_mass_number_receipt") is not True:
+ failures.append({"kind": kind, "object_id": object_id, "failure": "missing_not_mass_number_receipt_guard"})
+ if kind == "channel":
+ channel_count += 1
+ else:
+ ratio_count += 1
+ return {
+ "status": "PASS" if not failures else "FAIL",
+ "path": rel(path),
+ "channels_checked": channel_count,
+ "diagnostic_ratios_checked": ratio_count,
+ "failures": failures,
+ }
+
+
+def nomenclature_gate() -> dict[str, Any]:
+ path = REPO / "0-Core-Formalism/otom/docs/wiki/NotationNomenclatureRegistry.md"
+ text = path.read_text(encoding="utf-8") if path.exists() else ""
+ required = [
+ "mass_number != SMN",
+ "SMN != atomic_mass_number",
+ "SMN != Mass_Number_receipt",
+ "| `smn` | Semantic Mass Number |",
+ "Do not use this as an alias for SMN",
+ ]
+ missing = [item for item in required if item not in text]
+ forbidden = ["| `mass_number` | Mass Number | semantic mass number"]
+ forbidden_hits = [item for item in forbidden if item in text]
+ return {
+ "status": "PASS" if not missing and not forbidden_hits else "FAIL",
+ "path": rel(path),
+ "missing": missing,
+ "forbidden_hits": forbidden_hits,
+ }
+
+
+def build_registry() -> dict[str, Any]:
+ registry = {
+ "schema": "smn_tool_awareness_registry_v1",
+ "created_utc": datetime.now(timezone.utc).isoformat(),
+ "claim_boundary": "Tool awareness only. SMN routes attention; it is not physical mass, proof, truth, or a Mass Number admissibility receipt.",
+ "canonical_terms": [
+ {
+ "term": "Semantic Mass",
+ "tool_key": "semantic_mass",
+ "meaning": "raw semantic/routing pressure or burden",
+ "not_equal_to": ["SMN", "Mass Number", "physical mass"],
+ },
+ {
+ "term": "SMN",
+ "expanded": "Semantic Mass Number",
+ "tool_key": "smn",
+ "meaning": "countable project-local semantic-load number for a symbol, channel, ratio, route, or gate",
+ "formula": "SMN(x)=identity_load+relation_load+provenance_load+constraint_load+decision_load+repair_load",
+ "not_equal_to": ["atomic mass number", "isotope mass", "SI mass", "Mass Number admissibility packet", "proof", "truth"],
+ },
+ {
+ "term": "Mass Number",
+ "tool_key": "mass_number",
+ "meaning": "admissibility/accounting packet with residual and boundary guard",
+ "not_equal_to": ["SMN", "atomic mass number", "physical mass"],
+ },
+ ],
+ "normalization_rules": [
+ {
+ "match": "semantic mass number",
+ "normalize_to": "SMN",
+ "reason": "Avoid aliasing Mass Number admissibility packets.",
+ },
+ {
+ "match": "mass_number",
+ "normalize_to": "Mass Number",
+ "reason": "Keep existing admissibility-gate code paths intact.",
+ },
+ {
+ "match": "semantic_mass_number",
+ "normalize_to": "SMN data payload",
+ "reason": "Machine-readable score object, not physical mass and not proof.",
+ },
+ ],
+ "tool_rules": {
+ "search_index": "Index SMN as semantic-load terminology; do not merge with MassNumber gate entries.",
+ "tiddlywiki": "Link SMN references to [[Semantic Mass Numbers]] and Mass Number gate references to [[Mass Number Theory]].",
+ "equation_awareness": "Classify SMN formulas as semantic_load, not mass_number_transform.",
+ "stellar_gas_tools": "Read semantic_mass_number payloads as routing/audit priority metadata only.",
+ "promotion_gate": "High SMN may prioritize review but cannot admit without a receipt gate.",
+ },
+ "canonical_files": [file_entry(path) for path in CANONICAL_FILES],
+ "gates": {
+ "nomenclature": nomenclature_gate(),
+ "smn_data": smn_data_gate(),
+ },
+ }
+ registry["registry_hash"] = hash_obj({k: v for k, v in registry.items() if k != "registry_hash"})
+ return registry
+
+
+def main() -> int:
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ registry = build_registry()
+ status = "PASS" if all(gate.get("status") == "PASS" for gate in registry["gates"].values()) else "FAIL"
+ receipt = {
+ "schema": "smn_tool_awareness_receipt_v1",
+ "created_utc": datetime.now(timezone.utc).isoformat(),
+ "decision": "ADMIT_SMN_TOOL_AWARENESS" if status == "PASS" else "HOLD_SMN_TOOL_AWARENESS",
+ "claim_boundary": registry["claim_boundary"],
+ "registry": rel(REGISTRY),
+ "registry_hash": registry["registry_hash"],
+ "status": status,
+ "gates": registry["gates"],
+ }
+ REGISTRY.write_text(json.dumps(registry, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ print(json.dumps({"registry": rel(REGISTRY), "receipt": rel(RECEIPT), "status": status}, indent=2))
+ return 0 if status == "PASS" else 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/solids_physics_kernel_probe.py b/4-Infrastructure/shim/solids_physics_kernel_probe.py
new file mode 100644
index 00000000..9350c0c9
--- /dev/null
+++ b/4-Infrastructure/shim/solids_physics_kernel_probe.py
@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+"""Receipt-backed solids-physics kernel probe.
+
+This probe adds a small solids-domain route surface. It admits exact local
+linear-elastic algebra fixtures and keeps anisotropy, plasticity, fracture,
+wave-speed square roots, geometry, and boundary-value claims in HOLD.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from fractions import Fraction
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+OUT_DIR = REPO / "shared-data" / "data" / "solids_physics_kernels"
+REGISTRY = OUT_DIR / "solids_physics_kernel_registry.json"
+RECEIPT = OUT_DIR / "solids_physics_kernel_receipt.json"
+SUMMARY = OUT_DIR / "solids_physics_kernel.md"
+
+SOURCE_REFS = [
+ REPO / "shared-data/data/mass_number_transform_registry/mass_number_transform_registry_receipt.json",
+ REPO / "shared-data/data/cross_domain_kernel_adapters/cross_domain_kernel_adapter_registry_receipt.json",
+]
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_bytes(data: bytes) -> str:
+ return hashlib.sha256(data).hexdigest()
+
+
+def hash_obj(obj: Any) -> str:
+ return sha256_bytes(stable_json(obj).encode("utf-8"))
+
+
+def rel(path: Path) -> str:
+ try:
+ return str(path.relative_to(REPO))
+ except ValueError:
+ return str(path)
+
+
+def file_hash(path: Path) -> str | None:
+ return sha256_bytes(path.read_bytes()) if path.exists() else None
+
+
+def source_ref(path: Path) -> dict[str, Any]:
+ return {"path": rel(path), "exists": path.exists(), "sha256": file_hash(path)}
+
+
+def frac_payload(value: Fraction | tuple[Fraction, ...]) -> Any:
+ if isinstance(value, tuple):
+ return [frac_payload(item) for item in value]
+ return {"numerator": value.numerator, "denominator": value.denominator, "decimal": float(value)}
+
+
+def mn(a: Fraction, b: Fraction) -> Fraction:
+ return (a - b) / (a + b)
+
+
+def hooke_stress(E: Fraction, strain: Fraction) -> Fraction:
+ return E * strain
+
+
+def elastic_energy_from_strain(E: Fraction, strain: Fraction) -> Fraction:
+ return E * strain * strain / 2
+
+
+def elastic_energy_from_stress(stress: Fraction, E: Fraction) -> Fraction:
+ return stress * stress / (2 * E)
+
+
+def d_energy_d_strain(E: Fraction, strain: Fraction) -> Fraction:
+ return E * strain
+
+
+def isotropic_shear_modulus(E: Fraction, nu: Fraction) -> Fraction:
+ return E / (2 * (1 + nu))
+
+
+def isotropic_bulk_modulus(E: Fraction, nu: Fraction) -> Fraction:
+ return E / (3 * (1 - 2 * nu))
+
+
+def harmonic_equal_thickness_modulus(E1: Fraction, E2: Fraction) -> Fraction:
+ return 2 * E1 * E2 / (E1 + E2)
+
+
+def harmonic_from_mn(total: Fraction, x: Fraction) -> Fraction:
+ return total * (1 - x * x) / 2
+
+
+def check_equal(name: str, compressed: Any, direct: Any) -> dict[str, Any]:
+ return {
+ "name": name,
+ "compressed": frac_payload(compressed),
+ "direct": frac_payload(direct),
+ "pass": compressed == direct,
+ }
+
+
+def entry(
+ *,
+ entry_id: str,
+ kernel_opcode: str,
+ solids_role: str,
+ compressed_form: str,
+ expanded_form: str,
+ checks: list[dict[str, Any]],
+ decision: str,
+ residual_policy: str,
+) -> dict[str, Any]:
+ item = {
+ "entry_id": entry_id,
+ "kernel_opcode": kernel_opcode,
+ "solids_role": solids_role,
+ "compressed_form": compressed_form,
+ "expanded_form": expanded_form,
+ "checks": checks,
+ "all_checks_pass": all(check.get("pass", False) for check in checks) if checks else None,
+ "decision": decision,
+ "residual_policy": residual_policy,
+ "claim_boundary": "solids route fixture only; not a finite-element solver or material model",
+ }
+ item["entry_hash"] = hash_obj({k: v for k, v in item.items() if k != "entry_hash"})
+ return item
+
+
+def build_registry() -> dict[str, Any]:
+ E = Fraction(12)
+ strain = Fraction(1, 4)
+ stress = hooke_stress(E, strain)
+ nu = Fraction(1, 4)
+ E1 = Fraction(5)
+ E2 = Fraction(3)
+ total = E1 + E2
+ x = mn(E1, E2)
+
+ entries = [
+ entry(
+ entry_id="hooke_1d_stress",
+ kernel_opcode="LINEAR_MAP",
+ solids_role="one-dimensional linear elastic stress-strain map",
+ compressed_form="sigma = E*epsilon",
+ expanded_form="Hooke 1D linear elasticity",
+ checks=[check_equal("sigma_E12_eps1_4", stress, Fraction(3))],
+ decision="ACCEPT_LINEAR_ELASTIC_FIXTURE",
+ residual_policy="small-strain 1D fixture only; tensor strain, boundary conditions, and material range require receipts",
+ ),
+ entry(
+ entry_id="elastic_energy_density",
+ kernel_opcode="DERIV_QUADRATIC",
+ solids_role="quadratic elastic energy and conjugate stress derivative",
+ compressed_form="U = E*epsilon^2/2; dU/depsilon = sigma",
+ expanded_form="U = sigma*epsilon/2 = sigma^2/(2E)",
+ checks=[
+ check_equal("energy_strain_vs_stress", elastic_energy_from_strain(E, strain), elastic_energy_from_stress(stress, E)),
+ check_equal("dU_deps_equals_sigma", d_energy_d_strain(E, strain), stress),
+ ],
+ decision="ACCEPT_DERIVATIVE_FIXTURE",
+ residual_policy="linear-elastic scalar fixture only; path dependence and plastic work stay residualized",
+ ),
+ entry(
+ entry_id="isotropic_moduli_transform",
+ kernel_opcode="RATIONAL_MATERIAL_TRANSFORM",
+ solids_role="Young/Poisson to shear and bulk modulus transform",
+ compressed_form="G=E/(2*(1+nu)); K=E/(3*(1-2*nu))",
+ expanded_form="isotropic linear elastic moduli relations",
+ checks=[
+ check_equal("G_E12_nu1_4", isotropic_shear_modulus(E, nu), Fraction(24, 5)),
+ check_equal("K_E12_nu1_4", isotropic_bulk_modulus(E, nu), Fraction(8)),
+ ],
+ decision="ACCEPT_ISOTROPIC_FIXTURE",
+ residual_policy="isotropic linear-elastic fixture only; anisotropy and near-incompressibility require domain receipts",
+ ),
+ entry(
+ entry_id="equal_thickness_series_modulus",
+ kernel_opcode="MN_PAIR_HARMONIC",
+ solids_role="two-layer equal-thickness series effective modulus",
+ compressed_form="E_eff = S/2*(1-MN(E1,E2)^2)",
+ expanded_form="E_eff = 2*E1*E2/(E1+E2)",
+ checks=[check_equal("series_E5_3", harmonic_from_mn(total, x), harmonic_equal_thickness_modulus(E1, E2))],
+ decision="ACCEPT_KERNEL_ADAPTER",
+ residual_policy="equal-thickness 1D series fixture only; laminate orientation, shear coupling, and boundary conditions require receipts",
+ ),
+ entry(
+ entry_id="elastic_impedance_contrast",
+ kernel_opcode="MN_REFLECT",
+ solids_role="elastic/acoustic impedance contrast candidate at a solid boundary",
+ compressed_form="Gamma_Z = MN(Z2,Z1)",
+ expanded_form="Gamma_Z = (Z2-Z1)/(Z2+Z1)",
+ checks=[check_equal("solid_impedance_mn_9_4", mn(Fraction(9), Fraction(4)), Fraction(5, 13))],
+ decision="ACCEPT_KERNEL_ADAPTER",
+ residual_policy="contrast identity only; wave mode, incidence angle, attenuation, and boundary conditions require receipts",
+ ),
+ entry(
+ entry_id="longitudinal_wave_speed_route",
+ kernel_opcode="ANALYTIC_SQRT_RATIO",
+ solids_role="elastic wave-speed route",
+ compressed_form="c = sqrt(E/rho) or tensor generalization",
+ expanded_form="wave speed candidate",
+ checks=[],
+ decision="HOLD_ANALYTIC_ADAPTER",
+ residual_policy="requires square-root precision, density/source receipts, mode convention, and material assumptions",
+ ),
+ entry(
+ entry_id="von_mises_yield_route",
+ kernel_opcode="STRESS_INVARIANT",
+ solids_role="distortional-energy yield criterion route",
+ compressed_form="sigma_vm = invariant(stress deviator)",
+ expanded_form="von Mises candidate",
+ checks=[],
+ decision="HOLD_PLASTICITY_ADAPTER",
+ residual_policy="requires tensor convention, yield surface, hardening law, loading path, and experimental/source receipt",
+ ),
+ entry(
+ entry_id="fracture_toughness_route",
+ kernel_opcode="ANALYTIC_SQRT_GEOMETRY",
+ solids_role="crack-tip stress intensity route",
+ compressed_form="K = Y*sigma*sqrt(pi*a)",
+ expanded_form="linear elastic fracture mechanics candidate",
+ checks=[],
+ decision="HOLD_FRACTURE_ADAPTER",
+ residual_policy="requires crack geometry, plane stress/strain convention, units, boundary conditions, and source receipt",
+ ),
+ entry(
+ entry_id="anisotropic_stiffness_tensor_route",
+ kernel_opcode="TENSOR_CONSTITUTIVE_ADAPTER",
+ solids_role="anisotropic stiffness/compliance tensor route",
+ compressed_form="sigma_ij = C_ijkl*epsilon_kl",
+ expanded_form="anisotropic Hooke law candidate",
+ checks=[],
+ decision="HOLD_TENSOR_ADAPTER",
+ residual_policy="requires tensor index convention, symmetry class, units, material source, and closure receipt",
+ ),
+ ]
+ return {
+ "schema": "solids_physics_kernel_registry_v1",
+ "claim_boundary": (
+ "Solids-physics route registry only. Exact local linear-elastic algebra "
+ "fixtures may be accepted, but anisotropic, plasticity, fracture, wave, "
+ "geometry, boundary-value, and material-model claims stay HOLD until "
+ "source data, units, conventions, and residual policies are receipted."
+ ),
+ "canonical_statement": (
+ "Solids physics exposes reusable linear maps, quadratic derivative "
+ "kernels, rational modulus transforms, and MN boundary contrasts; "
+ "material truth lives behind adapter closure."
+ ),
+ "entries": entries,
+ "entry_count": len(entries),
+ "status_counts": {
+ status: sum(1 for item in entries if item["decision"] == status)
+ for status in sorted({item["decision"] for item in entries})
+ },
+ }
+
+
+def build_receipt(registry: dict[str, Any]) -> dict[str, Any]:
+ accepted_statuses = {
+ "ACCEPT_LINEAR_ELASTIC_FIXTURE",
+ "ACCEPT_DERIVATIVE_FIXTURE",
+ "ACCEPT_ISOTROPIC_FIXTURE",
+ "ACCEPT_KERNEL_ADAPTER",
+ }
+ accepted_checks_pass = all(
+ item["all_checks_pass"] is True
+ for item in registry["entries"]
+ if item["decision"] in accepted_statuses
+ )
+ receipt = {
+ "schema": "solids_physics_kernel_receipt_v1",
+ "generated_at_utc": datetime.now(timezone.utc).isoformat(),
+ "timestamp_role": "metadata_only",
+ "generated_at_utc_included_in_receipt_hash": False,
+ "registry_path": rel(REGISTRY),
+ "registry_hash": hash_obj(registry),
+ "source_refs": [source_ref(path) for path in SOURCE_REFS],
+ "entry_count": registry["entry_count"],
+ "status_counts": registry["status_counts"],
+ "accepted_checks_pass": accepted_checks_pass,
+ "decision": "HOLD_SOLIDS_DOMAIN_WITH_ACCEPTED_FIXTURES" if accepted_checks_pass else "HOLD_DIAGNOSTIC",
+ "claim_boundary": registry["claim_boundary"],
+ }
+ receipt["receipt_hash"] = sha256_bytes(
+ stable_json({k: v for k, v in receipt.items() if k not in {"receipt_hash", "generated_at_utc"}}).encode("utf-8")
+ )
+ return receipt
+
+
+def write_summary(registry: dict[str, Any], receipt: dict[str, Any]) -> None:
+ lines = [
+ "# Solids Physics Kernel Probe",
+ "",
+ f"Decision: `{receipt['decision']}` ",
+ f"Receipt hash: `{receipt['receipt_hash']}`",
+ "",
+ registry["claim_boundary"],
+ "",
+ "## Canonical Statement",
+ "",
+ registry["canonical_statement"],
+ "",
+ "## Entry Table",
+ "",
+ "| Entry | Kernel | Decision | Role |",
+ "|---|---|---|---|",
+ ]
+ for item in registry["entries"]:
+ lines.append(
+ f"| `{item['entry_id']}` | `{item['kernel_opcode']}` | "
+ f"`{item['decision']}` | {item['solids_role']} |"
+ )
+ lines.extend(["", "## Guardrail", "", registry["claim_boundary"]])
+ SUMMARY.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ registry = build_registry()
+ receipt = build_receipt(registry)
+ REGISTRY.write_text(json.dumps(registry, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_summary(registry, receipt)
+ print(
+ json.dumps(
+ {
+ "registry": rel(REGISTRY),
+ "receipt": rel(RECEIPT),
+ "summary": rel(SUMMARY),
+ "receipt_hash": receipt["receipt_hash"],
+ "decision": receipt["decision"],
+ "status_counts": registry["status_counts"],
+ },
+ indent=2,
+ sort_keys=True,
+ )
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/solved_math_pruning_surface.py b/4-Infrastructure/shim/solved_math_pruning_surface.py
new file mode 100644
index 00000000..1f636d77
--- /dev/null
+++ b/4-Infrastructure/shim/solved_math_pruning_surface.py
@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Build an admissible-prior index from the local math model map.
+
+This does not claim the listed equations are formal proofs. It classifies local
+model-map entries into evidence tiers so compression/logogram/FPGA searches can
+try known solved or implemented shapes first, then fall back to wider search.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_MODEL_MAP = Path("3-Mathematical-Models/MATH_MODEL_MAP.tsv")
+
+
+def evidence_tier(row: dict[str, str]) -> str:
+ implemented = row.get("Implemented", "")
+ status = row.get("Status", "")
+ location = row.get("Location", "")
+ purpose = row.get("Purpose", "")
+ haystack = " ".join([implemented, status, location, purpose]).lower()
+
+ if "lean" in haystack and "✅" in status:
+ return "formal_or_lean_backed"
+ if any(token in haystack for token in ["verilog", "fpga", "hardware"]) and "✅" in status:
+ return "hardware_or_hdl_backed"
+ if any(token in implemented.lower() for token in ["python", "rust", "c++", "6502", "subl"]) and "✅" in status:
+ return "implemented_local"
+ if implemented.lower() == "spec" and "✅" in status:
+ return "spec_admissible"
+ if implemented.lower() == "documented" and "✅" in status:
+ return "documented_reference"
+ if "✅" in status:
+ return "indexed_admissible"
+ return "unverified_or_pending"
+
+
+def tier_rank(tier: str) -> int:
+ ranks = {
+ "formal_or_lean_backed": 0,
+ "hardware_or_hdl_backed": 1,
+ "implemented_local": 2,
+ "spec_admissible": 3,
+ "documented_reference": 4,
+ "indexed_admissible": 5,
+ "unverified_or_pending": 6,
+ }
+ return ranks.get(tier, 9)
+
+
+def row_score(row: dict[str, str], tier: str) -> int:
+ score = 100 - tier_rank(tier) * 10
+ domain = row.get("Domain_Type", "")
+ bind = row.get("Bind_Class", "")
+ family = row.get("Family", "")
+ purpose = row.get("Purpose", "")
+ text = " ".join([domain, bind, family, purpose]).lower()
+ for token in ("compression", "encoding", "signal", "control", "routing", "hardware", "fpga"):
+ if token in text:
+ score += 3
+ if row.get("Location", "").startswith(("http://", "https://")):
+ score -= 5
+ return score
+
+
+def load_rows(path: Path) -> list[dict[str, str]]:
+ with path.open(newline="", encoding="utf-8") as handle:
+ reader = csv.DictReader(handle, delimiter="\t")
+ rows = []
+ for row in reader:
+ clean = {}
+ for key, value in row.items():
+ if key is None:
+ if value:
+ clean["Extra"] = " ".join(str(part) for part in value)
+ continue
+ clean[key] = str(value or "")
+ rows.append(clean)
+ return rows
+
+
+def matches_query(row: dict[str, str], query: str) -> bool:
+ if not query:
+ return True
+ q = query.lower()
+ return q in " ".join(row.values()).lower()
+
+
+def build_index(rows: list[dict[str, str]], query: str, include_documented: bool) -> dict[str, Any]:
+ entries = []
+ for row in rows:
+ if not matches_query(row, query):
+ continue
+ tier = evidence_tier(row)
+ if tier == "unverified_or_pending":
+ continue
+ if not include_documented and tier == "documented_reference":
+ continue
+ entry = {
+ "id": row.get("#", ""),
+ "model_name": row.get("Model_Name", ""),
+ "family": row.get("Family", ""),
+ "equation": row.get("Equation", ""),
+ "variables": row.get("Variables", ""),
+ "purpose": row.get("Purpose", ""),
+ "location": row.get("Location", ""),
+ "implemented": row.get("Implemented", ""),
+ "status": row.get("Status", ""),
+ "domain_type": row.get("Domain_Type", ""),
+ "bind_class": row.get("Bind_Class", ""),
+ "evidence_tier": tier,
+ "pruning_score": row_score(row, tier),
+ }
+ entries.append(entry)
+
+ entries.sort(key=lambda item: (-item["pruning_score"], tier_rank(item["evidence_tier"]), item["model_name"]))
+
+ by_tier = Counter(entry["evidence_tier"] for entry in entries)
+ by_domain = Counter(entry["domain_type"] for entry in entries if entry["domain_type"])
+ by_bind = Counter(entry["bind_class"] for entry in entries if entry["bind_class"])
+ return {
+ "schema": "solved_math_pruning_surface_v1",
+ "claim_boundary": "Rows are admissible search priors, not theorem claims unless their evidence tier says Lean/formal.",
+ "source": str(DEFAULT_MODEL_MAP),
+ "query": query,
+ "include_documented": include_documented,
+ "entry_count": len(entries),
+ "summary": {
+ "by_evidence_tier": dict(by_tier),
+ "top_domain_types": by_domain.most_common(12),
+ "top_bind_classes": by_bind.most_common(12),
+ },
+ "entries": entries,
+ }
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--model-map", type=Path, default=DEFAULT_MODEL_MAP)
+ parser.add_argument("--query", default="")
+ parser.add_argument("--include-documented", action="store_true")
+ parser.add_argument("--limit", type=int, default=50)
+ parser.add_argument("--out", type=Path)
+ args = parser.parse_args()
+
+ rows = load_rows(args.model_map)
+ index = build_index(rows, args.query, args.include_documented)
+ index["source"] = str(args.model_map)
+ if args.limit >= 0:
+ index["entries"] = index["entries"][: args.limit]
+ text = json.dumps(index, indent=2, ensure_ascii=False)
+ if args.out:
+ args.out.parent.mkdir(parents=True, exist_ok=True)
+ args.out.write_text(text + "\n", encoding="utf-8")
+ print(text)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/solved_problem_output_verifier.py b/4-Infrastructure/shim/solved_problem_output_verifier.py
new file mode 100644
index 00000000..f3930666
--- /dev/null
+++ b/4-Infrastructure/shim/solved_problem_output_verifier.py
@@ -0,0 +1,388 @@
+#!/usr/bin/env python3
+"""Run solved/known-problem checks and emit verification receipts.
+
+This harness is deliberately conservative. It reruns a small set of existing
+4-primitive Erdős scripts whose targets are solved theorems, solved lower-bound
+smokes, or finite constructions. Open conjecture smoke tests are listed as
+excluded so they cannot be promoted to theorem evidence by accident.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+WIKI = REPO / "6-Documentation" / "tiddlywiki-local" / "wiki" / "tiddlers"
+
+
+def sha256_bytes(data: bytes) -> str:
+ return hashlib.sha256(data).hexdigest()
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def ratio_ok(value: float, target: float = 1.0, eps: float = 1e-12) -> bool:
+ return abs(float(value) - target) <= eps
+
+
+def validate_egz(data: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+ analysis = data.get("theorem_analysis", {})
+ results = data.get("results", [])
+ packet_witness_ok = sum(
+ 1
+ for item in results
+ if item.get("subset_found")
+ and item.get("subset")
+ and sum(item["subset"]) % int(item["n"]) == 0
+ and len(item["subset"]) == int(item["n"])
+ )
+ ok = (
+ analysis.get("subset_found_count") == analysis.get("total_tests")
+ and ratio_ok(analysis.get("success_rate", 0.0))
+ and packet_witness_ok == len(results)
+ )
+ return ok, {
+ "subset_found_count": analysis.get("subset_found_count"),
+ "total_tests": analysis.get("total_tests"),
+ "success_rate": analysis.get("success_rate"),
+ "packet_witness_ok": packet_witness_ok,
+ }
+
+
+def validate_ekr(data: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+ analysis = data.get("theorem_analysis", [])
+ results = data.get("results", [])
+ ratio_hits = sum(1 for item in analysis if ratio_ok(item.get("ratio", 0.0)))
+ family_ok = sum(1 for item in results if item.get("is_intersecting") and item.get("family_size") == item.get("field", {}).get("theoretical_max"))
+ ok = bool(analysis) and ratio_hits == len(analysis) and family_ok == len(results)
+ return ok, {
+ "ratio_hits": ratio_hits,
+ "analysis_count": len(analysis),
+ "intersecting_optimal_family_count": family_ok,
+ "result_count": len(results),
+ }
+
+
+def validate_szekeres(data: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+ analysis = data.get("theorem_analysis", {})
+ results = data.get("results", [])
+ witness_ok = sum(
+ 1
+ for item in results
+ if item.get("theorem_holds") and int(item.get("max_monotone_length", 0)) >= int(item.get("n", 0)) + 1
+ )
+ ok = (
+ analysis.get("theorem_holds_count") == analysis.get("total_tests")
+ and ratio_ok(analysis.get("success_rate", 0.0))
+ and witness_ok == len(results)
+ )
+ return ok, {
+ "theorem_holds_count": analysis.get("theorem_holds_count"),
+ "total_tests": analysis.get("total_tests"),
+ "success_rate": analysis.get("success_rate"),
+ "monotone_witness_ok": witness_ok,
+ }
+
+
+def validate_distinct_distances(data: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+ analysis = data.get("problem_analysis", {})
+ results = data.get("results", [])
+ bound_ok = sum(
+ 1
+ for item in results
+ if item.get("bound_holds")
+ and item.get("num_distinct_distances", 0) >= item.get("theoretical_bound", float("inf"))
+ )
+ ok = (
+ analysis.get("bound_holds_count") == analysis.get("total_tests")
+ and ratio_ok(analysis.get("success_rate", 0.0))
+ and bound_ok == len(results)
+ )
+ return ok, {
+ "bound_holds_count": analysis.get("bound_holds_count"),
+ "total_tests": analysis.get("total_tests"),
+ "success_rate": analysis.get("success_rate"),
+ "per_instance_bound_ok": bound_ok,
+ }
+
+
+def validate_hadamard_sylvester(data: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+ analysis = data.get("conjecture_analysis", {})
+ results = data.get("results", [])
+ construction_ok = sum(
+ 1
+ for item in results
+ if item.get("hadamard_exists") and item.get("spectral", {}).get("is_orthogonal")
+ )
+ ok = (
+ analysis.get("hadamard_exists_count") == analysis.get("total_tests")
+ and ratio_ok(analysis.get("existence_rate", 0.0))
+ and construction_ok == len(results)
+ )
+ return ok, {
+ "hadamard_exists_count": analysis.get("hadamard_exists_count"),
+ "total_tests": analysis.get("total_tests"),
+ "existence_rate": analysis.get("existence_rate"),
+ "orthogonal_construction_ok": construction_ok,
+ "boundary_note": analysis.get("note"),
+ }
+
+
+CaseValidator = Callable[[dict[str, Any]], tuple[bool, dict[str, Any]]]
+
+
+CASES: list[dict[str, Any]] = [
+ {
+ "id": "erdos_ginzburg_ziv",
+ "title": "Erdos-Ginzburg-Ziv theorem",
+ "classification": "solved_theorem",
+ "script": "test_erdos_ginzburg_ziv_4primitive.py",
+ "result": "test_erdos_ginzburg_ziv_4primitive_results.json",
+ "validator": validate_egz,
+ "claim_boundary": "Finite generated instances verify the local witness detector against a solved theorem; this is not a proof of the theorem.",
+ },
+ {
+ "id": "erdos_ko_rado",
+ "title": "Erdos-Ko-Rado theorem",
+ "classification": "solved_theorem",
+ "script": "test_erdos_ko_rado_4primitive.py",
+ "result": "test_erdos_ko_rado_4primitive_results.json",
+ "validator": validate_ekr,
+ "claim_boundary": "Finite small parameter checks verify the local family detector against a solved theorem; this is not a proof of the theorem.",
+ },
+ {
+ "id": "erdos_szekeres",
+ "title": "Erdos-Szekeres monotone subsequence theorem",
+ "classification": "solved_theorem",
+ "script": "test_erdos_szekeres_4primitive.py",
+ "result": "test_erdos_szekeres_4primitive_results.json",
+ "validator": validate_szekeres,
+ "claim_boundary": "Finite random permutations verify the local monotone-subsequence detector against a solved theorem; this is not a proof of the theorem.",
+ },
+ {
+ "id": "erdos_distinct_distances",
+ "title": "Erdos distinct distances lower-bound smoke",
+ "classification": "solved_bound_smoke",
+ "script": "test_erdos_distinct_distances_4primitive.py",
+ "result": "test_erdos_distinct_distances_4primitive_results.json",
+ "validator": validate_distinct_distances,
+ "claim_boundary": "Finite point clouds verify the local lower-bound checker; this does not solve or certify the full extremal geometry result.",
+ },
+ {
+ "id": "hadamard_sylvester",
+ "title": "Hadamard Sylvester construction",
+ "classification": "finite_construction",
+ "script": "test_erdos_hadamard_4primitive.py",
+ "result": "test_erdos_hadamard_4primitive_results.json",
+ "validator": validate_hadamard_sylvester,
+ "claim_boundary": "Verifies Sylvester power-of-two Hadamard constructions only; the general Hadamard conjecture remains open.",
+ },
+]
+
+
+EXCLUDED_CASES = [
+ {
+ "id": "erdos_gyarfas",
+ "reason": "known anomaly lane: claimed failures need independent cycle certificates before use",
+ "result": "test_erdos_gyarfas_4primitive_results.json",
+ },
+ {
+ "id": "erdos_selfridge",
+ "reason": "open conjecture finite smoke only",
+ "result": "test_erdos_selfridge_4primitive_results.json",
+ },
+ {
+ "id": "erdos_straus",
+ "reason": "open conjecture finite smoke only",
+ "result": "test_erdos_straus_4primitive_results.json",
+ },
+ {
+ "id": "erdos_ternary_2n",
+ "reason": "open conjecture finite smoke only",
+ "result": "test_erdos_ternary_2n_4primitive_results.json",
+ },
+ {
+ "id": "erdos_mollin_walsh",
+ "reason": "status naming may be inverted; inspect before promotion",
+ "result": "test_erdos_mollin_walsh_4primitive_results.json",
+ },
+]
+
+
+def run_case(case: dict[str, Any], timeout: int) -> dict[str, Any]:
+ script = SHIM / case["script"]
+ result = SHIM / case["result"]
+ before_hash = sha256_bytes(result.read_bytes()) if result.exists() else None
+ proc = subprocess.run(
+ [sys.executable, str(script)],
+ cwd=str(REPO),
+ text=True,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ timeout=timeout,
+ check=False,
+ )
+ stdout_tail = proc.stdout[-4000:]
+ stderr_tail = proc.stderr[-4000:]
+ run_ok = proc.returncode == 0 and result.exists()
+ after_hash = sha256_bytes(result.read_bytes()) if result.exists() else None
+ validation_ok = False
+ metrics: dict[str, Any] = {}
+ result_top_keys: list[str] = []
+ if run_ok:
+ data = load_json(result)
+ result_top_keys = sorted(data.keys())
+ validation_ok, metrics = case["validator"](data)
+ return {
+ "id": case["id"],
+ "title": case["title"],
+ "classification": case["classification"],
+ "script": str(script.relative_to(REPO)),
+ "result": str(result.relative_to(REPO)),
+ "returncode": proc.returncode,
+ "run_ok": run_ok,
+ "validation_ok": validation_ok,
+ "result_hash_before": before_hash,
+ "result_hash_after": after_hash,
+ "result_top_keys": result_top_keys,
+ "metrics": metrics,
+ "stdout_tail": stdout_tail,
+ "stderr_tail": stderr_tail,
+ "claim_boundary": case["claim_boundary"],
+ }
+
+
+def build_curriculum(receipt: dict[str, Any]) -> list[dict[str, Any]]:
+ system = "You are a solved-problem verification router. Return compact JSON and never promote finite smoke tests into proofs."
+ records = []
+ for case in receipt["cases"]:
+ prompt = {
+ "task": "classify_solved_problem_output",
+ "case_id": case["id"],
+ "classification": case["classification"],
+ "metrics": case["metrics"],
+ "claim_boundary": case["claim_boundary"],
+ "instruction": "Decide whether this result can be used as verifier evidence for the local math stack.",
+ }
+ answer = {
+ "selected": bool(case["validation_ok"]),
+ "use_as": "solved_problem_verification" if case["validation_ok"] else "diagnostic_failure",
+ "evidence_tier": case["classification"],
+ "claim_boundary": case["claim_boundary"],
+ "source_path": case["result"],
+ "source_hash": case["result_hash_after"],
+ "receipt_rule": "Use as detector/output validation only; require formal proof receipts for theorem promotion.",
+ }
+ records.append(
+ {
+ "messages": [
+ {"role": "system", "content": system},
+ {"role": "user", "content": json.dumps(prompt, ensure_ascii=False)},
+ {"role": "assistant", "content": json.dumps(answer, ensure_ascii=False)},
+ ]
+ }
+ )
+ return records
+
+
+def write_wiki(receipt: dict[str, Any], path: Path) -> None:
+ passed = sum(1 for case in receipt["cases"] if case["validation_ok"])
+ total = len(receipt["cases"])
+ lines = [
+ "created: 20260507000000000",
+ "modified: 20260507000000000",
+ "tags: ResearchStack Erdos Verification Metaprobe Math",
+ "title: Solved Problem Output Verifier",
+ "type: text/vnd.tiddlywiki",
+ "",
+ "! Solved Problem Output Verifier",
+ "",
+ "This tiddler records the solved/known-problem verifier for the local 4-primitive Erdős scripts.",
+ "",
+ f"Durable source: `4-Infrastructure/shim/solved_problem_output_verifier.py`",
+ "",
+ f"Receipt: `4-Infrastructure/shim/solved_problem_output_verifier_receipt.json`",
+ "",
+ f"Curriculum: `4-Infrastructure/shim/solved_problem_output_verifier_curriculum.jsonl`",
+ "",
+ "!! Verification Result",
+ "",
+ f"* Cases passed: {passed}/{total}",
+ f"* Overall lawful: `{str(receipt['lawful']).lower()}`",
+ "",
+ "!! Included Cases",
+ "",
+ ]
+ for case in receipt["cases"]:
+ status = "PASS" if case["validation_ok"] else "FAIL"
+ lines.append(f"* {status} `{case['id']}` ({case['classification']}): {case['claim_boundary']}")
+ lines.extend(
+ [
+ "",
+ "!! Excluded / Non-Promotable Cases",
+ "",
+ ]
+ )
+ for case in receipt["excluded_cases"]:
+ lines.append(f"* `{case['id']}`: {case['reason']}")
+ lines.extend(
+ [
+ "",
+ "!! Claim Boundary",
+ "",
+ "This verifier checks local outputs against solved or construction-backed expectations. It does not prove the theorems, and it explicitly keeps open conjecture smoke tests out of the solved-problem lane.",
+ "",
+ "!! Links",
+ "",
+ "* [[Erdos Four Primitive Diagnostics]]",
+ "* [[Custom Equation Awareness Manifest]]",
+ "* [[Physics Math LLM Metaprobe Audit]]",
+ ]
+ )
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--timeout", type=int, default=120)
+ parser.add_argument("--receipt", type=Path, default=SHIM / "solved_problem_output_verifier_receipt.json")
+ parser.add_argument("--curriculum", type=Path, default=SHIM / "solved_problem_output_verifier_curriculum.jsonl")
+ parser.add_argument("--wiki", type=Path, default=WIKI / "Solved Problem Output Verifier.tid")
+ args = parser.parse_args()
+
+ cases = [run_case(case, args.timeout) for case in CASES]
+ pass_count = sum(1 for case in cases if case["validation_ok"])
+ receipt = {
+ "schema": "solved_problem_output_verifier_receipt_v1",
+ "timestamp": datetime.now(timezone.utc).isoformat(),
+ "claim_boundary": "Solved-problem runs validate local detectors and outputs; they are not theorem proofs and do not promote open conjecture smoke tests.",
+ "cases": cases,
+ "excluded_cases": EXCLUDED_CASES,
+ "pass_count": pass_count,
+ "case_count": len(cases),
+ "lawful": pass_count == len(cases),
+ }
+ args.receipt.parent.mkdir(parents=True, exist_ok=True)
+ args.receipt.write_text(json.dumps(receipt, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+ with args.curriculum.open("w", encoding="utf-8") as handle:
+ for record in build_curriculum(receipt):
+ handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+ write_wiki(receipt, args.wiki)
+ print(json.dumps(receipt, indent=2, ensure_ascii=False))
+ return 0 if receipt["lawful"] else 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/spamosaic_spatial_mosaic_prior.py b/4-Infrastructure/shim/spamosaic_spatial_mosaic_prior.py
new file mode 100644
index 00000000..bb0039d1
--- /dev/null
+++ b/4-Infrastructure/shim/spamosaic_spatial_mosaic_prior.py
@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Distill SpaMosaic into a bounded route prior for fragmented observations.
+
+SpaMosaic integrates partially overlapping spatial multi-omics datasets into a
+shared latent atlas using contrastive learning and spatial graph structure. For
+the compressor, the useful shape is not biological atlas construction itself:
+it is mosaic integration of incomplete route observations, batch correction,
+spatial-neighbor constraints, and missing-lane imputation that remains only a
+proposal until exact residual repair closes the byte stream.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+OUT = SHIM / "spamosaic_spatial_mosaic_prior_receipt.json"
+CURRICULUM_OUT = SHIM / "spamosaic_spatial_mosaic_prior_curriculum.jsonl"
+
+GENERATED_AT = "2026-05-08T00:00:00+00:00"
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+SOURCE_EVIDENCE = {
+ "news": {
+ "title": "AI tool unifies fragmented cell maps into spatial atlases across tissues",
+ "source": "Phys.org / Northwestern University",
+ "published_date": "2026-05-07",
+ "url": "https://phys.org/news/2026-05-ai-tool-fragmented-cell-spatial.html",
+ },
+ "primary_paper": {
+ "title": "Mosaic integration of spatial multi-omics with SpaMosaic",
+ "authors": "Xuhua Yan et al.",
+ "journal": "Nature Genetics",
+ "published_date": "2026-04-24",
+ "doi": "10.1038/s41588-026-02573-3",
+ "url": "https://www.nature.com/articles/s41588-026-02573-3",
+ },
+ "observed_core_claims": [
+ "mosaic_datasets_measure_only_partially_overlapping_modalities",
+ "contrastive_learning_learns_cross_dataset_similarities_and_differences",
+ "graph_neural_networks_use_spatial_neighbor_relationships",
+ "shared_latent_space_is_modality_agnostic_and_batch_corrected",
+ "method_identifies_coherent_spatial_domains",
+ "method_imputes_missing_molecular_layers",
+ "imputation_reliability_requires_further_testing",
+ "framework_scales_to_large_spatial_sections",
+ ],
+}
+
+
+MOSAIC_ROUTE_OPERATORS = [
+ {
+ "id": "partial_modality_observation",
+ "source_shape": "each tissue slice measures only some omics layers",
+ "route_mapping": "each corpus slice or route probe observes only some transform features",
+ "claim_boundary": "observation is incomplete until exact residual closes bytes",
+ },
+ {
+ "id": "contrastive_alignment",
+ "source_shape": "learn similarities and differences across fragmented datasets",
+ "route_mapping": "align route observations across slices without collapsing distinct byte states",
+ "claim_boundary": "alignment is a proposal feature, not proof of equivalence",
+ },
+ {
+ "id": "spatial_graph_constraint",
+ "source_shape": "neighboring cells constrain spatial domain inference",
+ "route_mapping": "neighbor spans constrain route-family continuity and sidecar locality",
+ "claim_boundary": "graph smoothness cannot override decode hash",
+ },
+ {
+ "id": "batch_effect_correction",
+ "source_shape": "remove technical processing differences while preserving biology",
+ "route_mapping": "normalize route-observation artifacts while preserving exact byte authority",
+ "claim_boundary": "correction must emit residual for every byte-affecting change",
+ },
+ {
+ "id": "missing_lane_imputation",
+ "source_shape": "predict unmeasured molecular layers",
+ "route_mapping": "predict missing tokenbook / sidecar / witness lanes before exact repair",
+ "claim_boundary": "imputed lane is sketch-only unless residual repair restores bytes",
+ },
+]
+
+
+EQUATIONS = [
+ {
+ "id": "SM0_mosaic_observation",
+ "equation": "O_s = (slice_s, observed_lanes_s, missing_lanes_s, spatial_graph_s)",
+ "meaning": "Each route observation is a partial lane measurement over a local graph.",
+ },
+ {
+ "id": "SM1_shared_latent_chart",
+ "equation": "z_s = Align_contrastive(O_s, batch_id_s, graph_s)",
+ "meaning": "Map fragmented observations into a shared chart while retaining batch provenance.",
+ },
+ {
+ "id": "SM2_batch_corrected_not_byte_corrected",
+ "equation": "batch_correct(z_s) != byte_correct(source_s)",
+ "meaning": "Removing observation artifacts is not the same as proving byte rehydration.",
+ },
+ {
+ "id": "SM3_missing_lane_prediction",
+ "equation": "imputed_lane_l = Predict(z_s, graph_s, modality_l)",
+ "meaning": "Missing route lanes can be proposed from nearby observations.",
+ },
+ {
+ "id": "SM4_exact_closure",
+ "equation": "promote iff hash(decode(imputed_lanes + exact_residuals)) == source_hash",
+ "meaning": "Imputation closes only through exact residual repair and hash.",
+ },
+ {
+ "id": "SM5_lower_bound",
+ "equation": "LB = mosaic_header + graph_receipt + batch_receipt + imputation_receipt + residual_floor",
+ "meaning": "All atlas/witness costs must be charged before route promotion.",
+ },
+]
+
+
+def build_receipt() -> dict[str, Any]:
+ receipt: dict[str, Any] = {
+ "schema": "spamosaic_spatial_mosaic_prior_v1",
+ "generated_at": GENERATED_AT,
+ "source_evidence": SOURCE_EVIDENCE,
+ "primary_decision": {
+ "name": "use_mosaic_integration_as_fragmented_route_observation_prior",
+ "statement": (
+ "Use SpaMosaic's shape as a prior for aligning incomplete route "
+ "observations across slices, correcting observation artifacts, "
+ "and proposing missing lanes. Treat every imputed lane as sketch "
+ "data until exact residual repair and rehydration hash close."
+ ),
+ },
+ "mosaic_route_operators": MOSAIC_ROUTE_OPERATORS,
+ "equations": EQUATIONS,
+ "candidate_dd_state_extension": [
+ "mosaic_observation_id",
+ "observed_lane_set",
+ "missing_lane_set",
+ "spatial_neighbor_graph_id",
+ "contrastive_alignment_id",
+ "batch_id",
+ "batch_correction_receipt_id",
+ "shared_latent_chart_id",
+ "spatial_domain_id",
+ "imputed_lane_id",
+ "imputation_confidence",
+ "imputation_reliability_status",
+ "exact_residual_lane_id",
+ "mosaic_lower_bound_bytes",
+ "byte_rehydration_hash",
+ ],
+ "candidate_dd_edges": [
+ "open_mosaic_route_observation",
+ "record_observed_and_missing_lanes",
+ "build_spatial_neighbor_graph",
+ "align_observations_contrastively",
+ "correct_batch_effect_with_receipt",
+ "identify_route_spatial_domain",
+ "predict_missing_route_lane",
+ "emit_exact_residual_for_imputed_lane",
+ "verify_mosaic_rehydration_hash",
+ "reject_imputation_without_exact_repair",
+ ],
+ "lower_bound": [
+ "mosaic_header_bytes",
+ "spatial_graph_receipt_floor",
+ "contrastive_alignment_receipt_floor",
+ "batch_correction_receipt_floor",
+ "imputed_lane_receipt_floor",
+ "exact_residual_lane_floor",
+ ],
+ "promotion_rule": [
+ "mosaic_layer_only_aligns_or_proposes_route_lanes",
+ "batch_correction_is_receipted_and_byte_preserving_or_residualized",
+ "spatial_graph_smoothness_does_not_override_byte_hash",
+ "missing_lane_imputation_carries_exact_residual_repair",
+ "imputation_reliability_status_is_recorded",
+ "decoded_hash_matches_source",
+ "measured_total_bytes_beat_incumbent_under_ratio_schema",
+ ],
+ "failure_rule": [
+ "imputed_lane_without_exact_residual -> not_promoted",
+ "batch_correction_changes_bytes_without_residual -> invalid_receipt",
+ "spatial_domain_match_without_byte_hash -> diagnostic_only",
+ "mosaic_header_larger_than_byte_gain -> prune",
+ "unbounded_neighbor_graph_or_alignment -> NaN0",
+ ],
+ "claim_boundary": (
+ "This prior imports SpaMosaic's fragmented-observation integration "
+ "shape. It is not evidence that biological atlas methods compress "
+ "text bytes, and it does not promote routes without exact decode, "
+ "hash, byte count, and explicit ratio schema."
+ ),
+ }
+ preimage = {key: value for key, value in receipt.items() if key != "receipt_hash"}
+ receipt["receipt_hash"] = sha256_text(stable_json(preimage))
+ return receipt
+
+
+def curriculum_lines(receipt: dict[str, Any]) -> list[dict[str, Any]]:
+ lines: list[dict[str, Any]] = []
+ for item in receipt["mosaic_route_operators"]:
+ lines.append({"type": "mosaic_route_operator", **item})
+ for item in receipt["equations"]:
+ lines.append({"type": "equation", **item})
+ for rule in receipt["promotion_rule"]:
+ lines.append({"type": "promotion_rule", "rule": rule})
+ for rule in receipt["failure_rule"]:
+ lines.append({"type": "failure_rule", "rule": rule})
+ return lines
+
+
+def main() -> None:
+ receipt = build_receipt()
+ OUT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ lines = curriculum_lines(receipt)
+ CURRICULUM_OUT.write_text(
+ "".join(json.dumps(line, sort_keys=True) + "\n" for line in lines),
+ encoding="utf-8",
+ )
+ print(json.dumps({
+ "receipt": rel(OUT),
+ "curriculum": rel(CURRICULUM_OUT),
+ "receipt_hash": receipt["receipt_hash"],
+ "curriculum_records": len(lines),
+ "decision": receipt["primary_decision"]["name"],
+ }, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stack_fail_closure_register.py b/4-Infrastructure/shim/stack_fail_closure_register.py
new file mode 100644
index 00000000..f4a9b5c4
--- /dev/null
+++ b/4-Infrastructure/shim/stack_fail_closure_register.py
@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+"""Create closure tickets for current stack failures and HOLD buckets."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+TRI = REPO / "shared-data" / "data" / "rrc_tri_cycle_audit" / "rrc_tri_cycle_audit_receipt.json"
+STACK = REPO / "shared-data" / "data" / "stack_solidification" / "stack_solidification_receipt.json"
+OUT_DIR = REPO / "shared-data" / "data" / "stack_solidification"
+OUT = OUT_DIR / "stack_fail_closure_register.json"
+DOC = REPO / "6-Documentation" / "docs" / "stack_fail_closure_register_2026-05-09.md"
+
+
+def load_json(path: Path) -> Any:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def git_dirty_count() -> int | None:
+ proc = subprocess.run(
+ ["git", "status", "--short", "--untracked-files=all"],
+ cwd=REPO,
+ text=True,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ check=False,
+ )
+ if proc.returncode != 0:
+ return None
+ return len([line for line in proc.stdout.splitlines() if line.strip()])
+
+
+def ticket(
+ ticket_id: str,
+ title: str,
+ failure_class: str,
+ status: str,
+ evidence: list[str],
+ closure_gate: list[str],
+ next_action: list[str],
+ owner_surface: str,
+) -> dict[str, Any]:
+ return {
+ "ticket_id": ticket_id,
+ "title": title,
+ "failure_class": failure_class,
+ "status": status,
+ "evidence": evidence,
+ "closure_gate": closure_gate,
+ "next_action": next_action,
+ "owner_surface": owner_surface,
+ }
+
+
+def build_register() -> dict[str, Any]:
+ tri = load_json(TRI)
+ stack = load_json(STACK) if STACK.exists() else {}
+ sem_receipt_path = OUT_DIR / "external_sem_entity_diff_probe_receipt.json"
+ sem_receipt = load_json(sem_receipt_path) if sem_receipt_path.exists() else {}
+ hold_checklist_path = OUT_DIR / "rrc_hold_closure_checklist.json"
+ hold_checklist = load_json(hold_checklist_path) if hold_checklist_path.exists() else {}
+ coeff_manifest_path = OUT_DIR / "network_topology_coefficient_calibration_manifest.json"
+ coeff_manifest = load_json(coeff_manifest_path) if coeff_manifest_path.exists() else {}
+ pred_registry_path = OUT_DIR / "network_topology_prediction_hold_registry.json"
+ pred_registry = load_json(pred_registry_path) if pred_registry_path.exists() else {}
+ beaver_controls_path = OUT_DIR / "beaver_mask_freshness_negative_controls.json"
+ beaver_controls = load_json(beaver_controls_path) if beaver_controls_path.exists() else {}
+ virtual_serial_path = OUT_DIR / "tang9k_rrc_q16_virtual_serial_probe.json"
+ virtual_serial = load_json(virtual_serial_path) if virtual_serial_path.exists() else {}
+ transport_routes_path = OUT_DIR / "tang9k_uart_transport_routes.json"
+ transport_routes = load_json(transport_routes_path) if transport_routes_path.exists() else {}
+ less_solid = tri.get("less_solid_surface_counts", {})
+ gates = tri.get("gates", {})
+ fpga = gates.get("fpga_witness", {})
+ compiler_receipt_path = REPO / "4-Infrastructure" / "shim" / "rainbow_raccoon_compiler_receipt.json"
+ compiler_receipt = load_json(compiler_receipt_path) if compiler_receipt_path.exists() else {}
+ compiler = stack.get("gates", {}).get("compiler", {})
+ if not compiler:
+ objects = compiler_receipt.get("compiled_objects", [])
+ compiler = {
+ "receipt_hash": compiler_receipt.get("receipt_hash"),
+ "candidate_count": sum(
+ 1 for obj in objects if obj.get("type_witness", {}).get("status") == "CANDIDATE"
+ ),
+ "hold_count": sum(
+ 1 for obj in objects if obj.get("type_witness", {}).get("status") == "HOLD"
+ ),
+ }
+ worktree = stack.get("gates", {}).get("worktree", {})
+ if not worktree:
+ dirty_count = git_dirty_count()
+ worktree = {
+ "status": "DIRTY" if dirty_count else "CLEAN",
+ "tracked_or_untracked_count": dirty_count,
+ }
+
+ tickets = [
+ ticket(
+ "FAIL-FPGA-UART-001",
+ "Live fabric UART transport has no observable bytes",
+ "fpga_transport_or_witness_debt",
+ "BLOCKED",
+ [
+ "Q16 software witness passes",
+ "Q16 hardware witness returns short receipt frames",
+ "TX-only beacon standard pins produced zero bytes on ttyUSB0 and ttyUSB1",
+ "TX-only beacon swapped pins produced zero bytes on ttyUSB0 and ttyUSB1",
+ "Old faXX/ffXX direct-probe interpretation is superseded as bridge/MPSSE behavior, not fabric proof",
+ "FPGA UART route analysis identifies the onboard BL702 bridge route as blocked and recommends external USB-UART",
+ "Forced JTAG reset plus SRAM reload succeeds, but beacon/Q16 UART receipts remain empty",
+ "Loopback-after-JTAG-clear diagnostic produced faXX-style bytes on ttyUSB0, consistent with bridge/MPSSE behavior rather than a valid fabric receipt",
+ (
+ "PTY-backed virtual serial Q16 probe: "
+ f"{virtual_serial.get('summary', {}).get('status', 'not_run')} "
+ f"({virtual_serial.get('summary', {}).get('match_count', 'not_run')}/"
+ f"{virtual_serial.get('summary', {}).get('case_count', 'not_run')} matches)"
+ ),
+ (
+ "UART transport router active route: "
+ f"{transport_routes.get('active_route', 'not_run')} "
+ f"({transport_routes.get('active_route_status', 'not_run')})"
+ ),
+ ],
+ [
+ "external USB-UART or verified onboard bridge captures beacon payload a6425131360a",
+ "loopback or beacon receipt passes before Q16 accelerator retry",
+ "Q16 hardware receipts match software receipts for shift, weighted, and monotone cases",
+ ],
+ [
+ "Attach external USB-UART: adapter TX to fabric RX pin 18, adapter RX to fabric TX pin 17, and GND to GND",
+ "Probe the new adapter path, usually /dev/ttyUSB2 or /dev/ttyACM0, with the TX-only beacon before Q16",
+ "If external UART works, patch host default port or call scripts with --port and rerun Q16 hardware receipts",
+ "If external UART fails, inspect PNR pin placement and add LED-observed heartbeat fallback",
+ ],
+ "6-Documentation/docs/fpga_uart_route_analysis_2026-05-09.md",
+ ),
+ ticket(
+ "FAIL-FPGA-FLASH-002",
+ "Durable flash programming readback fails",
+ "fpga_transport_or_witness_debt",
+ "HELD_SRAM_ONLY",
+ [
+ "SRAM load passes CRC",
+ "Flash programming attempt had readback CRC failure",
+ ],
+ [
+ "flash write and readback CRC pass for the exact Q16 bitstream",
+ "or documentation keeps SRAM-only boundary explicit",
+ ],
+ [
+ "Keep SRAM-only claim boundary until flash command and board target are verified",
+ "Do not mark hardware install persistent",
+ ],
+ "6-Documentation/docs/fpga_rrc_q16_accel_setup_2026-05-09.md",
+ ),
+ ticket(
+ "FAIL-SECURITY-BEAVER-003",
+ "Adaptive Beaver coefficients are not privacy-equivalent masks yet",
+ "security_proof_debt",
+ "HOLD",
+ [
+ f"{less_solid.get('security_proof_debt', 0)} security proof debt surfaces found",
+ "tri-cycle audit blocks promotion for adaptive mask claims",
+ f"mask freshness negative controls: {beaver_controls.get('summary', {}).get('status', 'not_run')}",
+ f"mask freshness case count: {beaver_controls.get('summary', {}).get('case_count', 'not_run')}",
+ ],
+ [
+ "formal independence/freshness theorem exists",
+ "secret-sharing non-reuse receipt exists",
+ "negative control shows adapted coefficients do not leak party inputs",
+ ],
+ [
+ "Add a Lean-facing finite-state mask freshness model",
+ "Generate negative-control fixtures for repeated coefficients and topology-derived coefficients",
+ ],
+ "Network-Topology-Theory.md + Fundamental_Network_Topology_Equation.md",
+ ),
+ ticket(
+ "FAIL-COEFFICIENT-CALIBRATION-004",
+ "Numeric weights remain receipt-weighted priors, not calibrated coefficients",
+ "coefficient_or_calibration_debt",
+ "HOLD",
+ [
+ f"{less_solid.get('coefficient_or_calibration_debt', 0)} coefficient/calibration debt surfaces found",
+ "receipt reweighting exists, but coefficient calibration and negative controls remain open",
+ f"coefficient HOLD manifest rows: {coeff_manifest.get('summary', {}).get('row_count', 'not_run')}",
+ ],
+ [
+ "dataset provenance receipt linked",
+ "coefficient calibration receipt linked",
+ "sensitivity sweep and negative controls pass",
+ ],
+ [
+ "Create coefficient calibration fixture manifest",
+ "Separate hypothesis weights from calibrated weights in docs and JSON surfaces",
+ ],
+ "shared-data/network_topology_database.json",
+ ),
+ ticket(
+ "FAIL-TOPOLOGY-PREDICTION-005",
+ "Topology predictions are not validation claims",
+ "topology_prediction_debt",
+ "HOLD",
+ [
+ f"{less_solid.get('topology_prediction_debt', 0)} topology prediction debt surfaces found",
+ "tri-cycle audit requires pre-registered target and independent comparison",
+ f"prediction HOLD registry rows: {pred_registry.get('summary', {}).get('row_count', 'not_run')}",
+ ],
+ [
+ "pre-registered prediction target exists",
+ "outcome receipt exists",
+ "independent public map or measurement comparison exists",
+ ],
+ [
+ "Create prediction-target registry with timestamps and immutable receipt hashes",
+ "Move existing predicted nodes into HOLD prediction queue, not validation table",
+ ],
+ "shared-data/network_topology_database.json",
+ ),
+ ticket(
+ "FAIL-RECEIPT-GATE-006",
+ "Route promotion lacks complete receipt and rollback closure",
+ "receipt_gate_debt",
+ "HOLD",
+ [
+ f"{less_solid.get('receipt_gate_debt', 0)} receipt-gate debt surfaces found",
+ "compiler keeps 6 objects HOLD and only 1 candidate",
+ f"compiler receipt hash: {compiler.get('receipt_hash')}",
+ f"optional sem entity probe: {sem_receipt.get('decision', 'not_run')}",
+ (
+ "HOLD closure checklist: "
+ f"{hold_checklist.get('summary', {}).get('open_closure_count', 'not_run')} open items"
+ ),
+ ],
+ [
+ "validation receipt exists",
+ "rollback hash exists",
+ "exact replay or decode closure hash matches",
+ ],
+ [
+ "Close every item in rrc_hold_closure_checklist.json before rerunning compiler promotion",
+ "Do not widen candidate admission beyond Q16 until Lean or independent replay closes",
+ ],
+ "4-Infrastructure/shim/rainbow_raccoon_compiler.py",
+ ),
+ ticket(
+ "FAIL-WORKTREE-SCOPE-007",
+ "Broad worktree is too dirty for safe sweep commit",
+ "release_hygiene_debt",
+ "BLOCKED_FOR_BROAD_STAGE",
+ [
+ f"worktree status: {worktree.get('status')}",
+ f"changed/untracked count: {worktree.get('tracked_or_untracked_count')}",
+ "staging manifest created for the solidification slice",
+ f"optional sem entity probe: {sem_receipt.get('decision', 'not_run')}",
+ ],
+ [
+ "commit scope is explicit file list",
+ "generated artifacts are intentionally included or excluded",
+ "no unrelated modified Lean/doc/probe files are swept in",
+ "entity-level change list exists for staged or scoped files when sem is available",
+ ],
+ [
+ "Use stack_solidification_staging_manifest_2026-05-09.md before any commit",
+ "Create separate manifests for CPU/logogram/wiki maturation slices if needed",
+ "Use /tmp/sem_probe/sem/crates/target/release/sem, not /usr/bin/sem, unless a durable sem binary is installed",
+ ],
+ "6-Documentation/docs/stack_solidification_staging_manifest_2026-05-09.md",
+ ),
+ ]
+ return {
+ "schema": "stack_fail_closure_register_v1",
+ "created_utc": datetime.now(timezone.utc).isoformat(),
+ "claim_boundary": "Closure register only. Tickets describe gates required to close failures; they do not claim closure.",
+ "source_receipts": [str(TRI.relative_to(REPO)), str(STACK.relative_to(REPO))],
+ "optional_tool_receipts": [str(sem_receipt_path.relative_to(REPO))] if sem_receipt_path.exists() else [],
+ "closure_receipts": [
+ str(path.relative_to(REPO))
+ for path in [hold_checklist_path, coeff_manifest_path, pred_registry_path, beaver_controls_path, virtual_serial_path, transport_routes_path]
+ if path.exists()
+ ],
+ "summary": {
+ "ticket_count": len(tickets),
+ "blocked_or_hold_count": sum(1 for item in tickets if item["status"] in {"BLOCKED", "HOLD", "BLOCKED_FOR_BROAD_STAGE", "HELD_SRAM_ONLY"}),
+ "fpga_hardware_status": fpga.get("hardware_status"),
+ "fpga_software_status": fpga.get("software_status"),
+ "promotion_decision": tri.get("promotion_decision"),
+ },
+ "tickets": tickets,
+ }
+
+
+def build_doc(register: dict[str, Any]) -> str:
+ lines = [
+ "# Stack Fail Closure Register",
+ "",
+ "**Date:** 2026-05-09",
+ "",
+ "This register turns current failures into closure gates. It does not mark them solved.",
+ "",
+ "## Summary",
+ "",
+ f"- Tickets: `{register['summary']['ticket_count']}`",
+ f"- Promotion decision: `{register['summary']['promotion_decision']}`",
+ f"- FPGA software status: `{register['summary']['fpga_software_status']}`",
+ f"- FPGA hardware status: `{register['summary']['fpga_hardware_status']}`",
+ "",
+ "## Tickets",
+ "",
+ ]
+ for item in register["tickets"]:
+ lines.append(f"### `{item['ticket_id']}` {item['title']}")
+ lines.append("")
+ lines.append(f"- Class: `{item['failure_class']}`")
+ lines.append(f"- Status: `{item['status']}`")
+ lines.append(f"- Owner surface: `{item['owner_surface']}`")
+ for evidence in item["evidence"]:
+ lines.append(f"- Evidence: {evidence}")
+ for gate in item["closure_gate"]:
+ lines.append(f"- Closure gate: {gate}")
+ for action in item["next_action"]:
+ lines.append(f"- Next action: {action}")
+ lines.append("")
+ lines.append("## Machine Receipt")
+ lines.append("")
+ lines.append(f"- `{OUT.relative_to(REPO)}`")
+ return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ register = build_register()
+ OUT.write_text(json.dumps(register, indent=2, sort_keys=True), encoding="utf-8")
+ DOC.write_text(build_doc(register), encoding="utf-8")
+ print(json.dumps({"receipt": str(OUT.relative_to(REPO)), "doc": str(DOC.relative_to(REPO)), "tickets": len(register["tickets"])}, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/stack_solidification_audit.py b/4-Infrastructure/shim/stack_solidification_audit.py
new file mode 100644
index 00000000..f90f146d
--- /dev/null
+++ b/4-Infrastructure/shim/stack_solidification_audit.py
@@ -0,0 +1,500 @@
+#!/usr/bin/env python3
+"""End-to-end stand-up audit for the Rainbow Raccoon stack.
+
+This is a snapshot tool, not a promotion tool. It collects the current proof,
+compiler, receipt, JSON, and hardware-boundary evidence into one receipt so the
+stack can be stabilized without turning HOLD surfaces into claims.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+OUT_DIR = REPO / "shared-data" / "data" / "stack_solidification"
+OUT = OUT_DIR / "stack_solidification_receipt.json"
+DOC = REPO / "6-Documentation" / "docs" / "stack_solidification_status_2026-05-09.md"
+
+JSON_SURFACES = [
+ "shared-data/network_topology_database.json",
+ "4-Infrastructure/shim/rainbow_raccoon_compiler_receipt.json",
+ "shared-data/data/rrc_tri_cycle_audit/rrc_tri_cycle_audit_receipt.json",
+ "shared-data/data/stack_solidification/external_sem_entity_diff_probe_receipt.json",
+ "shared-data/data/stack_solidification/rrc_hold_closure_checklist.json",
+ "shared-data/data/stack_solidification/network_topology_coefficient_calibration_manifest.json",
+ "shared-data/data/stack_solidification/network_topology_prediction_hold_registry.json",
+ "shared-data/data/stack_solidification/beaver_mask_freshness_negative_controls.json",
+ "shared-data/data/stack_solidification/whitespace_zero_grammar_probe.json",
+ "shared-data/data/stack_solidification/tang9k_rrc_q16_virtual_serial_probe.json",
+ "shared-data/data/stack_solidification/tang9k_uart_transport_routes.json",
+ "shared-data/data/stack_solidification/stack_fail_closure_register.json",
+ "shared-data/data/stack_solidification/smn_tool_awareness_registry.json",
+ "shared-data/data/stack_solidification/smn_tool_awareness_receipt.json",
+ "4-Infrastructure/shim/tang9k_uart_beacon_probe_receipt.json",
+ "4-Infrastructure/shim/tang9k_uart_beacon_swapped_probe_receipt.json",
+ "4-Infrastructure/shim/tang9k_uart_loopback_after_jtag_clear_probe_receipt.json",
+]
+
+PYTHON_SURFACES = [
+ "4-Infrastructure/shim/external_sem_entity_diff_probe.py",
+ "4-Infrastructure/shim/beaver_mask_freshness_negative_controls.py",
+ "4-Infrastructure/shim/whitespace_zero_grammar_probe.py",
+ "4-Infrastructure/shim/network_topology_hold_manifests.py",
+ "4-Infrastructure/shim/rainbow_raccoon_compiler.py",
+ "4-Infrastructure/shim/rrc_hold_closure_checklist.py",
+ "4-Infrastructure/shim/rrc_tri_cycle_audit.py",
+ "4-Infrastructure/shim/stack_fail_closure_register.py",
+ "4-Infrastructure/shim/tang9k_rrc_q16_accel.py",
+ "4-Infrastructure/shim/tang9k_rrc_q16_virtual_serial_probe.py",
+ "4-Infrastructure/shim/tang9k_uart_transport_router.py",
+ "4-Infrastructure/shim/tang9k_uart_beacon_probe.py",
+ "4-Infrastructure/shim/smn_tool_awareness_registry.py",
+ "4-Infrastructure/shim/enwiki9_logogram_receipt_aggregation_probe.py",
+ "4-Infrastructure/shim/stack_solidification_audit.py",
+]
+
+
+@dataclass
+class CmdResult:
+ command: list[str]
+ cwd: str
+ returncode: int
+ stdout_tail: str
+ stderr_tail: str
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+def run_cmd(command: list[str], cwd: Path, timeout: int = 300) -> CmdResult:
+ proc = subprocess.run(
+ command,
+ cwd=cwd,
+ text=True,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ timeout=timeout,
+ check=False,
+ )
+ return CmdResult(
+ command=command,
+ cwd=rel(cwd),
+ returncode=proc.returncode,
+ stdout_tail=proc.stdout[-6000:],
+ stderr_tail=proc.stderr[-6000:],
+ )
+
+
+def load_json(path: Path) -> Any:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def file_sha256(path: Path) -> str | None:
+ if not path.exists():
+ return None
+ h = hashlib.sha256()
+ with path.open("rb") as f:
+ for chunk in iter(lambda: f.read(1024 * 1024), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def json_gate() -> dict[str, Any]:
+ rows = []
+ for item in JSON_SURFACES:
+ path = REPO / item
+ try:
+ data = load_json(path)
+ rows.append(
+ {
+ "path": item,
+ "status": "PASS",
+ "top_level_type": type(data).__name__,
+ "sha256": file_sha256(path),
+ }
+ )
+ except Exception as exc: # pragma: no cover - diagnostic path
+ rows.append({"path": item, "status": "FAIL", "error": repr(exc)})
+ return {"status": "PASS" if all(row["status"] == "PASS" for row in rows) else "FAIL", "rows": rows}
+
+
+def py_compile_gate() -> dict[str, Any]:
+ cmd = ["python3", "-m", "py_compile", *PYTHON_SURFACES]
+ result = run_cmd(cmd, REPO, timeout=120)
+ return {"status": "PASS" if result.returncode == 0 else "FAIL", "result": result.__dict__}
+
+
+def refresh_support_receipts_gate() -> dict[str, Any]:
+ scripts = [
+ "4-Infrastructure/shim/network_topology_hold_manifests.py",
+ "4-Infrastructure/shim/beaver_mask_freshness_negative_controls.py",
+ "4-Infrastructure/shim/whitespace_zero_grammar_probe.py",
+ "4-Infrastructure/shim/tang9k_rrc_q16_virtual_serial_probe.py",
+ "4-Infrastructure/shim/tang9k_uart_transport_router.py",
+ "4-Infrastructure/shim/rrc_hold_closure_checklist.py",
+ ]
+ rows = []
+ for script in scripts:
+ result = run_cmd(["python3", script], REPO, timeout=300)
+ rows.append(
+ {
+ "script": script,
+ "status": "PASS" if result.returncode == 0 else "FAIL",
+ "result": result.__dict__,
+ }
+ )
+ return {"status": "PASS" if all(row["status"] == "PASS" for row in rows) else "FAIL", "rows": rows}
+
+
+def compiler_gate() -> dict[str, Any]:
+ result = run_cmd(["python3", "4-Infrastructure/shim/rainbow_raccoon_compiler.py"], REPO, timeout=120)
+ receipt_path = REPO / "4-Infrastructure" / "shim" / "rainbow_raccoon_compiler_receipt.json"
+ receipt = load_json(receipt_path) if receipt_path.exists() else {}
+ objects = receipt.get("compiled_objects", [])
+ return {
+ "status": "PASS_WITH_HOLDS" if result.returncode == 0 else "FAIL",
+ "result": result.__dict__,
+ "receipt": rel(receipt_path),
+ "receipt_hash": receipt.get("receipt_hash"),
+ "compiled_object_count": len(objects),
+ "candidate_count": sum(1 for obj in objects if obj.get("type_witness", {}).get("status") == "CANDIDATE"),
+ "hold_count": sum(1 for obj in objects if obj.get("type_witness", {}).get("status") == "HOLD"),
+ }
+
+
+def tri_cycle_gate(include_hardware: bool, hardware_port: str) -> dict[str, Any]:
+ cmd = ["python3", "4-Infrastructure/shim/rrc_tri_cycle_audit.py"]
+ if include_hardware:
+ cmd.extend(["--include-hardware", "--hardware-port", hardware_port])
+ result = run_cmd(cmd, REPO, timeout=300)
+ receipt_path = REPO / "shared-data" / "data" / "rrc_tri_cycle_audit" / "rrc_tri_cycle_audit_receipt.json"
+ receipt = load_json(receipt_path) if receipt_path.exists() else {}
+ gates = receipt.get("gates", {})
+ fpga = gates.get("fpga_witness", {})
+ return {
+ "status": "PASS_WITH_BLOCKED_HARDWARE" if result.returncode == 0 and fpga.get("hardware_status") == "FAIL" else "PASS" if result.returncode == 0 else "FAIL",
+ "result": result.__dict__,
+ "receipt": rel(receipt_path),
+ "promotion_decision": receipt.get("promotion_decision"),
+ "prover": gates.get("prover", {}).get("status"),
+ "compiler": gates.get("compiler", {}).get("status"),
+ "fpga_software": fpga.get("software_status"),
+ "fpga_hardware": fpga.get("hardware_status"),
+ "uart_beacon_any": fpga.get("uart_beacon", {}).get("any_beacon_seen"),
+ "less_solid_surface_counts": receipt.get("less_solid_surface_counts", {}),
+ }
+
+
+def lean_gate(run_full_lean: bool) -> dict[str, Any]:
+ if not run_full_lean:
+ return {"status": "SKIPPED", "reason": "run with --full-lean to refresh this gate"}
+ result = run_cmd(["lake", "build"], REPO / "0-Core-Formalism" / "lean" / "Semantics", timeout=600)
+ return {"status": "PASS" if result.returncode == 0 else "FAIL", "result": result.__dict__}
+
+
+def hardware_bitstream_gate() -> dict[str, Any]:
+ surfaces = [
+ "4-Infrastructure/hardware/tangnano9k_rrc_q16_accel.fs",
+ "4-Infrastructure/hardware/tangnano9k_uart_beacon.fs",
+ ]
+ return {
+ "status": "PASS" if all((REPO / p).exists() for p in surfaces) else "FAIL",
+ "bitstreams": [{"path": p, "sha256": file_sha256(REPO / p), "present": (REPO / p).exists()} for p in surfaces],
+ }
+
+
+def external_sem_gate() -> dict[str, Any]:
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "external_sem_entity_diff_probe_receipt.json"
+ if not path.exists():
+ return {"status": "NOT_RUN", "receipt": str(path.relative_to(REPO))}
+ receipt = load_json(path)
+ return {
+ "status": receipt.get("decision", "UNKNOWN"),
+ "receipt": str(path.relative_to(REPO)),
+ "gnu_parallel_collision": receipt.get("gnu_parallel_collision", {}).get("detected"),
+ "mapped_fail_tickets": receipt.get("mapped_fail_tickets", []),
+ }
+
+
+def hold_checklist_gate() -> dict[str, Any]:
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "rrc_hold_closure_checklist.json"
+ if not path.exists():
+ return {"status": "NOT_RUN", "receipt": str(path.relative_to(REPO))}
+ receipt = load_json(path)
+ return {
+ "status": "PASS_OPEN_ITEMS_TRACKED",
+ "receipt": str(path.relative_to(REPO)),
+ "hold_count": receipt.get("summary", {}).get("hold_count"),
+ "open_closure_count": receipt.get("summary", {}).get("open_closure_count"),
+ }
+
+
+def network_hold_manifest_gate() -> dict[str, Any]:
+ coeff = REPO / "shared-data" / "data" / "stack_solidification" / "network_topology_coefficient_calibration_manifest.json"
+ pred = REPO / "shared-data" / "data" / "stack_solidification" / "network_topology_prediction_hold_registry.json"
+ if not coeff.exists() or not pred.exists():
+ return {"status": "NOT_RUN", "coefficient_manifest": str(coeff.relative_to(REPO)), "prediction_registry": str(pred.relative_to(REPO))}
+ coeff_data = load_json(coeff)
+ pred_data = load_json(pred)
+ return {
+ "status": "PASS_HOLD_QUEUES_DECLARED",
+ "coefficient_manifest": str(coeff.relative_to(REPO)),
+ "prediction_registry": str(pred.relative_to(REPO)),
+ "coefficient_rows": coeff_data.get("summary", {}).get("row_count"),
+ "prediction_rows": pred_data.get("summary", {}).get("row_count"),
+ }
+
+
+def beaver_mask_freshness_gate() -> dict[str, Any]:
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "beaver_mask_freshness_negative_controls.json"
+ if not path.exists():
+ return {"status": "NOT_RUN", "receipt": str(path.relative_to(REPO))}
+ receipt = load_json(path)
+ return {
+ "status": receipt.get("summary", {}).get("status", "UNKNOWN"),
+ "receipt": str(path.relative_to(REPO)),
+ "lean_build": receipt.get("lean_build", {}).get("status"),
+ "case_count": receipt.get("summary", {}).get("case_count"),
+ "negative_control_count": receipt.get("summary", {}).get("negative_control_count"),
+ "promotion_effect": receipt.get("promotion_effect"),
+ }
+
+
+def whitespace_zero_grammar_gate() -> dict[str, Any]:
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "whitespace_zero_grammar_probe.json"
+ if not path.exists():
+ return {"status": "NOT_RUN", "receipt": str(path.relative_to(REPO))}
+ receipt = load_json(path)
+ return {
+ "status": receipt.get("summary", {}).get("status", "UNKNOWN"),
+ "receipt": str(path.relative_to(REPO)),
+ "lean_build": receipt.get("lean_build", {}).get("status"),
+ "case_count": receipt.get("summary", {}).get("case_count"),
+ "admit_count": receipt.get("summary", {}).get("admit_count"),
+ "hold_count": receipt.get("summary", {}).get("hold_count"),
+ "stored_whitespace_codes_total": receipt.get("summary", {}).get("stored_whitespace_codes_total"),
+ }
+
+
+def virtual_serial_gate() -> dict[str, Any]:
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "tang9k_rrc_q16_virtual_serial_probe.json"
+ if not path.exists():
+ return {"status": "NOT_RUN", "receipt": str(path.relative_to(REPO))}
+ receipt = load_json(path)
+ return {
+ "status": receipt.get("summary", {}).get("status", "UNKNOWN"),
+ "receipt": str(path.relative_to(REPO)),
+ "case_count": receipt.get("summary", {}).get("case_count"),
+ "match_count": receipt.get("summary", {}).get("match_count"),
+ "frames_seen": receipt.get("summary", {}).get("frames_seen"),
+ }
+
+
+def uart_transport_routes_gate() -> dict[str, Any]:
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "tang9k_uart_transport_routes.json"
+ if not path.exists():
+ return {"status": "NOT_RUN", "receipt": str(path.relative_to(REPO))}
+ receipt = load_json(path)
+ return {
+ "status": receipt.get("active_route_status", "UNKNOWN"),
+ "receipt": str(path.relative_to(REPO)),
+ "active_route": receipt.get("active_route"),
+ "route_count": len(receipt.get("route_table", [])),
+ "virtual_status": receipt.get("virtual_probe", {}).get("status"),
+ }
+
+
+def stack_fail_closure_gate() -> dict[str, Any]:
+ result = run_cmd(["python3", "4-Infrastructure/shim/stack_fail_closure_register.py"], REPO, timeout=120)
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "stack_fail_closure_register.json"
+ receipt = load_json(path) if path.exists() else {}
+ return {
+ "status": "PASS_TICKETS_DECLARED" if result.returncode == 0 else "FAIL",
+ "receipt": str(path.relative_to(REPO)),
+ "ticket_count": receipt.get("summary", {}).get("ticket_count"),
+ "blocked_or_hold_count": receipt.get("summary", {}).get("blocked_or_hold_count"),
+ "fpga_hardware_status": receipt.get("summary", {}).get("fpga_hardware_status"),
+ "promotion_decision": receipt.get("summary", {}).get("promotion_decision"),
+ "result": result.__dict__,
+ }
+
+
+def smn_tool_awareness_gate() -> dict[str, Any]:
+ result = run_cmd(["python3", "4-Infrastructure/shim/smn_tool_awareness_registry.py"], REPO, timeout=120)
+ path = REPO / "shared-data" / "data" / "stack_solidification" / "smn_tool_awareness_receipt.json"
+ receipt = load_json(path) if path.exists() else {}
+ return {
+ "status": receipt.get("status", "FAIL" if result.returncode else "UNKNOWN"),
+ "decision": receipt.get("decision"),
+ "receipt": str(path.relative_to(REPO)),
+ "nomenclature": receipt.get("gates", {}).get("nomenclature", {}).get("status"),
+ "smn_data": receipt.get("gates", {}).get("smn_data", {}).get("status"),
+ "result": result.__dict__,
+ }
+
+
+def worktree_gate() -> dict[str, Any]:
+ proc = subprocess.run(
+ ["git", "status", "--short"],
+ cwd=REPO,
+ text=True,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ timeout=120,
+ check=False,
+ )
+ counts: dict[str, int] = {}
+ total = 0
+ for line in proc.stdout.splitlines():
+ if not line.strip():
+ continue
+ total += 1
+ key = line[:2]
+ counts[key] = counts.get(key, 0) + 1
+ return {
+ "status": "DIRTY" if total else "CLEAN",
+ "tracked_or_untracked_count": total,
+ "status_prefix_counts": dict(sorted(counts.items())),
+ "note": "Broad working tree is dirty; stage only scoped artifacts.",
+ }
+
+
+def build_doc(receipt: dict[str, Any]) -> str:
+ gates = receipt["gates"]
+ tri = gates["tri_cycle"]
+ lines = [
+ "# Stack Solidification Status",
+ "",
+ "**Date:** 2026-05-09",
+ "",
+ "## Bottom Line",
+ "",
+ "The stack is buildable and internally gateable, but not promotable as a live hardware-accelerated system yet.",
+ "",
+ "## Gates",
+ "",
+ f"- Full Lean/Semantics build: `{gates['lean']['status']}`",
+ f"- JSON integrity: `{gates['json']['status']}`",
+ f"- Python shim compile: `{gates['python_compile']['status']}`",
+ f"- Support receipt refresh: `{gates['support_receipts']['status']}`",
+ f"- Rainbow Raccoon compiler: `{gates['compiler']['status']}` ({gates['compiler']['candidate_count']} candidate, {gates['compiler']['hold_count']} HOLD)",
+ f"- Tri-cycle audit: `{tri['status']}`; promotion decision `{tri['promotion_decision']}`",
+ f"- FPGA software witness: `{tri['fpga_software']}`",
+ f"- FPGA hardware witness: `{tri['fpga_hardware']}`",
+ f"- UART beacon seen: `{tri['uart_beacon_any']}`",
+ f"- Hardware bitstreams present: `{gates['hardware_bitstreams']['status']}`",
+ f"- Optional sem entity-diff aid: `{gates['external_sem']['status']}`",
+ f"- RRC HOLD closure checklist: `{gates['hold_checklist']['status']}` ({gates['hold_checklist'].get('open_closure_count')} open)",
+ f"- Network HOLD manifests: `{gates['network_hold_manifests']['status']}` ({gates['network_hold_manifests'].get('coefficient_rows')} coefficient rows, {gates['network_hold_manifests'].get('prediction_rows')} prediction rows)",
+ f"- Beaver mask freshness controls: `{gates['beaver_mask_freshness']['status']}` ({gates['beaver_mask_freshness'].get('case_count')} cases)",
+ f"- Whitespace-zero grammar: `{gates['whitespace_zero_grammar']['status']}` ({gates['whitespace_zero_grammar'].get('admit_count')} admitted, {gates['whitespace_zero_grammar'].get('hold_count')} HOLD)",
+ f"- Q16 virtual serial probe: `{gates['virtual_serial']['status']}` ({gates['virtual_serial'].get('match_count')}/{gates['virtual_serial'].get('case_count')} matches)",
+ f"- UART transport routes: `{gates['uart_transport_routes']['status']}` (active `{gates['uart_transport_routes'].get('active_route')}`)",
+ f"- Stack fail closure register: `{gates['stack_fail_closure']['status']}` ({gates['stack_fail_closure'].get('ticket_count')} tickets)",
+ f"- SMN tool awareness: `{gates['smn_tool_awareness']['status']}` ({gates['smn_tool_awareness'].get('decision')})",
+ f"- Worktree: `{gates['worktree']['status']}`",
+ "- Staging manifest: `6-Documentation/docs/stack_solidification_staging_manifest_2026-05-09.md`",
+ "",
+ "## Current Solid Core",
+ "",
+ "- Lean/Semantics builds end to end.",
+ "- Core JSON receipts and network topology database parse.",
+ "- Compiler gate admits only the Q16 fixed-point lowering certificate as candidate.",
+ "- Q16 software witness lane passes.",
+ "- Q16 host UART framing and parser pass over a PTY-backed virtual serial device.",
+ "- UART route table now selects the PTY-backed Q16 route while keeping blocked physical routes visible.",
+ "- HOLD buckets are explicit rather than silently promoted.",
+ "- Optional sem entity extraction is available for scoped Python audit files.",
+ "- SMN is tool-visible as Semantic Mass Number and explicitly separated from Mass Number admissibility packets.",
+ "- Every compiler HOLD object now has an explicit closure checklist.",
+ "- Current failures and broad HOLD buckets have closure tickets in a stack fail register.",
+ "- Network topology coefficients and predictions are split into HOLD queues.",
+ "- Beaver mask freshness has Lean-backed finite negative controls; full MPC security remains HOLD.",
+ "- Canonical logogram grammar can derive ordinary spaces from symbol count/order with zero stored whitespace codes.",
+ "- Agent routing now has repo-root, Lean/Semantics, and Infrastructure contracts.",
+ "- Stack receipts and the network topology database are visible through narrow `.gitignore` exceptions instead of broad `shared-data/` exposure.",
+ "",
+ "## Current Blockers",
+ "",
+ "- Live FPGA UART transport remains blocked: beacon receipts show no bytes on `/dev/ttyUSB0` or `/dev/ttyUSB1`.",
+ "- Hardware acceleration claims remain blocked until the UART route or external adapter path produces matching receipts.",
+ "- Security, coefficient, topology-prediction, and receipt-gate debts remain HOLD surfaces.",
+ "- The worktree is broad and dirty; do not stage by directory sweep.",
+ "- `/usr/bin/sem` is GNU Parallel on this machine; use the isolated sem binary path if sem is needed.",
+ "",
+ "## Less Solid Surface Counts",
+ "",
+ ]
+ for bucket, count in sorted(tri.get("less_solid_surface_counts", {}).items()):
+ lines.append(f"- `{bucket}`: {count}")
+ lines.extend(
+ [
+ "",
+ "## Next Stabilization Moves",
+ "",
+ "1. Resolve fabric UART transport with board bridge docs or an external USB-UART adapter.",
+ "2. Work the closure register tickets in order: UART transport, flash persistence, adaptive-mask security, coefficient calibration, topology predictions, receipt gates, then worktree scope.",
+ "3. Keep Q16 as the first narrow candidate lane; do not widen compiler promotion until more Lean-backed certificates exist.",
+ "4. Produce a scoped staging manifest before any commit because the working tree contains many unrelated/generated surfaces.",
+ "",
+ "## Receipt",
+ "",
+ f"- Machine receipt: `{rel(OUT)}`",
+ "- Staging manifest: `6-Documentation/docs/stack_solidification_staging_manifest_2026-05-09.md`",
+ ]
+ )
+ return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--full-lean", action="store_true")
+ parser.add_argument("--include-hardware", action="store_true")
+ parser.add_argument("--hardware-port", default="/dev/ttyUSB1")
+ args = parser.parse_args()
+
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ receipt: dict[str, Any] = {
+ "schema": "stack_solidification_receipt_v1",
+ "created_utc": datetime.now(timezone.utc).isoformat(),
+ "claim_boundary": "Stack status audit only. This does not promote HOLD surfaces or hardware acceleration claims.",
+ "gates": {},
+ }
+ receipt["gates"]["lean"] = lean_gate(args.full_lean)
+ receipt["gates"]["python_compile"] = py_compile_gate()
+ receipt["gates"]["compiler"] = compiler_gate()
+ receipt["gates"]["support_receipts"] = refresh_support_receipts_gate()
+ receipt["gates"]["tri_cycle"] = tri_cycle_gate(args.include_hardware, args.hardware_port)
+ receipt["gates"]["stack_fail_closure"] = stack_fail_closure_gate()
+ receipt["gates"]["smn_tool_awareness"] = smn_tool_awareness_gate()
+ receipt["gates"]["json"] = json_gate()
+ receipt["gates"]["hardware_bitstreams"] = hardware_bitstream_gate()
+ receipt["gates"]["external_sem"] = external_sem_gate()
+ receipt["gates"]["hold_checklist"] = hold_checklist_gate()
+ receipt["gates"]["network_hold_manifests"] = network_hold_manifest_gate()
+ receipt["gates"]["beaver_mask_freshness"] = beaver_mask_freshness_gate()
+ receipt["gates"]["whitespace_zero_grammar"] = whitespace_zero_grammar_gate()
+ receipt["gates"]["virtual_serial"] = virtual_serial_gate()
+ receipt["gates"]["uart_transport_routes"] = uart_transport_routes_gate()
+ receipt["gates"]["worktree"] = worktree_gate()
+ OUT.write_text(json.dumps(receipt, indent=2, sort_keys=True), encoding="utf-8")
+ DOC.write_text(build_doc(receipt), encoding="utf-8")
+ print(json.dumps({"receipt": rel(OUT), "doc": rel(DOC), "status": "WRITTEN"}, indent=2))
+ hard_fail = any(
+ receipt["gates"][gate]["status"] == "FAIL"
+ for gate in ["lean", "json", "python_compile", "compiler", "support_receipts", "stack_fail_closure", "hardware_bitstreams"]
+ )
+ return 1 if hard_fail else 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/stellar_gas_abelian_sandpile_probe.py b/4-Infrastructure/shim/stellar_gas_abelian_sandpile_probe.py
new file mode 100644
index 00000000..ad643170
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_abelian_sandpile_probe.py
@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""Treat stellar-gas eigenmass cells as an Abelian-sandpile-style diagnostic.
+
+The metaphor is operationalized carefully:
+
+* "grains" are normalized SMN/evidence eigenmass in a sky/redshift cell.
+* "toppling pressure" is a standardized mix of gas/shock propagation channels.
+* "avalanche candidates" are cells with both high eigenmass and high pressure.
+
+Boundary: this is a routing/diagnostic model over observational proxies. It is
+not a physical sandpile simulation, not stellar mass, and not cosmology.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[2]
+MASS_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_eigenvector_mass_probe.json"
+GROUP_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_population_grouping_study.json"
+OUT_DIR = ROOT / "shared-data/data/stellar_gas_observation"
+DOCS_DIR = ROOT / "6-Documentation/docs"
+TIDDLER_DIR = ROOT / "6-Documentation/tiddlywiki-local/wiki/tiddlers"
+
+OUT_JSON = OUT_DIR / "stellar_gas_abelian_sandpile_probe.json"
+RECEIPT_JSON = OUT_DIR / "stellar_gas_abelian_sandpile_probe_receipt.json"
+DOC_MD = DOCS_DIR / "stellar_gas_abelian_sandpile_probe_2026-05-09.md"
+TIDDLER = TIDDLER_DIR / "Stellar Gas Abelian Sandpile Probe.tid"
+
+
+CHANNELS = [
+ "log_desi_count",
+ "log_manga_count",
+ "partial_full_shock_fraction",
+ "shock_lier_fraction",
+ "shock_score_mean",
+ "gas_sigma_mean",
+ "gas_sigma_p90",
+ "stellar_sigma_mean",
+ "snr_mean",
+ "agn_liner_or_shock_fraction",
+ "star_forming_fraction",
+]
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ with path.open() as f:
+ return json.load(f)
+
+
+def safe_div(a: float, b: float) -> float:
+ return a / b if b else 0.0
+
+
+def pearson(a: list[float], b: list[float]) -> float:
+ if len(a) != len(b) or len(a) < 2:
+ return 0.0
+ ma = sum(a) / len(a)
+ mb = sum(b) / len(b)
+ va = [x - ma for x in a]
+ vb = [x - mb for x in b]
+ den = math.sqrt(sum(x * x for x in va) * sum(y * y for y in vb))
+ return sum(x * y for x, y in zip(va, vb)) / den if den else 0.0
+
+
+def mean_std(values: list[float]) -> tuple[float, float]:
+ if not values:
+ return 0.0, 1.0
+ mean = sum(values) / len(values)
+ var = sum((x - mean) ** 2 for x in values) / len(values)
+ std = math.sqrt(var)
+ return mean, std if std else 1.0
+
+
+def zscore(values: list[float]) -> list[float]:
+ mean, std = mean_std(values)
+ return [(x - mean) / std for x in values]
+
+
+def round9(x: float) -> float:
+ return round(x, 9)
+
+
+def cell_channels(mass_row: dict[str, Any], group_row: dict[str, Any]) -> dict[str, float]:
+ count = float(group_row["count"])
+ bpt = group_row.get("bpt_proxy_classes", {})
+ gas = group_row.get("gas_sigma_summary", {})
+ stellar = group_row.get("stellar_sigma_summary", {})
+ snr = group_row.get("snr_summary", {})
+ shock = group_row.get("shock_score_summary", {})
+ return {
+ "log_desi_count": math.log1p(float(mass_row["desi_count"])),
+ "log_manga_count": math.log1p(float(mass_row["manga_count"])),
+ "partial_full_shock_fraction": float(group_row.get("partial_or_full_shock_fraction") or 0.0),
+ "shock_lier_fraction": float(group_row.get("shock_lier_fraction") or 0.0),
+ "shock_score_mean": float(shock.get("mean") or 0.0),
+ "gas_sigma_mean": float(gas.get("mean") or 0.0),
+ "gas_sigma_p90": float(gas.get("p90") or 0.0),
+ "stellar_sigma_mean": float(stellar.get("mean") or 0.0),
+ "snr_mean": float(snr.get("mean") or 0.0),
+ "agn_liner_or_shock_fraction": safe_div(float(bpt.get("agn_liner_or_shock_proxy", 0)), count),
+ "star_forming_fraction": safe_div(float(bpt.get("star_forming_proxy", 0)), count),
+ }
+
+
+def build() -> tuple[dict[str, Any], dict[str, Any]]:
+ mass = load_json(MASS_JSON)
+ groups = load_json(GROUP_JSON)["groups"]["by_sky_z_cell"]
+
+ rows: list[dict[str, Any]] = []
+ for mass_row in mass["top_cell_masses"]:
+ cell = mass_row["cell"]
+ if cell not in groups:
+ continue
+ channels = cell_channels(mass_row, groups[cell])
+ rows.append(
+ {
+ "cell": cell,
+ "eigenmass": float(mass_row["normalized_eigenvector_mass"]),
+ "eigen_score": float(mass_row["eigen_score"]),
+ "channels": channels,
+ }
+ )
+
+ eigenmass_values = [row["eigenmass"] for row in rows]
+ channel_values = {name: [row["channels"][name] for row in rows] for name in CHANNELS}
+ channel_correlations = {
+ name: round9(pearson(eigenmass_values, values))
+ for name, values in channel_values.items()
+ }
+
+ pressure_components = [
+ "partial_full_shock_fraction",
+ "shock_lier_fraction",
+ "shock_score_mean",
+ "gas_sigma_mean",
+ "gas_sigma_p90",
+ "agn_liner_or_shock_fraction",
+ ]
+ z_components = {name: zscore(channel_values[name]) for name in pressure_components}
+ mass_z = zscore(eigenmass_values)
+
+ pressure_scores = []
+ for i, row in enumerate(rows):
+ pressure = sum(z_components[name][i] for name in pressure_components) / len(pressure_components)
+ toppling_index = 0.5 * mass_z[i] + 0.5 * pressure
+ pressure_scores.append(pressure)
+ row["sandpile"] = {
+ "grains": round9(row["eigenmass"]),
+ "toppling_pressure": round9(pressure),
+ "toppling_index": round9(toppling_index),
+ }
+
+ pressure_mean, pressure_std = mean_std(pressure_scores)
+ index_values = [row["sandpile"]["toppling_index"] for row in rows]
+ index_mean, index_std = mean_std(index_values)
+ for row in rows:
+ row["sandpile"]["state"] = (
+ "AVALANCHE_CANDIDATE"
+ if row["sandpile"]["toppling_index"] >= index_mean + index_std
+ else "LOADED"
+ if row["sandpile"]["toppling_index"] >= index_mean
+ else "STABLE"
+ )
+
+ rows.sort(key=lambda item: item["sandpile"]["toppling_index"], reverse=True)
+ created = datetime.now(timezone.utc).isoformat(timespec="seconds")
+ result = {
+ "schema": "stellar_gas_abelian_sandpile_probe_v0",
+ "created": created,
+ "decision": "ADMIT_SANDPILE_DIAGNOSTIC_HOLD_PHYSICAL_SANDPILE",
+ "claim_boundary": (
+ "Uses an Abelian-sandpile metaphor as a diagnostic over SMN/evidence "
+ "mass and gas/shock observational proxies. It is not a physical "
+ "sandpile simulation, not stellar mass, and not cosmology."
+ ),
+ "sources": {
+ "eigenmass": str(MASS_JSON.relative_to(ROOT)),
+ "population_groups": str(GROUP_JSON.relative_to(ROOT)),
+ },
+ "cell_count": len(rows),
+ "channel_correlations_with_eigenmass": channel_correlations,
+ "pressure_components": pressure_components,
+ "pressure_summary": {
+ "mean": round9(pressure_mean),
+ "std": round9(pressure_std),
+ },
+ "toppling_index_summary": {
+ "mean": round9(index_mean),
+ "std": round9(index_std),
+ },
+ "top_cells": rows[:25],
+ "interpretation": (
+ "High eigenmass plus high gas/shock pressure marks cells that deserve "
+ "fine-grained follow-up. Negative or weak channel correlation marks "
+ "channels that may be less explanatory for the current eigenmass surface."
+ ),
+ "holds": [
+ "HOLD_PHYSICAL_SANDPILE_SIMULATION",
+ "HOLD_DIRECT_STELLAR_MASS",
+ "HOLD_DIRECT_GAS_DENSITY_INFERENCE",
+ "HOLD_OBJECT_LEVEL_CROSSMATCH",
+ "HOLD_COSMOLOGY_FIT",
+ ],
+ }
+ receipt = {
+ "receipt_type": "stellar_gas_abelian_sandpile_probe_receipt",
+ "created": created,
+ "cell_count": len(rows),
+ "avalanche_candidate_count": sum(1 for row in rows if row["sandpile"]["state"] == "AVALANCHE_CANDIDATE"),
+ "decision": result["decision"],
+ "validated_outputs": [
+ str(OUT_JSON.relative_to(ROOT)),
+ str(DOC_MD.relative_to(ROOT)),
+ str(TIDDLER.relative_to(ROOT)),
+ ],
+ }
+ return result, receipt
+
+
+def write_docs(result: dict[str, Any]) -> None:
+ corr_lines = "\n".join(
+ f"- `{name}`: {value}"
+ for name, value in sorted(
+ result["channel_correlations_with_eigenmass"].items(),
+ key=lambda item: abs(item[1]),
+ reverse=True,
+ )
+ )
+ top_lines = "\n".join(
+ f"- `{row['cell']}`: state `{row['sandpile']['state']}`, grains `{row['sandpile']['grains']}`, "
+ f"pressure `{row['sandpile']['toppling_pressure']}`, index `{row['sandpile']['toppling_index']}`"
+ for row in result["top_cells"][:10]
+ )
+ holds = "\n".join(f"- `{hold}`" for hold in result["holds"])
+
+ DOC_MD.write_text(
+ f"""# Stellar Gas Abelian Sandpile Probe
+
+Status: `SANDPILE_DIAGNOSTIC`
+
+Decision: `{result['decision']}`
+
+This probe treats the stellar-gas eigenmass surface as an Abelian-sandpile-style
+diagnostic. Cells carry normalized eigenmass as "grains"; gas/shock observables
+act as toppling pressure; high grain/high-pressure cells become avalanche
+candidates for fine-grained follow-up.
+
+Claim boundary: this is a metaphor-backed diagnostic over observational proxies.
+It is not a physical sandpile simulation, not stellar mass, not direct gas
+density inference, and not a cosmology fit.
+
+## Channel Correlations With Eigenmass
+
+{corr_lines}
+
+## Toppling Candidates
+
+{top_lines}
+
+## Pressure Components
+
+```json
+{json.dumps(result['pressure_components'], indent=2)}
+```
+
+## Holds
+
+{holds}
+""",
+ encoding="utf-8",
+ )
+
+ TIDDLER.write_text(
+ f"""title: Stellar Gas Abelian Sandpile Probe
+tags: StellarGasObservation SemanticMassNumbers Eigenvector Physics Sandpile Receipts
+type: text/vnd.tiddlywiki
+
+Status: <>
+
+Decision: `{result['decision']}`
+
+This tiddler operationalizes the "stars as Abelian sand piles" metaphor as a
+diagnostic over the stellar-gas eigenmass surface.
+
+```
+eigenmass grains + gas/shock pressure -> toppling candidates
+```
+
+!! Channel Correlations With Eigenmass
+
+{corr_lines}
+
+!! Toppling Candidates
+
+{top_lines}
+
+!! Boundary
+
+This is not a physical sandpile simulation, not stellar mass, not direct gas
+density inference, and not a cosmology fit.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ result, receipt = build()
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ DOCS_DIR.mkdir(parents=True, exist_ok=True)
+ TIDDLER_DIR.mkdir(parents=True, exist_ok=True)
+ OUT_JSON.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT_JSON.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_docs(result)
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stellar_gas_eigenvector_mass_probe.py b/4-Infrastructure/shim/stellar_gas_eigenvector_mass_probe.py
new file mode 100644
index 00000000..64f740ae
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_eigenvector_mass_probe.py
@@ -0,0 +1,409 @@
+#!/usr/bin/env python3
+"""Infer an SMN/evidence eigenvector mass over DESI-MaNGA population cells.
+
+This probe treats the coarse DESI epoviz to MaNGA cell join as an evidence
+matrix. It computes the dominant covariance eigenvector with deterministic
+pure-Python Jacobi iteration, then emits a receipt-bearing semantic mass surface.
+
+Boundary: this is not physical mass, not stellar mass, and not a cosmology fit.
+It is a semantic/evidence-load direction over the current joined data surface.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[2]
+JOIN_JSON = ROOT / "shared-data/data/stellar_gas_observation/desi_epoviz_manga_population_cell_join.json"
+OUT_DIR = ROOT / "shared-data/data/stellar_gas_observation"
+DOCS_DIR = ROOT / "6-Documentation/docs"
+TIDDLER_DIR = ROOT / "6-Documentation/tiddlywiki-local/wiki/tiddlers"
+
+OUT_JSON = OUT_DIR / "stellar_gas_eigenvector_mass_probe.json"
+RECEIPT_JSON = OUT_DIR / "stellar_gas_eigenvector_mass_probe_receipt.json"
+DOC_MD = DOCS_DIR / "stellar_gas_eigenvector_mass_probe_2026-05-09.md"
+TIDDLER = TIDDLER_DIR / "Stellar Gas Eigenvector Mass Probe.tid"
+
+FEATURES = [
+ "log_desi_count",
+ "log_manga_count",
+ "partial_full_shock_fraction",
+ "shock_lier_fraction",
+ "BGS_share",
+ "ELG_share",
+ "LRG_share",
+ "QSO_share",
+]
+
+
+def dot(a: list[float], b: list[float]) -> float:
+ return sum(x * y for x, y in zip(a, b))
+
+
+def mat_vec(m: list[list[float]], v: list[float]) -> list[float]:
+ return [dot(row, v) for row in m]
+
+
+def norm(v: list[float]) -> float:
+ return math.sqrt(dot(v, v))
+
+
+def normalize(v: list[float]) -> list[float]:
+ n = norm(v)
+ if n == 0:
+ return [0.0 for _ in v]
+ return [x / n for x in v]
+
+
+def transpose(matrix: list[list[float]]) -> list[list[float]]:
+ return [list(col) for col in zip(*matrix)]
+
+
+def jacobi_eigen_symmetric(matrix: list[list[float]], max_iter: int = 200, eps: float = 1e-12) -> tuple[list[float], list[list[float]]]:
+ """Return eigenvalues and eigenvectors for a small symmetric matrix.
+
+ Eigenvectors are returned as columns in the second return value.
+ """
+
+ n = len(matrix)
+ a = [row[:] for row in matrix]
+ v = [[1.0 if i == j else 0.0 for j in range(n)] for i in range(n)]
+
+ iterations = 0
+ final_max_offdiag = 0.0
+ converged = False
+ for iteration in range(1, max_iter + 1):
+ p, q = 0, 1
+ max_off = 0.0
+ for i in range(n):
+ for j in range(i + 1, n):
+ val = abs(a[i][j])
+ if val > max_off:
+ max_off = val
+ p, q = i, j
+ iterations = iteration
+ final_max_offdiag = max_off
+ if max_off < eps:
+ converged = True
+ break
+
+ if abs(a[p][p] - a[q][q]) < eps:
+ angle = math.pi / 4
+ else:
+ angle = 0.5 * math.atan2(2.0 * a[p][q], a[q][q] - a[p][p])
+ c = math.cos(angle)
+ s = math.sin(angle)
+
+ app = c * c * a[p][p] - 2.0 * s * c * a[p][q] + s * s * a[q][q]
+ aqq = s * s * a[p][p] + 2.0 * s * c * a[p][q] + c * c * a[q][q]
+ a[p][p] = app
+ a[q][q] = aqq
+ a[p][q] = 0.0
+ a[q][p] = 0.0
+
+ for k in range(n):
+ if k == p or k == q:
+ continue
+ akp = c * a[k][p] - s * a[k][q]
+ akq = s * a[k][p] + c * a[k][q]
+ a[k][p] = akp
+ a[p][k] = akp
+ a[k][q] = akq
+ a[q][k] = akq
+
+ for k in range(n):
+ vkp = c * v[k][p] - s * v[k][q]
+ vkq = s * v[k][p] + c * v[k][q]
+ v[k][p] = vkp
+ v[k][q] = vkq
+
+ eigenvalues = [a[i][i] for i in range(n)]
+ return eigenvalues, v, {
+ "method": "jacobi_symmetric",
+ "max_iter": max_iter,
+ "eps": eps,
+ "iterations": iterations,
+ "converged": converged,
+ "final_max_offdiag": final_max_offdiag,
+ }
+
+
+def eigen_residual(matrix: list[list[float]], eigenvalue: float, eigenvector: list[float]) -> float:
+ av = mat_vec(matrix, eigenvector)
+ residual = [av_i - eigenvalue * v_i for av_i, v_i in zip(av, eigenvector)]
+ return norm(residual)
+
+
+def build_feature_rows(join: dict[str, Any]) -> tuple[list[str], list[list[float]], list[dict[str, Any]]]:
+ labels: list[str] = []
+ rows: list[list[float]] = []
+ payloads: list[dict[str, Any]] = []
+ for cell in join["manga_join"]["top_joined_cells"]:
+ mix = cell["desi_tracer_mix"]
+ total = sum(float(v) for v in mix.values()) or 1.0
+ labels.append(cell["cell"])
+ payloads.append(cell)
+ rows.append(
+ [
+ math.log1p(float(cell["desi_count"])),
+ math.log1p(float(cell["manga_count"])),
+ float(cell.get("manga_partial_or_full_shock_fraction") or 0.0),
+ float(cell.get("manga_shock_lier_fraction") or 0.0),
+ float(mix.get("BGS", 0.0)) / total,
+ float(mix.get("ELG", 0.0)) / total,
+ float(mix.get("LRG", 0.0)) / total,
+ float(mix.get("QSO", 0.0)) / total,
+ ]
+ )
+ return labels, rows, payloads
+
+
+def zscore(rows: list[list[float]]) -> tuple[list[list[float]], list[float], list[float]]:
+ cols = transpose(rows)
+ means = [sum(col) / len(col) for col in cols]
+ stds = []
+ for col, mean in zip(cols, means):
+ var = sum((x - mean) ** 2 for x in col) / len(col)
+ std = math.sqrt(var)
+ stds.append(std if std > 0 else 1.0)
+ scaled = [[(x - means[i]) / stds[i] for i, x in enumerate(row)] for row in rows]
+ return scaled, means, stds
+
+
+def covariance(rows: list[list[float]]) -> list[list[float]]:
+ n = len(rows)
+ cols = len(rows[0])
+ return [
+ [sum(row[i] * row[j] for row in rows) / (n - 1) for j in range(cols)]
+ for i in range(cols)
+ ]
+
+
+def build() -> tuple[dict[str, Any], dict[str, Any]]:
+ with JOIN_JSON.open() as f:
+ join = json.load(f)
+
+ labels, raw_rows, payloads = build_feature_rows(join)
+ scaled_rows, means, stds = zscore(raw_rows)
+ cov = covariance(scaled_rows)
+ values, vectors_as_columns, solver = jacobi_eigen_symmetric(cov)
+
+ order = sorted(range(len(values)), key=lambda i: values[i], reverse=True)
+ eigenvalues = [values[i] for i in order]
+ eigenvectors_by_rank = [[vectors_as_columns[row][i] for row in range(len(FEATURES))] for i in order]
+ dominant = normalize(eigenvectors_by_rank[0])
+
+ shock_index = FEATURES.index("partial_full_shock_fraction")
+ if dominant[shock_index] < 0:
+ dominant = [-x for x in dominant]
+ residual = eigen_residual(cov, eigenvalues[0], dominant)
+
+ scores = [dot(row, dominant) for row in scaled_rows]
+ min_score = min(scores)
+ shifted = [score - min_score for score in scores]
+ total_shifted = sum(shifted)
+ masses = [x / total_shifted if total_shifted > 0 else 1.0 / len(shifted) for x in shifted]
+
+ cell_masses = []
+ for label, payload, score, mass in zip(labels, payloads, scores, masses):
+ cell_masses.append(
+ {
+ "cell": label,
+ "eigen_score": round(score, 6),
+ "normalized_eigenvector_mass": round(mass, 6),
+ "desi_count": payload["desi_count"],
+ "manga_count": payload["manga_count"],
+ "manga_partial_or_full_shock_fraction": payload.get("manga_partial_or_full_shock_fraction"),
+ "manga_shock_lier_fraction": payload.get("manga_shock_lier_fraction"),
+ "desi_tracer_mix": payload["desi_tracer_mix"],
+ }
+ )
+ cell_masses.sort(key=lambda row: row["normalized_eigenvector_mass"], reverse=True)
+
+ total_eigen = sum(x for x in eigenvalues if x > 0)
+ explained = [(x / total_eigen if total_eigen > 0 else 0.0) for x in eigenvalues]
+ created = datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+ result = {
+ "schema": "stellar_gas_eigenvector_mass_probe_v0",
+ "created": created,
+ "decision": "ADMIT_SMN_EIGENVECTOR_MASS_HOLD_PHYSICAL_MASS",
+ "claim_boundary": (
+ "Eigenvector mass is an SMN/evidence-load direction over the coarse "
+ "DESI epoviz to MaNGA population-cell join. It is not physical mass, "
+ "not stellar mass, not a gas-density map, and not a cosmology fit."
+ ),
+ "source_join": str(JOIN_JSON.relative_to(ROOT)),
+ "feature_basis": FEATURES,
+ "feature_means": {name: round(means[i], 9) for i, name in enumerate(FEATURES)},
+ "feature_stds": {name: round(stds[i], 9) for i, name in enumerate(FEATURES)},
+ "cell_count": len(labels),
+ "eigenvalues": [round(x, 9) for x in eigenvalues],
+ "explained_mass_share": [round(x, 9) for x in explained],
+ "dominant_eigenvector": {name: round(dominant[i], 9) for i, name in enumerate(FEATURES)},
+ "dominant_eigenvalue": round(eigenvalues[0], 9),
+ "dominant_explained_mass_share": round(explained[0], 9),
+ "eigensolver_diagnostics": {
+ **solver,
+ "dominant_residual_l2": round(residual, 12),
+ "orthogonality_note": "Jacobi rotations return an orthonormal basis up to numeric roundoff; this receipt reports the dominant residual only.",
+ },
+ "top_cell_masses": cell_masses[:25],
+ "holds": [
+ "HOLD_PHYSICAL_MASS_INTERPRETATION",
+ "HOLD_OBJECT_LEVEL_CROSSMATCH",
+ "HOLD_DIRECT_GAS_DENSITY_INFERENCE",
+ "HOLD_SELECTION_FUNCTION_FIT",
+ "HOLD_COSMOLOGY_FIT",
+ ],
+ }
+
+ receipt = {
+ "receipt_type": "stellar_gas_eigenvector_mass_probe_receipt",
+ "created": created,
+ "source_join": str(JOIN_JSON.relative_to(ROOT)),
+ "cell_count": len(labels),
+ "dominant_eigenvalue": result["dominant_eigenvalue"],
+ "dominant_explained_mass_share": result["dominant_explained_mass_share"],
+ "eigensolver_diagnostics": result["eigensolver_diagnostics"],
+ "decision": result["decision"],
+ "validated_outputs": [
+ str(OUT_JSON.relative_to(ROOT)),
+ str(DOC_MD.relative_to(ROOT)),
+ str(TIDDLER.relative_to(ROOT)),
+ ],
+ }
+ return result, receipt
+
+
+def write_docs(result: dict[str, Any]) -> None:
+ vector_lines = "\n".join(
+ f"- `{name}`: {value}" for name, value in result["dominant_eigenvector"].items()
+ )
+ cell_lines = "\n".join(
+ f"- `{row['cell']}`: mass `{row['normalized_eigenvector_mass']}`, "
+ f"score `{row['eigen_score']}`, DESI `{row['desi_count']}`, MaNGA `{row['manga_count']}`"
+ for row in result["top_cell_masses"][:10]
+ )
+ holds = "\n".join(f"- `{hold}`" for hold in result["holds"])
+ diag = result["eigensolver_diagnostics"]
+
+ DOC_MD.write_text(
+ f"""# Stellar Gas Eigenvector Mass Probe
+
+Status: `SMN_EIGENVECTOR_MASS`
+
+Decision: `{result['decision']}`
+
+This probe computes the dominant covariance eigenvector over the coarse DESI
+epoviz to MaNGA population-cell join. The output is an SMN/evidence-load mass
+direction: it ranks the current coarse joined cells by this diagnostic score so
+later zoom work can choose explicit follow-up targets.
+
+Claim boundary: this is not physical mass, not stellar mass, not a direct gas
+density map, and not a cosmology fit.
+
+## Result
+
+Dominant eigenvalue:
+
+```text
+{result['dominant_eigenvalue']}
+```
+
+Dominant explained mass share:
+
+```text
+{result['dominant_explained_mass_share']}
+```
+
+## Dominant Eigenvector
+
+{vector_lines}
+
+## Eigensolver Diagnostics
+
+```text
+method: {diag['method']}
+converged: {diag['converged']}
+iterations: {diag['iterations']}
+final max off-diagonal: {diag['final_max_offdiag']}
+dominant residual L2: {diag['dominant_residual_l2']}
+```
+
+## Top Cell Masses
+
+{cell_lines}
+
+## Holds
+
+{holds}
+""",
+ encoding="utf-8",
+ )
+
+ TIDDLER.write_text(
+ f"""title: Stellar Gas Eigenvector Mass Probe
+tags: StellarGasObservation SemanticMassNumbers DESI MaNGA Eigenvector Receipts
+type: text/vnd.tiddlywiki
+
+Status: <>
+
+Decision: `{result['decision']}`
+
+The inferred eigenvector mass is the dominant SMN/evidence-load direction over
+the coarse DESI epoviz to MaNGA population-cell join.
+
+Dominant eigenvalue:
+
+```
+{result['dominant_eigenvalue']}
+```
+
+Dominant explained mass share:
+
+```
+{result['dominant_explained_mass_share']}
+```
+
+Eigensolver:
+
+```
+converged={diag['converged']} iterations={diag['iterations']} residual_l2={diag['dominant_residual_l2']}
+```
+
+!! Dominant Eigenvector
+
+{vector_lines}
+
+!! Top Cell Masses
+
+{cell_lines}
+
+!! Boundary
+
+This is not physical mass, not stellar mass, not direct gas-density inference,
+and not a cosmology fit.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ result, receipt = build()
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ DOCS_DIR.mkdir(parents=True, exist_ok=True)
+ TIDDLER_DIR.mkdir(parents=True, exist_ok=True)
+ OUT_JSON.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT_JSON.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_docs(result)
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stellar_gas_full_cell_eigenmass_stability.py b/4-Infrastructure/shim/stellar_gas_full_cell_eigenmass_stability.py
new file mode 100644
index 00000000..6627fb97
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_full_cell_eigenmass_stability.py
@@ -0,0 +1,586 @@
+#!/usr/bin/env python3
+"""Full-cell eigenmass stability and ablation controls.
+
+This probe reuses the existing DESI epoviz to MaNGA population-cell join and
+checks whether the 25-cell SMN/evidence-load eigenvector remains stable across
+all joined cells, leave-one-cell-out slices, deterministic null shuffles, and
+feature ablations.
+
+Boundary: this is evidence-geometry quality control. It is not physical mass,
+not gas density, not shock proof, and not cosmology.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import random
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[2]
+JOIN_JSON = ROOT / "shared-data/data/stellar_gas_observation/desi_epoviz_manga_population_cell_join.json"
+BASELINE_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_eigenvector_mass_probe.json"
+OUT_DIR = ROOT / "shared-data/data/stellar_gas_observation"
+DOCS_DIR = ROOT / "6-Documentation/docs"
+TIDDLER_DIR = ROOT / "6-Documentation/tiddlywiki-local/wiki/tiddlers"
+
+OUT_JSON = OUT_DIR / "stellar_gas_full_cell_eigenmass_stability.json"
+RECEIPT_JSON = OUT_DIR / "stellar_gas_full_cell_eigenmass_stability_receipt.json"
+DOC_MD = DOCS_DIR / "stellar_gas_full_cell_eigenmass_stability_2026-05-09.md"
+TIDDLER = TIDDLER_DIR / "Stellar Gas Full Cell Eigenmass Stability.tid"
+
+FEATURES = [
+ "log_desi_count",
+ "log_manga_count",
+ "partial_full_shock_fraction",
+ "shock_lier_fraction",
+ "BGS_share",
+ "ELG_share",
+ "LRG_share",
+ "QSO_share",
+]
+
+SHOCK_FEATURES = {"partial_full_shock_fraction", "shock_lier_fraction"}
+TRACER_FEATURES = {"BGS_share", "ELG_share", "LRG_share", "QSO_share"}
+
+
+def dot(a: list[float], b: list[float]) -> float:
+ return sum(x * y for x, y in zip(a, b))
+
+
+def norm(v: list[float]) -> float:
+ return math.sqrt(dot(v, v))
+
+
+def normalize(v: list[float]) -> list[float]:
+ n = norm(v)
+ if n == 0:
+ return [0.0 for _ in v]
+ return [x / n for x in v]
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+ denom = norm(a) * norm(b)
+ if denom == 0:
+ return 0.0
+ return dot(a, b) / denom
+
+
+def transpose(matrix: list[list[float]]) -> list[list[float]]:
+ return [list(col) for col in zip(*matrix)]
+
+
+def round9(value: float) -> float:
+ return round(value, 9)
+
+
+def jacobi_eigen_symmetric(matrix: list[list[float]], max_iter: int = 240, eps: float = 1e-12) -> tuple[list[float], list[list[float]], dict[str, Any]]:
+ n = len(matrix)
+ a = [row[:] for row in matrix]
+ v = [[1.0 if i == j else 0.0 for j in range(n)] for i in range(n)]
+
+ iterations = 0
+ final_max_offdiag = 0.0
+ converged = False
+ for iteration in range(1, max_iter + 1):
+ p, q = 0, 1
+ max_off = 0.0
+ for i in range(n):
+ for j in range(i + 1, n):
+ val = abs(a[i][j])
+ if val > max_off:
+ max_off = val
+ p, q = i, j
+ iterations = iteration
+ final_max_offdiag = max_off
+ if max_off < eps:
+ converged = True
+ break
+
+ if abs(a[p][p] - a[q][q]) < eps:
+ angle = math.pi / 4.0
+ else:
+ angle = 0.5 * math.atan2(2.0 * a[p][q], a[q][q] - a[p][p])
+ c = math.cos(angle)
+ s = math.sin(angle)
+
+ app = c * c * a[p][p] - 2.0 * s * c * a[p][q] + s * s * a[q][q]
+ aqq = s * s * a[p][p] + 2.0 * s * c * a[p][q] + c * c * a[q][q]
+ a[p][p] = app
+ a[q][q] = aqq
+ a[p][q] = 0.0
+ a[q][p] = 0.0
+
+ for k in range(n):
+ if k == p or k == q:
+ continue
+ akp = c * a[k][p] - s * a[k][q]
+ akq = s * a[k][p] + c * a[k][q]
+ a[k][p] = akp
+ a[p][k] = akp
+ a[k][q] = akq
+ a[q][k] = akq
+
+ for k in range(n):
+ vkp = c * v[k][p] - s * v[k][q]
+ vkq = s * v[k][p] + c * v[k][q]
+ v[k][p] = vkp
+ v[k][q] = vkq
+
+ return [a[i][i] for i in range(n)], v, {
+ "method": "jacobi_symmetric",
+ "max_iter": max_iter,
+ "eps": eps,
+ "iterations": iterations,
+ "converged": converged,
+ "final_max_offdiag": final_max_offdiag,
+ }
+
+
+def mat_vec(m: list[list[float]], v: list[float]) -> list[float]:
+ return [dot(row, v) for row in m]
+
+
+def eigen_residual(matrix: list[list[float]], eigenvalue: float, eigenvector: list[float]) -> float:
+ av = mat_vec(matrix, eigenvector)
+ residual = [av_i - eigenvalue * v_i for av_i, v_i in zip(av, eigenvector)]
+ return norm(residual)
+
+
+def zscore(rows: list[list[float]]) -> tuple[list[list[float]], list[float], list[float]]:
+ cols = transpose(rows)
+ means = [sum(col) / len(col) for col in cols]
+ stds = []
+ for col, mean in zip(cols, means):
+ var = sum((x - mean) ** 2 for x in col) / len(col)
+ std = math.sqrt(var)
+ stds.append(std if std > 0 else 1.0)
+ return [[(x - means[i]) / stds[i] for i, x in enumerate(row)] for row in rows], means, stds
+
+
+def covariance(rows: list[list[float]]) -> list[list[float]]:
+ n = len(rows)
+ cols = len(rows[0])
+ return [
+ [sum(row[i] * row[j] for row in rows) / (n - 1) for j in range(cols)]
+ for i in range(cols)
+ ]
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ with path.open() as f:
+ return json.load(f)
+
+
+def source_rows(join: dict[str, Any]) -> list[dict[str, Any]]:
+ rows = []
+ for cell in join["manga_join"]["top_joined_cells"]:
+ mix = cell["desi_tracer_mix"]
+ total = sum(float(v) for v in mix.values()) or 1.0
+ rows.append(
+ {
+ "cell": cell["cell"],
+ "payload": cell,
+ "features": {
+ "log_desi_count": math.log1p(float(cell["desi_count"])),
+ "log_manga_count": math.log1p(float(cell["manga_count"])),
+ "partial_full_shock_fraction": float(cell.get("manga_partial_or_full_shock_fraction") or 0.0),
+ "shock_lier_fraction": float(cell.get("manga_shock_lier_fraction") or 0.0),
+ "BGS_share": float(mix.get("BGS", 0.0)) / total,
+ "ELG_share": float(mix.get("ELG", 0.0)) / total,
+ "LRG_share": float(mix.get("LRG", 0.0)) / total,
+ "QSO_share": float(mix.get("QSO", 0.0)) / total,
+ },
+ }
+ )
+ return rows
+
+
+def permuted(values: list[Any], seed: int) -> list[Any]:
+ out = values[:]
+ random.Random(seed).shuffle(out)
+ return out
+
+
+def vector_for_features(row: dict[str, Any], features: list[str]) -> list[float]:
+ return [float(row["features"][feature]) for feature in features]
+
+
+def fit_eigenmass(rows: list[dict[str, Any]], features: list[str], baseline_vector: dict[str, float] | None = None) -> dict[str, Any]:
+ labels = [row["cell"] for row in rows]
+ raw_rows = [vector_for_features(row, features) for row in rows]
+ scaled_rows, means, stds = zscore(raw_rows)
+ cov = covariance(scaled_rows)
+ values, vectors_as_columns, solver = jacobi_eigen_symmetric(cov)
+ order = sorted(range(len(values)), key=lambda i: values[i], reverse=True)
+ eigenvalues = [values[i] for i in order]
+ dominant = normalize([vectors_as_columns[row][order[0]] for row in range(len(features))])
+
+ if baseline_vector is None:
+ if "partial_full_shock_fraction" in features:
+ anchor = dominant[features.index("partial_full_shock_fraction")]
+ else:
+ anchor = sum(dominant)
+ if anchor < 0:
+ dominant = [-x for x in dominant]
+ else:
+ common = [feature for feature in features if feature in baseline_vector]
+ candidate_common = [dominant[features.index(feature)] for feature in common]
+ baseline_common = [baseline_vector[feature] for feature in common]
+ if dot(candidate_common, baseline_common) < 0:
+ dominant = [-x for x in dominant]
+ residual = eigen_residual(cov, eigenvalues[0], dominant)
+
+ scores = [dot(row, dominant) for row in scaled_rows]
+ min_score = min(scores)
+ shifted = [score - min_score for score in scores]
+ total_shifted = sum(shifted)
+ masses = [x / total_shifted if total_shifted > 0 else 1.0 / len(shifted) for x in shifted]
+ cell_masses = [
+ {
+ "cell": label,
+ "eigen_score": round(score, 6),
+ "normalized_eigenvector_mass": round(mass, 6),
+ }
+ for label, score, mass in zip(labels, scores, masses)
+ ]
+ cell_masses.sort(key=lambda row: row["normalized_eigenvector_mass"], reverse=True)
+
+ total_eigen = sum(x for x in eigenvalues if x > 0)
+ explained = [(x / total_eigen if total_eigen > 0 else 0.0) for x in eigenvalues]
+ return {
+ "cell_count": len(rows),
+ "feature_basis": features,
+ "feature_means": {name: round9(means[i]) for i, name in enumerate(features)},
+ "feature_stds": {name: round9(stds[i]) for i, name in enumerate(features)},
+ "dominant_eigenvalue": round9(eigenvalues[0]),
+ "dominant_explained_mass_share": round9(explained[0]),
+ "eigensolver_diagnostics": {
+ **solver,
+ "dominant_residual_l2": round(residual, 12),
+ "orthogonality_note": "Jacobi rotations return an orthonormal basis up to numeric roundoff; this receipt reports the dominant residual only.",
+ },
+ "dominant_eigenvector": {name: round9(dominant[i]) for i, name in enumerate(features)},
+ "eigenvalues": [round9(x) for x in eigenvalues],
+ "explained_mass_share": [round9(x) for x in explained],
+ "top_cell_masses": cell_masses,
+ }
+
+
+def compare_to_baseline(candidate: dict[str, Any], baseline: dict[str, Any], top_n: int = 5) -> dict[str, Any]:
+ common = [feature for feature in FEATURES if feature in candidate["dominant_eigenvector"] and feature in baseline["dominant_eigenvector"]]
+ cand_vec = [candidate["dominant_eigenvector"][feature] for feature in common]
+ base_vec = [baseline["dominant_eigenvector"][feature] for feature in common]
+ base_top = {row["cell"] for row in baseline["top_cell_masses"][:top_n]}
+ cand_top = {row["cell"] for row in candidate["top_cell_masses"][:top_n]}
+ return {
+ "common_feature_basis": common,
+ "common_basis_cosine_to_original": round9(cosine(cand_vec, base_vec)),
+ "dominant_explained_share_delta": round9(candidate["dominant_explained_mass_share"] - baseline["dominant_explained_mass_share"]),
+ "top_cell_overlap_at_5": len(base_top & cand_top),
+ "top_cell_overlap_fraction_at_5": round9(len(base_top & cand_top) / top_n),
+ }
+
+
+def summarize_leave_one_out(values: list[dict[str, Any]]) -> dict[str, Any]:
+ cosines = sorted(row["common_basis_cosine_to_original"] for row in values)
+ overlaps = [row["top_cell_overlap_fraction_at_5"] for row in values]
+ return {
+ "loo_count": len(values),
+ "min_cosine_to_original": round9(cosines[0]),
+ "median_cosine_to_original": round9(cosines[len(cosines) // 2]),
+ "mean_cosine_to_original": round9(sum(cosines) / len(cosines)),
+ "mean_top5_overlap_fraction": round9(sum(overlaps) / len(overlaps)),
+ }
+
+
+def with_shuffled_feature_columns(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ shuffled_columns = {
+ feature: permuted([row["features"][feature] for row in rows], seed=2026050901 + idx)
+ for idx, feature in enumerate(FEATURES)
+ }
+ out = []
+ for idx, row in enumerate(rows):
+ clone = {"cell": row["cell"], "payload": row["payload"], "features": dict(row["features"])}
+ for feature in FEATURES:
+ clone["features"][feature] = shuffled_columns[feature][idx]
+ out.append(clone)
+ return out
+
+
+def with_shuffled_shocks(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ partial = permuted([row["features"]["partial_full_shock_fraction"] for row in rows], seed=2026050902)
+ lier = permuted([row["features"]["shock_lier_fraction"] for row in rows], seed=2026050903)
+ out = []
+ for idx, row in enumerate(rows):
+ clone = {"cell": row["cell"], "payload": row["payload"], "features": dict(row["features"])}
+ clone["features"]["partial_full_shock_fraction"] = partial[idx]
+ clone["features"]["shock_lier_fraction"] = lier[idx]
+ out.append(clone)
+ return out
+
+
+def control_result(name: str, rows: list[dict[str, Any]], features: list[str], baseline: dict[str, Any]) -> dict[str, Any]:
+ fit = fit_eigenmass(rows, features, baseline["dominant_eigenvector"])
+ return {
+ "control": name,
+ "cell_count": fit["cell_count"],
+ "feature_basis": fit["feature_basis"],
+ "dominant_eigenvalue": fit["dominant_eigenvalue"],
+ "dominant_explained_mass_share": fit["dominant_explained_mass_share"],
+ "dominant_eigenvector": fit["dominant_eigenvector"],
+ "comparison_to_original": compare_to_baseline(fit, baseline),
+ "top_cell_masses": fit["top_cell_masses"][:10],
+ }
+
+
+def build() -> tuple[dict[str, Any], dict[str, Any]]:
+ join = load_json(JOIN_JSON)
+ stored = load_json(BASELINE_JSON)
+ rows = source_rows(join)
+ baseline = fit_eigenmass(rows, FEATURES)
+
+ stored_compare = compare_to_baseline(baseline, stored, top_n=5)
+ stored_vector_abs_delta = {
+ feature: round9(abs(baseline["dominant_eigenvector"][feature] - stored["dominant_eigenvector"][feature]))
+ for feature in FEATURES
+ }
+
+ loo_rows = []
+ for cell in [row["cell"] for row in rows]:
+ subset = [row for row in rows if row["cell"] != cell]
+ fit = fit_eigenmass(subset, FEATURES, baseline["dominant_eigenvector"])
+ comparison = compare_to_baseline(fit, baseline)
+ loo_rows.append(
+ {
+ "held_out_cell": cell,
+ "dominant_explained_mass_share": fit["dominant_explained_mass_share"],
+ **comparison,
+ }
+ )
+
+ controls = [
+ control_result("shuffled_feature_columns", with_shuffled_feature_columns(rows), FEATURES, baseline),
+ control_result("shuffled_shock_channels", with_shuffled_shocks(rows), FEATURES, baseline),
+ control_result("desi_count_removed", rows, [feature for feature in FEATURES if feature != "log_desi_count"], baseline),
+ control_result("shock_proxy_removed", rows, [feature for feature in FEATURES if feature not in SHOCK_FEATURES], baseline),
+ control_result("tracer_mix_removed", rows, [feature for feature in FEATURES if feature not in TRACER_FEATURES], baseline),
+ ]
+
+ created = datetime.now(timezone.utc).isoformat(timespec="seconds")
+ result = {
+ "schema": "stellar_gas_full_cell_eigenmass_stability_v0",
+ "created": created,
+ "decision": "REPORT_FULL_CELL_EIGENMASS_STABILITY_WITH_NULL_CONTROLS_HOLD_PHYSICAL_CLAIMS",
+ "claim_boundary": (
+ "Full-cell stability and ablation controls for the joined DESI/MaNGA "
+ "SMN/evidence-load eigenvector. This does not promote physical mass, "
+ "gas density, shock proof, or cosmology."
+ ),
+ "sources": {
+ "join": str(JOIN_JSON.relative_to(ROOT)),
+ "stored_25_cell_probe": str(BASELINE_JSON.relative_to(ROOT)),
+ },
+ "full_cell_baseline": baseline,
+ "stored_25_cell_comparison": {
+ "stored_cell_count": stored["cell_count"],
+ "recomputed_cell_count": baseline["cell_count"],
+ "common_basis_cosine_to_stored": stored_compare["common_basis_cosine_to_original"],
+ "top_cell_overlap_at_5": stored_compare["top_cell_overlap_at_5"],
+ "max_abs_eigenvector_component_delta": round9(max(stored_vector_abs_delta.values())),
+ "abs_eigenvector_component_delta": stored_vector_abs_delta,
+ },
+ "leave_one_cell_out_stability": {
+ "summary": summarize_leave_one_out(loo_rows),
+ "rows": loo_rows,
+ },
+ "null_and_ablation_controls": controls,
+ "holds": [
+ "HOLD_PHYSICAL_MASS_INTERPRETATION",
+ "HOLD_DIRECT_GAS_DENSITY_INFERENCE",
+ "HOLD_SHOCK_PROOF",
+ "HOLD_OBJECT_LEVEL_CROSSMATCH",
+ "HOLD_SELECTION_FUNCTION_FIT",
+ "HOLD_COSMOLOGY_FIT",
+ ],
+ }
+ receipt = {
+ "receipt_type": "stellar_gas_full_cell_eigenmass_stability_receipt",
+ "created": created,
+ "source_join": str(JOIN_JSON.relative_to(ROOT)),
+ "stored_25_cell_probe": str(BASELINE_JSON.relative_to(ROOT)),
+ "full_cell_count": baseline["cell_count"],
+ "stored_25_cell_count": stored["cell_count"],
+ "stored_comparison_cosine": result["stored_25_cell_comparison"]["common_basis_cosine_to_stored"],
+ "leave_one_out_min_cosine": result["leave_one_cell_out_stability"]["summary"]["min_cosine_to_original"],
+ "control_names": [control["control"] for control in controls],
+ "eigensolver_diagnostics": baseline["eigensolver_diagnostics"],
+ "decision": result["decision"],
+ "validated_outputs": [
+ str(OUT_JSON.relative_to(ROOT)),
+ str(DOC_MD.relative_to(ROOT)),
+ str(TIDDLER.relative_to(ROOT)),
+ ],
+ }
+ return result, receipt
+
+
+def write_docs(result: dict[str, Any]) -> None:
+ baseline = result["full_cell_baseline"]
+ stored = result["stored_25_cell_comparison"]
+ loo = result["leave_one_cell_out_stability"]["summary"]
+ controls = result["null_and_ablation_controls"]
+ diag = baseline["eigensolver_diagnostics"]
+ vector_lines = "\n".join(
+ f"- `{name}`: {value}" for name, value in baseline["dominant_eigenvector"].items()
+ )
+ control_lines = "\n".join(
+ "- `{control}`: cosine `{cosine}`, explained share `{share}`, top5 overlap `{overlap}`".format(
+ control=control["control"],
+ cosine=control["comparison_to_original"]["common_basis_cosine_to_original"],
+ share=control["dominant_explained_mass_share"],
+ overlap=control["comparison_to_original"]["top_cell_overlap_fraction_at_5"],
+ )
+ for control in controls
+ )
+ holds = "\n".join(f"- `{hold}`" for hold in result["holds"])
+
+ DOC_MD.write_text(
+ f"""# Stellar Gas Full Cell Eigenmass Stability
+
+Status: `FULL_CELL_EIGENMASS_STABILITY`
+
+Decision: `{result['decision']}`
+
+This probe checks the 25-cell DESI/MaNGA joined-cell eigenmass against all
+available joined cells, leave-one-cell-out slices, deterministic null shuffles,
+and feature ablations.
+
+Claim boundary: this is evidence-geometry quality control only. It does not
+promote physical mass, gas density, shock proof, object-level crossmatch, or
+cosmology.
+
+## Full-Cell Baseline
+
+Cell count: `{baseline['cell_count']}`
+
+Dominant eigenvalue:
+
+```text
+{baseline['dominant_eigenvalue']}
+```
+
+Dominant explained mass share:
+
+```text
+{baseline['dominant_explained_mass_share']}
+```
+
+Dominant eigenvector:
+
+{vector_lines}
+
+## Stored 25-Cell Comparison
+
+```text
+common-basis cosine to stored probe: {stored['common_basis_cosine_to_stored']}
+top-cell overlap at 5: {stored['top_cell_overlap_at_5']}
+max abs component delta: {stored['max_abs_eigenvector_component_delta']}
+```
+
+## Eigensolver Diagnostics
+
+```text
+method: {diag['method']}
+converged: {diag['converged']}
+iterations: {diag['iterations']}
+final max off-diagonal: {diag['final_max_offdiag']}
+dominant residual L2: {diag['dominant_residual_l2']}
+```
+
+## Leave-One-Cell-Out Stability
+
+```text
+loo count: {loo['loo_count']}
+min cosine to original: {loo['min_cosine_to_original']}
+median cosine to original: {loo['median_cosine_to_original']}
+mean cosine to original: {loo['mean_cosine_to_original']}
+mean top5 overlap: {loo['mean_top5_overlap_fraction']}
+```
+
+## Null And Ablation Controls
+
+{control_lines}
+
+## Holds
+
+{holds}
+""",
+ encoding="utf-8",
+ )
+
+ TIDDLER.write_text(
+ f"""title: Stellar Gas Full Cell Eigenmass Stability
+tags: StellarGasObservation DESI MaNGA Eigenvector Controls Receipts
+type: text/vnd.tiddlywiki
+
+Status: <>
+
+Decision: `{result['decision']}`
+
+This tiddler records a full-cell stability and null-control check for the
+DESI/MaNGA joined-cell SMN/evidence-load eigenvector.
+
+Cell count: `{baseline['cell_count']}`
+
+Stored 25-cell cosine:
+
+```
+{stored['common_basis_cosine_to_stored']}
+```
+
+Leave-one-cell-out minimum cosine:
+
+```
+{loo['min_cosine_to_original']}
+```
+
+Eigensolver:
+
+```
+converged={diag['converged']} iterations={diag['iterations']} residual_l2={diag['dominant_residual_l2']}
+```
+
+!! Original Dominant Eigenvector
+
+{vector_lines}
+
+!! Null And Ablation Controls
+
+{control_lines}
+
+!! Boundary
+
+This is evidence-geometry quality control only. It is not physical mass, gas
+density, shock proof, or cosmology.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ result, receipt = build()
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ DOCS_DIR.mkdir(parents=True, exist_ok=True)
+ TIDDLER_DIR.mkdir(parents=True, exist_ok=True)
+ OUT_JSON.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT_JSON.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_docs(result)
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stellar_gas_gdrive_pull.py b/4-Infrastructure/shim/stellar_gas_gdrive_pull.py
new file mode 100644
index 00000000..71bed890
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_gdrive_pull.py
@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""Direct-to-Google-Drive seed puller for stellar gas observation routes.
+
+The puller streams source payloads through rclone instead of writing observation
+payloads into the repository. Local files are limited to source manifests and
+receipts.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+
+REPO = Path(__file__).resolve().parents[2]
+SOURCE_PATH = REPO / "shared-data/data/stellar_gas_observation/stellar_gas_gdrive_sources.json"
+SCHEMA_PATH = REPO / "shared-data/data/stellar_gas_observation/stellar_gas_observation_schema.json"
+RECEIPT_DIR = REPO / "shared-data/data/stellar_gas_observation"
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+def load_json(path: Path) -> dict:
+ return json.loads(path.read_text())
+
+
+def run(cmd: list[str], input_bytes: bytes | None = None) -> subprocess.CompletedProcess:
+ return subprocess.run(
+ cmd,
+ input=input_bytes,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ check=False,
+ )
+
+
+def rclone_available(remote: str) -> tuple[bool, str]:
+ proc = run(["rclone", "lsf", remote])
+ if proc.returncode == 0:
+ return True, proc.stdout.decode(errors="replace").strip()
+ return False, proc.stderr.decode(errors="replace").strip()
+
+
+def head_content_length(url: str, timeout: int) -> int | None:
+ req = Request(url, method="HEAD", headers={"User-Agent": "ResearchStack-StellarGasPull/0"})
+ try:
+ with urlopen(req, timeout=timeout) as response:
+ value = response.headers.get("Content-Length")
+ return int(value) if value else None
+ except Exception:
+ return None
+
+
+def fetch_bytes(url: str, timeout: int, max_bytes: int) -> tuple[bytes, str | None]:
+ req = Request(url, headers={"User-Agent": "ResearchStack-StellarGasPull/0"})
+ with urlopen(req, timeout=timeout) as response:
+ chunks: list[bytes] = []
+ total = 0
+ while True:
+ chunk = response.read(1024 * 1024)
+ if not chunk:
+ break
+ total += len(chunk)
+ if total > max_bytes:
+ raise ValueError(f"payload exceeded max_bytes={max_bytes}")
+ chunks.append(chunk)
+ content_type = response.headers.get("Content-Type")
+ return b"".join(chunks), content_type
+
+
+def rcat(remote_path: str, payload: bytes) -> tuple[bool, str]:
+ proc = run(["rclone", "rcat", remote_path], input_bytes=payload)
+ if proc.returncode == 0:
+ return True, proc.stdout.decode(errors="replace").strip()
+ return False, proc.stderr.decode(errors="replace").strip()
+
+
+def copy_local_to_drive(local_path: Path, remote_path: str) -> tuple[bool, str]:
+ proc = run(["rclone", "copyto", str(local_path), remote_path, "--checksum"])
+ if proc.returncode == 0:
+ return True, proc.stdout.decode(errors="replace").strip()
+ return False, proc.stderr.decode(errors="replace").strip()
+
+
+def pull_source(source: dict, destination: str, max_bytes: int, timeout: int, execute: bool) -> dict:
+ source_id = source["id"]
+ output_name = source["output_name"]
+ remote_path = f"{destination.rstrip('/')}/raw/{output_name}"
+ result = {
+ "id": source_id,
+ "title": source.get("title"),
+ "source_url": source["source_url"],
+ "archive": source.get("archive"),
+ "source_kind": source.get("source_kind"),
+ "model_relevance": source.get("model_relevance", []),
+ "drive_path": remote_path,
+ "retrieved_at": now_iso(),
+ "decision": "HOLD_ROUTE_ONLY",
+ "byte_count": 0,
+ "payload_sha256": None,
+ "content_type": None,
+ "notes": [],
+ }
+
+ if not source.get("pull_enabled", False):
+ result["notes"].append(source.get("route_only_reason", "pull disabled by source manifest"))
+ return result
+
+ length = head_content_length(source["source_url"], timeout)
+ result["head_content_length"] = length
+ if length is not None and length > max_bytes:
+ result["decision"] = "HOLD_OVERSIZE"
+ result["notes"].append(f"content-length {length} exceeds max_bytes {max_bytes}")
+ return result
+
+ if not execute:
+ result["decision"] = "DRY_RUN_READY"
+ result["notes"].append("execute flag not set")
+ return result
+
+ try:
+ payload, content_type = fetch_bytes(source["source_url"], timeout, max_bytes)
+ except Exception as exc:
+ result["decision"] = "QUARANTINE_FETCH_FAILED"
+ result["notes"].append(str(exc))
+ return result
+
+ digest = hashlib.sha256(payload).hexdigest()
+ ok, message = rcat(remote_path, payload)
+ result.update(
+ {
+ "byte_count": len(payload),
+ "payload_sha256": digest,
+ "content_type": content_type,
+ "rclone_message": message,
+ }
+ )
+ result["decision"] = "ADMIT_GDRIVE_PAYLOAD" if ok else "QUARANTINE_RCLONE_FAILED"
+ return result
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--sources", type=Path, default=SOURCE_PATH)
+ parser.add_argument("--schema", type=Path, default=SCHEMA_PATH)
+ parser.add_argument("--destination", default=None)
+ parser.add_argument("--max-bytes", type=int, default=None)
+ parser.add_argument("--timeout", type=int, default=45)
+ parser.add_argument("--execute", action="store_true")
+ args = parser.parse_args()
+
+ manifest = load_json(args.sources)
+ destination = args.destination or manifest["default_drive_destination"]
+ max_bytes = args.max_bytes or int(manifest.get("default_max_bytes", 20_000_000))
+ receipt_path = RECEIPT_DIR / f"stellar_gas_gdrive_pull_receipt_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+
+ remote_root = destination.split("/", 1)[0]
+ remote_ok, remote_message = rclone_available(remote_root)
+ if not remote_ok:
+ receipt = {
+ "schema": "stellar_gas_gdrive_pull_receipt_v0",
+ "created": now_iso(),
+ "destination": destination,
+ "decision": "QUARANTINE_NO_GDRIVE_REMOTE",
+ "remote_check": remote_message,
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+ print(json.dumps(receipt, indent=2))
+ return 2
+
+ results = [
+ pull_source(source, destination, max_bytes, args.timeout, args.execute)
+ for source in manifest["sources"]
+ ]
+
+ copied_control_files = []
+ if args.execute:
+ for local, name in [
+ (args.sources, "stellar_gas_gdrive_sources.json"),
+ (args.schema, "stellar_gas_observation_schema.json"),
+ ]:
+ remote_path = f"{destination.rstrip('/')}/control/{name}"
+ ok, message = copy_local_to_drive(local, remote_path)
+ copied_control_files.append(
+ {
+ "local": str(local.relative_to(REPO)),
+ "drive_path": remote_path,
+ "ok": ok,
+ "message": message,
+ }
+ )
+
+ admitted = [item for item in results if item["decision"] == "ADMIT_GDRIVE_PAYLOAD"]
+ receipt = {
+ "schema": "stellar_gas_gdrive_pull_receipt_v0",
+ "created": now_iso(),
+ "claim_boundary": "Direct-to-Google-Drive seed pull. Payloads are streamed to Drive; local repo stores only manifests and receipts. Heavy products remain route-only unless explicitly enabled.",
+ "source_manifest": str(args.sources.relative_to(REPO)),
+ "observation_schema": str(args.schema.relative_to(REPO)),
+ "destination": destination,
+ "execute": args.execute,
+ "max_bytes": max_bytes,
+ "remote_check": "PASS",
+ "control_files": copied_control_files,
+ "summary": {
+ "source_count": len(results),
+ "admitted_payload_count": len(admitted),
+ "admitted_payload_bytes": sum(item["byte_count"] for item in admitted),
+ "route_or_hold_count": len(results) - len(admitted),
+ },
+ "results": results,
+ "decision": "ADMIT_SEED_PULL_TO_GDRIVE" if args.execute else "HOLD_DRY_RUN_ONLY",
+ }
+
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+
+ if args.execute:
+ remote_receipt = f"{destination.rstrip('/')}/receipts/{receipt_path.name}"
+ ok, message = copy_local_to_drive(receipt_path, remote_receipt)
+ receipt["receipt_upload"] = {
+ "drive_path": remote_receipt,
+ "ok": ok,
+ "message": message,
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+
+ print(json.dumps(receipt, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/4-Infrastructure/shim/stellar_gas_line_ratio_diagnostics.py b/4-Infrastructure/shim/stellar_gas_line_ratio_diagnostics.py
new file mode 100644
index 00000000..e81766c2
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_line_ratio_diagnostics.py
@@ -0,0 +1,409 @@
+#!/usr/bin/env python3
+"""Compute MaNGA emission-line ratio diagnostics from DAPall arrays."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import math
+import statistics
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+REPO = Path(__file__).resolve().parents[2]
+SEED_SCRIPT = REPO / "4-Infrastructure/shim/sdss_manga_dapall_observation_seed.py"
+DATA_DIR = REPO / "shared-data/data/stellar_gas_observation"
+CHANNELS = DATA_DIR / "sdss_manga_dr17_emission_line_channels.json"
+DEFAULT_FITS = REPO / "shared-data/artifacts/stellar_gas_observation/dapall-v3_1_1-3.1.0.fits"
+DESTINATION = "Gdrive:topological_storage/research-stack/stellar-gas-observation/seed-2026-05-09"
+DOC = REPO / "6-Documentation/docs/stellar_gas_line_ratio_diagnostics_2026-05-09.md"
+
+
+TARGET_COLUMNS = [
+ "PLATEIFU",
+ "MANGAID",
+ "DAPTYPE",
+ "Z",
+ "HA_GSIGMA_1RE",
+ "HA_GSIGMA_HI_CLIP",
+ "EMLINE_GFLUX_1RE",
+ "EMLINE_GFLUX_TOT",
+ "EMLINE_GEW_1RE",
+]
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+def load_json(path: Path) -> dict:
+ return json.loads(path.read_text())
+
+
+def load_seed_module():
+ spec = importlib.util.spec_from_file_location("sdss_manga_dapall_observation_seed", SEED_SCRIPT)
+ if spec is None or spec.loader is None:
+ raise RuntimeError(f"cannot load {SEED_SCRIPT}")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def run(cmd: list[str]) -> subprocess.CompletedProcess:
+ return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+
+
+def rclone_copyto(local: Path, remote: str) -> tuple[bool, str]:
+ proc = run(["rclone", "copyto", str(local), remote, "--checksum"])
+ message = (proc.stderr or proc.stdout).decode(errors="replace").strip()
+ return proc.returncode == 0, message
+
+
+def finite(value) -> bool:
+ return isinstance(value, (int, float)) and math.isfinite(value) and value > -900
+
+
+def pos(value) -> float | None:
+ if finite(value) and value > 0:
+ return float(value)
+ return None
+
+
+def log_ratio(num: float | None, den: float | None) -> float | None:
+ if num is None or den is None or num <= 0 or den <= 0:
+ return None
+ return math.log10(num / den)
+
+
+def ratio(num: float | None, den: float | None) -> float | None:
+ if num is None or den is None or den <= 0:
+ return None
+ return num / den
+
+
+def classify_bpt(log_nii_ha: float | None, log_oiii_hb: float | None) -> str:
+ if log_nii_ha is None or log_oiii_hb is None:
+ return "unclassified"
+ # Common demarcation curves. This is a diagnostic proxy only.
+ if log_nii_ha >= 0.47:
+ return "agn_liner_or_shock_proxy"
+ kewley = 0.61 / (log_nii_ha - 0.47) + 1.19
+ kauffmann = 0.61 / (log_nii_ha - 0.05) + 1.3
+ if log_oiii_hb > kewley:
+ return "agn_liner_or_shock_proxy"
+ if log_oiii_hb > kauffmann:
+ return "composite_proxy"
+ return "star_forming_proxy"
+
+
+def classify_shock(log_sii_ha, log_oi_ha, gas_sigma):
+ score = 0.0
+ reasons = []
+ if log_sii_ha is not None and log_sii_ha > -0.4:
+ score += 0.35
+ reasons.append("elevated_sii_ha")
+ if log_oi_ha is not None and log_oi_ha > -1.1:
+ score += 0.35
+ reasons.append("elevated_oi_ha")
+ if gas_sigma is not None and gas_sigma > 120:
+ score += 0.30
+ reasons.append("broad_halpha_sigma")
+ if score >= 0.65:
+ label = "shock_lier_proxy"
+ elif score > 0:
+ label = "partial_shock_proxy"
+ else:
+ label = "no_shock_proxy"
+ return min(1.0, score), label, reasons
+
+
+def summarize(vals: list[float]) -> dict:
+ values = sorted(v for v in vals if math.isfinite(v))
+ if not values:
+ return {"count": 0}
+ return {
+ "count": len(values),
+ "min": round(values[0], 6),
+ "max": round(values[-1], 6),
+ "mean": round(statistics.fmean(values), 6),
+ "median": round(statistics.median(values), 6),
+ "p90": round(values[int(0.9 * (len(values) - 1))], 6),
+ }
+
+
+def iter_rows(fits_path: Path):
+ seed = load_seed_module()
+ with fits_path.open("rb") as f:
+ hdu_index = 0
+ while True:
+ try:
+ header, _ = seed.read_header(f)
+ except EOFError:
+ break
+ data_start = f.tell()
+ if str(header.get("XTENSION", "PRIMARY")) == "BINTABLE":
+ row_len = int(header["NAXIS1"])
+ row_count = int(header["NAXIS2"])
+ pcount = int(header.get("PCOUNT", 0))
+ columns = seed.build_columns(header)
+ by_name = {col["name"]: col for col in columns}
+ selected = [by_name[name] for name in TARGET_COLUMNS if name in by_name]
+ hdu_name = str(header.get("EXTNAME", f"HDU{hdu_index}"))
+ for row_idx in range(row_count):
+ f.seek(data_start + row_idx * row_len)
+ row = f.read(row_len)
+ fields = {}
+ for col in selected:
+ raw = row[col["offset"] : col["offset"] + col["width"]]
+ value = seed.decode_value(raw, col)
+ if isinstance(value, str):
+ value = value.replace("\u0000", "").strip()
+ fields[col["name"]] = value
+ yield hdu_index, hdu_name, row_idx, fields
+ f.seek(data_start + seed.padded_size(row_len * row_count + pcount))
+ else:
+ bitpix = int(header.get("BITPIX", 8))
+ naxis = int(header.get("NAXIS", 0))
+ if naxis == 0:
+ data_size = 0
+ else:
+ pixels = 1
+ for axis in range(1, naxis + 1):
+ pixels *= int(header.get(f"NAXIS{axis}", 0))
+ data_size = abs(bitpix) // 8 * pixels
+ f.seek(data_start + seed.padded_size(data_size))
+ hdu_index += 1
+
+
+def build_diagnostics(fits_path: Path) -> dict:
+ channel_payload = load_json(CHANNELS)
+ index = {c["label"]: c["index0"] for c in channel_payload["channels"]}
+ required = ["Ha-6564", "Hb-4862", "OIII-5008", "NII-6585", "SII-6718", "SII-6732", "OI-6302"]
+ missing = [name for name in required if name not in index]
+ if missing:
+ raise RuntimeError(f"missing channel labels: {missing}")
+
+ summaries = {
+ "log_nii_ha": [],
+ "log_sii_ha": [],
+ "log_oi_ha": [],
+ "log_oiii_hb": [],
+ "balmer_decrement": [],
+ "gas_sigma_1re_kms": [],
+ "shock_lier_score": [],
+ }
+ classes: dict[str, int] = {}
+ shock_classes: dict[str, int] = {}
+ examples = []
+ total = 0
+ valid_ratio_rows = 0
+ for hdu_index, hdu_name, row_idx, fields in iter_rows(fits_path):
+ total += 1
+ flux = fields.get("EMLINE_GFLUX_1RE")
+ if not isinstance(flux, list) or len(flux) < 35:
+ continue
+ ha = pos(flux[index["Ha-6564"]])
+ hb = pos(flux[index["Hb-4862"]])
+ oiii = pos(flux[index["OIII-5008"]])
+ nii = pos(flux[index["NII-6585"]])
+ sii = None
+ sii_1 = pos(flux[index["SII-6718"]])
+ sii_2 = pos(flux[index["SII-6732"]])
+ if sii_1 is not None and sii_2 is not None:
+ sii = sii_1 + sii_2
+ oi = pos(flux[index["OI-6302"]])
+ gas_sigma = pos(fields.get("HA_GSIGMA_1RE"))
+
+ log_nii_ha = log_ratio(nii, ha)
+ log_sii_ha = log_ratio(sii, ha)
+ log_oi_ha = log_ratio(oi, ha)
+ log_oiii_hb = log_ratio(oiii, hb)
+ balmer = ratio(ha, hb)
+ if any(v is not None for v in [log_nii_ha, log_sii_ha, log_oi_ha, log_oiii_hb]):
+ valid_ratio_rows += 1
+
+ bpt = classify_bpt(log_nii_ha, log_oiii_hb)
+ classes[bpt] = classes.get(bpt, 0) + 1
+ shock_score, shock_label, reasons = classify_shock(log_sii_ha, log_oi_ha, gas_sigma)
+ shock_classes[shock_label] = shock_classes.get(shock_label, 0) + 1
+
+ for key, value in [
+ ("log_nii_ha", log_nii_ha),
+ ("log_sii_ha", log_sii_ha),
+ ("log_oi_ha", log_oi_ha),
+ ("log_oiii_hb", log_oiii_hb),
+ ("balmer_decrement", balmer),
+ ("gas_sigma_1re_kms", gas_sigma),
+ ("shock_lier_score", shock_score),
+ ]:
+ if value is not None and math.isfinite(value):
+ summaries[key].append(float(value))
+
+ if len(examples) < 20 and shock_score >= 0.65:
+ examples.append(
+ {
+ "hdu_name": hdu_name,
+ "row_index": row_idx,
+ "plateifu": fields.get("PLATEIFU"),
+ "mangaid": fields.get("MANGAID"),
+ "z": fields.get("Z"),
+ "line_ratios": {
+ "log_NII6585_Ha": log_nii_ha,
+ "log_SII6718_6732_Ha": log_sii_ha,
+ "log_OI6302_Ha": log_oi_ha,
+ "log_OIII5008_Hb": log_oiii_hb,
+ "Ha_Hb": balmer,
+ },
+ "gas_sigma_1re_kms": gas_sigma,
+ "bpt_proxy_class": bpt,
+ "shock_lier_proxy": shock_label,
+ "shock_reasons": reasons,
+ "shock_lier_score": shock_score,
+ }
+ )
+
+ shock_fraction = (
+ (shock_classes.get("shock_lier_proxy", 0) + 0.5 * shock_classes.get("partial_shock_proxy", 0))
+ / total
+ if total
+ else 0.0
+ )
+ return {
+ "schema": "stellar_gas_line_ratio_diagnostics_v0",
+ "created": now_iso(),
+ "claim_boundary": "Line-ratio diagnostics from MaNGA DAPall integrated Gaussian flux arrays. These are proxy classifications; they do not prove a physical shock, AGN, or ionization mechanism.",
+ "source_fits": str(fits_path.relative_to(REPO)) if fits_path.is_relative_to(REPO) else str(fits_path),
+ "channel_map": str(CHANNELS.relative_to(REPO)),
+ "rows_seen": total,
+ "valid_ratio_rows": valid_ratio_rows,
+ "bpt_proxy_classes": classes,
+ "shock_lier_proxy_classes": shock_classes,
+ "aggregate_ratios": {k: summarize(v) for k, v in summaries.items()},
+ "shock_lier_support": {
+ "fractional_proxy_support": round(shock_fraction, 6),
+ "gate": "ADMIT_LINE_RATIO_SHOCK_PROXY_SUPPORT" if shock_fraction > 0 else "HOLD_NO_LINE_RATIO_SUPPORT",
+ },
+ "example_shock_lier_rows": examples,
+ "model_refinement": {
+ "saha_ionization": "line ratios now present; still HOLD for electron density and temperature",
+ "radiative_transfer": "Balmer decrement and flux lanes now named; still HOLD for attenuation model",
+ "shock_excitation": "SII/Ha, OI/Ha, OIII/Hb, NII/Ha, and H-alpha sigma now form a proxy gate",
+ },
+ "decision": "ADMIT_LINE_RATIO_DIAGNOSTIC_SURFACE",
+ }
+
+
+def write_doc(result: dict, path: Path) -> None:
+ support = result["shock_lier_support"]
+ agg = result["aggregate_ratios"]
+ lines = [
+ "# Stellar Gas Line Ratio Diagnostics",
+ "",
+ "**Date:** 2026-05-09",
+ "",
+ f"**Decision:** `{result['decision']}`",
+ "",
+ "**Claim boundary:** line-ratio proxy only. This does not prove a",
+ "physical shock, AGN, stellar breakout, or ionization mechanism.",
+ "",
+ "## What Changed",
+ "",
+ "The 35-element MaNGA emission-line arrays now have named channels, so",
+ "physics can propagate through line ratios instead of anonymous vector",
+ "positions.",
+ "",
+ "```text",
+ f"rows seen: {result['rows_seen']}",
+ f"valid ratio rows: {result['valid_ratio_rows']}",
+ f"shock proxy support: {support['fractional_proxy_support']}",
+ f"shock proxy gate: {support['gate']}",
+ "```",
+ "",
+ "## Aggregate Ratios",
+ "",
+ "| Ratio | Count | Mean | Median | P90 |",
+ "|---|---:|---:|---:|---:|",
+ ]
+ for key in [
+ "log_nii_ha",
+ "log_sii_ha",
+ "log_oi_ha",
+ "log_oiii_hb",
+ "balmer_decrement",
+ "gas_sigma_1re_kms",
+ "shock_lier_score",
+ ]:
+ s = agg[key]
+ lines.append(
+ f"| `{key}` | {s.get('count', 0)} | {s.get('mean', '')} | "
+ f"{s.get('median', '')} | {s.get('p90', '')} |"
+ )
+ lines += [
+ "",
+ "## Proxy Classes",
+ "",
+ "```json",
+ json.dumps(
+ {
+ "bpt_proxy_classes": result["bpt_proxy_classes"],
+ "shock_lier_proxy_classes": result["shock_lier_proxy_classes"],
+ },
+ indent=2,
+ ),
+ "```",
+ "",
+ "## Physics Propagation",
+ "",
+ "- Saha/ionization now has line-ratio support, but still needs electron density and temperature.",
+ "- Radiative transfer now has named flux and Balmer-decrement lanes, but still needs an attenuation model.",
+ "- Shock excitation now has SII/Ha, OI/Ha, OIII/Hb, NII/Ha, and H-alpha sigma proxy support.",
+ "",
+ ]
+ path.write_text("\n".join(lines))
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--fits", type=Path, default=DEFAULT_FITS)
+ parser.add_argument("--destination", default=DESTINATION)
+ args = parser.parse_args()
+ result = build_diagnostics(args.fits)
+ out = DATA_DIR / "stellar_gas_line_ratio_diagnostics.json"
+ out.write_text(json.dumps(result, indent=2) + "\n")
+ write_doc(result, DOC)
+
+ receipt_path = DATA_DIR / f"stellar_gas_line_ratio_diagnostics_receipt_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+ receipt = {
+ "schema": "stellar_gas_line_ratio_diagnostics_receipt_v0",
+ "created": now_iso(),
+ "claim_boundary": result["claim_boundary"],
+ "channel_map": str(CHANNELS.relative_to(REPO)),
+ "diagnostics_file": str(out.relative_to(REPO)),
+ "doc_file": str(DOC.relative_to(REPO)),
+ "decision": result["decision"],
+ "shock_lier_support": result["shock_lier_support"],
+ "uploads": {},
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+ uploads = {
+ "channel_map": (CHANNELS, f"{args.destination}/derived/{CHANNELS.name}"),
+ "diagnostics": (out, f"{args.destination}/derived/{out.name}"),
+ "doc": (DOC, f"{args.destination}/docs/{DOC.name}"),
+ "receipt": (receipt_path, f"{args.destination}/receipts/{receipt_path.name}"),
+ }
+ for key, (local, remote) in uploads.items():
+ ok, message = rclone_copyto(local, remote)
+ receipt["uploads"][key] = {"drive_path": remote, "ok": ok, "message": message}
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+ if receipt["uploads"]["receipt"]["ok"]:
+ rclone_copyto(receipt_path, receipt["uploads"]["receipt"]["drive_path"])
+ print(json.dumps(receipt, indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/4-Infrastructure/shim/stellar_gas_multiscale_eigenmass_alignment.py b/4-Infrastructure/shim/stellar_gas_multiscale_eigenmass_alignment.py
new file mode 100644
index 00000000..7597990c
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_multiscale_eigenmass_alignment.py
@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""Compare row-level DESI eigenmass with DESI/MaNGA joined-cell eigenmass.
+
+This probe measures whether the SMN/evidence-load direction survives the zoom
+from the literal DESI row surface into the gas/shock-constrained MaNGA overlap
+surface. It reports a tracer-subspace cosine alignment and a sharpening factor.
+
+Boundary: this is an evidence-geometry comparison. It is not physical mass, not
+stellar mass, not a gas-density map, and not a cosmology fit.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[2]
+ROW_JSON = ROOT / "shared-data/data/stellar_gas_observation/desi_epoviz_row_eigenmass_probe.json"
+CELL_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_eigenvector_mass_probe.json"
+OUT_DIR = ROOT / "shared-data/data/stellar_gas_observation"
+DOCS_DIR = ROOT / "6-Documentation/docs"
+TIDDLER_DIR = ROOT / "6-Documentation/tiddlywiki-local/wiki/tiddlers"
+
+OUT_JSON = OUT_DIR / "stellar_gas_multiscale_eigenmass_alignment.json"
+RECEIPT_JSON = OUT_DIR / "stellar_gas_multiscale_eigenmass_alignment_receipt.json"
+DOC_MD = DOCS_DIR / "stellar_gas_multiscale_eigenmass_alignment_2026-05-09.md"
+TIDDLER = TIDDLER_DIR / "Stellar Gas Multiscale Eigenmass Alignment.tid"
+
+
+TRACER_ORDER = ["QSO", "ELG", "LRG", "BGS"]
+
+
+def dot(a: list[float], b: list[float]) -> float:
+ return sum(x * y for x, y in zip(a, b))
+
+
+def norm(v: list[float]) -> float:
+ return math.sqrt(dot(v, v))
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+ denom = norm(a) * norm(b)
+ if denom == 0:
+ return 0.0
+ return dot(a, b) / denom
+
+
+def round9(x: float) -> float:
+ return round(x, 9)
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ with path.open() as f:
+ return json.load(f)
+
+
+def tracer_vector_from_row(row: dict[str, float]) -> list[float]:
+ return [
+ row["tracer_QSO"],
+ row["tracer_ELG"],
+ row["tracer_LRG"],
+ row["tracer_BGS"],
+ ]
+
+
+def tracer_vector_from_cell(cell: dict[str, float]) -> list[float]:
+ return [
+ cell["QSO_share"],
+ cell["ELG_share"],
+ cell["LRG_share"],
+ cell["BGS_share"],
+ ]
+
+
+def classify_alignment(value: float) -> str:
+ if value >= 0.85:
+ return "STRONG_ALIGNMENT"
+ if value >= 0.65:
+ return "MODERATE_ALIGNMENT"
+ if value >= 0.35:
+ return "WEAK_ALIGNMENT"
+ if value > -0.35:
+ return "ORTHOGONAL_OR_MIXED"
+ return "ANTI_ALIGNMENT"
+
+
+def build() -> tuple[dict[str, Any], dict[str, Any]]:
+ row = load_json(ROW_JSON)
+ cell = load_json(CELL_JSON)
+ row_vec = tracer_vector_from_row(row["dominant_eigenvector"])
+ cell_vec = tracer_vector_from_cell(cell["dominant_eigenvector"])
+ tracer_alignment = cosine(row_vec, cell_vec)
+
+ row_share = float(row["dominant_explained_mass_share"])
+ cell_share = float(cell["dominant_explained_mass_share"])
+ sharpening_factor = cell_share / row_share if row_share else 0.0
+ eigenvalue_ratio = float(cell["dominant_eigenvalue"]) / float(row["dominant_eigenvalue"])
+
+ created = datetime.now(timezone.utc).isoformat(timespec="seconds")
+ result = {
+ "schema": "stellar_gas_multiscale_eigenmass_alignment_v0",
+ "created": created,
+ "decision": "ADMIT_MULTISCALE_EIGENMASS_ALIGNMENT_HOLD_PHYSICAL_MASS",
+ "claim_boundary": (
+ "Compares SMN/evidence-load eigenvectors across DESI row level and "
+ "DESI/MaNGA joined-cell level. It does not infer physical mass, "
+ "stellar mass, gas density, or cosmology."
+ ),
+ "sources": {
+ "row_eigenmass": str(ROW_JSON.relative_to(ROOT)),
+ "cell_eigenmass": str(CELL_JSON.relative_to(ROOT)),
+ },
+ "row_level": {
+ "cell_or_row_count": row["row_count"],
+ "dominant_eigenvalue": row["dominant_eigenvalue"],
+ "dominant_explained_mass_share": row_share,
+ "tracer_subvector_order": TRACER_ORDER,
+ "tracer_subvector": [round9(x) for x in row_vec],
+ },
+ "cell_level": {
+ "cell_or_row_count": cell["cell_count"],
+ "dominant_eigenvalue": cell["dominant_eigenvalue"],
+ "dominant_explained_mass_share": cell_share,
+ "tracer_subvector_order": TRACER_ORDER,
+ "tracer_subvector": [round9(x) for x in cell_vec],
+ },
+ "alignment": {
+ "tracer_subspace_cosine": round9(tracer_alignment),
+ "alignment_class": classify_alignment(tracer_alignment),
+ "constraint_sharpening_factor": round9(sharpening_factor),
+ "dominant_eigenvalue_ratio_cell_over_row": round9(eigenvalue_ratio),
+ "interpretation": (
+ "The cell-level explained share is larger than the row-level share "
+ "under this diagnostic ratio. This is an accounting comparison, not "
+ "a causal gas/shock mechanism."
+ ),
+ },
+ "holds": [
+ "HOLD_PHYSICAL_MASS_INTERPRETATION",
+ "HOLD_DIRECT_GAS_DENSITY_INFERENCE",
+ "HOLD_OBJECT_LEVEL_CROSSMATCH",
+ "HOLD_SELECTION_FUNCTION_FIT",
+ "HOLD_COSMOLOGY_FIT",
+ ],
+ }
+ receipt = {
+ "receipt_type": "stellar_gas_multiscale_eigenmass_alignment_receipt",
+ "created": created,
+ "row_rows": row["row_count"],
+ "cell_count": cell["cell_count"],
+ "tracer_subspace_cosine": result["alignment"]["tracer_subspace_cosine"],
+ "constraint_sharpening_factor": result["alignment"]["constraint_sharpening_factor"],
+ "decision": result["decision"],
+ "validated_outputs": [
+ str(OUT_JSON.relative_to(ROOT)),
+ str(DOC_MD.relative_to(ROOT)),
+ str(TIDDLER.relative_to(ROOT)),
+ ],
+ }
+ return result, receipt
+
+
+def write_docs(result: dict[str, Any]) -> None:
+ align = result["alignment"]
+ row = result["row_level"]
+ cell = result["cell_level"]
+ holds = "\n".join(f"- `{hold}`" for hold in result["holds"])
+ tracer_lines = "\n".join(
+ f"- `{name}`: row `{row['tracer_subvector'][i]}`, cell `{cell['tracer_subvector'][i]}`"
+ for i, name in enumerate(TRACER_ORDER)
+ )
+
+ DOC_MD.write_text(
+ f"""# Stellar Gas Multiscale Eigenmass Alignment
+
+Status: `MULTISCALE_EIGENMASS_ALIGNMENT`
+
+Decision: `{result['decision']}`
+
+This probe compares the row-level DESI epoviz eigenmass with the DESI/MaNGA
+joined-cell eigenmass. It reports a tracer-subspace cosine and explained-share
+ratio between the literal row data and the coarse joined-cell overlap surface.
+
+Claim boundary: this is not physical mass, not stellar mass, not gas-density
+inference, and not a cosmology fit.
+
+## Alignment Result
+
+Tracer-subspace cosine:
+
+```text
+{align['tracer_subspace_cosine']}
+```
+
+Alignment class:
+
+```text
+{align['alignment_class']}
+```
+
+Constraint sharpening factor:
+
+```text
+{align['constraint_sharpening_factor']}
+```
+
+Dominant eigenvalue ratio, cell over row:
+
+```text
+{align['dominant_eigenvalue_ratio_cell_over_row']}
+```
+
+## Tracer Subvectors
+
+{tracer_lines}
+
+## Scale Comparison
+
+```text
+row level rows: {row['cell_or_row_count']}
+row explained share: {row['dominant_explained_mass_share']}
+cell level cells: {cell['cell_or_row_count']}
+cell explained share: {cell['dominant_explained_mass_share']}
+```
+
+## Holds
+
+{holds}
+""",
+ encoding="utf-8",
+ )
+
+ TIDDLER.write_text(
+ f"""title: Stellar Gas Multiscale Eigenmass Alignment
+tags: StellarGasObservation DESI MaNGA SemanticMassNumbers Eigenvector Receipts
+type: text/vnd.tiddlywiki
+
+Status: <>
+
+Decision: `{result['decision']}`
+
+This tiddler compares the row-level DESI epoviz eigenmass with the DESI/MaNGA
+joined-cell eigenmass.
+
+Tracer-subspace cosine:
+
+```
+{align['tracer_subspace_cosine']}
+```
+
+Alignment class:
+
+```
+{align['alignment_class']}
+```
+
+Constraint sharpening factor:
+
+```
+{align['constraint_sharpening_factor']}
+```
+
+!! Tracer Subvectors
+
+{tracer_lines}
+
+!! Boundary
+
+This is SMN/evidence-load alignment, not physical mass or cosmology inference.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ result, receipt = build()
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ DOCS_DIR.mkdir(parents=True, exist_ok=True)
+ TIDDLER_DIR.mkdir(parents=True, exist_ok=True)
+ OUT_JSON.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT_JSON.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_docs(result)
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stellar_gas_population_grouping_study.py b/4-Infrastructure/shim/stellar_gas_population_grouping_study.py
new file mode 100644
index 00000000..f9134f88
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_population_grouping_study.py
@@ -0,0 +1,620 @@
+#!/usr/bin/env python3
+"""Population study for MaNGA stellar-gas groupings.
+
+This is the first local population layer for the DESI -> environment prior ->
+stellar-gas distribution bridge. It groups MaNGA DAPall galaxies by redshift,
+sky cell, BPT proxy, shock/LIER proxy, gas sigma, and stellar sigma. DESI is
+kept as a join target only: no direct DESI gas-map claim is made here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import math
+import statistics
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SEED_SCRIPT = REPO / "4-Infrastructure/shim/sdss_manga_dapall_observation_seed.py"
+DATA_DIR = REPO / "shared-data/data/stellar_gas_observation"
+CHANNELS = DATA_DIR / "sdss_manga_dr17_emission_line_channels.json"
+DEFAULT_FITS = REPO / "shared-data/artifacts/stellar_gas_observation/dapall-v3_1_1-3.1.0.fits"
+DESTINATION = "Gdrive:topological_storage/research-stack/stellar-gas-observation/seed-2026-05-09"
+
+OUT = DATA_DIR / "stellar_gas_population_grouping_study.json"
+DOC = REPO / "6-Documentation/docs/stellar_gas_population_grouping_study_2026-05-09.md"
+TIDDLER = REPO / "6-Documentation/tiddlywiki-local/wiki/tiddlers/Stellar Gas Population Grouping Study.tid"
+
+PREFERRED_DAPTYPE = "HYB10-MILESHC-MASTARSSP"
+
+TARGET_COLUMNS = [
+ "PLATEIFU",
+ "MANGAID",
+ "DAPTYPE",
+ "OBJRA",
+ "OBJDEC",
+ "Z",
+ "BINSNR",
+ "SNR_MED",
+ "STELLAR_SIGMA_1RE",
+ "HA_GSIGMA_1RE",
+ "EMLINE_GFLUX_1RE",
+]
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+def load_seed_module():
+ spec = importlib.util.spec_from_file_location("sdss_manga_dapall_observation_seed", SEED_SCRIPT)
+ if spec is None or spec.loader is None:
+ raise RuntimeError(f"cannot load {SEED_SCRIPT}")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def load_channels() -> dict[str, int]:
+ payload = json.loads(CHANNELS.read_text(encoding="utf-8"))
+ return {row["label"]: row["index0"] for row in payload["channels"]}
+
+
+def run(cmd: list[str]) -> subprocess.CompletedProcess:
+ return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+
+
+def rclone_copyto(local: Path, remote: str) -> tuple[bool, str]:
+ proc = run(["rclone", "copyto", str(local), remote, "--checksum"])
+ message = (proc.stderr or proc.stdout).decode(errors="replace").strip()
+ return proc.returncode == 0, message
+
+
+def finite(value: Any) -> bool:
+ return isinstance(value, (int, float)) and math.isfinite(value) and value > -900
+
+
+def pos(value: Any) -> float | None:
+ if finite(value) and value > 0:
+ return float(value)
+ return None
+
+
+def scalar(value: Any) -> float | None:
+ if finite(value):
+ return float(value)
+ return None
+
+
+def mean_list(value: Any) -> float | None:
+ if not isinstance(value, list):
+ return None
+ vals = [float(v) for v in value if finite(v)]
+ return statistics.fmean(vals) if vals else None
+
+
+def log_ratio(num: float | None, den: float | None) -> float | None:
+ if num is None or den is None or num <= 0 or den <= 0:
+ return None
+ return math.log10(num / den)
+
+
+def ratio(num: float | None, den: float | None) -> float | None:
+ if num is None or den is None or den <= 0:
+ return None
+ return num / den
+
+
+def classify_bpt(log_nii_ha: float | None, log_oiii_hb: float | None) -> str:
+ if log_nii_ha is None or log_oiii_hb is None:
+ return "unclassified"
+ if log_nii_ha >= 0.47:
+ return "agn_liner_or_shock_proxy"
+ kewley = 0.61 / (log_nii_ha - 0.47) + 1.19
+ kauffmann = 0.61 / (log_nii_ha - 0.05) + 1.3
+ if log_oiii_hb > kewley:
+ return "agn_liner_or_shock_proxy"
+ if log_oiii_hb > kauffmann:
+ return "composite_proxy"
+ return "star_forming_proxy"
+
+
+def classify_shock(log_sii_ha: float | None, log_oi_ha: float | None, gas_sigma: float | None) -> tuple[float, str]:
+ score = 0.0
+ if log_sii_ha is not None and log_sii_ha > -0.4:
+ score += 0.35
+ if log_oi_ha is not None and log_oi_ha > -1.1:
+ score += 0.35
+ if gas_sigma is not None and gas_sigma > 120:
+ score += 0.30
+ if score >= 0.65:
+ return min(1.0, score), "shock_lier_proxy"
+ if score > 0:
+ return score, "partial_shock_proxy"
+ return 0.0, "no_shock_proxy"
+
+
+def z_bin(z: float | None) -> str:
+ if z is None:
+ return "z_missing"
+ if z < 0.02:
+ return "z_000_002"
+ if z < 0.04:
+ return "z_002_004"
+ if z < 0.06:
+ return "z_004_006"
+ if z < 0.08:
+ return "z_006_008"
+ return "z_008_plus"
+
+
+def sigma_bin(value: float | None, prefix: str) -> str:
+ if value is None:
+ return f"{prefix}_missing"
+ if value < 50:
+ return f"{prefix}_000_050"
+ if value < 100:
+ return f"{prefix}_050_100"
+ if value < 150:
+ return f"{prefix}_100_150"
+ if value < 250:
+ return f"{prefix}_150_250"
+ return f"{prefix}_250_plus"
+
+
+def sky_bin(ra: float | None, dec: float | None) -> str:
+ if ra is None or dec is None:
+ return "sky_missing"
+ ra_bin = int(max(0, min(5, math.floor((ra % 360.0) / 60.0))))
+ dec_band = "south" if dec < 0 else "north"
+ return f"ra{ra_bin:02d}_{dec_band}"
+
+
+def sky_z_cell(ra: float | None, dec: float | None, z: float | None) -> str:
+ return f"{sky_bin(ra, dec)}__{z_bin(z)}"
+
+
+def summarize(vals: list[float]) -> dict[str, Any]:
+ values = sorted(v for v in vals if math.isfinite(v))
+ if not values:
+ return {"count": 0}
+ return {
+ "count": len(values),
+ "min": round(values[0], 6),
+ "max": round(values[-1], 6),
+ "mean": round(statistics.fmean(values), 6),
+ "median": round(statistics.median(values), 6),
+ "p90": round(values[int(0.9 * (len(values) - 1))], 6),
+ }
+
+
+def iter_rows(fits_path: Path):
+ seed = load_seed_module()
+ with fits_path.open("rb") as f:
+ hdu_index = 0
+ while True:
+ try:
+ header, _ = seed.read_header(f)
+ except EOFError:
+ break
+ data_start = f.tell()
+ if str(header.get("XTENSION", "PRIMARY")) == "BINTABLE":
+ row_len = int(header["NAXIS1"])
+ row_count = int(header["NAXIS2"])
+ pcount = int(header.get("PCOUNT", 0))
+ columns = seed.build_columns(header)
+ by_name = {col["name"]: col for col in columns}
+ selected = [by_name[name] for name in TARGET_COLUMNS if name in by_name]
+ hdu_name = str(header.get("EXTNAME", f"HDU{hdu_index}"))
+ for row_idx in range(row_count):
+ f.seek(data_start + row_idx * row_len)
+ row = f.read(row_len)
+ fields: dict[str, Any] = {}
+ for col in selected:
+ raw = row[col["offset"] : col["offset"] + col["width"]]
+ value = seed.decode_value(raw, col)
+ if isinstance(value, str):
+ value = value.replace("\u0000", "").strip()
+ fields[col["name"]] = value
+ yield hdu_index, hdu_name, row_idx, fields
+ f.seek(data_start + seed.padded_size(row_len * row_count + pcount))
+ else:
+ bitpix = int(header.get("BITPIX", 8))
+ naxis = int(header.get("NAXIS", 0))
+ data_size = 0
+ if naxis:
+ pixels = 1
+ for axis in range(1, naxis + 1):
+ pixels *= int(header.get(f"NAXIS{axis}", 0))
+ data_size = abs(bitpix) // 8 * pixels
+ f.seek(data_start + seed.padded_size(data_size))
+ hdu_index += 1
+
+
+def add_count(bucket: dict[str, int], key: str) -> None:
+ bucket[key] = bucket.get(key, 0) + 1
+
+
+def group_template() -> dict[str, Any]:
+ return {
+ "count": 0,
+ "bpt_proxy_classes": {},
+ "shock_lier_proxy_classes": {},
+ "z_bins": {},
+ "gas_sigma_bins": {},
+ "stellar_sigma_bins": {},
+ "sky_bins": {},
+ "shock_scores": [],
+ "gas_sigma_values": [],
+ "stellar_sigma_values": [],
+ "snr_values": [],
+ }
+
+
+def update_group(group: dict[str, Any], row: dict[str, Any]) -> None:
+ group["count"] += 1
+ add_count(group["bpt_proxy_classes"], row["bpt_proxy_class"])
+ add_count(group["shock_lier_proxy_classes"], row["shock_lier_proxy_class"])
+ add_count(group["z_bins"], row["z_bin"])
+ add_count(group["gas_sigma_bins"], row["gas_sigma_bin"])
+ add_count(group["stellar_sigma_bins"], row["stellar_sigma_bin"])
+ add_count(group["sky_bins"], row["sky_bin"])
+ group["shock_scores"].append(row["shock_lier_score"])
+ if row["gas_sigma_1re_kms"] is not None:
+ group["gas_sigma_values"].append(row["gas_sigma_1re_kms"])
+ if row["stellar_sigma_1re_kms"] is not None:
+ group["stellar_sigma_values"].append(row["stellar_sigma_1re_kms"])
+ if row["snr_mean"] is not None:
+ group["snr_values"].append(row["snr_mean"])
+
+
+def finalize_group(group: dict[str, Any]) -> dict[str, Any]:
+ count = group["count"] or 1
+ shock = group["shock_lier_proxy_classes"]
+ group["shock_lier_fraction"] = round(shock.get("shock_lier_proxy", 0) / count, 6)
+ group["partial_or_full_shock_fraction"] = round(
+ (shock.get("shock_lier_proxy", 0) + shock.get("partial_shock_proxy", 0)) / count,
+ 6,
+ )
+ group["shock_score_summary"] = summarize(group.pop("shock_scores"))
+ group["gas_sigma_summary"] = summarize(group.pop("gas_sigma_values"))
+ group["stellar_sigma_summary"] = summarize(group.pop("stellar_sigma_values"))
+ group["snr_summary"] = summarize(group.pop("snr_values"))
+ return group
+
+
+def row_payload(fields: dict[str, Any], channel_index: dict[str, int]) -> dict[str, Any] | None:
+ flux = fields.get("EMLINE_GFLUX_1RE")
+ if not isinstance(flux, list) or len(flux) < 35:
+ return None
+ ha = pos(flux[channel_index["Ha-6564"]])
+ hb = pos(flux[channel_index["Hb-4862"]])
+ oiii = pos(flux[channel_index["OIII-5008"]])
+ nii = pos(flux[channel_index["NII-6585"]])
+ sii_1 = pos(flux[channel_index["SII-6718"]])
+ sii_2 = pos(flux[channel_index["SII-6732"]])
+ sii = sii_1 + sii_2 if sii_1 is not None and sii_2 is not None else None
+ oi = pos(flux[channel_index["OI-6302"]])
+ gas_sigma = pos(fields.get("HA_GSIGMA_1RE"))
+ stellar_sigma = pos(fields.get("STELLAR_SIGMA_1RE"))
+ z = scalar(fields.get("Z"))
+ ra = scalar(fields.get("OBJRA"))
+ dec = scalar(fields.get("OBJDEC"))
+ log_nii_ha = log_ratio(nii, ha)
+ log_sii_ha = log_ratio(sii, ha)
+ log_oi_ha = log_ratio(oi, ha)
+ log_oiii_hb = log_ratio(oiii, hb)
+ balmer = ratio(ha, hb)
+ shock_score, shock_class = classify_shock(log_sii_ha, log_oi_ha, gas_sigma)
+ bpt = classify_bpt(log_nii_ha, log_oiii_hb)
+ return {
+ "plateifu": fields.get("PLATEIFU"),
+ "mangaid": fields.get("MANGAID"),
+ "daptype": fields.get("DAPTYPE"),
+ "ra": ra,
+ "dec": dec,
+ "z": z,
+ "z_bin": z_bin(z),
+ "sky_bin": sky_bin(ra, dec),
+ "sky_z_cell": sky_z_cell(ra, dec, z),
+ "snr_mean": mean_list(fields.get("SNR_MED")) or scalar(fields.get("BINSNR")),
+ "gas_sigma_1re_kms": gas_sigma,
+ "stellar_sigma_1re_kms": stellar_sigma,
+ "gas_sigma_bin": sigma_bin(gas_sigma, "gas_sigma"),
+ "stellar_sigma_bin": sigma_bin(stellar_sigma, "stellar_sigma"),
+ "line_ratios": {
+ "log_NII6585_Ha": log_nii_ha,
+ "log_SII6718_6732_Ha": log_sii_ha,
+ "log_OI6302_Ha": log_oi_ha,
+ "log_OIII5008_Hb": log_oiii_hb,
+ "Ha_Hb": balmer,
+ },
+ "bpt_proxy_class": bpt,
+ "shock_lier_proxy_class": shock_class,
+ "shock_lier_score": shock_score,
+ }
+
+
+def build_population_study(fits_path: Path, preferred_daptype: str) -> dict[str, Any]:
+ channel_index = load_channels()
+ required = ["Ha-6564", "Hb-4862", "OIII-5008", "NII-6585", "SII-6718", "SII-6732", "OI-6302"]
+ missing = [name for name in required if name not in channel_index]
+ if missing:
+ raise RuntimeError(f"missing channel labels: {missing}")
+
+ all_rows = 0
+ selected_rows: list[dict[str, Any]] = []
+ by_plateifu: dict[str, dict[str, Any]] = {}
+ daptype_counts: dict[str, int] = {}
+ for _, _, _, fields in iter_rows(fits_path):
+ all_rows += 1
+ payload = row_payload(fields, channel_index)
+ if not payload:
+ continue
+ daptype = str(payload.get("daptype") or "unknown")
+ add_count(daptype_counts, daptype)
+ plateifu = str(payload.get("plateifu") or "")
+ current = by_plateifu.get(plateifu)
+ if current is None or daptype == preferred_daptype:
+ by_plateifu[plateifu] = payload
+
+ selected_rows = list(by_plateifu.values())
+ groups = {
+ "by_bpt_proxy_class": {},
+ "by_shock_lier_proxy_class": {},
+ "by_redshift_bin": {},
+ "by_sky_bin": {},
+ "by_sky_z_cell": {},
+ "by_gas_sigma_bin": {},
+ "by_stellar_sigma_bin": {},
+ }
+ aggregate = group_template()
+ for row in selected_rows:
+ update_group(aggregate, row)
+ for group_name, key_name in [
+ ("by_bpt_proxy_class", "bpt_proxy_class"),
+ ("by_shock_lier_proxy_class", "shock_lier_proxy_class"),
+ ("by_redshift_bin", "z_bin"),
+ ("by_sky_bin", "sky_bin"),
+ ("by_sky_z_cell", "sky_z_cell"),
+ ("by_gas_sigma_bin", "gas_sigma_bin"),
+ ("by_stellar_sigma_bin", "stellar_sigma_bin"),
+ ]:
+ key = row[key_name]
+ groups[group_name].setdefault(key, group_template())
+ update_group(groups[group_name][key], row)
+
+ finalized_groups = {
+ group_name: {
+ key: finalize_group(value)
+ for key, value in sorted(group.items(), key=lambda item: (-item[1]["count"], item[0]))
+ }
+ for group_name, group in groups.items()
+ }
+ top_cells = [
+ {"cell": key, **value}
+ for key, value in list(finalized_groups["by_sky_z_cell"].items())[:20]
+ ]
+ examples = sorted(
+ selected_rows,
+ key=lambda row: (row["shock_lier_score"], row["gas_sigma_1re_kms"] or 0.0),
+ reverse=True,
+ )[:20]
+ return {
+ "schema": "stellar_gas_population_grouping_study_v1",
+ "created": now_iso(),
+ "decision": "ADMIT_POPULATION_GROUPING_SURFACE",
+ "claim_boundary": "MaNGA stellar-gas population grouping only. A coarse DESI/MaNGA cell join exists; object-level crossmatch remains HOLD. Proxy classes do not prove physical shock, AGN, or gas mechanism.",
+ "source_fits": str(fits_path.relative_to(REPO)) if fits_path.is_relative_to(REPO) else str(fits_path),
+ "channel_map": str(CHANNELS.relative_to(REPO)),
+ "preferred_daptype": preferred_daptype,
+ "rows_seen_all_daptypes": all_rows,
+ "daptype_counts": daptype_counts,
+ "unique_plateifu_count": len(by_plateifu),
+ "selected_population_count": len(selected_rows),
+ "aggregate": finalize_group(aggregate),
+ "groups": finalized_groups,
+ "top_sky_z_cells_for_desi_join": top_cells,
+ "top_shock_lier_examples": examples,
+ "desi_bridge": {
+ "status": "COARSE_CELL_JOIN_EXISTS_OBJECT_CROSSMATCH_HOLD",
+ "source_prior": "shared-data/data/stack_solidification/desi_stellar_gas_distribution_prior.json",
+ "join_key_shape": "coarse sky/redshift population cell; object-level cone/crossmatch remains HOLD",
+ "required_fields": ["ra", "dec", "z", "tracer_type", "selection_flags"],
+ },
+ }
+
+
+def write_doc(result: dict[str, Any]) -> None:
+ agg = result["aggregate"]
+ groups = result["groups"]
+ lines = [
+ "# Stellar Gas Population Grouping Study",
+ "",
+ "**Date:** 2026-05-09",
+ "",
+ f"**Decision:** `{result['decision']}`",
+ "",
+ "**Claim boundary:** MaNGA stellar-gas population grouping only. DESI",
+ "environment inference remains a prior bridge until a DESI-MaNGA join",
+ "receipt exists. Proxy classes do not prove physical shock, AGN, or gas",
+ "mechanism.",
+ "",
+ "## Population Surface",
+ "",
+ "```text",
+ f"rows seen, all DAP types: {result['rows_seen_all_daptypes']}",
+ f"unique Plate-IFU count: {result['unique_plateifu_count']}",
+ f"selected population: {result['selected_population_count']}",
+ f"preferred DAPTYPE: {result['preferred_daptype']}",
+ "```",
+ "",
+ "## Aggregate",
+ "",
+ "```json",
+ json.dumps(
+ {
+ "bpt_proxy_classes": agg["bpt_proxy_classes"],
+ "shock_lier_proxy_classes": agg["shock_lier_proxy_classes"],
+ "partial_or_full_shock_fraction": agg["partial_or_full_shock_fraction"],
+ "gas_sigma_summary": agg["gas_sigma_summary"],
+ "stellar_sigma_summary": agg["stellar_sigma_summary"],
+ },
+ indent=2,
+ ),
+ "```",
+ "",
+ "## Redshift Bins",
+ "",
+ "| Bin | Count | Shock+Partial Fraction | Gas Sigma Median | Stellar Sigma Median |",
+ "|---|---:|---:|---:|---:|",
+ ]
+ for key, value in groups["by_redshift_bin"].items():
+ lines.append(
+ f"| `{key}` | {value['count']} | {value['partial_or_full_shock_fraction']} | "
+ f"{value['gas_sigma_summary'].get('median', '')} | {value['stellar_sigma_summary'].get('median', '')} |"
+ )
+ lines += [
+ "",
+ "## DESI-Ready Sky/Redshift Cells",
+ "",
+ "These are population cells for a later DESI join. They are not DESI",
+ "environment classes yet.",
+ "",
+ "| Cell | Count | Shock+Partial Fraction | Main BPT Counts |",
+ "|---|---:|---:|---|",
+ ]
+ for row in result["top_sky_z_cells_for_desi_join"][:12]:
+ lines.append(
+ f"| `{row['cell']}` | {row['count']} | {row['partial_or_full_shock_fraction']} | "
+ f"`{row['bpt_proxy_classes']}` |"
+ )
+ lines += [
+ "",
+ "## What This Gives Us",
+ "",
+ "- A population baseline over unique MaNGA Plate-IFU rows.",
+ "- Grouped shock/LIER and BPT proxy counts by redshift and sky cell.",
+ "- DESI-ready cells for a future sky-cone plus redshift-window join.",
+ "- Residual target: cells whose local gas state diverges from later DESI environment priors.",
+ "",
+ "## Receipt",
+ "",
+ "`shared-data/data/stellar_gas_observation/stellar_gas_population_grouping_study_receipt_*.json`",
+ "",
+ ]
+ DOC.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def write_tiddler(result: dict[str, Any]) -> None:
+ agg = result["aggregate"]
+ TIDDLER.write_text(
+ f"""created: 20260509224000000
+modified: 20260509224000000
+tags: ResearchStack StellarGas MaNGA PopulationStudy DESI Calibration
+title: Stellar Gas Population Grouping Study
+type: text/vnd.tiddlywiki
+
+! Stellar Gas Population Grouping Study
+
+Status: `ADMIT_POPULATION_GROUPING_SURFACE`
+
+This page records the first local population grouping pass over MaNGA DAPall
+stellar-gas diagnostics.
+
+```text
+unique Plate-IFU count: {result['unique_plateifu_count']}
+selected population: {result['selected_population_count']}
+preferred DAPTYPE: {result['preferred_daptype']}
+```
+
+!! Aggregate
+
+```json
+{json.dumps({
+ 'bpt_proxy_classes': agg['bpt_proxy_classes'],
+ 'shock_lier_proxy_classes': agg['shock_lier_proxy_classes'],
+ 'partial_or_full_shock_fraction': agg['partial_or_full_shock_fraction'],
+}, indent=2)}
+```
+
+!! DESI Bridge
+
+The sky/redshift cells are DESI-ready join buckets, not DESI environment classes
+yet.
+
+```text
+MaNGA population cell
+ -> future DESI sky-cone/redshift join
+ -> environment prior
+ -> gas-state residual map
+```
+
+!! Boundary
+
+Proxy classes do not prove physical shock, AGN, or gas mechanism. DESI
+environment inference remains HOLD until the join receipt exists.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--fits", type=Path, default=DEFAULT_FITS)
+ parser.add_argument("--preferred-daptype", default=PREFERRED_DAPTYPE)
+ parser.add_argument("--destination", default=DESTINATION)
+ parser.add_argument("--no-upload", action="store_true")
+ args = parser.parse_args()
+
+ result = build_population_study(args.fits, args.preferred_daptype)
+ OUT.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_doc(result)
+ write_tiddler(result)
+
+ receipt_path = DATA_DIR / f"stellar_gas_population_grouping_study_receipt_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+ receipt: dict[str, Any] = {
+ "schema": "stellar_gas_population_grouping_study_receipt_v1",
+ "created": now_iso(),
+ "claim_boundary": result["claim_boundary"],
+ "study_file": str(OUT.relative_to(REPO)),
+ "doc_file": str(DOC.relative_to(REPO)),
+ "tiddler_file": str(TIDDLER.relative_to(REPO)),
+ "source_fits": result["source_fits"],
+ "decision": result["decision"],
+ "summary": {
+ "unique_plateifu_count": result["unique_plateifu_count"],
+ "selected_population_count": result["selected_population_count"],
+ "partial_or_full_shock_fraction": result["aggregate"]["partial_or_full_shock_fraction"],
+ "desi_bridge_status": result["desi_bridge"]["status"],
+ },
+ "uploads": {},
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ if not args.no_upload:
+ uploads = {
+ "study": (OUT, f"{args.destination}/derived/{OUT.name}"),
+ "doc": (DOC, f"{args.destination}/docs/{DOC.name}"),
+ "tiddler": (TIDDLER, f"{args.destination}/docs/{TIDDLER.name.replace(' ', '_')}"),
+ "receipt": (receipt_path, f"{args.destination}/receipts/{receipt_path.name}"),
+ }
+ for key, (local, remote) in uploads.items():
+ ok, message = rclone_copyto(local, remote)
+ receipt["uploads"][key] = {"drive_path": remote, "ok": ok, "message": message}
+ receipt_path.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ if receipt["uploads"].get("receipt", {}).get("ok"):
+ rclone_copyto(receipt_path, receipt["uploads"]["receipt"]["drive_path"])
+
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/4-Infrastructure/shim/stellar_gas_sandpile_fine_zoom.py b/4-Infrastructure/shim/stellar_gas_sandpile_fine_zoom.py
new file mode 100644
index 00000000..cfe9753c
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_sandpile_fine_zoom.py
@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""Fine-zoom object examples under the stellar-gas sandpile candidates.
+
+This script drills from the sandpile cell diagnostic down to MaNGA Plate-IFU
+examples in the avalanche-candidate cells. It keeps the same proxy boundary as
+the population study: these are observable gas/shock routing candidates, not
+proof of a physical shock mechanism.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[2]
+POP_SCRIPT = ROOT / "4-Infrastructure/shim/stellar_gas_population_grouping_study.py"
+SANDPILE_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_abelian_sandpile_probe.json"
+OUT_DIR = ROOT / "shared-data/data/stellar_gas_observation"
+DOCS_DIR = ROOT / "6-Documentation/docs"
+TIDDLER_DIR = ROOT / "6-Documentation/tiddlywiki-local/wiki/tiddlers"
+
+OUT_JSON = OUT_DIR / "stellar_gas_sandpile_fine_zoom.json"
+RECEIPT_JSON = OUT_DIR / "stellar_gas_sandpile_fine_zoom_receipt.json"
+DOC_MD = DOCS_DIR / "stellar_gas_sandpile_fine_zoom_2026-05-09.md"
+TIDDLER = TIDDLER_DIR / "Stellar Gas Sandpile Fine Zoom.tid"
+
+EXAMPLES_PER_CELL = 8
+
+
+def load_population_module():
+ spec = importlib.util.spec_from_file_location("stellar_gas_population_grouping_study", POP_SCRIPT)
+ if spec is None or spec.loader is None:
+ raise RuntimeError(f"cannot load {POP_SCRIPT}")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ with path.open() as f:
+ return json.load(f)
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def finite(value: Any) -> bool:
+ return isinstance(value, (int, float)) and math.isfinite(value)
+
+
+def round6(value: float | None) -> float | None:
+ if value is None or not math.isfinite(value):
+ return None
+ return round(value, 6)
+
+
+def object_pressure(row: dict[str, Any]) -> float:
+ gas_sigma = row.get("gas_sigma_1re_kms") or 0.0
+ stellar_sigma = row.get("stellar_sigma_1re_kms") or 0.0
+ snr = row.get("snr_mean") or 0.0
+ pressure = float(row.get("shock_lier_score") or 0.0)
+ pressure += min(float(gas_sigma) / 250.0, 2.0)
+ pressure += min(float(stellar_sigma) / 250.0, 2.0) * 0.5
+ pressure += min(max(float(snr), 0.0) / 50.0, 1.0) * 0.25
+ if row.get("bpt_proxy_class") == "agn_liner_or_shock_proxy":
+ pressure += 0.5
+ if row.get("shock_lier_proxy_class") == "shock_lier_proxy":
+ pressure += 0.5
+ return pressure
+
+
+def compact_row(row: dict[str, Any]) -> dict[str, Any]:
+ ratios = row.get("line_ratios", {})
+ return {
+ "plateifu": row.get("plateifu"),
+ "mangaid": row.get("mangaid"),
+ "ra": round6(row.get("ra")),
+ "dec": round6(row.get("dec")),
+ "z": round6(row.get("z")),
+ "sky_z_cell": row.get("sky_z_cell"),
+ "bpt_proxy_class": row.get("bpt_proxy_class"),
+ "shock_lier_proxy_class": row.get("shock_lier_proxy_class"),
+ "shock_lier_score": round6(row.get("shock_lier_score")),
+ "gas_sigma_1re_kms": round6(row.get("gas_sigma_1re_kms")),
+ "stellar_sigma_1re_kms": round6(row.get("stellar_sigma_1re_kms")),
+ "snr_mean": round6(row.get("snr_mean")),
+ "object_pressure": round6(object_pressure(row)),
+ "line_ratios": {key: round6(value) for key, value in ratios.items()},
+ }
+
+
+def build() -> tuple[dict[str, Any], dict[str, Any]]:
+ pop = load_population_module()
+ sandpile = load_json(SANDPILE_JSON)
+ candidate_cells = [
+ row["cell"]
+ for row in sandpile["top_cells"]
+ if row["sandpile"]["state"] == "AVALANCHE_CANDIDATE"
+ ]
+ candidate_set = set(candidate_cells)
+
+ channel_index = pop.load_channels()
+ by_plateifu: dict[str, dict[str, Any]] = {}
+ rows_seen = 0
+ rows_in_candidate_cells = 0
+
+ for _, _, _, fields in pop.iter_rows(pop.DEFAULT_FITS):
+ rows_seen += 1
+ payload = pop.row_payload(fields, channel_index)
+ if not payload:
+ continue
+ daptype = str(payload.get("daptype") or "")
+ plateifu = str(payload.get("plateifu") or "")
+ current = by_plateifu.get(plateifu)
+ if current is None or daptype == pop.PREFERRED_DAPTYPE:
+ by_plateifu[plateifu] = payload
+
+ examples_by_cell: dict[str, list[dict[str, Any]]] = {cell: [] for cell in candidate_cells}
+ for row in by_plateifu.values():
+ cell = row.get("sky_z_cell")
+ if cell not in candidate_set:
+ continue
+ rows_in_candidate_cells += 1
+ examples_by_cell[cell].append(row)
+
+ output_cells = []
+ for sand_row in sandpile["top_cells"]:
+ cell = sand_row["cell"]
+ if cell not in candidate_set:
+ continue
+ examples = sorted(
+ examples_by_cell[cell],
+ key=lambda row: object_pressure(row),
+ reverse=True,
+ )[:EXAMPLES_PER_CELL]
+ output_cells.append(
+ {
+ "cell": cell,
+ "sandpile": sand_row["sandpile"],
+ "channel_summary": sand_row["channels"],
+ "candidate_count": len(examples_by_cell[cell]),
+ "top_examples": [compact_row(row) for row in examples],
+ }
+ )
+
+ created = now_iso()
+ result = {
+ "schema": "stellar_gas_sandpile_fine_zoom_v0",
+ "created": created,
+ "decision": "ADMIT_FINE_ZOOM_OBJECT_EXAMPLES_HOLD_MECHANISM_PROOF",
+ "claim_boundary": (
+ "Fine-zoom object examples under sandpile avalanche-candidate cells. "
+ "Proxy classes and object-pressure scores route follow-up; they do "
+ "not prove physical shock, AGN, stellar mass, or gas mechanism."
+ ),
+ "sources": {
+ "sandpile_probe": str(SANDPILE_JSON.relative_to(ROOT)),
+ "manga_fits": str(pop.DEFAULT_FITS.relative_to(ROOT)),
+ "population_script": str(POP_SCRIPT.relative_to(ROOT)),
+ },
+ "rows_seen_all_daptypes": rows_seen,
+ "unique_plateifu_count": len(by_plateifu),
+ "candidate_cell_count": len(candidate_cells),
+ "rows_in_candidate_cells": rows_in_candidate_cells,
+ "examples_per_cell": EXAMPLES_PER_CELL,
+ "candidate_cells": output_cells,
+ "holds": [
+ "HOLD_PHYSICAL_SHOCK_PROOF",
+ "HOLD_DIRECT_STELLAR_MASS",
+ "HOLD_DIRECT_GAS_DENSITY_INFERENCE",
+ "HOLD_OBJECT_LEVEL_DESI_CROSSMATCH",
+ "HOLD_COSMOLOGY_FIT",
+ ],
+ }
+ receipt = {
+ "receipt_type": "stellar_gas_sandpile_fine_zoom_receipt",
+ "created": created,
+ "candidate_cell_count": len(candidate_cells),
+ "rows_in_candidate_cells": rows_in_candidate_cells,
+ "examples_written": sum(len(cell["top_examples"]) for cell in output_cells),
+ "decision": result["decision"],
+ "validated_outputs": [
+ str(OUT_JSON.relative_to(ROOT)),
+ str(DOC_MD.relative_to(ROOT)),
+ str(TIDDLER.relative_to(ROOT)),
+ ],
+ }
+ return result, receipt
+
+
+def write_docs(result: dict[str, Any]) -> None:
+ cell_lines = []
+ for cell in result["candidate_cells"]:
+ top = cell["top_examples"][0] if cell["top_examples"] else {}
+ cell_lines.append(
+ f"- `{cell['cell']}`: candidates `{cell['candidate_count']}`, "
+ f"top `{top.get('plateifu')}`, pressure `{top.get('object_pressure')}`, "
+ f"class `{top.get('shock_lier_proxy_class')}`"
+ )
+ holds = "\n".join(f"- `{hold}`" for hold in result["holds"])
+
+ DOC_MD.write_text(
+ f"""# Stellar Gas Sandpile Fine Zoom
+
+Status: `FINE_ZOOM_OBJECT_EXAMPLES`
+
+Decision: `{result['decision']}`
+
+This fine-zoom pass drills from sandpile avalanche-candidate cells down to MaNGA
+Plate-IFU examples. It is meant to show which concrete objects carry the
+strongest local proxy pressure under the cell-level eigenmass surface.
+
+Claim boundary: proxy classes and object-pressure scores route follow-up; they
+do not prove physical shock, AGN, stellar mass, gas density, or cosmology.
+
+## Summary
+
+```text
+candidate cells: {result['candidate_cell_count']}
+candidate-cell objects: {result['rows_in_candidate_cells']}
+examples per cell: {result['examples_per_cell']}
+```
+
+## Top Object Per Candidate Cell
+
+{chr(10).join(cell_lines)}
+
+## Holds
+
+{holds}
+""",
+ encoding="utf-8",
+ )
+
+ TIDDLER.write_text(
+ f"""title: Stellar Gas Sandpile Fine Zoom
+tags: StellarGasObservation MaNGA SemanticMassNumbers Sandpile Receipts
+type: text/vnd.tiddlywiki
+
+Status: <>
+
+Decision: `{result['decision']}`
+
+This tiddler drills from the Abelian-sandpile candidate cells into MaNGA
+Plate-IFU examples.
+
+```
+candidate cells: {result['candidate_cell_count']}
+candidate-cell objects: {result['rows_in_candidate_cells']}
+examples per cell: {result['examples_per_cell']}
+```
+
+!! Top Object Per Candidate Cell
+
+{chr(10).join(cell_lines)}
+
+!! Boundary
+
+These are proxy-ranked follow-up candidates, not proof of physical shock, AGN,
+stellar mass, gas density, or cosmology.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ result, receipt = build()
+ OUT_JSON.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT_JSON.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_docs(result)
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stellar_gas_sandpile_graph_replay.py b/4-Infrastructure/shim/stellar_gas_sandpile_graph_replay.py
new file mode 100644
index 00000000..0b939c3c
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_sandpile_graph_replay.py
@@ -0,0 +1,444 @@
+#!/usr/bin/env python3
+"""Graph replay hardening for the stellar-gas sandpile diagnostic.
+
+This converts the existing sandpile metaphor into a reproducible graph
+diagnostic. It is a toppling proxy over sky/redshift cells, not a physical
+sandpile simulation and not a claim about stellar gas mechanics.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections import deque
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SANDPILE_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_abelian_sandpile_probe.json"
+FINE_ZOOM_JSON = ROOT / "shared-data/data/stellar_gas_observation/stellar_gas_sandpile_fine_zoom.json"
+OUT_DIR = ROOT / "shared-data/data/stellar_gas_observation"
+DOCS_DIR = ROOT / "6-Documentation/docs"
+TIDDLER_DIR = ROOT / "6-Documentation/tiddlywiki-local/wiki/tiddlers"
+
+OUT_JSON = OUT_DIR / "stellar_gas_sandpile_graph_replay.json"
+RECEIPT_JSON = OUT_DIR / "stellar_gas_sandpile_graph_replay_receipt.json"
+DOC_MD = DOCS_DIR / "stellar_gas_sandpile_graph_replay_2026-05-09.md"
+TIDDLER = TIDDLER_DIR / "Stellar Gas Sandpile Graph Replay.tid"
+
+Z_BIN_ORDER = {
+ "z_000_002": 0,
+ "z_002_004": 1,
+ "z_004_006": 2,
+ "z_006_008": 3,
+ "z_008_plus": 4,
+}
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ with path.open(encoding="utf-8") as f:
+ return json.load(f)
+
+
+def sha256_file(path: Path) -> str:
+ h = hashlib.sha256()
+ with path.open("rb") as f:
+ for chunk in iter(lambda: f.read(1024 * 1024), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def sha256_payload(payload: Any) -> str:
+ raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+ return hashlib.sha256(raw).hexdigest()
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def parse_cell(cell: str) -> dict[str, Any]:
+ sky_sector, z_bin = cell.split("__", 1)
+ ra_sector, hemisphere = sky_sector.split("_", 1)
+ return {
+ "cell": cell,
+ "sky_sector": sky_sector,
+ "ra_sector": int(ra_sector.removeprefix("ra")),
+ "hemisphere": hemisphere,
+ "z_bin": z_bin,
+ "z_bin_index": Z_BIN_ORDER[z_bin],
+ }
+
+
+def are_adjacent(a: dict[str, Any], b: dict[str, Any]) -> bool:
+ same_z = a["z_bin_index"] == b["z_bin_index"]
+ same_ra = a["ra_sector"] == b["ra_sector"]
+ same_hemisphere = a["hemisphere"] == b["hemisphere"]
+ ra_neighbor = same_z and same_hemisphere and abs(a["ra_sector"] - b["ra_sector"]) == 1
+ hemisphere_neighbor = same_z and same_ra and a["hemisphere"] != b["hemisphere"]
+ redshift_neighbor = same_ra and same_hemisphere and abs(a["z_bin_index"] - b["z_bin_index"]) == 1
+ return ra_neighbor or hemisphere_neighbor or redshift_neighbor
+
+
+def round9(value: float) -> float:
+ return round(value, 9)
+
+
+def seed_counts(fine_zoom: dict[str, Any]) -> dict[str, int]:
+ return {
+ cell["cell"]: int(cell["candidate_count"])
+ for cell in fine_zoom["candidate_cells"]
+ }
+
+
+def node_rows(sandpile: dict[str, Any], fine_zoom: dict[str, Any]) -> list[dict[str, Any]]:
+ counts = seed_counts(fine_zoom)
+ index_std = float(sandpile["toppling_index_summary"]["std"]) or 1.0
+ rows = []
+ for row in sorted(sandpile["top_cells"], key=lambda item: item["cell"]):
+ parsed = parse_cell(row["cell"])
+ proxy_z = float(row["sandpile"]["toppling_index"]) / index_std
+ rows.append(
+ {
+ **parsed,
+ "state": row["sandpile"]["state"],
+ "grains": float(row["sandpile"]["grains"]),
+ "toppling_pressure": float(row["sandpile"]["toppling_pressure"]),
+ "toppling_index": float(row["sandpile"]["toppling_index"]),
+ "toppling_index_z_proxy": round9(proxy_z),
+ "candidate_object_count": counts.get(row["cell"], 0),
+ }
+ )
+ return rows
+
+
+def graph_edges(rows: list[dict[str, Any]]) -> list[dict[str, str]]:
+ edges = []
+ for i, left in enumerate(rows):
+ for right in rows[i + 1 :]:
+ if are_adjacent(left, right):
+ edges.append({"source": left["cell"], "target": right["cell"]})
+ return edges
+
+
+def adjacency(nodes: list[str], edges: list[dict[str, str]]) -> dict[str, list[str]]:
+ out = {node: [] for node in nodes}
+ for edge in edges:
+ out[edge["source"]].append(edge["target"])
+ out[edge["target"]].append(edge["source"])
+ return {node: sorted(neighbors) for node, neighbors in out.items()}
+
+
+def threshold_and_grain_tables(rows: list[dict[str, Any]], adj: dict[str, list[str]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+ threshold_table = []
+ grain_table = []
+ for row in rows:
+ cell = row["cell"]
+ degree = len(adj[cell])
+ threshold = max(1, degree + 1)
+ proxy_z = max(0.0, row["toppling_index_z_proxy"])
+ initial_grains = max(0, math.ceil(proxy_z * threshold))
+ threshold_table.append(
+ {
+ "cell": cell,
+ "degree": degree,
+ "toppling_threshold": threshold,
+ "threshold_rule": "degree_plus_one_toppling_proxy",
+ }
+ )
+ grain_table.append(
+ {
+ "cell": cell,
+ "initial_grains": initial_grains,
+ "grain_rule": "ceil(max(0, toppling_index_z_proxy) * threshold)",
+ "toppling_index_z_proxy": row["toppling_index_z_proxy"],
+ "seed_object_count": row["candidate_object_count"],
+ "source_state": row["state"],
+ }
+ )
+ return threshold_table, grain_table
+
+
+def replay_one(seed: str, adj: dict[str, list[str]], thresholds: dict[str, int], grains: dict[str, int]) -> dict[str, Any]:
+ working = dict(grains)
+ topple_count = {cell: 0 for cell in working}
+ touched = set()
+ q: deque[str] = deque([seed])
+ max_steps = max(1, len(working) * 20)
+ steps = 0
+ while q and steps < max_steps:
+ cell = q.popleft()
+ if working[cell] < thresholds[cell]:
+ continue
+ steps += 1
+ touched.add(cell)
+ topple_count[cell] += 1
+ working[cell] -= thresholds[cell]
+ for neighbor in adj[cell]:
+ working[neighbor] += 1
+ if working[neighbor] >= thresholds[neighbor]:
+ q.append(neighbor)
+
+ toppled_cells = sorted(cell for cell, count in topple_count.items() if count)
+ return {
+ "seed_cell": seed,
+ "terminated": not q,
+ "step_limit": max_steps,
+ "topple_events": sum(topple_count.values()),
+ "avalanche_size_cells": len(toppled_cells),
+ "toppled_cells": toppled_cells,
+ "final_seed_grains": working[seed],
+ }
+
+
+def build() -> tuple[dict[str, Any], dict[str, Any]]:
+ sandpile = load_json(SANDPILE_JSON)
+ fine_zoom = load_json(FINE_ZOOM_JSON)
+ rows = node_rows(sandpile, fine_zoom)
+ nodes = [row["cell"] for row in rows]
+ edges = graph_edges(rows)
+ adj = adjacency(nodes, edges)
+ threshold_table, grain_table = threshold_and_grain_tables(rows, adj)
+ thresholds = {row["cell"]: int(row["toppling_threshold"]) for row in threshold_table}
+ grains = {row["cell"]: int(row["initial_grains"]) for row in grain_table}
+ seed_cells = sorted(
+ row["cell"]
+ for row in rows
+ if row["state"] == "AVALANCHE_CANDIDATE" and row["candidate_object_count"] > 0
+ )
+ avalanches = [replay_one(seed, adj, thresholds, grains) for seed in seed_cells]
+
+ canonical_graph = {
+ "adjacency_rule": (
+ "Edges join same-redshift neighboring RA sectors, same-RA north/south sectors, "
+ "or same-sky-sector adjacent redshift bins."
+ ),
+ "nodes": [
+ {
+ "cell": row["cell"],
+ "ra_sector": row["ra_sector"],
+ "hemisphere": row["hemisphere"],
+ "z_bin": row["z_bin"],
+ }
+ for row in rows
+ ],
+ "edges": edges,
+ "threshold_table": threshold_table,
+ "initial_grain_table": grain_table,
+ }
+ graph_hash = sha256_payload(canonical_graph)
+ replay_payload = {
+ "graph_hash": graph_hash,
+ "seed_cells": seed_cells,
+ "avalanche_replay": avalanches,
+ }
+ replay_hash = sha256_payload(replay_payload)
+ created = now_iso()
+ result = {
+ "schema": "stellar_gas_sandpile_graph_replay_v0",
+ "created": created,
+ "decision": "ADMIT_GRAPH_TOPPLING_PROXY_HOLD_PHYSICAL_SANDPILE_SIMULATION",
+ "claim_boundary": (
+ "This is a reproducible graph diagnostic and toppling proxy over existing "
+ "stellar-gas evidence cells. It is not a physical sandpile simulation, "
+ "not a stellar-gas mechanism proof, and not a cosmology fit."
+ ),
+ "sources": {
+ "sandpile_probe": str(SANDPILE_JSON.relative_to(ROOT)),
+ "fine_zoom_examples": str(FINE_ZOOM_JSON.relative_to(ROOT)),
+ },
+ "source_hashes": {
+ "sandpile_probe_sha256": sha256_file(SANDPILE_JSON),
+ "fine_zoom_examples_sha256": sha256_file(FINE_ZOOM_JSON),
+ },
+ "seed_evidence": {
+ "avalanche_cell_count": len(seed_cells),
+ "candidate_object_count": int(fine_zoom["rows_in_candidate_cells"]),
+ "candidate_counts_by_cell": seed_counts(fine_zoom),
+ },
+ "adjacency_rule": canonical_graph["adjacency_rule"],
+ "graph_hash": graph_hash,
+ "replay_hash": replay_hash,
+ "node_count": len(nodes),
+ "edge_count": len(edges),
+ "nodes": rows,
+ "edges": edges,
+ "adjacency": adj,
+ "toppling_threshold_table": threshold_table,
+ "initial_grain_table": grain_table,
+ "avalanche_sizes": [
+ {
+ "seed_cell": row["seed_cell"],
+ "avalanche_size_cells": row["avalanche_size_cells"],
+ "topple_events": row["topple_events"],
+ "terminated": row["terminated"],
+ }
+ for row in avalanches
+ ],
+ "avalanche_replay": avalanches,
+ "holds": [
+ "HOLD_PHYSICAL_SANDPILE_SIMULATION",
+ "HOLD_STELLAR_GAS_MECHANISM_PROOF",
+ "HOLD_DIRECT_STELLAR_MASS",
+ "HOLD_DIRECT_GAS_DENSITY_INFERENCE",
+ "HOLD_COSMOLOGY_FIT",
+ ],
+ }
+ receipt = {
+ "receipt_type": "stellar_gas_sandpile_graph_replay_receipt",
+ "created": created,
+ "decision": result["decision"],
+ "graph_hash": graph_hash,
+ "replay_hash": replay_hash,
+ "node_count": len(nodes),
+ "edge_count": len(edges),
+ "seed_avalanche_cell_count": len(seed_cells),
+ "seed_candidate_object_count": int(fine_zoom["rows_in_candidate_cells"]),
+ "avalanche_sizes": result["avalanche_sizes"],
+ "validated_outputs": [
+ str(OUT_JSON.relative_to(ROOT)),
+ str(RECEIPT_JSON.relative_to(ROOT)),
+ str(DOC_MD.relative_to(ROOT)),
+ str(TIDDLER.relative_to(ROOT)),
+ ],
+ }
+ return result, receipt
+
+
+def write_docs(result: dict[str, Any], receipt: dict[str, Any]) -> None:
+ threshold_lines = "\n".join(
+ f"| `{row['cell']}` | {row['degree']} | {row['toppling_threshold']} |"
+ for row in result["toppling_threshold_table"]
+ )
+ grain_lines = "\n".join(
+ f"| `{row['cell']}` | {row['initial_grains']} | {row['toppling_index_z_proxy']} | {row['seed_object_count']} |"
+ for row in result["initial_grain_table"]
+ )
+ avalanche_lines = "\n".join(
+ f"| `{row['seed_cell']}` | {row['avalanche_size_cells']} | {row['topple_events']} | `{row['terminated']}` |"
+ for row in result["avalanche_sizes"]
+ )
+ holds = "\n".join(f"- `{hold}`" for hold in result["holds"])
+
+ DOC_MD.write_text(
+ f"""# Stellar Gas Sandpile Graph Replay
+
+Status: `GRAPH_TOPPLING_PROXY`
+
+Decision: `{result['decision']}`
+
+This hardening pass turns the sandpile metaphor into a reproducible graph
+diagnostic. Nodes are sky/redshift cells. Edges are defined by sky-sector
+neighbors plus adjacent redshift bins. Grain and toppling values are diagnostic
+proxies derived from the existing cell-level toppling index.
+
+Claim boundary: this is not a physical sandpile simulation, not a stellar-gas
+mechanism proof, not direct stellar mass, not gas density inference, and not a
+cosmology fit.
+
+## Replay Receipt
+
+```json
+{json.dumps(receipt, indent=2, sort_keys=True)}
+```
+
+## Seed Evidence
+
+```text
+avalanche cells: {result['seed_evidence']['avalanche_cell_count']}
+candidate objects: {result['seed_evidence']['candidate_object_count']}
+graph nodes: {result['node_count']}
+graph edges: {result['edge_count']}
+graph hash: {result['graph_hash']}
+replay hash: {result['replay_hash']}
+```
+
+## Toppling Threshold Table
+
+| cell | degree | threshold |
+| --- | ---: | ---: |
+{threshold_lines}
+
+## Initial Grain Table
+
+| cell | initial grains | index z proxy | seed objects |
+| --- | ---: | ---: | ---: |
+{grain_lines}
+
+## Avalanche Sizes
+
+| seed cell | size cells | topple events | terminated |
+| --- | ---: | ---: | --- |
+{avalanche_lines}
+
+## Holds
+
+{holds}
+""",
+ encoding="utf-8",
+ )
+
+ TIDDLER.write_text(
+ f"""title: Stellar Gas Sandpile Graph Replay
+tags: StellarGasObservation SemanticMassNumbers Sandpile GraphReplay Receipts
+type: text/vnd.tiddlywiki
+
+Status: <>
+
+Decision: `{result['decision']}`
+
+This tiddler records the graph/replay hardening of the stellar-gas sandpile
+diagnostic. It is a toppling proxy over evidence cells, not a physical sandpile
+simulation or mechanism proof.
+
+```
+avalanche cells: {result['seed_evidence']['avalanche_cell_count']}
+candidate objects: {result['seed_evidence']['candidate_object_count']}
+graph nodes: {result['node_count']}
+graph edges: {result['edge_count']}
+graph hash: {result['graph_hash']}
+replay hash: {result['replay_hash']}
+```
+
+!! Toppling Threshold Table
+
+|cell | degree | threshold |
+|---|---:|---:|
+{threshold_lines}
+
+!! Initial Grain Table
+
+|cell | initial grains | index z proxy | seed objects |
+|---|---:|---:|---:|
+{grain_lines}
+
+!! Avalanche Sizes
+
+|seed cell | size cells | topple events | terminated |
+|---|---:|---:|---|
+{avalanche_lines}
+
+!! Boundary
+
+Diagnostic/toppling proxy only. Holds: {", ".join(result["holds"])}.
+""",
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ result, receipt = build()
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ DOCS_DIR.mkdir(parents=True, exist_ok=True)
+ TIDDLER_DIR.mkdir(parents=True, exist_ok=True)
+ OUT_JSON.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ RECEIPT_JSON.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_docs(result, receipt)
+ print(json.dumps(receipt, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/stellar_gas_shock_eigen_fit.py b/4-Infrastructure/shim/stellar_gas_shock_eigen_fit.py
new file mode 100644
index 00000000..c571f447
--- /dev/null
+++ b/4-Infrastructure/shim/stellar_gas_shock_eigen_fit.py
@@ -0,0 +1,452 @@
+#!/usr/bin/env python3
+"""Fit SDSS MaNGA DAPall observation proxies against local shock eigen lanes.
+
+This is an observation-proxy fit, not astrophysical validation. It measures
+whether the pulled MaNGA gas/velocity columns provide nonzero support for the
+physical-shock eigen axis identified in the stack-solidification audit.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import math
+import statistics
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+REPO = Path(__file__).resolve().parents[2]
+SEED_SCRIPT = REPO / "4-Infrastructure/shim/sdss_manga_dapall_observation_seed.py"
+DATA_DIR = REPO / "shared-data/data/stellar_gas_observation"
+DOC_PATH = REPO / "6-Documentation/docs/stellar_gas_shock_eigen_fit_2026-05-09.md"
+DEFAULT_FITS = REPO / "shared-data/artifacts/stellar_gas_observation/dapall-v3_1_1-3.1.0.fits"
+DESTINATION = "Gdrive:topological_storage/research-stack/stellar-gas-observation/seed-2026-05-09"
+
+
+TARGET_COLUMNS = [
+ "PLATEIFU",
+ "MANGAID",
+ "DAPTYPE",
+ "Z",
+ "BINSNR",
+ "SNR_MED",
+ "STELLAR_SIGMA_1RE",
+ "STELLAR_VEL_LO_CLIP",
+ "STELLAR_VEL_HI_CLIP",
+ "HA_GVEL_LO_CLIP",
+ "HA_GVEL_HI_CLIP",
+ "HA_GSIGMA_1RE",
+ "HA_GSIGMA_HI_CLIP",
+ "EMLINE_RCHI2_1RE",
+]
+
+
+LOCAL_EIGEN_PRIORS = {
+ "radiation_absorption": {
+ "cluster": "Electromagnetism & Circuits",
+ "eigenvalue": 0.96875,
+ "prior_strength": 0.176777,
+ },
+ "diffusion_material_transport": {
+ "cluster": "Condensed Matter & Superconductivity",
+ "eigenvalue": 0.969697,
+ "prior_strength": 0.174078,
+ },
+ "radiation_spectrum": {
+ "cluster": "Quantum Mechanics & Particle Physics",
+ "eigenvalue": 0.970588,
+ "prior_strength": 0.171499,
+ },
+ "acoustic_boundary": {
+ "cluster": "Materials Science & Engineering",
+ "eigenvalue": 0.992063,
+ "prior_strength": 0.089087,
+ },
+ "local_stack_shock_alignment": {
+ "cluster": "Cognitive & Semantic Systems",
+ "eigenvalue": 0.998464,
+ "prior_strength": 0.039193,
+ },
+ "classical_hydrodynamic_shock": {
+ "cluster": "Detonics & Shock Physics",
+ "eigenvalue": None,
+ "prior_strength": 0.0,
+ },
+}
+
+
+def now_iso() -> str:
+ return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+
+def load_seed_module():
+ spec = importlib.util.spec_from_file_location("sdss_manga_dapall_observation_seed", SEED_SCRIPT)
+ if spec is None or spec.loader is None:
+ raise RuntimeError(f"cannot load {SEED_SCRIPT}")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def run(cmd: list[str]) -> subprocess.CompletedProcess:
+ return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+
+
+def rclone_copyto(local: Path, remote: str) -> tuple[bool, str]:
+ proc = run(["rclone", "copyto", str(local), remote, "--checksum"])
+ message = (proc.stderr or proc.stdout).decode(errors="replace").strip()
+ return proc.returncode == 0, message
+
+
+def finite(value) -> bool:
+ return isinstance(value, (int, float)) and math.isfinite(value) and value > -900
+
+
+def scalar(value):
+ if finite(value):
+ return float(value)
+ return None
+
+
+def list_mean(value):
+ if isinstance(value, list):
+ vals = [float(v) for v in value if finite(v)]
+ return statistics.fmean(vals) if vals else None
+ return scalar(value)
+
+
+def clamp01(value: float) -> float:
+ return max(0.0, min(1.0, value))
+
+
+def summarize(values: list[float]) -> dict:
+ vals = sorted(v for v in values if math.isfinite(v))
+ if not vals:
+ return {"count": 0}
+ return {
+ "count": len(vals),
+ "min": round(vals[0], 6),
+ "max": round(vals[-1], 6),
+ "mean": round(statistics.fmean(vals), 6),
+ "median": round(statistics.median(vals), 6),
+ "p90": round(vals[int(0.9 * (len(vals) - 1))], 6),
+ }
+
+
+def row_proxy(fields: dict) -> dict | None:
+ gas_lo = scalar(fields.get("HA_GVEL_LO_CLIP"))
+ gas_hi = scalar(fields.get("HA_GVEL_HI_CLIP"))
+ stellar_lo = scalar(fields.get("STELLAR_VEL_LO_CLIP"))
+ stellar_hi = scalar(fields.get("STELLAR_VEL_HI_CLIP"))
+ gas_sigma = scalar(fields.get("HA_GSIGMA_1RE"))
+ gas_sigma_hi = scalar(fields.get("HA_GSIGMA_HI_CLIP"))
+ stellar_sigma = scalar(fields.get("STELLAR_SIGMA_1RE"))
+ rchi2 = scalar(fields.get("EMLINE_RCHI2_1RE"))
+ snr = list_mean(fields.get("SNR_MED"))
+
+ gas_span = None if gas_lo is None or gas_hi is None else max(0.0, gas_hi - gas_lo)
+ stellar_span = None if stellar_lo is None or stellar_hi is None else max(0.0, stellar_hi - stellar_lo)
+ if gas_span is None and gas_sigma is None and rchi2 is None:
+ return None
+
+ velocity_contrast = None
+ if gas_span is not None and stellar_span is not None:
+ velocity_contrast = gas_span / max(stellar_span, 1.0)
+
+ sigma_contrast = None
+ if gas_sigma is not None and stellar_sigma is not None:
+ sigma_contrast = gas_sigma / max(stellar_sigma, 1.0)
+
+ quality = clamp01((snr or 0.0) / 20.0)
+ fit_quality = clamp01(1.0 / max(rchi2 or 99.0, 1.0))
+ span_score = clamp01((gas_span or 0.0) / 1000.0)
+ sigma_score = clamp01((gas_sigma or 0.0) / 300.0)
+ contrast_score = clamp01((velocity_contrast or 0.0) / 5.0)
+ # Proxy only: broad gas line + high gas/stellar contrast + acceptable fit/SNR.
+ shock_proxy_score = clamp01(
+ 0.35 * span_score
+ + 0.30 * sigma_score
+ + 0.20 * contrast_score
+ + 0.10 * fit_quality
+ + 0.05 * quality
+ )
+
+ return {
+ "gas_velocity_span_kms": gas_span,
+ "stellar_velocity_span_kms": stellar_span,
+ "velocity_contrast": velocity_contrast,
+ "gas_sigma_1re_kms": gas_sigma,
+ "gas_sigma_hi_clip_kms": gas_sigma_hi,
+ "stellar_sigma_1re_kms": stellar_sigma,
+ "sigma_contrast": sigma_contrast,
+ "emline_rchi2_1re": rchi2,
+ "snr_med_mean": snr,
+ "shock_proxy_score": shock_proxy_score,
+ }
+
+
+def iter_bintable_rows(fits_path: Path, limit_rows: int | None = None):
+ seed = load_seed_module()
+ emitted = 0
+ with fits_path.open("rb") as f:
+ hdu_index = 0
+ while True:
+ try:
+ header, _ = seed.read_header(f)
+ except EOFError:
+ break
+ data_start = f.tell()
+ xtension = str(header.get("XTENSION", "PRIMARY"))
+ if xtension == "BINTABLE":
+ row_len = int(header["NAXIS1"])
+ row_count = int(header["NAXIS2"])
+ pcount = int(header.get("PCOUNT", 0))
+ columns = seed.build_columns(header)
+ by_name = {col["name"]: col for col in columns}
+ selected = [by_name[name] for name in TARGET_COLUMNS if name in by_name]
+ hdu_name = str(header.get("EXTNAME", f"HDU{hdu_index}"))
+ for row_idx in range(row_count):
+ if limit_rows is not None and emitted >= limit_rows:
+ return
+ f.seek(data_start + row_idx * row_len)
+ row = f.read(row_len)
+ fields = {}
+ for col in selected:
+ raw = row[col["offset"] : col["offset"] + col["width"]]
+ value = seed.decode_value(raw, col)
+ if isinstance(value, str):
+ value = value.replace("\u0000", "").strip()
+ fields[col["name"]] = value
+ emitted += 1
+ yield hdu_index, hdu_name, row_idx, fields
+ f.seek(data_start + seed.padded_size(row_len * row_count + pcount))
+ else:
+ bitpix = int(header.get("BITPIX", 8))
+ naxis = int(header.get("NAXIS", 0))
+ if naxis == 0:
+ data_size = 0
+ else:
+ pixels = 1
+ for axis in range(1, naxis + 1):
+ pixels *= int(header.get(f"NAXIS{axis}", 0))
+ data_size = abs(bitpix) // 8 * pixels
+ f.seek(data_start + seed.padded_size(data_size))
+ hdu_index += 1
+
+
+def build_fit(fits_path: Path, limit_rows: int | None) -> dict:
+ rows = []
+ summaries = {
+ "gas_velocity_span_kms": [],
+ "stellar_velocity_span_kms": [],
+ "velocity_contrast": [],
+ "gas_sigma_1re_kms": [],
+ "gas_sigma_hi_clip_kms": [],
+ "stellar_sigma_1re_kms": [],
+ "sigma_contrast": [],
+ "emline_rchi2_1re": [],
+ "snr_med_mean": [],
+ "shock_proxy_score": [],
+ }
+ hdu_counts: dict[str, int] = {}
+ admitted = 0
+ for hdu_index, hdu_name, row_idx, fields in iter_bintable_rows(fits_path, limit_rows):
+ hdu_counts[hdu_name] = hdu_counts.get(hdu_name, 0) + 1
+ proxy = row_proxy(fields)
+ if proxy is None:
+ continue
+ admitted += 1
+ for key, value in proxy.items():
+ if value is not None and isinstance(value, (int, float)) and math.isfinite(value):
+ summaries[key].append(float(value))
+ if len(rows) < 20:
+ rows.append(
+ {
+ "hdu_index": hdu_index,
+ "hdu_name": hdu_name,
+ "row_index": row_idx,
+ "plateifu": fields.get("PLATEIFU"),
+ "mangaid": fields.get("MANGAID"),
+ "daptype": fields.get("DAPTYPE"),
+ "z": fields.get("Z"),
+ "proxy": {
+ k: round(v, 6) if isinstance(v, float) else v for k, v in proxy.items()
+ },
+ }
+ )
+
+ shock_scores = summaries["shock_proxy_score"]
+ score_mean = statistics.fmean(shock_scores) if shock_scores else 0.0
+ nonzero_fraction = (
+ sum(1 for score in shock_scores if score > 0.05) / len(shock_scores)
+ if shock_scores
+ else 0.0
+ )
+ physical_support = clamp01(0.65 * score_mean + 0.35 * nonzero_fraction)
+
+ prior = LOCAL_EIGEN_PRIORS["classical_hydrodynamic_shock"]["prior_strength"]
+ refined_strength = clamp01(max(prior, physical_support))
+ support_delta = refined_strength - prior
+ decision = (
+ "ADMIT_NONZERO_PHYSICAL_SHOCK_SUPPORT"
+ if admitted and refined_strength > 0.0
+ else "HOLD_NO_OBSERVATION_SUPPORT"
+ )
+
+ return {
+ "schema": "stellar_gas_shock_eigen_fit_v0",
+ "created": now_iso(),
+ "claim_boundary": "Observation-proxy fit from SDSS MaNGA gas/velocity columns to the local physical shock eigen axis. It does not prove shock hydrodynamics, stellar breakout, or causality.",
+ "source_fits": str(fits_path.relative_to(REPO)) if fits_path.is_relative_to(REPO) else str(fits_path),
+ "row_limit": limit_rows,
+ "hdu_counts_seen": hdu_counts,
+ "admitted_proxy_rows": admitted,
+ "local_eigen_priors": LOCAL_EIGEN_PRIORS,
+ "aggregate_observables": {key: summarize(vals) for key, vals in summaries.items()},
+ "physical_shock_axis_refinement": {
+ "prior_strength": prior,
+ "observation_proxy_mean": round(score_mean, 6),
+ "nonzero_proxy_fraction": round(nonzero_fraction, 6),
+ "refined_strength": round(refined_strength, 6),
+ "support_delta": round(support_delta, 6),
+ "status_change": "0.000000_to_nonzero_observation_proxy"
+ if support_delta > 0
+ else "unchanged",
+ },
+ "top_sample_rows": sorted(
+ rows,
+ key=lambda item: item["proxy"].get("shock_proxy_score") or 0.0,
+ reverse=True,
+ )[:10],
+ "model_refinement": {
+ "before": "physical shock axis was HOLD with Detonics/Shock Physics strength 0.000000",
+ "after": "MaNGA gas velocity/sigma/residual columns provide a nonzero observation-proxy lane",
+ "next_gate": "replace proxy score with line-ratio and uncertainty-aware physical model fit",
+ },
+ "decision": decision,
+ }
+
+
+def write_markdown(result: dict, path: Path) -> None:
+ refine = result["physical_shock_axis_refinement"]
+ agg = result["aggregate_observables"]
+ lines = [
+ "# Stellar Gas Shock Eigen Fit",
+ "",
+ "**Date:** 2026-05-09",
+ "",
+ f"**Decision:** `{result['decision']}`",
+ "",
+ "**Claim boundary:** observation-proxy fit only. This does not claim",
+ "astrophysical validation, stellar shock breakout detection, or causality.",
+ "",
+ "## What Changed",
+ "",
+ "The physical shock eigen axis now has a nonzero observation-backed proxy",
+ "from SDSS DR17 MaNGA DAPall gas and velocity columns.",
+ "",
+ "```text",
+ f"prior strength: {refine['prior_strength']:.6f}",
+ f"proxy mean: {refine['observation_proxy_mean']:.6f}",
+ f"nonzero fraction: {refine['nonzero_proxy_fraction']:.6f}",
+ f"refined strength: {refine['refined_strength']:.6f}",
+ f"support delta: {refine['support_delta']:.6f}",
+ "```",
+ "",
+ "## Observable Proxies",
+ "",
+ "| Observable | Count | Mean | Median | P90 |",
+ "|---|---:|---:|---:|---:|",
+ ]
+ for key in [
+ "gas_velocity_span_kms",
+ "stellar_velocity_span_kms",
+ "velocity_contrast",
+ "gas_sigma_1re_kms",
+ "stellar_sigma_1re_kms",
+ "emline_rchi2_1re",
+ "snr_med_mean",
+ "shock_proxy_score",
+ ]:
+ s = agg[key]
+ lines.append(
+ f"| `{key}` | {s.get('count', 0)} | {s.get('mean', '')} | "
+ f"{s.get('median', '')} | {s.get('p90', '')} |"
+ )
+ lines += [
+ "",
+ "## Gate",
+ "",
+ "```text",
+ "if admitted_proxy_rows == 0:",
+ " HOLD_NO_OBSERVATION_SUPPORT",
+ "elif refined_strength > 0:",
+ " ADMIT_NONZERO_PHYSICAL_SHOCK_SUPPORT",
+ "else:",
+ " HOLD_RESIDUAL_CONTEXT",
+ "```",
+ "",
+ "## Next Work",
+ "",
+ "1. Add emission-line index metadata so the 35-element MaNGA arrays become",
+ " named H-alpha, H-beta, OIII, NII, and SII lanes.",
+ "2. Replace the current proxy with line-ratio diagnostics and uncertainties.",
+ "3. Compare high-score rows against Rankine-Hugoniot / Sedov-Taylor receipt",
+ " gates only after source-specific physical context is present.",
+ "",
+ ]
+ path.write_text("\n".join(lines))
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--fits", type=Path, default=DEFAULT_FITS)
+ parser.add_argument("--limit-rows", type=int, default=None)
+ parser.add_argument("--destination", default=DESTINATION)
+ args = parser.parse_args()
+
+ if not args.fits.exists():
+ raise FileNotFoundError(args.fits)
+
+ DATA_DIR.mkdir(parents=True, exist_ok=True)
+ result = build_fit(args.fits, args.limit_rows)
+ out_path = DATA_DIR / "stellar_gas_shock_eigen_fit.json"
+ out_path.write_text(json.dumps(result, indent=2) + "\n")
+ write_markdown(result, DOC_PATH)
+
+ receipt_path = DATA_DIR / f"stellar_gas_shock_eigen_fit_receipt_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+ receipt = {
+ "schema": "stellar_gas_shock_eigen_fit_receipt_v0",
+ "created": now_iso(),
+ "claim_boundary": result["claim_boundary"],
+ "fit_file": str(out_path.relative_to(REPO)),
+ "doc_file": str(DOC_PATH.relative_to(REPO)),
+ "source_fits": result["source_fits"],
+ "decision": result["decision"],
+ "refinement": result["physical_shock_axis_refinement"],
+ "uploads": {},
+ }
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+
+ uploads = {
+ "fit": (out_path, f"{args.destination.rstrip('/')}/derived/{out_path.name}"),
+ "doc": (DOC_PATH, f"{args.destination.rstrip('/')}/docs/{DOC_PATH.name}"),
+ "receipt": (receipt_path, f"{args.destination.rstrip('/')}/receipts/{receipt_path.name}"),
+ }
+ for name, (local, remote) in uploads.items():
+ ok, message = rclone_copyto(local, remote)
+ receipt["uploads"][name] = {"drive_path": remote, "ok": ok, "message": message}
+ receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
+ if receipt["uploads"]["receipt"]["ok"]:
+ rclone_copyto(receipt_path, receipt["uploads"]["receipt"]["drive_path"])
+
+ print(json.dumps(receipt, indent=2))
+ return 0 if result["decision"].startswith("ADMIT") else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/4-Infrastructure/shim/symbolic_law_replay_harness.py b/4-Infrastructure/shim/symbolic_law_replay_harness.py
new file mode 100644
index 00000000..079e65be
--- /dev/null
+++ b/4-Infrastructure/shim/symbolic_law_replay_harness.py
@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Tiny symbolic-law replay harness.
+
+This is the first replay fixture for the SRBench/Feynman route surface. It uses
+small built-in ground-truth laws and deliberate mutations to test deterministic
+replay, residual accounting, and HOLD/ADMIT separation without downloading any
+external dataset.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import math
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal, getcontext
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+OUT_DIR = REPO / "shared-data" / "data" / "symbolic_law_replay"
+RECEIPT = OUT_DIR / "symbolic_law_replay_receipt.json"
+TABLE = OUT_DIR / "symbolic_law_replay_table.jsonl"
+
+getcontext().prec = 40
+
+
+ALLOWED_BINOPS = {
+ ast.Add: lambda a, b: a + b,
+ ast.Sub: lambda a, b: a - b,
+ ast.Mult: lambda a, b: a * b,
+ ast.Div: lambda a, b: a / b,
+ ast.Pow: lambda a, b: a**b,
+}
+ALLOWED_UNARY = {
+ ast.UAdd: lambda a: a,
+ ast.USub: lambda a: -a,
+}
+ALLOWED_FUNCS = {
+ "sin": Decimal,
+ "cos": Decimal,
+}
+
+
+@dataclass(frozen=True)
+class Fixture:
+ fixture_id: str
+ route_surface: str
+ truth_formula: str
+ candidate_formula: str
+ variables: list[str]
+ samples: list[dict[str, str]]
+ negative_control: bool
+
+
+FIXTURES = [
+ Fixture(
+ fixture_id="feynman_newton_gravity_admit",
+ route_surface="SRBench / Feynman",
+ truth_formula="G*m1*m2/(r**2)",
+ candidate_formula="G*m1*m2/(r**2)",
+ variables=["G", "m1", "m2", "r"],
+ samples=[
+ {"G": "6.67430e-11", "m1": "5.972e24", "m2": "7.348e22", "r": "3.844e8"},
+ {"G": "6.67430e-11", "m1": "1.989e30", "m2": "5.972e24", "r": "1.496e11"},
+ {"G": "6.67430e-11", "m1": "1.0e5", "m2": "2.0e5", "r": "3000"},
+ ],
+ negative_control=False,
+ ),
+ Fixture(
+ fixture_id="feynman_newton_gravity_negative",
+ route_surface="SRBench / Feynman",
+ truth_formula="G*m1*m2/(r**2)",
+ candidate_formula="G*m1*m2/r",
+ variables=["G", "m1", "m2", "r"],
+ samples=[
+ {"G": "6.67430e-11", "m1": "5.972e24", "m2": "7.348e22", "r": "3.844e8"},
+ {"G": "6.67430e-11", "m1": "1.989e30", "m2": "5.972e24", "r": "1.496e11"},
+ {"G": "6.67430e-11", "m1": "1.0e5", "m2": "2.0e5", "r": "3000"},
+ ],
+ negative_control=True,
+ ),
+ Fixture(
+ fixture_id="feynman_kinetic_energy_admit",
+ route_surface="DLMF / Feynman",
+ truth_formula="0.5*m*(v**2)",
+ candidate_formula="0.5*m*(v**2)",
+ variables=["m", "v"],
+ samples=[
+ {"m": "1.0", "v": "3.0"},
+ {"m": "2.5", "v": "4.0"},
+ {"m": "0.125", "v": "12.0"},
+ ],
+ negative_control=False,
+ ),
+]
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+def decimal_from_node(node: ast.AST, env: dict[str, Decimal]) -> Decimal:
+ if isinstance(node, ast.Expression):
+ return decimal_from_node(node.body, env)
+ if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+ return Decimal(str(node.value))
+ if isinstance(node, ast.Name):
+ if node.id not in env:
+ raise ValueError(f"unknown variable {node.id}")
+ return env[node.id]
+ if isinstance(node, ast.BinOp):
+ op_type = type(node.op)
+ if op_type not in ALLOWED_BINOPS:
+ raise ValueError(f"unsupported operator {op_type.__name__}")
+ return ALLOWED_BINOPS[op_type](decimal_from_node(node.left, env), decimal_from_node(node.right, env))
+ if isinstance(node, ast.UnaryOp):
+ op_type = type(node.op)
+ if op_type not in ALLOWED_UNARY:
+ raise ValueError(f"unsupported unary operator {op_type.__name__}")
+ return ALLOWED_UNARY[op_type](decimal_from_node(node.operand, env))
+ raise ValueError(f"unsupported expression node {type(node).__name__}")
+
+
+def evaluate(formula: str, sample: dict[str, str]) -> Decimal:
+ tree = ast.parse(formula, mode="eval")
+ env = {key: Decimal(value) for key, value in sample.items()}
+ return decimal_from_node(tree, env)
+
+
+def normalize_decimal(value: Decimal) -> str:
+ if value == 0:
+ return "0"
+ return format(value.normalize(), "E")
+
+
+def run_fixture(fixture: Fixture) -> dict[str, Any]:
+ rows = []
+ absolute_errors: list[Decimal] = []
+ for idx, sample in enumerate(fixture.samples):
+ truth = evaluate(fixture.truth_formula, sample)
+ candidate = evaluate(fixture.candidate_formula, sample)
+ error = abs(truth - candidate)
+ absolute_errors.append(error)
+ rows.append(
+ {
+ "sample_index": idx,
+ "sample": sample,
+ "truth": normalize_decimal(truth),
+ "candidate": normalize_decimal(candidate),
+ "absolute_error": normalize_decimal(error),
+ }
+ )
+
+ max_error = max(absolute_errors) if absolute_errors else Decimal(0)
+ replay_valid = max_error == 0
+ residual_declared = True
+ encoded_payload = {
+ "formula": fixture.candidate_formula,
+ "variables": fixture.variables,
+ "sample_count": len(fixture.samples),
+ }
+ explicit_payload = {
+ "truth_values": [row["truth"] for row in rows],
+ }
+ encoded_bytes = len(stable_json(encoded_payload).encode("utf-8"))
+ explicit_bytes = len(stable_json(explicit_payload).encode("utf-8"))
+ residual_bytes = 0 if replay_valid else len(stable_json({"errors": [row["absolute_error"] for row in rows]}).encode("utf-8"))
+ total_candidate_bytes = encoded_bytes + residual_bytes
+ byte_gain = explicit_bytes - total_candidate_bytes
+
+ # This fixture only admits exact deterministic replay. Byte gain is reported
+ # as a diagnostic because the sample is intentionally tiny.
+ status = "ADMIT_FIXTURE" if replay_valid and residual_declared and not fixture.negative_control else "HOLD"
+ if byte_gain <= 0:
+ status = "HOLD_DIAGNOSTIC"
+ if fixture.negative_control and replay_valid:
+ status = "FAIL_NEGATIVE_CONTROL"
+
+ result = {
+ "fixture_id": fixture.fixture_id,
+ "route_surface": fixture.route_surface,
+ "truth_formula": fixture.truth_formula,
+ "candidate_formula": fixture.candidate_formula,
+ "formula_hash": sha256_text(fixture.candidate_formula),
+ "negative_control": fixture.negative_control,
+ "rows": rows,
+ "max_absolute_error": normalize_decimal(max_error),
+ "replay_valid": replay_valid,
+ "residual_declared": residual_declared,
+ "encoded_bytes": encoded_bytes,
+ "explicit_bytes": explicit_bytes,
+ "residual_bytes": residual_bytes,
+ "byte_gain": byte_gain,
+ "status": status,
+ }
+ result["result_hash"] = sha256_text(stable_json({k: v for k, v in result.items() if k != "result_hash"}))
+ return result
+
+
+def main() -> int:
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+ results = [run_fixture(fixture) for fixture in FIXTURES]
+ with TABLE.open("w", encoding="utf-8") as handle:
+ for result in results:
+ handle.write(json.dumps(result, sort_keys=True) + "\n")
+ receipt = {
+ "schema": "symbolic_law_replay_receipt_v1",
+ "generated_at_utc": datetime.now(timezone.utc).isoformat(),
+ "fixture_count": len(results),
+ "table": rel(TABLE),
+ "status_counts": {status: sum(1 for result in results if result["status"] == status) for status in sorted({result["status"] for result in results})},
+ "results": results,
+ "decision": "HOLD",
+ "claim_boundary": (
+ "Tiny symbolic-law replay fixture only. It tests deterministic evaluation, "
+ "negative-control behavior, and residual accounting; it is not an SRBench score, "
+ "not an external dataset ingest, and not a compression benchmark."
+ ),
+ }
+ receipt["receipt_hash"] = sha256_text(stable_json({k: v for k, v in receipt.items() if k != "receipt_hash"}))
+ RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ print(json.dumps({"receipt": rel(RECEIPT), "table": rel(TABLE), "receipt_hash": receipt["receipt_hash"], "status_counts": receipt["status_counts"]}, indent=2, sort_keys=True))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/t16_candidate_pipeline_equation_prior.py b/4-Infrastructure/shim/t16_candidate_pipeline_equation_prior.py
new file mode 100644
index 00000000..8356c3b9
--- /dev/null
+++ b/4-Infrastructure/shim/t16_candidate_pipeline_equation_prior.py
@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Distill the T16 transit-search pipeline into an equation-mining prior.
+
+The source paper is an astronomy result, not an equation-discovery result. This
+runner records the transferable method shape: large uniform preprocessing,
+cheap candidate extraction, diagnostic feature expansion, regime-specific
+classifiers, automated vetting, and expensive confirmation only for survivors.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+RECEIPT = SHIM / "t16_candidate_pipeline_equation_prior_receipt.json"
+CURRICULUM = SHIM / "t16_candidate_pipeline_equation_prior_curriculum.jsonl"
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def build_receipt() -> dict[str, Any]:
+ bridge = {
+ "source": {
+ "arxiv": "2604.18579",
+ "title": (
+ "The T16 Planet Hunt: 10,000 New Planet Candidates from TESS "
+ "Cycle 1 and the Confirmation of a Hot Jupiter Around TIC 183374187"
+ ),
+ "doi": "10.48550/arXiv.2604.18579",
+ "related_doi": "10.3847/1538-4365/ae5b6c",
+ "source_claim": "large-scale machine-learning-assisted transit search",
+ },
+ "observed_source_shape": {
+ "input_count": 83_717_159,
+ "target_count": 54_401_549,
+ "candidate_count": 11_554,
+ "new_candidate_count": 10_091,
+ "single_transit_count": 411,
+ "validated_example": "TIC 183374187 radial-velocity confirmation",
+ },
+ "transferable_pipeline": [
+ "uniform_detrending_and_systematics_correction",
+ "cheap_linear_search_for_candidate_events",
+ "fold_candidate_over_period_grid",
+ "extract_harmonic_alias_features",
+ "train_regime_specific_random_forest_classifiers",
+ "drop_low_importance_or_noisy_features",
+ "apply_probability_thresholds",
+ "graph_vet_local_contamination",
+ "prune_overpopulated_systematic_bins",
+ "run_fast_physical_model_fit",
+ "run_image_or_context_residual_check",
+ "reserve_expensive_confirmation_for_survivors",
+ "record_injection_recovery_as_future_completeness_gate",
+ ],
+ "equation_adaptation": {
+ "equation_trace": (
+ "sequence of symbolic, numeric, unit, residual, and proof-state "
+ "observations extracted from an equation candidate"
+ ),
+ "detrending": (
+ "remove notation-specific, source-specific, and formatting-specific "
+ "systematics before scoring mathematical signal"
+ ),
+ "candidate_event": (
+ "localized invariant, residual collapse, dimensional consistency, "
+ "operator match, or compression-gain hint"
+ ),
+ "period_grid_analogue": (
+ "probe aliases such as scale, reciprocal, dual, Fourier, log, "
+ "normalization, and dimensional rescaling variants"
+ ),
+ "harmonic_features": [
+ "primary_score",
+ "half_scale_score",
+ "double_scale_score",
+ "triple_scale_score",
+ "inverse_candidate_score",
+ "delta_loss",
+ "residual_ratio",
+ "symbolic_depth",
+ "unit_consistency",
+ "domain_context",
+ ],
+ "regime_split": [
+ "small_closed_form_equations",
+ "high_dimensional_symbolic_systems",
+ "noisy_empirical_fits",
+ "compression_route_equations",
+ "physics_or_hardware_control_equations",
+ ],
+ "confirmation": [
+ "Lean_or_symbolic_check",
+ "numeric_reproduction",
+ "unit_and_dimension_check",
+ "held_out_data_check",
+ "exact_decode_hash_for_Hutter_use",
+ ],
+ },
+ "equation_prior": {
+ "score": (
+ "priority = cheap_signal_score + alias_consistency + context_support "
+ "- contamination_risk - systematic_bin_penalty - confirmation_cost"
+ ),
+ "promote_if": [
+ "candidate_survives_regime_classifier",
+ "local_contamination_or_duplicate_source_is_resolved",
+ "systematic_alias_bin_is_not_overpopulated",
+ "expensive_validator_confirms_the_claim",
+ "Hutter_use_has_exact_decode_hash_and_measured_bytes",
+ ],
+ "fail_closed_if": [
+ "source_context_is_unverified",
+ "candidate_only_exists_after_notation_detrending",
+ "alias_family_is_overpopulated_without_independent_support",
+ "classifier_probability_replaces_proof",
+ "manual_or_expensive_validator_rejects_candidate",
+ ],
+ },
+ "claim_boundary": (
+ "This receipt extracts a candidate-search method from an astronomy "
+ "pipeline. It is not evidence that transit-search features prove "
+ "equations, compression gains, or physical laws."
+ ),
+ }
+ bridge["receipt_hash"] = sha256_text(stable_json(bridge))
+ return bridge
+
+
+def write_curriculum(receipt: dict[str, Any]) -> None:
+ rows = [
+ {
+ "task": "map_transit_pipeline_to_equation_pipeline",
+ "input": "uniformly detrended light curves plus transit candidate vetting",
+ "target": "uniform equation traces plus proof/receipt candidate vetting",
+ },
+ {
+ "task": "separate_candidate_score_from_proof",
+ "input": "random forest probability and BLS/CETRA features",
+ "target": "equation priority only, never a proof substitute",
+ },
+ {
+ "task": "define_expensive_confirmation_boundary",
+ "input": "radial velocity and MCMC follow-up",
+ "target": "Lean/numeric/unit/Hutter exact-receipt validation",
+ },
+ ]
+ CURRICULUM.write_text(
+ "".join(json.dumps(row, sort_keys=True) + "\n" for row in rows),
+ encoding="utf-8",
+ )
+
+
+def main() -> None:
+ receipt = build_receipt()
+ RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ write_curriculum(receipt)
+ print(json.dumps({
+ "receipt": str(RECEIPT.relative_to(REPO)),
+ "curriculum": str(CURRICULUM.relative_to(REPO)),
+ "receipt_hash": receipt["receipt_hash"],
+ "candidate_count": receipt["observed_source_shape"]["candidate_count"],
+ "transferable_stage_count": len(receipt["transferable_pipeline"]),
+ }, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/tammes_focused_adversarial_hutter_prior.py b/4-Infrastructure/shim/tammes_focused_adversarial_hutter_prior.py
new file mode 100644
index 00000000..9a940b50
--- /dev/null
+++ b/4-Infrastructure/shim/tammes_focused_adversarial_hutter_prior.py
@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""Build a Tammes-focused adversarial route prior for Hutter work.
+
+The prior combines three shapes:
+
+* Tammes / spherical-code spacing: keep route candidates diverse by maximizing
+ nearest-neighbor distance on a route feature manifold.
+* Multimetal nanocrystal composition focusing: use staged scaffold decisions
+ that collapse a large theoretical frontier into a smaller lawful frontier.
+* Adversarial Conway-style tournament stress: hash rule/glyph candidates into
+ hostile local-interaction tests before spending promotion evaluator budget.
+
+This is a route-selection and stress-testing prior. It is not a compression
+result and does not promote any Hutter route without exact byte receipts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+OUT = SHIM / "tammes_focused_adversarial_hutter_prior_receipt.json"
+CURRICULUM_OUT = SHIM / "tammes_focused_adversarial_hutter_prior_curriculum.jsonl"
+
+GENERATED_AT = "2026-05-08T00:00:00+00:00"
+HUTTER_ENWIK9_TARGET_BYTES = 109_685_197
+
+SOURCE_RECEIPTS = {
+ "hutter_equation_metastate_transfold": SHIM
+ / "hutter_equation_metastate_transfold_receipt.json",
+ "multimetal_nanocrystal_composition_focusing_prior": SHIM
+ / "multimetal_nanocrystal_composition_focusing_prior_receipt.json",
+ "projectable_geometry_topology_model": SHIM
+ / "projectable_geometry_topology_model_receipt.json",
+}
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def receipt_hash(path: Path, data: dict[str, Any]) -> str:
+ for key in (
+ "receipt_hash",
+ "stable_topology_model_hash_sha256",
+ "stable_shell_dd_hash_sha256",
+ ):
+ value = data.get(key)
+ if isinstance(value, str):
+ return value
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def source_receipt_records(receipts: dict[str, dict[str, Any]]) -> dict[str, Any]:
+ return {
+ name: {
+ "path": rel(SOURCE_RECEIPTS[name]),
+ "schema": receipt.get("schema", "unknown"),
+ "hash": receipt_hash(SOURCE_RECEIPTS[name], receipt),
+ }
+ for name, receipt in receipts.items()
+ }
+
+
+def source_evidence() -> dict[str, Any]:
+ return {
+ "tammes_problem": {
+ "shape": "place N points on a sphere/manifold to maximize the minimum pairwise distance",
+ "route_use": "diversify route candidates and avoid wasting evaluator time on near-duplicates",
+ "reference_url": "https://mathworld.wolfram.com/SphericalCode.html",
+ "claim_status": "standard_geometry_prior",
+ },
+ "multimetal_nanocrystal": {
+ "title": "Researchers combine five metals to build a better nanocrystal",
+ "source": "Phys.org / Stanford University",
+ "published_date": "2026-05-07",
+ "url": "https://phys.org/news/2026-05-combine-metals-nanocrystal.html",
+ "primary_paper_doi": "10.1126/science.aea8044",
+ "route_use": "composition focusing / staged decision tree for lawful frontier collapse",
+ "claim_status": "verified_article_shape_not_byte_evidence",
+ },
+ "adversarial_conway_prompt": {
+ "title": "Adversarial Conway: Example Matches",
+ "source": "Reddit r/gameoflife",
+ "url": "https://www.reddit.com/r/gameoflife/comments/1t71s3m/adversarial_conway_example_matches/",
+ "observed_shape": "hashed contestant glyphs enter a tournament-like adversarial cellular-automaton arena",
+ "route_use": "stress route rules under hostile local interactions before promotion",
+ "claim_status": "community_prompt_not_peer_reviewed_source",
+ },
+ }
+
+
+def route_embedding() -> dict[str, Any]:
+ return {
+ "route_point": [
+ "transform_family_id",
+ "tokenbook_policy_id",
+ "residual_policy_id",
+ "witness_budget_class",
+ "decoder_cost_class",
+ "locality_profile_id",
+ "byte_gain_floor_class",
+ "failure_signature_id",
+ "adversarial_fragility_class",
+ "composition_focus_score",
+ ],
+ "metric": (
+ "d_route(i,j) = weighted distance over route_point fields, with "
+ "hard separation for incompatible residual or decoder policies"
+ ),
+ "normalization": (
+ "candidate coordinates are proposal features only; no coordinate "
+ "is promotion evidence until exact bytes are measured"
+ ),
+ }
+
+
+def equations() -> list[dict[str, str]]:
+ return [
+ {
+ "id": "TFA0_route_embedding",
+ "equation": "x_i = embed(route_i) in M_Hutter",
+ "meaning": "Represent each candidate route as a point on the Hutter feature manifold.",
+ },
+ {
+ "id": "TFA1_tammes_diversity",
+ "equation": "D_Tammes(R) = min_{i != j} d_route(x_i, x_j)",
+ "meaning": "Prefer route batches whose nearest candidates are still meaningfully separated.",
+ },
+ {
+ "id": "TFA2_composition_focus",
+ "equation": "F_focus = 1 - focused_frontier_size / theoretical_frontier_size",
+ "meaning": "Reward staged constraints that collapse the legal frontier without losing decode reachability.",
+ },
+ {
+ "id": "TFA3_decision_tree_attachment",
+ "equation": "node_{t+1} = attach(argmin_l cost(l | scaffold_t), node_t)",
+ "meaning": "Use nanocrystal-style staged attachment as a deterministic route decision tree.",
+ },
+ {
+ "id": "TFA4_adversarial_fragility",
+ "equation": "A_adv(route) = failed_stress_cases / total_stress_cases",
+ "meaning": "Measure how often a route rule breaks under hostile local rewrite / automaton tests.",
+ },
+ {
+ "id": "TFA5_priority_score",
+ "equation": (
+ "Priority = gain_floor + alpha*D_Tammes + beta*F_focus "
+ "- residual_floor - witness_floor - decoder_floor - gamma*A_adv"
+ ),
+ "meaning": "Rank what to evaluate next; this score never promotes by itself.",
+ },
+ {
+ "id": "TFA6_promotion",
+ "equation": "promote iff decode(route_artifact) == source and bytes_total < incumbent",
+ "meaning": "Promotion authority remains exact reconstruction and counted byte improvement.",
+ },
+ ]
+
+
+def dd_state_extension() -> list[str]:
+ return [
+ "tammes_route_lattice_id",
+ "route_feature_vector_id",
+ "route_manifold_chart_id",
+ "nearest_neighbor_distance_floor",
+ "tammes_diversity_score",
+ "composition_scaffold_id",
+ "decision_tree_node_id",
+ "attachment_order_receipt_id",
+ "focused_frontier_size",
+ "theoretical_frontier_size",
+ "composition_focus_score",
+ "adversarial_glyph_hash",
+ "adversarial_arena_id",
+ "stress_case_count",
+ "failed_stress_case_count",
+ "adversarial_fragility_score",
+ "route_priority_score",
+ "exact_residual_lane_id",
+ "byte_rehydration_hash",
+ ]
+
+
+def dd_edges() -> list[str]:
+ return [
+ "embed_route_on_hutter_manifold",
+ "compute_route_pair_distance",
+ "maximize_nearest_neighbor_route_distance",
+ "open_composition_scaffold_decision_tree",
+ "attach_route_lane_by_focus_cost",
+ "measure_frontier_collapse",
+ "hash_route_glyph_for_adversarial_arena",
+ "run_adversarial_conway_stress_cases",
+ "penalize_adversarial_fragility",
+ "rank_route_priority",
+ "reject_near_duplicate_route",
+ "emit_exact_residual_lane",
+ "close_with_byte_rehydration_hash",
+ ]
+
+
+def promotion_rule() -> list[str]:
+ return [
+ "route_batch_has_tammes_separation_above_floor",
+ "composition_scaffold_decision_tree_is_deterministic_or_receipted",
+ "frontier_collapse_preserves_decode_reachability",
+ "adversarial_stress_failures_are_zero_or_fail_closed_before_expensive_promotion",
+ "all residual/witness/decoder/container costs are counted",
+ "decoded_hash_matches_source_hash",
+ "measured_total_bytes_beat_incumbent_under_explicit_ratio_schema",
+ ]
+
+
+def failure_rule() -> list[str]:
+ return [
+ "tammes_route_points_collapse_to_near_duplicates -> prune_batch",
+ "decision_tree_attachment_ambiguous_without_tie_break -> fail_closed",
+ "focused_frontier_loses_decode_reachability -> fail_closed",
+ "adversarial_arena_generates_unbounded_rule_search -> NaN0",
+ "stress_survivorship_used_as_byte_evidence -> diagnostic_only",
+ "witness_or_stress_metadata_exceeds_byte_gain -> prune",
+ ]
+
+
+def current_hutter_context(receipts: dict[str, dict[str, Any]]) -> dict[str, Any]:
+ metastate = receipts["hutter_equation_metastate_transfold"]["current_best_metastate"]
+ return {
+ "current_route": metastate["transform_route"],
+ "source_corpus_id": metastate["source_corpus_id"],
+ "source_bytes": metastate["source_bytes"],
+ "compressed_total_bytes": metastate["compressed_total_bytes"],
+ "baseline_bytes": metastate["baseline_bytes"],
+ "margin_vs_baseline_bytes": metastate["margin_vs_baseline_bytes"],
+ "projected_enwik9_total_bytes": metastate["projected_enwik9_total_bytes"],
+ "projected_gap_to_hard_target_bytes": metastate[
+ "projected_gap_to_hard_target_bytes"
+ ],
+ "hard_target_bytes_enwik9": HUTTER_ENWIK9_TARGET_BYTES,
+ "route_use": (
+ "Use this prior to choose diverse, focused, adversarially stable "
+ "payload-transform trials before adding more witness bytes."
+ ),
+ }
+
+
+def build_receipt() -> dict[str, Any]:
+ receipts = {name: load_json(path) for name, path in SOURCE_RECEIPTS.items()}
+ receipt: dict[str, Any] = {
+ "schema": "tammes_focused_adversarial_hutter_prior_v1",
+ "generated_at": GENERATED_AT,
+ "runner": rel(Path(__file__)),
+ "source_evidence": source_evidence(),
+ "source_receipts": source_receipt_records(receipts),
+ "primary_decision": {
+ "name": "tammes_focused_adversarial_route_lattice",
+ "statement": (
+ "Adapt Tammes spacing to the Hutter feature manifold, use "
+ "nanocrystal-style staged decision trees to collapse route "
+ "frontiers, and add adversarial Conway-style local-interaction "
+ "stress before exact byte evaluation."
+ ),
+ },
+ "route_embedding": route_embedding(),
+ "equations": equations(),
+ "candidate_dd_state_extension": dd_state_extension(),
+ "candidate_dd_edges": dd_edges(),
+ "promotion_rule": promotion_rule(),
+ "failure_rule": failure_rule(),
+ "current_hutter_context": current_hutter_context(receipts),
+ "claim_boundary": (
+ "This is a route-prior and evaluator-scheduling artifact. Tammes "
+ "spacing, nanocrystal composition focusing, and adversarial Conway "
+ "stress do not prove compression. Hutter promotion still requires "
+ "exact decode, matching hashes, measured total bytes, explicit ratio "
+ "schema, and counted residual/witness/decoder/container costs."
+ ),
+ }
+ preimage = {key: value for key, value in receipt.items() if key != "receipt_hash"}
+ receipt["receipt_hash"] = sha256_text(stable_json(preimage))
+ return receipt
+
+
+def curriculum_lines(receipt: dict[str, Any]) -> list[dict[str, Any]]:
+ lines: list[dict[str, Any]] = []
+ for equation in receipt["equations"]:
+ lines.append({"type": "equation", **equation})
+ for edge in receipt["candidate_dd_edges"]:
+ lines.append({"type": "dd_edge", "edge": edge})
+ for rule in receipt["promotion_rule"]:
+ lines.append({"type": "promotion_rule", "rule": rule})
+ for rule in receipt["failure_rule"]:
+ lines.append({"type": "failure_rule", "rule": rule})
+ return lines
+
+
+def main() -> None:
+ receipt = build_receipt()
+ OUT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ lines = curriculum_lines(receipt)
+ CURRICULUM_OUT.write_text(
+ "".join(json.dumps(line, sort_keys=True) + "\n" for line in lines),
+ encoding="utf-8",
+ )
+ print(
+ json.dumps(
+ {
+ "receipt": rel(OUT),
+ "curriculum": rel(CURRICULUM_OUT),
+ "receipt_hash": receipt["receipt_hash"],
+ "equation_count": len(receipt["equations"]),
+ "dd_edge_count": len(receipt["candidate_dd_edges"]),
+ "current_route": receipt["current_hutter_context"]["current_route"],
+ },
+ indent=2,
+ sort_keys=True,
+ )
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/tammes_focused_adversarial_hutter_wiki8_trial.py b/4-Infrastructure/shim/tammes_focused_adversarial_hutter_wiki8_trial.py
new file mode 100644
index 00000000..51e48c5d
--- /dev/null
+++ b/4-Infrastructure/shim/tammes_focused_adversarial_hutter_wiki8_trial.py
@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Run the Tammes-focused adversarial route prior over wiki8 trial results.
+
+This consumes a real reversible compression approach receipt and asks:
+
+* does the Tammes/focus/adversarial priority select byte-winning routes?
+* does it prune near-duplicate or fragile candidates before promotion?
+* does it improve measured bytes over the existing best route?
+
+It does not invent a new transform. Improvement here means better route
+selection among already evaluated exact routes, not a new compressed payload.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from pathlib import Path
+from typing import Any
+
+
+REPO = Path(__file__).resolve().parents[2]
+SHIM = REPO / "4-Infrastructure" / "shim"
+DEFAULT_APPROACH = SHIM / "tammes_focused_adversarial_hutter_wiki8_approach_trial_receipt.json"
+PRIOR = SHIM / "tammes_focused_adversarial_hutter_prior_receipt.json"
+OUT = SHIM / "tammes_focused_adversarial_hutter_wiki8_trial_receipt.json"
+
+TOPOLOGY_WITNESS_BYTES = 16
+
+
+def stable_json(obj: Any) -> str:
+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_text(text: str) -> str:
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def rel(path: Path) -> str:
+ return str(path.relative_to(REPO))
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def route_key(route: dict[str, Any]) -> str:
+ return f"{route['transform']}->{route['codec']}"
+
+
+def feature_vector(route: dict[str, Any], raw_baseline: int) -> list[float]:
+ transform_index = {
+ "raw": 0.0,
+ "xml_token": 1.0,
+ "class_lane_boat": 2.0,
+ "delta_boat": 3.0,
+ }.get(route["transform"], 4.0)
+ codec_index = {
+ "stored": 0.0,
+ "zlib9": 1.0,
+ "bz2": 2.0,
+ "lzma": 3.0,
+ }.get(route["codec"], 4.0)
+ encoded = float(route["encoded_size"])
+ compressed = float(route["compressed_size"])
+ gain = float(raw_baseline - compressed)
+ ratio = float(route["ratio"])
+ metadata_cost = float(len(stable_json(route.get("metadata", {}))))
+ return [
+ transform_index / 4.0,
+ codec_index / 4.0,
+ min(encoded / max(1.0, compressed * 4.0), 4.0) / 4.0,
+ max(-1.0, min(1.0, gain / max(1.0, raw_baseline))),
+ min(ratio, 1.0),
+ min(metadata_cost / 2048.0, 1.0),
+ ]
+
+
+def euclidean(a: list[float], b: list[float]) -> float:
+ return math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))
+
+
+def nearest_distance(route: dict[str, Any], routes: list[dict[str, Any]], raw_baseline: int) -> float:
+ own = feature_vector(route, raw_baseline)
+ distances = [
+ euclidean(own, feature_vector(other, raw_baseline))
+ for other in routes
+ if other is not route
+ ]
+ return min(distances) if distances else 0.0
+
+
+def adversarial_fragility(route: dict[str, Any]) -> float:
+ """Cheap deterministic stress proxy for already-evaluated routes.
+
+ Real adversarial Conway stress will need a separate local rewrite arena.
+ This proxy penalizes routes that already failed rehydration, have unbounded
+ metadata, or expand badly before codec rescue.
+ """
+
+ if not route.get("rehydrated_ok"):
+ return 1.0
+ encoded = int(route["encoded_size"])
+ compressed = int(route["compressed_size"])
+ metadata = len(stable_json(route.get("metadata", {})))
+ expansion = max(0.0, encoded / max(1, compressed) - 4.0) / 8.0
+ metadata_pressure = metadata / 4096.0
+ return max(0.0, min(1.0, expansion + metadata_pressure))
+
+
+def focus_score(route: dict[str, Any], routes: list[dict[str, Any]]) -> float:
+ same_transform = [other for other in routes if other["transform"] == route["transform"]]
+ if not routes:
+ return 0.0
+ # Higher when this transform family is a small, coherent subfrontier and
+ # the selected route is the best member of that family.
+ family_fraction = len(same_transform) / len(routes)
+ best_family = min(same_transform, key=lambda item: item["compressed_size"])
+ best_bonus = 1.0 if best_family is route else 0.0
+ return max(0.0, min(1.0, (1.0 - family_fraction) * 0.5 + best_bonus * 0.5))
+
+
+def priority(route: dict[str, Any], routes: list[dict[str, Any]], raw_baseline: int) -> dict[str, Any]:
+ witness = 0 if route["transform"] == "raw" else TOPOLOGY_WITNESS_BYTES
+ total = int(route["compressed_size"]) + witness
+ gain_floor = (raw_baseline - total) / max(1, raw_baseline)
+ residual_floor = 0.0 if route.get("rehydrated_ok") else 1.0
+ witness_floor = witness / max(1, raw_baseline)
+ decoder_floor = {
+ "stored": 0.0,
+ "zlib9": 0.03,
+ "bz2": 0.05,
+ "lzma": 0.09,
+ }.get(route["codec"], 0.12)
+ tammes = nearest_distance(route, routes, raw_baseline)
+ focus = focus_score(route, routes)
+ adv = adversarial_fragility(route)
+ score = (
+ 8.0 * gain_floor
+ + 0.03 * tammes
+ + 0.03 * focus
+ - residual_floor
+ - witness_floor
+ - 0.15 * decoder_floor
+ - 0.03 * adv
+ )
+ return {
+ "route": route_key(route),
+ "transform": route["transform"],
+ "codec": route["codec"],
+ "compressed_bytes": int(route["compressed_size"]),
+ "witness_bytes": witness,
+ "total_bytes": total,
+ "gain_vs_raw_after_witness_bytes": raw_baseline - total,
+ "gain_floor": gain_floor,
+ "tammes_diversity": tammes,
+ "composition_focus": focus,
+ "adversarial_fragility": adv,
+ "decoder_floor": decoder_floor,
+ "priority": score,
+ "rehydrated_ok": bool(route.get("rehydrated_ok")),
+ }
+
+
+def unique_slices(slices: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ seen: set[tuple[str, int, str]] = set()
+ unique = []
+ for item in slices:
+ key = (
+ item.get("slice_name", ""),
+ int(item.get("source_bytes", 0)),
+ item.get("source_hash_sha256", ""),
+ )
+ if key in seen:
+ continue
+ seen.add(key)
+ unique.append(item)
+ return unique
+
+
+def evaluate_slice(item: dict[str, Any]) -> dict[str, Any]:
+ routes = item["results"]
+ raw_baseline = int(item["best_raw_baseline"]["compressed_size"])
+ scored = [priority(route, routes, raw_baseline) for route in routes]
+ selected = max(scored, key=lambda row: row["priority"])
+ measured_best = min(
+ scored,
+ key=lambda row: row["total_bytes"],
+ )
+ raw_best = min(
+ (row for row in scored if row["transform"] == "raw"),
+ key=lambda row: row["total_bytes"],
+ )
+ selected_is_measured_best = selected["route"] == measured_best["route"]
+ selected_beats_raw = selected["total_bytes"] < raw_best["total_bytes"]
+ measured_best_beats_raw = measured_best["total_bytes"] < raw_best["total_bytes"]
+ return {
+ "slice_name": item["slice_name"],
+ "source_path": item["source_path"],
+ "source_bytes": item["source_bytes"],
+ "source_hash_sha256": item["source_hash_sha256"],
+ "raw_best": raw_best,
+ "selected_by_tammes_prior": selected,
+ "measured_best_after_witness": measured_best,
+ "selected_is_measured_best": selected_is_measured_best,
+ "selected_beats_raw": selected_beats_raw,
+ "measured_best_beats_raw": measured_best_beats_raw,
+ "improvement_vs_existing_best_bytes": (
+ int(item["best"]["compressed_size"]) - selected["total_bytes"]
+ ),
+ "top_ranked_routes": sorted(scored, key=lambda row: row["priority"], reverse=True)[:6],
+ }
+
+
+def build_receipt(approach_path: Path) -> dict[str, Any]:
+ approach = load_json(approach_path)
+ prior = load_json(PRIOR)
+ wiki8_slices = [
+ item for item in approach.get("slices", [])
+ if Path(item.get("source_path", "")).name == "enwik8"
+ ]
+ slices = [evaluate_slice(item) for item in unique_slices(wiki8_slices)]
+ selected_best_count = sum(item["selected_is_measured_best"] for item in slices)
+ selected_win_count = sum(item["selected_beats_raw"] for item in slices)
+ measured_win_count = sum(item["measured_best_beats_raw"] for item in slices)
+ total_improvement_vs_existing = sum(
+ item["improvement_vs_existing_best_bytes"] for item in slices
+ )
+ receipt: dict[str, Any] = {
+ "schema": "tammes_focused_adversarial_hutter_wiki8_trial_v1",
+ "source_receipts": {
+ "approach_trial": {
+ "path": rel(approach_path),
+ "stable_approach_hash_sha256": approach.get("stable_approach_hash_sha256"),
+ },
+ "tammes_prior": {
+ "path": rel(PRIOR),
+ "receipt_hash": prior.get("receipt_hash"),
+ },
+ },
+ "trial_policy": {
+ "topology_witness_bytes_for_non_raw_routes": TOPOLOGY_WITNESS_BYTES,
+ "priority_formula": (
+ "8.0*gain_floor + 0.03*tammes + 0.03*focus - residual_floor "
+ "- witness_floor - 0.15*decoder_floor - 0.03*adversarial_fragility"
+ ),
+ "claim_boundary": (
+ "This trial selects among already evaluated reversible routes. "
+ "It does not add a new compressor or claim Hutter improvement."
+ ),
+ },
+ "summary": {
+ "input_slice_count_before_wiki8_filter": len(approach.get("slices", [])),
+ "slice_count": len(slices),
+ "selected_measured_best_count": selected_best_count,
+ "selected_beats_raw_count": selected_win_count,
+ "measured_best_beats_raw_count": measured_win_count,
+ "total_improvement_vs_existing_best_bytes": total_improvement_vs_existing,
+ "improved_existing_best": total_improvement_vs_existing > 0,
+ "all_selected_rehydrated": all(
+ item["selected_by_tammes_prior"]["rehydrated_ok"] for item in slices
+ ),
+ },
+ "slices": slices,
+ "verdict": (
+ "no_new_byte_improvement"
+ if total_improvement_vs_existing <= 0
+ else "selection_improved_existing_best"
+ ),
+ "claim_boundary": (
+ "Tammes/focus/adversarial scoring is an evaluator scheduling prior. "
+ "Measured bytes and exact rehydration remain the authority."
+ ),
+ }
+ preimage = {key: value for key, value in receipt.items() if key != "receipt_hash"}
+ receipt["receipt_hash"] = sha256_text(stable_json(preimage))
+ return receipt
+
+
+def main() -> None:
+ receipt = build_receipt(DEFAULT_APPROACH)
+ OUT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ print(json.dumps({
+ "receipt": rel(OUT),
+ "receipt_hash": receipt["receipt_hash"],
+ "summary": receipt["summary"],
+ "verdict": receipt["verdict"],
+ }, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/4-Infrastructure/shim/tang9k_hutter_symbol_surface.py b/4-Infrastructure/shim/tang9k_hutter_symbol_surface.py
new file mode 100644
index 00000000..a2d5dc46
--- /dev/null
+++ b/4-Infrastructure/shim/tang9k_hutter_symbol_surface.py
@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""Host harness for Tang9K Hutter/metaprobe symbol surface.
+
+This harness frames short compressed text tokens for the FPGA and computes the
+same substitution receipt in software. If --port is supplied and pyserial is
+installed, it also sends the frame over USB UART.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from pathlib import Path
+from typing import Iterable
+
+MAGIC_IN = 0xA5
+MAGIC_OUT = 0xA6
+VERSION = 0x01
+OP_SUBSTITUTE = 0x10
+
+
+def substitute(byte: int) -> tuple[int, bool]:
+ table = {
+ ord(" "): 0x0,
+ ord("e"): 0x1,
+ ord("E"): 0x1,
+ ord("t"): 0x2,
+ ord("T"): 0x2,
+ ord("a"): 0x3,
+ ord("A"): 0x3,
+ ord("o"): 0x4,
+ ord("O"): 0x4,
+ ord("i"): 0x5,
+ ord("I"): 0x5,
+ ord("n"): 0x6,
+ ord("N"): 0x6,
+ ord("s"): 0x7,
+ ord("S"): 0x7,
+ ord("r"): 0x8,
+ ord("R"): 0x8,
+ ord("h"): 0x9,
+ ord("H"): 0x9,
+ ord("l"): 0xA,
+ ord("L"): 0xA,
+ ord("d"): 0xB,
+ ord("c"): 0xC,
+ ord("C"): 0xC,
+ ord("u"): 0xD,
+ ord("U"): 0xD,
+ ord("F"): 0xE,
+ ord("D"): 0xF,
+ }
+ if byte in table:
+ return table[byte], True
+ return byte & 0xF, False
+
+
+def xor_crc(values: Iterable[int]) -> int:
+ crc = 0
+ for value in values:
+ crc ^= value & 0xFF
+ return crc
+
+
+def receipt_for_payload(payload: bytes) -> dict:
+ rolling_hash = 0xACE1
+ mapped = 0
+ literal = 0
+ codes = []
+ for byte in payload:
+ code, hit = substitute(byte)
+ codes.append({"byte": byte, "char": chr(byte), "code": code, "hit": hit})
+ rolling_hash = (((rolling_hash << 1) & 0xFFFF) | (rolling_hash >> 15)) ^ (
+ (0x10 if hit else 0x00) | code
+ )
+ if hit:
+ mapped += 1
+ else:
+ literal += 1
+ return {
+ "hash16": rolling_hash,
+ "mapped_count": mapped,
+ "literal_count": literal,
+ "codes": codes,
+ }
+
+
+def pbacs_cmyk_state_for_payload(payload: bytes) -> int:
+ error_acc = 0
+ stress_acc = 0
+ mapped_count = 0
+ literal_count = 0
+ for byte in payload:
+ code, hit = substitute(byte)
+ value_q16 = ((1 if hit else 0) << 15) | (code << 11)
+ candidate = value_q16 + error_acc
+ bit_out = 1 if candidate > 0x8000 else 0
+ error_acc = candidate - (0x10000 if bit_out else 0)
+ abs_error = abs(error_acc)
+ residual_term = (abs_error >> 4) & 0x3FFF
+ mismatch_term = ((literal_count & 0x0F) << 4) | (mapped_count & 0x0F)
+ mask_term = (1 if hit else 0) << 4
+ stress_acc = max(
+ 0,
+ min(
+ 0xFFFF,
+ stress_acc - (stress_acc >> 6) + residual_term + mismatch_term + mask_term,
+ ),
+ )
+ if hit:
+ mapped_count += 1
+ else:
+ literal_count += 1
+ return (stress_acc >> 14) & 0x03
+
+
+def led_reservoir_address(route_state: int, mapped_count: int) -> dict:
+ logical = ((route_state & 0x03) << 4) | (mapped_count & 0x0F)
+ physical_active_low = logical ^ 0x3F
+ return {
+ "schema": "tang9k_led_reservoir_address_v1",
+ "logical_bits": f"{logical:06b}",
+ "logical_hex": f"0x{logical:02x}",
+ "route_state": (logical >> 4) & 0x03,
+ "mapped_bucket": logical & 0x0F,
+ "physical_active_low_bits": f"{physical_active_low:06b}",
+ "physical_active_low_hex": f"0x{physical_active_low:02x}",
+ "meaning": "logical LED reservoir address is {PBACS/CMYK route_state[1:0], mapped_count[3:0]}; board LEDs are active low",
+ }
+
+
+def build_frame(seq: int, payload: bytes) -> bytes:
+ if len(payload) > 16:
+ raise ValueError("Surface-0 payload is limited to 16 bytes per frame")
+ frame = bytearray([MAGIC_IN, VERSION, seq & 0xFF, OP_SUBSTITUTE, len(payload)])
+ frame.extend(payload)
+ frame.append(xor_crc(frame))
+ return bytes(frame)
+
+
+def parse_glyph_ids(value: str) -> list[int]:
+ glyph_ids = []
+ for part in value.split(","):
+ part = part.strip()
+ if not part:
+ continue
+ glyph_ids.append(int(part, 0))
+ return glyph_ids
+
+
+def glyph_ids_to_surface_bytes(glyph_ids: list[int]) -> bytes:
+ if len(glyph_ids) > 16:
+ raise ValueError("Surface-0 accepts at most 16 glyph IDs per frame")
+ # Surface-0 works on bank-local glyph IDs. The host GlyphBook maps full
+ # Unicode/PUA/custom logograms to these low-byte hot-path banks.
+ return bytes(glyph_id & 0xFF for glyph_id in glyph_ids)
+
+
+def parse_receipt(frame: bytes) -> dict:
+ if len(frame) != 11 or frame[0] != MAGIC_OUT or frame[1] != VERSION:
+ raise ValueError(f"invalid receipt frame: {frame.hex()}")
+ if xor_crc(frame[:-1]) != frame[-1]:
+ raise ValueError("receipt checksum mismatch")
+ return {
+ "seq": frame[2],
+ "status": frame[3],
+ "payload_len": frame[4],
+ "opcode": frame[5],
+ "hash16": (frame[6] << 8) | frame[7],
+ "mapped_count": frame[8],
+ "literal_count": frame[9],
+ "crc": frame[10],
+ }
+
+
+def _read_receipt_candidate(ser, timeout_s: float = 0.75) -> bytes:
+ deadline = time.monotonic() + timeout_s
+ buf = bytearray()
+ while time.monotonic() < deadline:
+ chunk = ser.read(1)
+ if not chunk:
+ continue
+ buf.extend(chunk)
+ while buf and buf[0] != MAGIC_OUT:
+ del buf[0]
+ if len(buf) >= 11:
+ return bytes(buf[:11])
+ return bytes(buf)
+
+
+def send_serial(port: str, baud: int, frame: bytes, retries: int = 5, resync: bool = True) -> bytes:
+ try:
+ import serial # type: ignore
+ except ImportError as exc:
+ raise SystemExit("pyserial is required for --port mode") from exc
+
+ with serial.Serial(port, baudrate=baud, timeout=2) as ser:
+ time.sleep(0.05)
+ ser.reset_input_buffer()
+ ser.reset_output_buffer()
+ last = b""
+ for _ in range(max(1, retries)):
+ ser.reset_input_buffer()
+ if resync:
+ # If the FPGA UART parser is stranded in payload/CRC state,
+ # enough non-magic bytes complete the partial frame and return
+ # it to RX_WAIT_MAGIC. In wait state, these bytes are ignored.
+ ser.write(b"\x00" * 32)
+ ser.flush()
+ time.sleep(0.02)
+ ser.reset_input_buffer()
+ ser.write(frame)
+ ser.flush()
+ raw = _read_receipt_candidate(ser)
+ last = raw
+ try:
+ parsed = parse_receipt(raw)
+ if parsed["status"] == 0:
+ return raw
+ except ValueError:
+ pass
+ time.sleep(0.05)
+ return last
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--text", default="D0A37FEED", help="compressed token text")
+ parser.add_argument(
+ "--glyph-ids",
+ help="comma-separated logogram/GlyphBook IDs; e.g. 0xe101,0xe10f,0x42",
+ )
+ parser.add_argument("--seq", type=lambda x: int(x, 0), default=1)
+ parser.add_argument("--port", help="optional USB serial port, e.g. /dev/ttyUSB1")
+ parser.add_argument("--baud", type=int, default=115200)
+ parser.add_argument("--retries", type=int, default=5)
+ parser.add_argument("--out", type=Path)
+ args = parser.parse_args()
+
+ glyph_ids = parse_glyph_ids(args.glyph_ids) if args.glyph_ids else []
+ if glyph_ids:
+ payload = glyph_ids_to_surface_bytes(glyph_ids)
+ input_kind = "glyphbook_bank_ids"
+ input_value = [f"0x{glyph_id:x}" for glyph_id in glyph_ids]
+ else:
+ payload = args.text.encode("ascii")
+ input_kind = "ascii_metaprobe_token"
+ input_value = args.text
+ frame = build_frame(args.seq, payload)
+ expected = receipt_for_payload(payload)
+ result = {
+ "schema": "tang9k_hutter_symbol_surface_receipt_v1",
+ "claim_boundary": "FPGA accelerates substitution witness only; host owns full codec/decodec",
+ "input_kind": input_kind,
+ "input": input_value,
+ "surface_payload_hex": payload.hex(),
+ "frame_hex": frame.hex(),
+ "expected": expected,
+ "expected_led_reservoir": led_reservoir_address(
+ pbacs_cmyk_state_for_payload(payload), expected["mapped_count"]
+ ),
+ }
+
+ if args.port:
+ raw_receipt = send_serial(args.port, args.baud, frame, retries=args.retries)
+ result["hardware_receipt_hex"] = raw_receipt.hex()
+ if raw_receipt:
+ try:
+ parsed = parse_receipt(raw_receipt)
+ result["hardware_receipt"] = parsed
+ result["hardware_led_reservoir"] = led_reservoir_address(
+ pbacs_cmyk_state_for_payload(payload), parsed["mapped_count"]
+ )
+ result["hardware_matches_expected"] = (
+ parsed["status"] == 0
+ and parsed["hash16"] == expected["hash16"]
+ and parsed["mapped_count"] == expected["mapped_count"]
+ and parsed["literal_count"] == expected["literal_count"]
+ )
+ except ValueError as exc:
+ result["hardware_receipt"] = None
+ result["hardware_matches_expected"] = False
+ result["hardware_note"] = f"non-surface UART response: {exc}"
+ else:
+ result["hardware_receipt"] = None
+ result["hardware_matches_expected"] = False
+ result["hardware_note"] = "no UART receipt received; topology is present but expected bitstream may not be loaded"
+
+ text = json.dumps(result, indent=2)
+ if args.out:
+ args.out.parent.mkdir(parents=True, exist_ok=True)
+ args.out.write_text(text + "\n", encoding="utf-8")
+ print(text)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/4-Infrastructure/shim/tang9k_hutter_symbol_surface_hardware_probe_ttyUSB1.json b/4-Infrastructure/shim/tang9k_hutter_symbol_surface_hardware_probe_ttyUSB1.json
new file mode 100644
index 00000000..0e841f6a
--- /dev/null
+++ b/4-Infrastructure/shim/tang9k_hutter_symbol_surface_hardware_probe_ttyUSB1.json
@@ -0,0 +1,73 @@
+{
+ "schema": "tang9k_hutter_symbol_surface_receipt_v1",
+ "claim_boundary": "FPGA accelerates substitution witness only; host owns full codec/decodec",
+ "input_kind": "ascii_metaprobe_token",
+ "input": "D0A37FEED",
+ "surface_payload_hex": "443041333746454544",
+ "frame_hex": "a5010110094430413337464545448f",
+ "expected": {
+ "hash16": 55296,
+ "mapped_count": 6,
+ "literal_count": 3,
+ "codes": [
+ {
+ "byte": 68,
+ "char": "D",
+ "code": 15,
+ "hit": true
+ },
+ {
+ "byte": 48,
+ "char": "0",
+ "code": 0,
+ "hit": false
+ },
+ {
+ "byte": 65,
+ "char": "A",
+ "code": 3,
+ "hit": true
+ },
+ {
+ "byte": 51,
+ "char": "3",
+ "code": 3,
+ "hit": false
+ },
+ {
+ "byte": 55,
+ "char": "7",
+ "code": 7,
+ "hit": false
+ },
+ {
+ "byte": 70,
+ "char": "F",
+ "code": 14,
+ "hit": true
+ },
+ {
+ "byte": 69,
+ "char": "E",
+ "code": 1,
+ "hit": true
+ },
+ {
+ "byte": 69,
+ "char": "E",
+ "code": 1,
+ "hit": true
+ },
+ {
+ "byte": 68,
+ "char": "D",
+ "code": 15,
+ "hit": true
+ }
+ ]
+ },
+ "hardware_receipt_hex": "ff4bff88ff8c",
+ "hardware_receipt": null,
+ "hardware_matches_expected": false,
+ "hardware_note": "non-surface UART response: invalid receipt frame: ff4bff88ff8c"
+}
diff --git a/4-Infrastructure/shim/tang9k_ipc_worker/.gitignore b/4-Infrastructure/shim/tang9k_ipc_worker/.gitignore
new file mode 100644
index 00000000..b83d2226
--- /dev/null
+++ b/4-Infrastructure/shim/tang9k_ipc_worker/.gitignore
@@ -0,0 +1 @@
+/target/
diff --git a/4-Infrastructure/shim/tang9k_ipc_worker/Cargo.lock b/4-Infrastructure/shim/tang9k_ipc_worker/Cargo.lock
new file mode 100644
index 00000000..bfe704eb
--- /dev/null
+++ b/4-Infrastructure/shim/tang9k_ipc_worker/Cargo.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "tang9k_ipc_worker"
+version = "0.1.0"
diff --git a/4-Infrastructure/shim/tang9k_ipc_worker/Cargo.toml b/4-Infrastructure/shim/tang9k_ipc_worker/Cargo.toml
new file mode 100644
index 00000000..7bfdf05a
--- /dev/null
+++ b/4-Infrastructure/shim/tang9k_ipc_worker/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "tang9k_ipc_worker"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
diff --git a/4-Infrastructure/shim/tang9k_ipc_worker/src/main.rs b/4-Infrastructure/shim/tang9k_ipc_worker/src/main.rs
new file mode 100644
index 00000000..58879345
--- /dev/null
+++ b/4-Infrastructure/shim/tang9k_ipc_worker/src/main.rs
@@ -0,0 +1,486 @@
+#![allow(dead_code)]
+
+use std::env;
+use std::fs::OpenOptions;
+use std::io;
+use std::os::fd::AsRawFd;
+use std::path::PathBuf;
+use std::ptr::NonNull;
+use std::sync::atomic::{fence, AtomicU32, Ordering};
+use std::thread;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+const DEFAULT_RING: &str = "/dev/shm/tang9k_gpu_fpga_symbol_surface.ring";
+const MAGIC: &[u8; 4] = b"T9IP";
+const VERSION: u32 = 1;
+const HEADER_SIZE: usize = 64;
+const RECORD_SIZE: usize = 64;
+
+const HEADER_MAGIC_OFFSET: usize = 0;
+const HEADER_VERSION_OFFSET: usize = 4;
+const HEADER_SLOTS_OFFSET: usize = 8;
+const HEADER_WRITE_INDEX_OFFSET: usize = 12;
+const HEADER_READ_INDEX_OFFSET: usize = 16;
+
+const REC_STATUS_OFFSET: usize = 0;
+const REC_MODE_OFFSET: usize = 1;
+const REC_SEQ_OFFSET: usize = 2;
+const REC_PAYLOAD_OFFSET: usize = 4;
+const REC_EXPECTED_HASH_OFFSET: usize = 20;
+const REC_RECEIPT_HASH_OFFSET: usize = 22;
+const REC_MAPPED_OFFSET: usize = 24;
+const REC_LITERAL_OFFSET: usize = 25;
+const REC_HW_STATUS_OFFSET: usize = 26;
+const REC_PAYLOAD_LEN_OFFSET: usize = 27;
+const REC_TIMESTAMP_NS_OFFSET: usize = 28;
+
+const STATUS_EMPTY: u8 = 0;
+const STATUS_PENDING: u8 = 1;
+const STATUS_DONE: u8 = 2;
+const STATUS_ERROR: u8 = 3;
+
+#[allow(non_camel_case_types)]
+type c_void = core::ffi::c_void;
+
+unsafe extern "C" {
+ fn mmap(
+ addr: *mut c_void,
+ length: usize,
+ prot: i32,
+ flags: i32,
+ fd: i32,
+ offset: isize,
+ ) -> *mut c_void;
+ fn munmap(addr: *mut c_void, length: usize) -> i32;
+ fn msync(addr: *mut c_void, length: usize, flags: i32) -> i32;
+}
+
+const PROT_READ: i32 = 0x1;
+const PROT_WRITE: i32 = 0x2;
+const MAP_SHARED: i32 = 0x01;
+const MS_SYNC: i32 = 0x4;
+
+#[derive(Debug)]
+struct Config {
+ ring: PathBuf,
+ cmd: Command,
+}
+
+#[derive(Debug)]
+enum Command {
+ Abi,
+ Status,
+ Consume { max_records: usize, spin_ms: u64 },
+}
+
+struct RingMap {
+ ptr: NonNull,
+ len: usize,
+}
+
+#[derive(Clone, Debug)]
+struct Header {
+ version: u32,
+ slots: u32,
+ write_index: u32,
+ read_index: u32,
+}
+
+#[derive(Clone, Debug)]
+struct Receipt {
+ slot: u32,
+ seq: u16,
+ status: u8,
+ expected_hash: u16,
+ receipt_hash: u16,
+ mapped_count: u8,
+ literal_count: u8,
+}
+
+fn main() -> io::Result<()> {
+ let config = Config::from_args();
+ match config.cmd {
+ Command::Abi => {
+ println!(
+ "{{\"schema\":\"tang9k_ipc_worker_abi_v1\",\"header_size\":{},\"record_size\":{},\"default_ring\":\"{}\"}}",
+ HEADER_SIZE, RECORD_SIZE, DEFAULT_RING
+ );
+ Ok(())
+ }
+ Command::Status => {
+ let ring = RingMap::open(&config.ring)?;
+ let header = ring.header()?;
+ let counts = ring.status_counts(&header);
+ println!(
+ "{{\"schema\":\"tang9k_ipc_worker_status_v1\",\"ring\":\"{}\",\"header\":{{\"version\":{},\"slots\":{},\"write_index\":{},\"read_index\":{}}},\"status_counts\":{{\"0\":{},\"1\":{},\"2\":{},\"3\":{}}}}}",
+ config.ring.display(),
+ header.version,
+ header.slots,
+ header.write_index,
+ header.read_index,
+ counts[0],
+ counts[1],
+ counts[2],
+ counts[3],
+ );
+ Ok(())
+ }
+ Command::Consume {
+ max_records,
+ spin_ms,
+ } => {
+ let ring = RingMap::open(&config.ring)?;
+ let receipts = ring.consume(max_records, Duration::from_millis(spin_ms))?;
+ print_consume_report(&config.ring, &receipts);
+ Ok(())
+ }
+ }
+}
+
+impl Config {
+ fn from_args() -> Self {
+ let mut ring = PathBuf::from(DEFAULT_RING);
+ let mut cmd = None;
+ let mut max_records = 1usize;
+ let mut spin_ms = 0u64;
+
+ let mut args = env::args().skip(1);
+ while let Some(arg) = args.next() {
+ match arg.as_str() {
+ "--ring" => {
+ if let Some(value) = args.next() {
+ ring = PathBuf::from(value);
+ }
+ }
+ "abi" => cmd = Some(Command::Abi),
+ "status" => cmd = Some(Command::Status),
+ "consume" => {
+ cmd = Some(Command::Consume {
+ max_records,
+ spin_ms,
+ })
+ }
+ "--max-records" => {
+ if let Some(value) = args.next() {
+ max_records = value.parse().unwrap_or(1);
+ }
+ cmd = Some(Command::Consume {
+ max_records,
+ spin_ms,
+ });
+ }
+ "--spin-ms" => {
+ if let Some(value) = args.next() {
+ spin_ms = value.parse().unwrap_or(0);
+ }
+ cmd = Some(Command::Consume {
+ max_records,
+ spin_ms,
+ });
+ }
+ _ => {}
+ }
+ }
+
+ Self {
+ ring,
+ cmd: cmd.unwrap_or(Command::Status),
+ }
+ }
+}
+
+impl RingMap {
+ fn open(path: &PathBuf) -> io::Result {
+ let file = OpenOptions::new().read(true).write(true).open(path)?;
+ let len = file.metadata()?.len() as usize;
+ if len < HEADER_SIZE {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidData,
+ "ring is smaller than header",
+ ));
+ }
+
+ let raw = unsafe {
+ mmap(
+ std::ptr::null_mut(),
+ len,
+ PROT_READ | PROT_WRITE,
+ MAP_SHARED,
+ file.as_raw_fd(),
+ 0,
+ )
+ };
+ if raw as isize == -1 {
+ return Err(io::Error::last_os_error());
+ }
+ Ok(Self {
+ ptr: NonNull::new(raw.cast::()).expect("mmap returned null"),
+ len,
+ })
+ }
+
+ fn header(&self) -> io::Result {
+ let magic = self.bytes(HEADER_MAGIC_OFFSET, 4);
+ if magic != MAGIC {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidData,
+ "not a Tang9K IPC symbol surface ring",
+ ));
+ }
+ let version = self.load_u32(HEADER_VERSION_OFFSET, Ordering::Acquire);
+ let slots = self.load_u32(HEADER_SLOTS_OFFSET, Ordering::Acquire);
+ let write_index = self.load_u32(HEADER_WRITE_INDEX_OFFSET, Ordering::Acquire);
+ let read_index = self.load_u32(HEADER_READ_INDEX_OFFSET, Ordering::Acquire);
+ if version != VERSION {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidData,
+ format!("unsupported ring version {version}"),
+ ));
+ }
+ if HEADER_SIZE + (slots as usize * RECORD_SIZE) > self.len {
+ return Err(io::Error::new(
+ io::ErrorKind::InvalidData,
+ "ring header slot count exceeds mapped file size",
+ ));
+ }
+ Ok(Header {
+ version,
+ slots,
+ write_index,
+ read_index,
+ })
+ }
+
+ fn consume(&self, max_records: usize, spin: Duration) -> io::Result> {
+ let deadline = SystemTime::now() + spin;
+ let mut receipts = Vec::new();
+ while receipts.len() < max_records {
+ let Some(receipt) = self.consume_one()? else {
+ if spin.is_zero() || SystemTime::now() >= deadline {
+ break;
+ }
+ thread::yield_now();
+ continue;
+ };
+ receipts.push(receipt);
+ }
+ unsafe {
+ msync(self.ptr.as_ptr().cast::(), self.len, MS_SYNC);
+ }
+ Ok(receipts)
+ }
+
+ fn consume_one(&self) -> io::Result ")
+ in_code = False
+ else:
+ out.append("")
+ in_code = True
+ continue
+ if in_code:
+ out.append(html.escape(line))
+ continue
+ if not line.strip():
+ flush_para()
+ flush_list()
+ continue
+ if re.match(r"^(-{3,}|\*{3,}|_{3,})\s*$", line.strip()):
+ flush_para()
+ flush_list()
+ out.append("
")
+ continue
+ if line.startswith("# "):
+ flush_para()
+ flush_list()
+ out.append(f"{render_inline(line[2:].strip())}
")
+ elif line.startswith("## "):
+ flush_para()
+ flush_list()
+ out.append(f"{render_inline(line[3:].strip())}
")
+ elif line.startswith("### "):
+ flush_para()
+ flush_list()
+ out.append(f"{render_inline(line[4:].strip())}
")
+ elif line.startswith("> "):
+ flush_para()
+ flush_list()
+ out.append(f"{render_inline(line[2:].strip())}
")
+ elif line.startswith("- "):
+ flush_para()
+ list_items.append(line[2:].strip())
+ elif line.startswith("!["):
+ flush_para()
+ flush_list()
+ match = re.match(r"!\[(?P[^\]]*)\]\((?P[^)]+)\)", line)
+ if match:
+ out.append(
+ f")}\")
"
+ )
+ else:
+ para.append(line)
+ else:
+ flush_list()
+ para.append(line)
+ flush_para()
+ flush_list()
+ if in_code:
+ out.append(" ")
+ return "\n\n" + "\n".join(out) + "\n"
+
+
+def prepare(markdown_path: Path, output_dir: Path | None = None) -> dict:
+ markdown_path = markdown_path.resolve()
+ source_dir = markdown_path.parent
+ raw = markdown_path.read_text(encoding="utf-8")
+ title = next((line[2:].strip() for line in raw.splitlines() if line.startswith("# ")), markdown_path.stem)
+ subtitle = next((line[3:].strip() for line in raw.splitlines() if line.startswith("## ")), "")
+ bundle_dir = (output_dir or source_dir / "substack_bundle").resolve()
+ assets_dir = bundle_dir / "assets"
+ assets_dir.mkdir(parents=True, exist_ok=True)
+
+ converted: list[str] = []
+ copied_assets: list[str] = []
+ missing_assets: list[str] = []
+
+ for line in raw.splitlines():
+ match = IMAGE_RE.match(line)
+ if not match:
+ converted.append(line)
+ continue
+ name = match.group("name").strip()
+ src = (source_dir / name).resolve()
+ if src.exists() and src.is_file():
+ dest = assets_dir / src.name
+ shutil.copy2(src, dest)
+ copied_assets.append(str(dest))
+ converted.append(f"")
+ else:
+ missing_assets.append(name)
+ converted.append(f"")
+
+ post_md = bundle_dir / "post.md"
+ post_html = bundle_dir / "post.html"
+ manifest = bundle_dir / "manifest.json"
+ converted_text = "\n".join(converted).rstrip() + "\n"
+ post_md.write_text(converted_text, encoding="utf-8")
+ post_html.write_text(markdown_to_basic_html(converted_text), encoding="utf-8")
+
+ data = {
+ "title": title,
+ "subtitle": subtitle,
+ "slug": slugify_title(title),
+ "source": str(markdown_path),
+ "bundle_dir": str(bundle_dir),
+ "post_md": str(post_md),
+ "post_html": str(post_html),
+ "copied_assets": copied_assets,
+ "missing_assets": missing_assets,
+ }
+ manifest.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+ return data
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Prepare a Markdown draft for Substack.")
+ parser.add_argument("markdown_path", type=Path)
+ parser.add_argument("--output-dir", type=Path)
+ args = parser.parse_args()
+ print(json.dumps(prepare(args.markdown_path, args.output_dir), indent=2))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/5-Applications/plugins/substack-connector/scripts/substack_mcp_server.py b/5-Applications/plugins/substack-connector/scripts/substack_mcp_server.py
new file mode 100755
index 00000000..02e93834
--- /dev/null
+++ b/5-Applications/plugins/substack-connector/scripts/substack_mcp_server.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Tiny JSON-RPC tool surface for the repo-local Substack helper.
+
+This implements just enough MCP-style JSON-RPC for future local plugin use.
+The CLI helper remains the canonical path in normal shell workflows.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from prepare_substack_post import prepare
+
+
+TOOLS = [
+ {
+ "name": "prepare_substack_post",
+ "description": "Prepare a local Markdown draft and assets for Substack import.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "markdown_path": {"type": "string"},
+ "output_dir": {"type": "string"},
+ },
+ "required": ["markdown_path"],
+ },
+ }
+]
+
+
+def respond(request_id, result=None, error=None) -> None:
+ payload = {"jsonrpc": "2.0", "id": request_id}
+ if error is not None:
+ payload["error"] = {"code": -32000, "message": str(error)}
+ else:
+ payload["result"] = result
+ print(json.dumps(payload), flush=True)
+
+
+def handle(message: dict) -> None:
+ method = message.get("method")
+ request_id = message.get("id")
+ params = message.get("params") or {}
+
+ try:
+ if method == "initialize":
+ respond(request_id, {"protocolVersion": "2024-11-05", "serverInfo": {"name": "substack-connector", "version": "0.1.0"}, "capabilities": {"tools": {}}})
+ elif method == "tools/list":
+ respond(request_id, {"tools": TOOLS})
+ elif method == "tools/call":
+ name = params.get("name")
+ args = params.get("arguments") or {}
+ if name != "prepare_substack_post":
+ raise ValueError(f"unknown tool: {name}")
+ output_dir = Path(args["output_dir"]) if args.get("output_dir") else None
+ data = prepare(Path(args["markdown_path"]), output_dir)
+ respond(request_id, {"content": [{"type": "text", "text": json.dumps(data, indent=2)}]})
+ else:
+ respond(request_id, {})
+ except Exception as exc:
+ respond(request_id, error=exc)
+
+
+def main() -> int:
+ for line in sys.stdin:
+ if not line.strip():
+ continue
+ handle(json.loads(line))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/5-Applications/plugins/substack-connector/scripts/update_existing_post.py b/5-Applications/plugins/substack-connector/scripts/update_existing_post.py
new file mode 100644
index 00000000..65ae548d
--- /dev/null
+++ b/5-Applications/plugins/substack-connector/scripts/update_existing_post.py
@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Update an existing Substack post from a prepared local Markdown bundle."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from dotenv import load_dotenv
+from substack import Api
+from substack.post import Post
+
+
+def markdown_body_without_title(markdown: str) -> tuple[str, str, str]:
+ lines = markdown.splitlines()
+ title = ""
+ subtitle = ""
+ body_start = 0
+ if lines and lines[0].startswith("# "):
+ title = lines[0][2:].strip()
+ body_start = 1
+ if len(lines) > 1 and lines[1].startswith("## "):
+ subtitle = lines[1][3:].strip()
+ body_start = 2
+ while body_start < len(lines) and not lines[body_start].strip():
+ body_start += 1
+ return title, subtitle, "\n".join(lines[body_start:]).strip() + "\n"
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description="Update an existing Substack post from local Markdown.")
+ parser.add_argument("markdown_path", type=Path)
+ parser.add_argument("--post-id", type=int, required=True)
+ parser.add_argument("--env-path", type=Path, default=Path.home() / ".substack.env")
+ parser.add_argument("--publication-url", default="https://froginnponds.substack.com")
+ parser.add_argument("--publish", action="store_true", help="Publish the updated draft without sending email.")
+ args = parser.parse_args()
+
+ load_dotenv(args.env_path)
+ cookies = os.getenv("COOKIES_STRING")
+ if not cookies:
+ raise SystemExit("COOKIES_STRING is missing from the Substack env file")
+
+ markdown_path = args.markdown_path.resolve()
+ markdown = markdown_path.read_text(encoding="utf-8")
+ title, subtitle, body_markdown = markdown_body_without_title(markdown)
+ if not title:
+ raise SystemExit("Markdown must start with a # title")
+
+ api = Api(cookies_string=cookies, publication_url=args.publication_url)
+ user_id = api.get_user_id()
+ existing = api.get_draft(args.post_id)
+
+ backup_dir = markdown_path.parent / "substack_backups"
+ backup_dir.mkdir(parents=True, exist_ok=True)
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+ backup_path = backup_dir / f"post_{args.post_id}_{stamp}.json"
+ backup_path.write_text(json.dumps(existing, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+ cwd = Path.cwd()
+ try:
+ os.chdir(markdown_path.parent)
+ post = Post(
+ title=title,
+ subtitle=subtitle,
+ user_id=user_id,
+ audience=existing.get("audience") or "everyone",
+ write_comment_permissions=existing.get("write_comment_permissions") or "everyone",
+ )
+ post.from_markdown(body_markdown, api=api)
+ finally:
+ os.chdir(cwd)
+
+ payload = post.get_draft()
+ payload["draft_bylines"] = existing.get("draft_bylines") or payload.get("draft_bylines")
+ payload["draft_section_id"] = existing.get("draft_section_id")
+ payload["section_chosen"] = existing.get("section_chosen", True)
+
+ updated = api.put_draft(args.post_id, **payload)
+ print(json.dumps({
+ "updated_post_id": args.post_id,
+ "title": title,
+ "subtitle": subtitle,
+ "backup_path": str(backup_path),
+ "draft_updated_at": updated.get("draft_updated_at"),
+ "is_published": updated.get("is_published"),
+ "published": False,
+ }, indent=2))
+
+ if args.publish:
+ api.prepublish_draft(args.post_id)
+ published = api.publish_draft(args.post_id, send=False, share_automatically=False)
+ print(json.dumps({
+ "published": True,
+ "post_id": args.post_id,
+ "slug": published.get("slug"),
+ "canonical_url": published.get("canonical_url") or published.get("canonicalUrl"),
+ }, indent=2))
+
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/5-Applications/scripts/.prover_config.json.example b/5-Applications/scripts/.prover_config.json.example
new file mode 100644
index 00000000..53a10a40
--- /dev/null
+++ b/5-Applications/scripts/.prover_config.json.example
@@ -0,0 +1,17 @@
+{
+ "backend": "ollama",
+ "model": "zeyu-zheng/BFS-Prover-V2-7B:q8_0",
+ "backends": {
+ "ollama": {
+ "host": "localhost",
+ "port": 11434
+ },
+ "unsloth": {
+ "model_path": "unsloth/llama-3-8b-bnb-4bit"
+ },
+ "thoth": {
+ "api_key": "YOUR_THOTH_API_KEY",
+ "endpoint": "http://localhost:8000"
+ }
+ }
+}
diff --git a/scripts/SCIENCEHUB_README.md b/5-Applications/scripts/SCIENCEHUB_README.md
similarity index 100%
rename from scripts/SCIENCEHUB_README.md
rename to 5-Applications/scripts/SCIENCEHUB_README.md
diff --git a/5-Applications/scripts/adaptive_research_analysis.py b/5-Applications/scripts/adaptive_research_analysis.py
new file mode 100644
index 00000000..9ab733fe
--- /dev/null
+++ b/5-Applications/scripts/adaptive_research_analysis.py
@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["requests", "rich"]
+# ///
+"""
+Adaptive Research Stack Analyzer
+Uses Ollama Cloud API to run a three-pass analysis:
+ 1. Summarize - distill key ideas from core documents
+ 2. Cross-link - find connections across domains
+ 3. Critique - identify gaps, weak claims, missing proofs
+
+Usage:
+ uv run scripts/adaptive_research_analysis.py
+ uv run scripts/adaptive_research_analysis.py --model gemma3:12b --out /tmp/analysis.md
+"""
+
+import argparse
+import datetime
+import json
+import os
+import sys
+import textwrap
+from pathlib import Path
+
+import requests
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+RESEARCH_ROOT = Path("/home/allaun/Documents/Research Stack")
+API_BASE = "https://ollama.com/v1"
+API_KEY = os.environ.get("OLLAMA_API_KEY", "")
+# Model priority: cogito (Cognition 671B) → qwen3-next (80B) → gemma4 (31B) → deepseek-v4-flash
+DEFAULT_MODEL = "cogito-2.1:671b"
+FALLBACK_CHAIN = ["qwen3-next:80b", "gemma4:31b", "deepseek-v4-flash"]
+
+# Key documents to feed into the analysis (relative to RESEARCH_ROOT)
+CORE_DOCS = [
+ "README.md",
+ "CONCEPTS.md",
+ "ARCHITECTURE.md",
+ "SIGNAL_THEORY_COMPENDIUM.md",
+ "6-Documentation/EXPLANATION_FOR_HUMANS.md",
+ "6-Documentation/MATH_CORE.md",
+ "6-Documentation/VISION_NORTH_STAR.md",
+ "6-Documentation/GLOSSARY.md",
+ "6-Documentation/FIRST_PRINCIPLES_DAG.md",
+ "6-Documentation/FIELD_EQUATION_COMPARISON.md",
+ "6-Documentation/docs/SKEPTICISM_GRADIENT_REASSESSMENT_2026-04-29.md",
+ "6-Documentation/docs/CLAIM_STATE_AUDIT_2026-05-05.md",
+ "6-Documentation/docs/IMPLEMENTATION_ATTACK_ANALYSIS.md",
+ "6-Documentation/docs/ENE_RESEARCH_TOPIC_CANDIDATES.md",
+ "6-Documentation/docs/OTOM_V1_PAPER_STRUCTURE_AND_NEXT_GEN_SIMULATOR.md",
+ "6-Documentation/docs/stack_solidification_staging_manifest_2026-05-10.md",
+ "6-Documentation/docs/cross_domain_adaptation_numeric_review.md",
+ "6-Documentation/docs/BAD_MATH_CLEANUP_REPORT.md",
+]
+
+DOMAIN_DIRS = {
+ "Core Formalism (Lean)": "0-Core-Formalism",
+ "Distributed Systems": "1-Distributed-Systems",
+ "Search Space": "2-Search-Space",
+ "Mathematical Models": "3-Mathematical-Models",
+ "Infrastructure / FPGA": "4-Infrastructure",
+ "Applications": "5-Applications",
+ "Documentation": "6-Documentation/docs",
+}
+
+MAX_CHARS_PER_DOC = 8_000 # truncate individual docs (DeepSeek handles large context)
+MAX_CONTEXT_CHARS = 120_000 # total context fed per LLM call
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def load_doc(path: Path, max_chars: int = MAX_CHARS_PER_DOC) -> str:
+ try:
+ text = path.read_text(errors="replace")
+ if len(text) > max_chars:
+ text = text[:max_chars] + f"\n\n[... truncated at {max_chars} chars ...]"
+ return text
+ except Exception as e:
+ return f"[Could not read {path}: {e}]"
+
+
+def gather_context() -> str:
+ """Load core docs and first-file samples from each domain directory."""
+ parts = []
+
+ # Core documents
+ for rel in CORE_DOCS:
+ p = RESEARCH_ROOT / rel
+ if p.exists():
+ parts.append(f"\n\n---\n## FILE: {rel}\n\n{load_doc(p)}")
+
+ # Domain directory samples — grab up to 3 .md files per domain
+ for domain, rel_dir in DOMAIN_DIRS.items():
+ d = RESEARCH_ROOT / rel_dir
+ if not d.is_dir():
+ continue
+ md_files = sorted(d.glob("*.md"))[:3]
+ for mdf in md_files:
+ rel_path = mdf.relative_to(RESEARCH_ROOT)
+ parts.append(f"\n\n---\n## FILE [{domain}]: {rel_path}\n\n{load_doc(mdf, 3000)}")
+
+ combined = "\n".join(parts)
+ if len(combined) > MAX_CONTEXT_CHARS:
+ combined = combined[:MAX_CONTEXT_CHARS] + "\n\n[... context truncated ...]"
+ return combined
+
+
+def chat(model: str, system: str, user: str, label: str, retries: int = 3) -> str:
+ """Call Ollama Cloud chat completions endpoint with retry + fallback."""
+ import time
+
+ headers = {
+ "Authorization": f"Bearer {API_KEY}",
+ "Content-Type": "application/json",
+ }
+
+ models_to_try = [model] + [m for m in FALLBACK_CHAIN if m != model]
+
+ for attempt_model in models_to_try:
+ payload = {
+ "model": attempt_model,
+ "messages": [
+ {"role": "system", "content": system},
+ {"role": "user", "content": user},
+ ],
+ "stream": False,
+ "options": {"temperature": 0.3, "num_predict": 8192},
+ }
+ for attempt in range(1, retries + 1):
+ with Progress(
+ SpinnerColumn(),
+ TextColumn(f"[bold cyan]{label}[/bold cyan] (model: {attempt_model}, attempt {attempt}/{retries}) ..."),
+ transient=True,
+ console=console,
+ ) as progress:
+ progress.add_task("", total=None)
+ try:
+ resp = requests.post(
+ f"{API_BASE}/chat/completions",
+ headers=headers,
+ json=payload,
+ timeout=600,
+ )
+ except requests.exceptions.Timeout:
+ console.print(f"[yellow]Timeout on attempt {attempt}, retrying...[/yellow]")
+ time.sleep(5 * attempt)
+ continue
+
+ if resp.status_code == 200:
+ data = resp.json()
+ content = data["choices"][0]["message"]["content"]
+ # Strip