feat(contracts): add evidence freshness conformance vectors

fixtures/contracts/evidence-freshness-conformance-v1/manifest.json

@@ -0,0 +1,56 @@
+{
+  "consumer_owned": [
+    "threshold-values",
+    "ui-language",
+    "alert-policy",
+    "build-versus-reader-behavior",
+    "production-calculator"
+  ],
+  "consumer_profiles": {
+    "desktop-command-center": {
+      "state_mapping": {
+        "aging": "aging",
+        "fresh": "fresh",
+        "stale": "stale",
+        "unavailable": "unknown",
+        "unknown": "unknown"
+      }
+    },
+    "operator-control-plane": {
+      "state_mapping": {
+        "aging": "aging",
+        "fresh": "fresh",
+        "stale": "stale",
+        "unavailable": "unavailable",
+        "unknown": "unverified"
+      }
+    },
+    "public-site-projection": {
+      "state_mapping": {
+        "aging": "resting",
+        "fresh": "fresh",
+        "stale": "cold",
+        "unavailable": "unknown",
+        "unknown": "unknown"
+      }
+    }
+  },
+  "contract_version": "1.0.0",
+  "non_goals": [
+    "shared-runtime-library",
+    "shared-alert-policy",
+    "shared-ui-copy"
+  ],
+  "owner": {
+    "artifact_path": "fixtures/contracts/evidence-freshness-conformance-v1/vectors.json",
+    "artifact_sha256": "3111e2dd43b12f74481450b4ad07e7b8f285ff9b5e6931fd1ea3ded521fc0e7c",
+    "generator": "src.evidence_freshness_conformance:build_vectors",
+    "manifest_path": "fixtures/contracts/evidence-freshness-conformance-v1/manifest.json",
+    "repository": "saagpatel/GithubRepoAuditor"
+  },
+  "schema": "EvidenceFreshnessConformanceManifestV1",
+  "versioning": {
+    "compatibility": "consumers-must-ignore-unknown-top-level-fields-and-new-cases",
+    "policy": "additive-minor-breaking-major"
+  }
+}

fixtures/contracts/evidence-freshness-conformance-v1/vectors.json

@@ -0,0 +1,235 @@
+{
+  "additive_canary": {
+    "consumer_behavior": "ignore-compatible-addition"
+  },
+  "canonical_reasons": [
+    "within_fresh_window",
+    "within_aging_window",
+    "at_or_beyond_stale_boundary",
+    "timestamp_missing",
+    "timestamp_unparseable",
+    "timestamp_timezone_missing",
+    "timestamp_future_within_tolerance",
+    "timestamp_future_beyond_tolerance",
+    "read_unavailable",
+    "policy_not_applicable"
+  ],
+  "canonical_states": [
+    "fresh",
+    "aging",
+    "stale",
+    "unknown",
+    "unavailable"
+  ],
+  "cases": [
+    {
+      "expected": {
+        "age_ms": 0,
+        "reason": "within_fresh_window",
+        "state": "fresh"
+      },
+      "id": "fresh_at_reader_clock",
+      "input": {
+        "generated_at": "2026-08-01T12:00:00.000Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 604799999,
+        "reason": "within_fresh_window",
+        "state": "fresh"
+      },
+      "id": "fresh_one_ms_before_aging_boundary",
+      "input": {
+        "generated_at": "2026-07-25T12:00:00.001Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 604800000,
+        "reason": "within_aging_window",
+        "state": "aging"
+      },
+      "id": "aging_at_exact_boundary",
+      "input": {
+        "generated_at": "2026-07-25T12:00:00.000Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 1209599999,
+        "reason": "within_aging_window",
+        "state": "aging"
+      },
+      "id": "aging_one_ms_before_stale_boundary",
+      "input": {
+        "generated_at": "2026-07-18T12:00:00.001Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 1209600000,
+        "reason": "at_or_beyond_stale_boundary",
+        "state": "stale"
+      },
+      "id": "stale_at_exact_boundary",
+      "input": {
+        "generated_at": "2026-07-18T12:00:00.000Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 1209600001,
+        "reason": "at_or_beyond_stale_boundary",
+        "state": "stale"
+      },
+      "id": "stale_beyond_boundary",
+      "input": {
+        "generated_at": "2026-07-18T11:59:59.999Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": null,
+        "reason": "timestamp_missing",
+        "state": "unknown"
+      },
+      "id": "missing_timestamp",
+      "input": {
+        "generated_at": null,
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": null,
+        "reason": "timestamp_unparseable",
+        "state": "unknown"
+      },
+      "id": "empty_timestamp",
+      "input": {
+        "generated_at": "",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": null,
+        "reason": "timestamp_unparseable",
+        "state": "unknown"
+      },
+      "id": "unparseable_timestamp",
+      "input": {
+        "generated_at": "not-a-timestamp",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": null,
+        "reason": "timestamp_timezone_missing",
+        "state": "unknown"
+      },
+      "id": "timezone_missing",
+      "input": {
+        "generated_at": "2026-08-01T12:00:00.000",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 0,
+        "reason": "within_fresh_window",
+        "state": "fresh"
+      },
+      "id": "offset_normalizes_to_reader_clock",
+      "input": {
+        "generated_at": "2026-08-01T07:00:00.000-05:00",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 0,
+        "reason": "timestamp_future_within_tolerance",
+        "state": "fresh"
+      },
+      "id": "future_at_skew_tolerance",
+      "input": {
+        "generated_at": "2026-08-01T12:01:00.000Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": null,
+        "reason": "timestamp_future_beyond_tolerance",
+        "state": "unknown"
+      },
+      "id": "future_one_ms_beyond_skew_tolerance",
+      "input": {
+        "generated_at": "2026-08-01T12:01:00.001Z",
+        "policy_state": "configured",
+        "read_state": "available"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": null,
+        "reason": "read_unavailable",
+        "state": "unavailable"
+      },
+      "id": "unavailable_read_wins",
+      "input": {
+        "generated_at": "2026-08-01T12:00:00.000Z",
+        "policy_state": "configured",
+        "read_state": "unavailable"
+      }
+    },
+    {
+      "expected": {
+        "age_ms": 60000,
+        "reason": "policy_not_applicable",
+        "state": "unknown"
+      },
+      "id": "policy_not_applicable_preserves_age",
+      "input": {
+        "generated_at": "2026-08-01T11:59:00.000Z",
+        "policy_state": "not_applicable",
+        "read_state": "available"
+      }
+    }
+  ],
+  "contract_version": "1.0.0",
+  "evaluation_clock": "2026-08-01T12:00:00.000Z",
+  "policy": {
+    "aging_after_ms": 604800000,
+    "boundary_semantics": "fresh_when_age_lt_aging;aging_when_age_lt_stale;stale_when_age_gte_stale",
+    "skew_tolerance_ms": 60000,
+    "stale_after_ms": 1209600000
+  },
+  "schema": "EvidenceFreshnessConformanceV1",
+  "timestamp_contract": {
+    "normalization": "UTC",
+    "reader_clock": "injected-never-wall-clock",
+    "timezone": "explicit-Z-or-offset-required"
+  }
+}

scripts/generate_evidence_freshness_conformance.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Write or verify the EvidenceFreshnessConformanceV1 contract artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from src.evidence_freshness_conformance import (  # noqa: E402
+    MANIFEST_RELATIVE_PATH,
+    VECTORS_RELATIVE_PATH,
+    manifest_bytes,
+    vectors_bytes,
+)
+
+
+def _artifacts() -> tuple[tuple[Path, bytes], ...]:
+    return (
+        (REPO_ROOT / VECTORS_RELATIVE_PATH, vectors_bytes()),
+        (REPO_ROOT / MANIFEST_RELATIVE_PATH, manifest_bytes()),
+    )
+
+
+def _check() -> int:
+    drifted = [
+        path.relative_to(REPO_ROOT)
+        for path, expected in _artifacts()
+        if not path.is_file() or path.read_bytes() != expected
+    ]
+    if drifted:
+        print(
+            "Evidence freshness conformance artifacts drifted: "
+            + ", ".join(str(path) for path in drifted),
+            file=sys.stderr,
+        )
+        print(
+            "Regenerate with: python scripts/generate_evidence_freshness_conformance.py",
+            file=sys.stderr,
+        )
+        return 1
+    print("EvidenceFreshnessConformanceV1 artifacts are current.")
+    return 0
+
+
+def _write() -> int:
+    for path, content in _artifacts():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+        print(f"Wrote {path.relative_to(REPO_ROOT)}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Fail when committed artifacts differ from deterministic output.",
+    )
+    args = parser.parse_args()
+    return _check() if args.check else _write()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())