cctally 1.116.1 → 1.117.2

package/bin/_lib_provider_activity.py

@@ -627,15 +627,23 @@ def _witness(status, instant, reason, total, examined, digest) -> ActivityWitnes
         files_total=total, files_examined=examined, digest=digest)
 
 
-def capture_activity(transcript_path: str | None, *, cache_path: pathlib.Path) -> ActivityWitness:
+def capture_activity(transcript_path: str | None, *, cache_path: pathlib.Path,
+                     seed_path: pathlib.Path | None = None) -> ActivityWitness:
     """Capture one arrival's provider-activity evidence (spec 4.1). Called
     once per arrival, before the intake commit and outside the intake
     critical section; never raises for anything a transcript or the cache
-    can contain."""
+    can contain.
+
+    ``seed_path`` is the starting state of an absent cache (#1019 C4): the
+    same contributor's document in a previous spool, read without its lock
+    and never written. Its records are keyed by file incarnation, so a seed
+    is as valid as a document this arrival would write; an unreadable or
+    invalid seed is an ordinary first arrival."""
     if not isinstance(transcript_path, str) or not transcript_path:
         return _witness("unknown", None, "no-transcript-path", 0, 0, _digest([], True, True))
     try:
-        return _capture_locked(transcript_path, pathlib.Path(cache_path))
+        return _capture_locked(transcript_path, pathlib.Path(cache_path),
+                               None if seed_path is None else pathlib.Path(seed_path))
     except Exception:
         # Every transcript and cache condition is classified above; anything
         # else is still an explicit, eligible unknown capture, never a
@@ -643,18 +651,28 @@ def capture_activity(transcript_path: str | None, *, cache_path: pathlib.Path) -
         return _witness("unknown", None, "unreadable", 0, 0, _digest([], False, False))
 
 
-def _capture_locked(transcript_path: str, cache_path: pathlib.Path) -> ActivityWitness:
+def _capture_locked(transcript_path: str, cache_path: pathlib.Path,
+                    seed_path: pathlib.Path | None) -> ActivityWitness:
     lock = _lock_cache(cache_path)
     try:
+        seeded = False
         if lock is None:
             cache, cache_valid, contended = _Cache(), True, True
         else:
-            (cache, cache_valid), contended = _load_cache(cache_path), False
+            contended = False
+            # Under the lock no other arrival writes this cache, so an absent
+            # document stays absent until this arrival stores one.
+            seeded = seed_path is not None and not os.path.lexists(cache_path)
+            if seeded:
+                seed, seed_valid = _load_cache(seed_path)
+                cache, cache_valid = (seed if seed_valid else _Cache()), True
+            else:
+                cache, cache_valid = _load_cache(cache_path)
         before = None if contended else _cache_document(cache)
         result = _capture(transcript_path, cache, cache_valid=cache_valid)
         if lock is not None:
             after = _cache_document(cache)
-            if after != before or not cache_valid:
+            if after != before or not cache_valid or seeded:
                 _store_cache(cache_path, after)
         return result
     finally:

package/bin/_lib_quota_calibration.py

@@ -48,6 +48,16 @@ class RegimeRejection(str, enum.Enum):
     #: gate. The mark is S1 stating that the regime must not be used to
     #: predict, so it is refused here rather than applied.
     DETECTION_ONLY = "calibration-detection-only"
+    #: #1015 spec 5.4: the open regime was fitted before a reviewed
+    #: correction to its inputs was materialized (its lineage assesses
+    #: `tainted`, or a sweep already annotated it). Wire code
+    #: `recalibration-needed`.
+    RECALIBRATION_NEEDED = "recalibration-needed"
+    #: #1015 spec 5.4: the regime's correction lineage could not be read
+    #: (no published facts, a missing projection, a read error) or holds an
+    #: unresolved reference. Never an unverified calibrated number; the wire
+    #: states `unavailable`.
+    LINEAGE_UNAVAILABLE = "calibration-lineage-unavailable"
 
 
 #: The qualification S1 writes onto a successor fit that is below its
@@ -96,6 +106,12 @@ class ValidatedRegime:
     #: member of `qm.COEFFICIENT_ERAS` (#978).
     coefficient_era: str
     qualifications: tuple = ()
+    #: The fit-weighted family composition of the days the regime's fit was
+    #: taken over (#991 spec 4.5), the reference the evidence-bounded family
+    #: test measures a consumer population against. None when the stored
+    #: record carries no valid one, which disables that test for the regime
+    #: and leaves the radius rule alone deciding.
+    fit_family_shares: "dict | None" = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -162,6 +178,36 @@ def _shares(value) -> "dict | None":
     return out
 
 
+def _fit_reference_shares(value) -> "dict | None":
+    """A stored `fitFamilyShares`, or None when it is unusable (#991).
+
+    Stricter than `_shares`, which accepts `{}`, negative shares and any sum
+    and stays as it is for the TV references: a non-empty dict of string keys
+    and finite, non-negative numbers whose `math.fsum` is within 1e-9 of 1,
+    returned exactly as stored, never renormalized or rounded. Anything else
+    is None, not a rejection, because the regime's fit and its TV references
+    remain usable.
+    """
+    if not isinstance(value, dict) or not value:
+        return None
+    out = {}
+    for name, share in value.items():
+        if not isinstance(name, str) or isinstance(share, bool) \
+                or not isinstance(share, (int, float)) \
+                or not _finite(share) or share < 0.0:
+            return None
+        out[name] = float(share)
+    try:
+        total = math.fsum(out[k] for k in sorted(out))
+    except OverflowError:
+        # Finite shares whose sum leaves the float range are no
+        # distribution; raising would take the whole calibration with it.
+        return None
+    if abs(total - 1.0) > 1e-9:
+        return None
+    return out
+
+
 def _optional_radius(value):
     """`(ok, radius)` — a radius is absent, or a finite non-negative float."""
     if value is None:
@@ -272,6 +318,7 @@ def validate_regime(raw, *, account_key, expected_fingerprint,
         class_radius=class_radius,
         coefficient_era=era.id,
         qualifications=marks,
+        fit_family_shares=_fit_reference_shares(raw.get("fitFamilyShares")),
     )
 
 
@@ -338,9 +385,16 @@ def apply_regime(regime: ValidatedRegime, entries, *, interval
     if aggregated is None:
         return ApplyRejection.EMPTY_POPULATION
     family_shares, class_shares = aggregated
-    if not qm.is_supported(family_shares, class_shares,
-                           regime.family_shares, regime.family_radius,
-                           regime.class_shares, regime.class_radius):
+    # #991 spec 4.6: the same evaluator as the forecast probe, against the
+    # regime's OWN fit-weighted family composition and era.
+    support = qm.evaluate_prediction_support(
+        family_shares, class_shares,
+        family_centre=regime.family_shares,
+        family_radius=regime.family_radius,
+        class_centre=regime.class_shares,
+        class_radius=regime.class_radius,
+        fit_family_shares=regime.fit_family_shares, era=era)
+    if not support.supported:
         return ApplyRejection.UNSUPPORTED_COMPOSITION
 
     units = population_units(entries, era=era)

package/bin/_lib_quota_copy.py

@@ -1,6 +1,7 @@
 """#661 S2 Task D1 — the ONE cause-code copy table (spec section 8).
 
-S1 publishes fifteen withheld-figure codes in `EVIDENCE_CODES`. Section 8
+S1 publishes fifteen withheld-figure codes in `EVIDENCE_CODES`, and #1015
+adds a sixteenth, `recalibration-needed`. Section 8
 renders them through one table in two registers, and this module is that
 table.
 
@@ -27,7 +28,7 @@ matters because a dashboard tab can outlive a server restart through
 `execvp` and will meet an older server's envelope.
 
 Pure: no I/O, no clock, no store. The cause vocabulary is the closed
-15-member `EVIDENCE_CODES` union, and the separate basis vocabulary names
+16-member `EVIDENCE_CODES` union, and the separate basis vocabulary names
 which measurement produced a projection. They share this rendering boundary
 but never one semantic union: a basis is not a withholding cause.
 """
@@ -79,6 +80,10 @@ _LONG_FORM: dict = {
         "the stored calibration came from a newer cctally than this one",
     "unavailable":
         "no usable calibration could be read for this account",
+    # --- #1015: the stored calibration's own refusal (U3, spec 2) ---
+    "recalibration-needed":
+        "the stored calibration was fitted before a correction to its "
+        "inputs; run cctally quota to recalibrate",
 }
 
 #: Projection-basis copy in the same two registers, deliberately separate