gabriel / musehub public
musehub_overseer_provenance.py python
131 lines 4.4 KB
Raw
sha256:417c976b0b9320bb758749eb014d9087354fa3186e2abd2fc949e74a670237e7 merge(F7b B1): carry overseer provenance onto dev; resolve … Human minor ⚠ breaking 29 days ago
1 """MuseHub overseer-run provenance enrichment service — Phase 9A-4 live (F7).
2
3 Content-free enrichment records keyed by portable `flow_run:…` refs. Canonical run state
4 remains in Knowtation; MuseHub enriches version-lineage pointers only.
5 """
6
7 from __future__ import annotations
8
9 import re
10 from dataclasses import dataclass
11 from datetime import UTC, datetime
12 from typing import Any
13
14 from musehub.config import settings
15
16 OVERSEER_PROVENANCE_ENRICHMENT_AUTHORIZED: bool = True
17 CONTRACT_VERSION = "scooling.overseer_provenance_enrichment/v0"
18 RUN_REF_RE = re.compile(r"^flow_run:[A-Za-z0-9._:-]{1,128}$")
19 HASH_RE = re.compile(r"^[a-f0-9]{64}$")
20 SAFE_IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
21
22
23 @dataclass(frozen=True, slots=True)
24 class OverseerRunProvenanceRecord:
25 """Content-free durable enrichment record returned to Scooling consumers."""
26
27 run_ref: str
28 review_tray_outcome_ref: str
29 outcome: str
30 constitution_version: str
31 agent_version_ref: str
32 worker_model_family: str
33 checker_model_family: str
34 external_ref: str | None
35 actor_hash: str
36 produced_at: str
37
38
39 def is_overseer_provenance_enrichment_enabled() -> bool:
40 """Runtime posture gate — compile-time authorization and env opt-in required."""
41 return (
42 OVERSEER_PROVENANCE_ENRICHMENT_AUTHORIZED
43 and settings.musehub_overseer_provenance_enrichment_enabled == "enabled"
44 )
45
46
47 def _validate_record_shape(record: OverseerRunProvenanceRecord) -> bool:
48 if not RUN_REF_RE.match(record.run_ref):
49 return False
50 if record.review_tray_outcome_ref != f"outcome:{record.run_ref}":
51 return False
52 if record.outcome not in {"pass", "fail"}:
53 return False
54 if not SAFE_IDENTIFIER_RE.match(record.constitution_version):
55 return False
56 if not SAFE_IDENTIFIER_RE.match(record.agent_version_ref):
57 return False
58 if not SAFE_IDENTIFIER_RE.match(record.worker_model_family):
59 return False
60 if not SAFE_IDENTIFIER_RE.match(record.checker_model_family):
61 return False
62 if record.external_ref is not None and len(record.external_ref) > 512:
63 return False
64 if not HASH_RE.match(record.actor_hash):
65 return False
66 return True
67
68
69 def _serialize_record(record: OverseerRunProvenanceRecord) -> dict[str, Any]:
70 return {
71 "schema": "scooling.overseer_run_provenance/v0",
72 "contractVersion": CONTRACT_VERSION,
73 "runRef": record.run_ref,
74 "reviewTrayOutcomeRef": record.review_tray_outcome_ref,
75 "outcome": record.outcome,
76 "constitutionVersion": record.constitution_version,
77 "agentVersionRef": record.agent_version_ref,
78 "workerModelFamily": record.worker_model_family,
79 "checkerModelFamily": record.checker_model_family,
80 "externalRef": record.external_ref,
81 "actorHash": record.actor_hash,
82 "producedAt": record.produced_at,
83 "untrusted": True,
84 }
85
86
87 # In-memory enrichment store for staging/loopback until durable tables land.
88 _ENRICHMENT_STORE: dict[str, OverseerRunProvenanceRecord] = {
89 "flow_run:fixture-overseer-001": OverseerRunProvenanceRecord(
90 run_ref="flow_run:fixture-overseer-001",
91 review_tray_outcome_ref="outcome:flow_run:fixture-overseer-001",
92 outcome="pass",
93 constitution_version="0.1.0",
94 agent_version_ref="agent:fixture-overseer-v0.1.0",
95 worker_model_family="family:ollama",
96 checker_model_family="family:llama_cpp",
97 external_ref=None,
98 actor_hash="a" * 64,
99 produced_at="2026-07-09T12:00:00Z",
100 ),
101 }
102
103
104 def seed_overseer_provenance_record(record: OverseerRunProvenanceRecord) -> None:
105 """Test/operator helper — upserts one enrichment record."""
106 if not _validate_record_shape(record):
107 raise ValueError("provenance_record_invalid")
108 _ENRICHMENT_STORE[record.run_ref] = record
109
110
111 def get_overseer_run_provenance(run_ref: str) -> dict[str, Any] | None:
112 """Lookup one content-free enrichment record by portable run ref."""
113 trimmed = run_ref.strip()
114 if not RUN_REF_RE.match(trimmed):
115 return None
116
117 record = _ENRICHMENT_STORE.get(trimmed)
118 if record is None:
119 return None
120
121 if not _validate_record_shape(record):
122 return None
123
124 return {
125 "schema": "musehub.overseer_run_provenance_envelope/v0",
126 "record": _serialize_record(record),
127 }
128
129
130 def default_produced_at() -> str:
131 return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
File History 1 commit
sha256:417c976b0b9320bb758749eb014d9087354fa3186e2abd2fc949e74a670237e7 merge(F7b B1): carry overseer provenance onto dev; resolve … Human minor ⚠ 29 days ago