gea-program 0.1.0__py3-none-any.whl

gea/config_versioning.py

@@ -0,0 +1,133 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""config_versioning — version-controlled configuration with export, import
+and rollback (SOW 4.2.1.4 change and continuity; 4.2.24 audit trail).
+
+Every configuration the program runs on - the well-test criteria file, the
+alarm definitions, the tag catalogue, the drift-monitor thresholds - is
+committed here as a numbered version with author, note, timestamp, sha256
+and a key-level diff against the previous version. Nothing is ever deleted:
+a rollback is a new version whose content equals an older one, recorded as
+such. `export` writes any version to a file; `import_file` commits a file.
+
+Store layout (one directory):
+
+    <dir>/<name>/v0001.json      the content
+    <dir>/<name>/history.jsonl   one line per version: meta + diff summary
+
+Headless-safe: standard library only.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+def _iso(dt: Optional[datetime] = None) -> str:
+    dt = dt or datetime.now(timezone.utc)
+    return dt.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+def _sha(obj: Any) -> str:
+    return hashlib.sha256(json.dumps(obj, sort_keys=True, default=str).encode('utf-8')).hexdigest()[:16]
+
+
+def _flatten(obj: Any, prefix: str = '') -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            out.update(_flatten(v, f'{prefix}{k}.'))
+    elif isinstance(obj, list):
+        for i, v in enumerate(obj):
+            out.update(_flatten(v, f'{prefix}[{i}].'))
+    else:
+        out[prefix[:-1]] = obj
+    return out
+
+
+def diff(old: Any, new: Any) -> dict:
+    a, b = _flatten(old), _flatten(new)
+    added = sorted(k for k in b if k not in a)
+    removed = sorted(k for k in a if k not in b)
+    changed = sorted(k for k in a if k in b and a[k] != b[k])
+    return {'added': added, 'removed': removed,
+            'changed': [{'key': k, 'before': a[k], 'after': b[k]} for k in changed],
+            'n_changes': len(added) + len(removed) + len(changed)}
+
+
+class ConfigStore:
+    def __init__(self, root: str):
+        self.root = str(root)
+        os.makedirs(self.root, exist_ok=True)
+
+    def _dir(self, name: str) -> str:
+        d = os.path.join(self.root, name)
+        os.makedirs(d, exist_ok=True)
+        return d
+
+    def history(self, name: str) -> List[dict]:
+        p = os.path.join(self._dir(name), 'history.jsonl')
+        if not os.path.exists(p):
+            return []
+        with open(p, encoding='utf-8') as f:
+            return [json.loads(l) for l in f if l.strip()]
+
+    def latest_version(self, name: str) -> int:
+        h = self.history(name)
+        return h[-1]['version'] if h else 0
+
+    def get(self, name: str, version: Optional[int] = None) -> Any:
+        v = version or self.latest_version(name)
+        if v == 0:
+            raise KeyError(f'no versions of {name}')
+        with open(os.path.join(self._dir(name), f'v{v:04d}.json'), encoding='utf-8') as f:
+            return json.load(f)
+
+    def commit(self, name: str, content: Any, author: str, note: str = '', now: Optional[datetime] = None,
+               rollback_of: Optional[int] = None) -> dict:
+        prev_v = self.latest_version(name)
+        prev = self.get(name, prev_v) if prev_v else None
+        if prev is not None and _sha(prev) == _sha(content) and rollback_of is None:
+            return {'name': name, 'version': prev_v, 'unchanged': True, 'sha256': _sha(content)}
+        v = prev_v + 1
+        with open(os.path.join(self._dir(name), f'v{v:04d}.json'), 'w', encoding='utf-8') as f:
+            json.dump(content, f, indent=1, sort_keys=True, default=str)
+        meta = {'name': name, 'version': v, 'timestamp_utc': _iso(now), 'author': author, 'note': note,
+                'sha256': _sha(content), 'previous_version': prev_v or None,
+                'diff': diff(prev, content) if prev is not None else {'added': sorted(_flatten(content)), 'removed': [], 'changed': [], 'n_changes': len(_flatten(content))},
+                'rollback_of': rollback_of}
+        with open(os.path.join(self._dir(name), 'history.jsonl'), 'a', encoding='utf-8') as f:
+            f.write(json.dumps(meta, default=str) + '\n')
+        return meta
+
+    def import_file(self, name: str, path: str, author: str, note: str = '', now: Optional[datetime] = None) -> dict:
+        with open(path, encoding='utf-8') as f:
+            content = json.load(f)
+        return self.commit(name, content, author, note or f'imported from {os.path.basename(path)}', now=now)
+
+    def export(self, name: str, path: str, version: Optional[int] = None) -> str:
+        with open(path, 'w', encoding='utf-8') as f:
+            json.dump(self.get(name, version), f, indent=1, sort_keys=True)
+        return path
+
+    def rollback(self, name: str, to_version: int, author: str, note: str = '', now: Optional[datetime] = None) -> dict:
+        target = self.get(name, to_version)
+        return self.commit(name, target, author, note or f'rollback to v{to_version:04d}', now=now, rollback_of=to_version)
+
+    def names(self) -> List[str]:
+        return sorted(d for d in os.listdir(self.root) if os.path.isdir(os.path.join(self.root, d)))
+
+    def summary(self) -> List[dict]:
+        out = []
+        for n in self.names():
+            h = self.history(n)
+            if h:
+                out.append({'name': n, 'versions': len(h), 'latest': h[-1]['version'], 'sha256': h[-1]['sha256'],
+                            'last_change_utc': h[-1]['timestamp_utc'], 'last_author': h[-1]['author'],
+                            'rollbacks': sum(1 for e in h if e.get('rollback_of'))})
+        return out

gea/correlation.py

@@ -0,0 +1,155 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""correlation - Part 4 of the subsurface surveying tool: WELL-TO-WELL
+CORRELATION (v1.81.0), with the honest finding stated up front.
+
+THE FINDING (2026-08-29, and re-verified on every run): with 29 globally
+scattered sites, the library currently supports ZERO cross-site depth-frame
+correlations - every candidate pair (CaCO3 Barbados x Walvis, thermal
+conductivity Hikurangi x Prydz, friction coefficient Barbados x Costa Rica)
+has overlapping depth RANGES but too few coinciding SAMPLES (max 3 common
+bins against a floor of 5). The engine reports that refusal census instead
+of manufacturing correlations, and the machinery stands ready for the data
+that will change the answer (co-located suites, twin holes, denser columns).
+
+WHERE THE REAL STRUCTURE LIVES - THE TIME FRAME: four sites carry archive
+age models, and one (the ACEX Lomonosov Ridge age-depth model, 0-55,904 ka)
+is the library's MASTER CHRONOLOGY, whose window overlaps every other
+age-bearing site (Bengal 0.5-193.5 ka; EPICA 611-799 ka; Fram 12,050-17,370
+ka). Time is the Earth Model's fourth axis, and this module registers it.
+
+DISTANCE HONESTY (doctrine): a statistical correlation between sites more
+than CONTINUITY_KM apart is NEVER presented as geological continuity -
+the continuity_claim field says 'NONE' with the distance printed. Only
+twin holes (< CONTINUITY_KM) may claim physical continuity, and none
+currently qualify with shared properties.
+"""
+
+from __future__ import annotations
+
+import collections
+import math
+import re
+import statistics
+from typing import Dict, List
+
+from .earth_model import EarthModel, haversine_km
+
+CONTINUITY_KM = 5.0        # beyond this, correlation is statistics, not strata
+MIN_COMMON_BINS = 5        # below this, the pair REFUSES (disclosed)
+TARGET_BINS = 8            # default overlap resolution (disclosed)
+
+_AGE_WORD = re.compile(r'\bage\b', re.IGNORECASE)
+
+
+def _family(prop: str) -> str:
+    return prop.split(' [')[0].split(' (')[0].strip().lower()
+
+
+def time_frame(em: EarthModel = None) -> Dict:
+    """The library's fourth axis: every archive age model, its window, the
+    pairwise epoch overlaps, and the master chronology (the site whose
+    window overlaps the most others)."""
+    em = em or EarthModel()
+    ages = []
+    for s in em.sites.values():
+        for r in s.records:
+            if _AGE_WORD.search(r.property) and 'ka' in (r.unit or '').lower():
+                vals = [v for v in r.values if v == v]
+                if vals:
+                    ages.append({'site': s.key, 'entry': r.entry,
+                                 'property': r.property, 'unit': r.unit,
+                                 'age_min_ka': min(vals), 'age_max_ka': max(vals)})
+    overlaps = []
+    for i in range(len(ages)):
+        for j in range(i + 1, len(ages)):
+            a, b = ages[i], ages[j]
+            if a['site'] == b['site']:
+                continue
+            lo = max(a['age_min_ka'], b['age_min_ka'])
+            hi = min(a['age_max_ka'], b['age_max_ka'])
+            if hi > lo:
+                overlaps.append({'a': a['site'], 'b': b['site'],
+                                 'epoch_overlap_ka': (lo, hi),
+                                 'span_ka': round(hi - lo, 3)})
+    counts = collections.Counter()
+    for o in overlaps:
+        counts[o['a']] += 1
+        counts[o['b']] += 1
+    master = counts.most_common(1)[0] if counts else (None, 0)
+    return {'age_bearing_records': ages, 'n_sites': len({a['site'] for a in ages}),
+            'epoch_overlaps': overlaps,
+            'master_chronology': {'site': master[0], 'overlaps_others': master[1]}}
+
+
+def depth_frame_pairs(em: EarthModel = None, target_bins: int = TARGET_BINS,
+                      min_common: int = MIN_COMMON_BINS) -> Dict:
+    """Every cross-site same-property pair with overlapping z_ref: correlated
+    where the samples support it, REFUSED with counts where they do not -
+    and today they do not, anywhere. Nothing is interpolated between
+    archives; bins carry only real samples."""
+    em = em or EarthModel()
+    recs = []
+    for s in em.sites.values():
+        for r in s.records:
+            if r.z_ref_m and r.values:
+                pts = [(z, v) for z, v in zip(r.z_ref_m, r.values) if v == v]
+                if len(pts) >= 5:
+                    recs.append((s, r, pts))
+    fams = collections.defaultdict(list)
+    for s, r, pts in recs:
+        fams[_family(r.property)].append((s, r, pts))
+    ok, refused = [], []
+    for fname, group in fams.items():
+        for i in range(len(group)):
+            for j in range(i + 1, len(group)):
+                sa, ra, pa = group[i]
+                sb, rb, pb = group[j]
+                if sa.key == sb.key:
+                    continue
+                lo = max(min(z for z, _ in pa), min(z for z, _ in pb))
+                hi = min(max(z for z, _ in pa), max(z for z, _ in pb))
+                if hi <= lo:
+                    continue
+                w = (hi - lo) / target_bins
+                def _bins(pts):
+                    b = collections.defaultdict(list)
+                    for z, v in pts:
+                        if lo <= z <= hi:
+                            b[int((z - lo) // w)].append(v)
+                    return {k: sum(v) / len(v) for k, v in b.items()}
+                ba, bb = _bins(pa), _bins(pb)
+                common = sorted(set(ba) & set(bb))
+                dist = haversine_km(sa.latitude, sa.longitude,
+                                    sb.latitude, sb.longitude)
+                base = {'property_family': fname, 'a': sa.key, 'b': sb.key,
+                        'entries': (ra.entry, rb.entry),
+                        'z_overlap_m': round(hi - lo, 1),
+                        'common_bins': len(common), 'target_bins': target_bins,
+                        'distance_km': round(dist, 1),
+                        'continuity_claim': (
+                            'TWIN_HOLE_ELIGIBLE' if dist < CONTINUITY_KM else
+                            'NONE - statistical comparison only (%.0f km '
+                            'exceeds the %.0f km continuity threshold)'
+                            % (dist, CONTINUITY_KM))}
+                if len(common) < min_common:
+                    base['status'] = 'REFUSED_THIN_DATA (min %d)' % min_common
+                    refused.append(base)
+                    continue
+                xa = [ba[k] for k in common]
+                xb = [bb[k] for k in common]
+                ma, mb = statistics.mean(xa), statistics.mean(xb)
+                den = math.sqrt(sum((x - ma) ** 2 for x in xa)
+                                * (sum((y - mb) ** 2 for y in xb)))
+                base['status'] = 'OK'
+                base['pearson_r'] = ((sum((x - ma) * (y - mb)
+                                          for x, y in zip(xa, xb)) / den)
+                                     if den else float('nan'))
+                ok.append(base)
+    return {'ok': ok, 'refused': refused, 'n_ok': len(ok),
+            'n_refused': len(refused),
+            'finding': ('the library currently supports %d cross-site '
+                        'depth-frame correlations; %d candidate pairs '
+                        'refused thin - the honest census, not a failure'
+                        % (len(ok), len(refused)))}