trooth 0.1.1__tar.gz → 0.2.0__tar.gz

{trooth-0.1.1 → trooth-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trooth
-Version: 0.1.1
+Version: 0.2.0
 Summary: Read a company's Semanto signed copy and check it: signatures, keys, DNS binding, page proofs and the public log.
 Author: Trooth, LLC
 License-Expression: Apache-2.0
@@ -75,7 +75,7 @@ Canonical JSON here supports integers exactly. A non-integer float raises `Canon
 
 ## Tests
 
-`python3 -m pytest` runs every shared vector in `verifier/test-vectors/v1` (positive and negative), the RFC 6962 known roots, the RFC 8785 cases, the state rules and the command line.
+`python3 -m pytest` runs every shared vector in `verifier/test-vectors/v1` (positive and negative), the answer cases in `verifier/test-vectors/answer-v1`, the source's refresh and offline behavior, the RFC 6962 known roots, the RFC 8785 cases, the state rules and the command line.
 
 ## SemantoClient
 
@@ -86,3 +86,14 @@ print(r["ok"], r["dns"], r["reason"])
 ```
 
 It fetches with the standard library (pass `fetch=` to use your own), checks the response signature and the domain's `_trooth-keys` TXT record over DNS over HTTPS, and keeps key sets and DNS answers five minutes.
+
+## SemantoSource
+
+```python
+from trooth import SemantoSource
+acme = SemantoSource("acme.com", on_event=lambda e: print(e["event"], e["detail"]))
+a = acme.answer(question="How much is the Starter plan?")
+print(a["status"], a["text"])
+```
+
+It loads `/.well-known/trooth.semanto` and the company's keys from the company's site, checks the file once for each new body, reads the site again at most every 15 minutes, and answers fact IDs and plain questions in process with the same matcher as Trooth's service (`trooth_semanto_verify.answer`, compared case by case with `verifier/test-vectors/answer-v1`). When Trooth's API cannot be reached it keeps answering from the last version that checked out and logs `trooth_api_unreachable`; a new version that does not check out is refused and the last good one stays in use. A fact marked changed since signing or expired returns its mark and no value.

{trooth-0.1.1 → trooth-0.2.0}/README.md

@@ -45,7 +45,7 @@ Canonical JSON here supports integers exactly. A non-integer float raises `Canon
 
 ## Tests
 
-`python3 -m pytest` runs every shared vector in `verifier/test-vectors/v1` (positive and negative), the RFC 6962 known roots, the RFC 8785 cases, the state rules and the command line.
+`python3 -m pytest` runs every shared vector in `verifier/test-vectors/v1` (positive and negative), the answer cases in `verifier/test-vectors/answer-v1`, the source's refresh and offline behavior, the RFC 6962 known roots, the RFC 8785 cases, the state rules and the command line.
 
 ## SemantoClient
 
@@ -56,3 +56,14 @@ print(r["ok"], r["dns"], r["reason"])
 ```
 
 It fetches with the standard library (pass `fetch=` to use your own), checks the response signature and the domain's `_trooth-keys` TXT record over DNS over HTTPS, and keeps key sets and DNS answers five minutes.
+
+## SemantoSource
+
+```python
+from trooth import SemantoSource
+acme = SemantoSource("acme.com", on_event=lambda e: print(e["event"], e["detail"]))
+a = acme.answer(question="How much is the Starter plan?")
+print(a["status"], a["text"])
+```
+
+It loads `/.well-known/trooth.semanto` and the company's keys from the company's site, checks the file once for each new body, reads the site again at most every 15 minutes, and answers fact IDs and plain questions in process with the same matcher as Trooth's service (`trooth_semanto_verify.answer`, compared case by case with `verifier/test-vectors/answer-v1`). When Trooth's API cannot be reached it keeps answering from the last version that checked out and logs `trooth_api_unreachable`; a new version that does not check out is refused and the last good one stays in use. A fact marked changed since signing or expired returns its mark and no value.

{trooth-0.1.1 → trooth-0.2.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trooth"
-version = "0.1.1"
+version = "0.2.0"
 description = "Read a company's Semanto signed copy and check it: signatures, keys, DNS binding, page proofs and the public log."
 readme = "README.md"
 requires-python = ">=3.11"

{trooth-0.1.1 → trooth-0.2.0}/trooth/__init__.py

@@ -5,10 +5,14 @@
     from trooth import SemantoClient
     r = SemantoClient().read("https://acme.com/pricing")
 
+    from trooth import SemantoSource
+    a = SemantoSource("acme.com").answer(question="What is your phone number?")
+
 The checks themselves live in trooth_semanto_verify (the same functions and reason codes as the JavaScript and Go
 kits). Framework integrations are optional extras: trooth[langchain], trooth[llama-index], trooth[openai-agents].
 """
 from trooth_semanto_verify.client import SemantoClient
+from trooth_semanto_verify.source import SemantoSource
 
-__version__ = "0.1.1"
-__all__ = ["SemantoClient", "__version__"]
+__version__ = "0.2.0"
+__all__ = ["SemantoClient", "SemantoSource", "__version__"]

{trooth-0.1.1 → trooth-0.2.0}/trooth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trooth
-Version: 0.1.1
+Version: 0.2.0
 Summary: Read a company's Semanto signed copy and check it: signatures, keys, DNS binding, page proofs and the public log.
 Author: Trooth, LLC
 License-Expression: Apache-2.0
@@ -75,7 +75,7 @@ Canonical JSON here supports integers exactly. A non-integer float raises `Canon
 
 ## Tests
 
-`python3 -m pytest` runs every shared vector in `verifier/test-vectors/v1` (positive and negative), the RFC 6962 known roots, the RFC 8785 cases, the state rules and the command line.
+`python3 -m pytest` runs every shared vector in `verifier/test-vectors/v1` (positive and negative), the answer cases in `verifier/test-vectors/answer-v1`, the source's refresh and offline behavior, the RFC 6962 known roots, the RFC 8785 cases, the state rules and the command line.
 
 ## SemantoClient
 
@@ -86,3 +86,14 @@ print(r["ok"], r["dns"], r["reason"])
 ```
 
 It fetches with the standard library (pass `fetch=` to use your own), checks the response signature and the domain's `_trooth-keys` TXT record over DNS over HTTPS, and keeps key sets and DNS answers five minutes.
+
+## SemantoSource
+
+```python
+from trooth import SemantoSource
+acme = SemantoSource("acme.com", on_event=lambda e: print(e["event"], e["detail"]))
+a = acme.answer(question="How much is the Starter plan?")
+print(a["status"], a["text"])
+```
+
+It loads `/.well-known/trooth.semanto` and the company's keys from the company's site, checks the file once for each new body, reads the site again at most every 15 minutes, and answers fact IDs and plain questions in process with the same matcher as Trooth's service (`trooth_semanto_verify.answer`, compared case by case with `verifier/test-vectors/answer-v1`). When Trooth's API cannot be reached it keeps answering from the last version that checked out and logs `trooth_api_unreachable`; a new version that does not check out is refused and the last good one stays in use. A fact marked changed since signing or expired returns its mark and no value.

{trooth-0.1.1 → trooth-0.2.0}/trooth.egg-info/SOURCES.txt

@@ -14,10 +14,12 @@ trooth/integrations/llama_index.py
 trooth/integrations/openai_agents.py
 trooth_semanto_verify/__init__.py
 trooth_semanto_verify/__main__.py
+trooth_semanto_verify/answer.py
 trooth_semanto_verify/canonical.py
 trooth_semanto_verify/cli.py
 trooth_semanto_verify/client.py
 trooth_semanto_verify/httpsig.py
 trooth_semanto_verify/jws.py
 trooth_semanto_verify/merkle.py
+trooth_semanto_verify/source.py
 trooth_semanto_verify/verify.py

{trooth-0.1.1 → trooth-0.2.0}/trooth_semanto_verify/__init__.py

@@ -91,4 +91,4 @@ __all__ = [
     "version_id",
 ]
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

trooth-0.2.0/trooth_semanto_verify/answer.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Trooth, LLC
+"""The answer matcher, run in process on a company's signed copy.
+
+A fact ID or a plain question goes in; out comes the signed fact word for word with its typed value, conditions, date
+and check link, or the candidates when more than one fact fits, or the not-published reply when none does. No model and
+no generated wording: the same question against the same version gives the same answer as Trooth's service. MATCHER["id"]
+names the matcher and equals the `matcher` field of the service's answers; test-vectors/answer-v1 holds the service's
+answers to compare. The steps, in order: fact_id, question_map, key_terms, similarity.
+"""
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional
+
+MATCHER: Dict[str, Any] = json.loads('{"id":"matcher-1-a75202e1","order":["fact_id","question_map","key_terms","similarity"],"SIMILARITY_THRESHOLD":0.34,"SIMILARITY_MARGIN":0.05,"KEY_TERMS":[["^contact\\\\.phone$|\\\\.telephone$",["phone","call","telephone","number"]],["^contact\\\\.(support_)?email$",["email","e-mail","mail"]],["^contact\\\\.address",["address","located","location","office","headquarters"]],["^hours\\\\.",["open","hours","close","opening","closing"]],["price|pricing|offer",["price","cost","how much","plan","pricing","fee"]],["^identity\\\\.founding_date$",["founded","started","established","since"]],["^identity\\\\.legal_name$",["legal name","legal entity","company name","registered"]],["refund|return",["refund","return","money back"]],["shipping|delivery",["shipping","delivery","ship"]]],"catalog":[["security.mfa",["multi-factor","multifactor","two-factor","2FA","MFA"]],["security.mfa_methods",["authenticator","TOTP","passkey","SMS","security key","WebAuthn","FIDO"]],["security.encryption_at_rest",["encrypted at rest","encryption at rest","at rest"]],["security.encryption_in_transit",["in transit","TLS"]],["security.soc2",["SOC 2","SOC2","SOC-2"]],["security.iso27001",["ISO 27001","ISO/IEC 27001","ISO27001"]],["security.data_residency",["data residency","stored in","hosted in","data center","region"]],["security.page_url",["security page","trust center","trust page"]],["privacy.subprocessors",["subprocessor","sub-processor"]],["privacy.data_deletion_days",["delet","purge","retention"]],["terms.uptime_commitment",["uptime","availability","SLA"]],["terms.sla_credits",["service credit","SLA credit","credits"]],["terms.minimum_term",["minimum term","contract term","commitment","annual contract","month-to-month"]],["terms.cancellation_notice",["cancel","notice"]],["support.hours",["support hours","support is available","support team","support"]],["support.channels",["email","chat","phone","ticket","portal"]],["commercial.pricing_model",["per seat","per user","usage-based","flat","tiered","pricing model","priced"]],["commercial.starting_price",["starts at","starting at","from","per month","per user","per seat"]],["commercial.free_trial",["free trial","trial"]],["commercial.returns_window_days",["return","refund"]],["commercial.authorized_sellers",["buy","sold","retailer","available at","stockist"]],["commercial.shipping_free_over",["free shipping","shipping"]],["commercial.ships_international",["international","worldwide","outside the"]],["products.{slug}.price",["price","cost","costs","priced","retails"]],["products.{slug}.sale_price",["sale","discount","off","deal"]],["products.{slug}.availability",["in stock","out of stock","available","sold out","backorder","pre-order","preorder"]],["products.{slug}.sizes",["size","sizes"]],["products.{slug}.variants",["color","colour","variant","option","finish"]],["products.{slug}.variant_differences",["difference","differs","compared","versus","vs"]],["products.{slug}.materials",["made of","made from","material","ingredient","contains"]],["products.{slug}.warranty",["warranty","guarantee"]],["products.{slug}.safety_warnings",["warning","caution","not suitable","choking","hazard"]],["products.{slug}.safety_standards",["standard","tested to","complies","compliant","EN ","ASTM","CPSC","UL "]],["products.{slug}.dimensions",["weigh","weight","dimension","measures","cm","inches","kg","lb"]],["local.hours",["open","hours","opening"]],["local.hours_sunday",["sunday"]],["local.holiday_hours",["holiday","christmas","thanksgiving","closed on"]],["local.address",["located","address","find us","at "]],["local.phone",["phone","call","telephone","reach"]],["local.email",["email","e-mail","@"]],["local.services",["service","offer","provide"]],["local.service_price",["cost","price","charge","fee"]],["local.parking",["parking","park","garage","lot"]],["local.accessibility",["wheelchair","accessible","step-free","ramp","elevator"]],["local.appointment_policy",["appointment","book","reservation"]],["local.walk_ins",["walk-in","walk in","walk-ins","without an appointment"]],["local.payment_methods",["accept","payment","cash","card","Apple Pay","Google Pay"]],["local.delivery",["deliver","delivery","pickup","pick-up","curbside"]],["local.languages",["language","speak","spoken","Spanish","French","Mandarin"]]]}')
+
+MARK_WORDS = {
+    "changed_since_signing": "Changed since signing: the page this came from no longer says it the same way. Check the page before quoting a value.",
+    "expired": "Expired: the company said this held only until a date that has passed.",
+}
+
+_STOP = {"the", "a", "an", "is", "are", "do", "does", "what", "whats", "how", "when", "where", "who", "which", "of", "to", "for", "in", "on", "at", "your", "you", "their", "they", "its", "it", "and", "or", "can", "i", "we", "our", "my", "me", "this", "that", "page", "lists", "gives", "says"}
+_KEY_TERMS = [(re.compile(src), terms) for src, terms in MATCHER["KEY_TERMS"]]
+_ALNUM = re.compile(r"[^\W_]+")
+_NOT_ALNUM = re.compile(r"[\W_]+")
+
+
+def not_published(org: str, domain: str) -> str:
+    return f"{org}'s signed record does not answer this. Ask {org} at {domain}."
+
+
+def _js_json(v: Any) -> str:
+    return json.dumps(v, ensure_ascii=False, separators=(",", ":"))
+
+
+def matcher_id(m: Optional[Dict[str, Any]] = None) -> str:
+    """The matcher's identity, worked out from its data (FNV-1a over the UTF-16 code units of its JSON)."""
+    m = m or MATCHER
+    src = _js_json({"order": m["order"], "SIMILARITY_THRESHOLD": m["SIMILARITY_THRESHOLD"], "SIMILARITY_MARGIN": m["SIMILARITY_MARGIN"], "KEY_TERMS": m["KEY_TERMS"], "catalog": m["catalog"]})
+    h = 0x811C9DC5
+    units = src.encode("utf-16-le")
+    for i in range(0, len(units), 2):
+        h = ((h ^ (units[i] | units[i + 1] << 8)) * 0x01000193) & 0xFFFFFFFF
+    return f"matcher-1-{h:08x}"
+
+
+def _lower(s: str) -> str:
+    return unicodedata.normalize("NFKC", s.lower())
+
+
+def _words(s: str) -> set:
+    out = set()
+    for w in _ALNUM.findall(_lower(s)):
+        if len(w) > 1 and w not in _STOP:
+            out.add(re.sub(r"s$", "", re.sub(r"(ies)$", "y", w)))
+    return out
+
+
+def _norm(s: str) -> str:
+    return _NOT_ALNUM.sub(" ", _lower(s)).strip()
+
+
+def _parse_time(s: str) -> datetime:
+    return datetime.fromisoformat(s.replace("Z", "+00:00"))
+
+
+def fact_marks(file: dict, changed: Iterable[str] = (), now: Optional[datetime] = None) -> Dict[str, str]:
+    """The marks in force: "expired" past a fact's valid_to, "changed_since_signing" when the version passed its
+    not_after or the monitor found the sentence changed (`changed`: fact IDs for this version)."""
+    now = now or datetime.now(timezone.utc)
+    today = now.astimezone(timezone.utc).strftime("%Y-%m-%d")
+    na = file["header"].get("not_after")
+    lapsed = na is not None and _parse_time(na) < now
+    ch = set(changed)
+    out: Dict[str, str] = {}
+    for f in file["facts"]:
+        if f.get("valid_to") and f["valid_to"] < today:
+            out[f["id"]] = "expired"
+        elif lapsed or f["id"] in ch:
+            out[f["id"]] = "changed_since_signing"
+    return out
+
+
+def _nz(*vals: Any) -> Any:
+    for v in vals:
+        if v is not None:
+            return v
+    return None
+
+
+def _as_answered(f: dict, mark: Optional[str]) -> dict:
+    return {
+        "fact_id": f["id"], "key": f["key"], "statement": None if mark else f["statement"], "typed": None if mark else f.get("typed"),
+        "conditions": [] if mark else (f.get("conditions") or []), "location": f.get("location"), "valid_from": f.get("valid_from"),
+        "valid_to": f.get("valid_to"), "provenance": f["provenance"], "source_url": f["evidence"]["url"], "mark": mark,
+    }
+
+
+def _distinct(facts: List[dict]) -> List[dict]:
+    seen: Dict[str, dict] = {}
+    for f in facts:
+        typed = f.get("typed") or {}
+        k = f"{_js_json(_nz(typed.get('value'), f.get('value'), f['statement']))}|{f.get('location') or ''}|{';'.join(f.get('conditions') or [])}"
+        seen.setdefault(k, f)
+    return list(seen.values())
+
+
+def _match(file: dict, fact_id: Optional[str], question: Optional[str]):
+    facts = file["facts"]
+    if fact_id:
+        f = next((x for x in facts if x["id"] == fact_id), None)
+        return ("fact_id" if f else None), ([f] if f else [])
+    q = question or ""
+    nq = _norm(q)
+    by_id = {f["id"]: f for f in facts}
+    for e in file.get("question_map") or []:
+        if _norm(e["question"]) == nq and e.get("fact_ids"):
+            return "question_map", [by_id[i] for i in e["fact_ids"] if i in by_id]
+    lq = f" {nq} "
+    for rx, terms in _KEY_TERMS:
+        if not any(f" {t} " in lq or f" {t}s " in lq for t in terms):
+            continue
+        hits = [f for f in facts if rx.search(f["key"])]
+        if hits:
+            return "key_terms", hits
+    for key, terms in MATCHER["catalog"]:
+        if not any(f" {_norm(t)} " in lq for t in terms):
+            continue
+        hits = [f for f in facts if f["key"] == key]
+        if hits:
+            return "key_terms", hits
+    qw = _words(q)
+    if not qw:
+        return None, []
+    ranked = []
+    for f in facts:
+        fw = _words(f["statement"])
+        s = len(qw & fw) / len(qw | fw)
+        if s >= MATCHER["SIMILARITY_THRESHOLD"]:
+            ranked.append((s, f))
+    if not ranked:
+        return None, []
+    ranked.sort(key=lambda x: -x[0])
+    top = ranked[0][0]
+    return "similarity", [f for s, f in ranked if top - s <= MATCHER["SIMILARITY_MARGIN"]]
+
+
+def answer(file: dict, company: dict, fact_id: Optional[str] = None, question: Optional[str] = None, marks: Optional[Dict[str, str]] = None, check_base: str = "https://api.trooth.co/public/semanto", signed_at: Optional[str] = None) -> dict:
+    """Answer a fact ID or a plain question from a checked signed copy, as Trooth's service does.
+
+    company: {"trooth_id", "org", "domain"}; marks: from fact_marks()."""
+    marks = marks or {}
+    h = file["header"]
+    check = f"{check_base.rstrip('/')}/{company['trooth_id']}/versions/{h['version']}"
+    base = {"object": "semanto.answer", "matcher": MATCHER["id"], "company": {"trooth_id": company["trooth_id"], "name": company["org"], "domain": company["domain"]},
+            "version": h["version"], "version_hash": file["root_hash"], "signed_at": _nz(signed_at, (file.get("witness") or {}).get("at")), "check": check}
+    by, facts = _match(file, fact_id, question)
+    found = _distinct(facts)
+    if not found:
+        return {**base, "status": "not_published", "matched_by": None, "facts": [], "text": not_published(company["org"], company["domain"])}
+    if len(found) > 1:
+        return {**base, "status": "candidates", "matched_by": by, "facts": [_as_answered(f, marks.get(f["id"])) for f in found[:10]],
+                "text": f"{len(found)} signed facts of {company['org']} could answer this; none is picked. Ask about one of them by its fact ID."}
+    f = found[0]
+    mark = marks.get(f["id"])
+    lines = [MARK_WORDS[mark]] if mark else [f["statement"], *([f"Conditions: {'; '.join(f['conditions'])}."] if f.get("conditions") else [])]
+    lines.append(f"Check: {check}")
+    return {**base, "status": "answer", "matched_by": by, "facts": [_as_answered(f, mark)], "text": "\n".join(lines[:3])}

trooth-0.2.0/trooth_semanto_verify/source.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Trooth, LLC
+"""SemantoSource: a company's signed copy, loaded from the company's own site and answered from in process.
+
+    from trooth import SemantoSource
+    acme = SemantoSource("acme.com")
+    a = acme.answer(question="What is your phone number?")
+    if a["status"] == "answer":
+        show(a["text"])
+
+It reads https://<domain>/.well-known/trooth.semanto and the company's keys from the same site, checks the file
+(signature, witness, roots, window) once for each new body it serves, and answers value questions with the same matcher
+as Trooth's service (answer.py). It reads the site again at most every refresh_seconds (900 at most, so a new version is
+used within 15 minutes), and the marks (changed since signing, expired) with each refresh.
+
+Trooth's API is used only for Trooth's witness keys and the monitor's marks. When it cannot be reached the source keeps
+answering from the last version that checked out, keeps the last keys and marks, applies the date marks itself, and logs
+a "trooth_api_unreachable" event. A new version is adopted only when it checks out; until then the last good one stays
+in use and the failure is logged. The standard library does the HTTP; pass `fetch` to use your own.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.parse
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
+
+from .answer import answer as _answer
+from .answer import fact_marks
+from .client import Fetch, urllib_fetch
+from .verify import verify_semanto
+
+TROOTH_API = "https://api.trooth.co"
+MAX_REFRESH_SECONDS = 900
+
+
+class SemantoSource:
+    def __init__(self, domain: str, fetch: Optional[Fetch] = None, api_base: str = TROOTH_API, refresh_seconds: float = MAX_REFRESH_SECONDS,
+                 now: Optional[Callable[[], float]] = None, on_event: Optional[Callable[[dict], None]] = None):
+        d = domain.lower()
+        for p in ("https://", "http://"):
+            if d.startswith(p):
+                d = d[len(p):]
+        self.domain = d.split("/")[0]
+        self.fetch: Fetch = fetch or urllib_fetch
+        self.api_base = api_base.rstrip("/")
+        self.refresh_seconds = min(max(refresh_seconds, 1), MAX_REFRESH_SECONDS)
+        self.now = now or time.time
+        self.on_event = on_event
+        self.events: List[dict] = []
+        self.file: Optional[dict] = None
+        self.company: Optional[dict] = None
+        self.trooth_keys: Optional[dict] = None
+        self.changed: List[str] = []
+        self.checked_at: Optional[float] = None
+        self.checks = 0
+        self._body: Optional[str] = None
+        self._lock = threading.Lock()
+
+    def _log(self, event: str, detail: str) -> None:
+        e = {"at": datetime.fromtimestamp(self.now(), timezone.utc).isoformat().replace("+00:00", "Z"), "event": event, "detail": detail}
+        self.events.append(e)
+        del self.events[:-200]
+        if self.on_event:
+            try:
+                self.on_event(e)
+            except Exception:  # noqa: BLE001 (the caller's logger must not stop an answer)
+                pass
+
+    def _json(self, url: str) -> Any:
+        status, _, body = self.fetch(url, {"Accept": "application/json"})
+        if status != 200:
+            raise RuntimeError(f"answered {status}")
+        return json.loads(body)
+
+    def _trooth_key_set(self) -> Optional[dict]:
+        try:
+            self.trooth_keys = self._json(f"{self.api_base}/public/semanto/.well-known/trooth-keys.json")
+        except Exception as e:  # noqa: BLE001
+            self._log("trooth_api_unreachable", f"Trooth's keys could not be read ({e}); {'the last ones are used' if self.trooth_keys else 'none are known yet'}.")
+        return self.trooth_keys
+
+    def _in_use(self) -> str:
+        return f"version {self.file['header']['version']} stays in use" if self.file else "there is no version yet"
+
+    def refresh(self) -> None:
+        """Read the site again, adopt a new version that checks out, and read the marks. Never raises."""
+        with self._lock:
+            started = self.now()
+            try:
+                self._load()
+            finally:
+                self.checked_at = started
+
+    def _load(self) -> None:
+        try:
+            file = self._json(f"https://{self.domain}/.well-known/trooth.semanto")
+        except Exception as e:  # noqa: BLE001
+            self._log("site_unreachable", f"https://{self.domain}/.well-known/trooth.semanto could not be read ({e}); {self._in_use()}.")
+            return
+        body = json.dumps(file, sort_keys=True, separators=(",", ":"))
+        if body != self._body:
+            try:
+                company = self._json(f"https://{self.domain}/.well-known/trooth-keys.json")
+            except Exception as e:  # noqa: BLE001
+                self._log("site_unreachable", f"The company's keys could not be read ({e}); the new version is not adopted.")
+                return
+            trooth = self._trooth_key_set()
+            res = verify_semanto(file, None, {"company": company, "trooth": trooth or {"keys": []}}, now=datetime.fromtimestamp(self.now(), timezone.utc))
+            self.checks += 1
+            h = file.get("header") or {}
+            domains = [str(d).lower() for d in h.get("domains") or []]
+            if res.get("ok") and self.domain not in domains:
+                self._log("version_refused", f"Version {h.get('version')} is for {', '.join(domains)}, not {self.domain}.")
+            elif not res.get("ok"):
+                self._log("version_refused", f"Version {h.get('version')} did not check out ({res.get('reason')}); {self._in_use()}.")
+            else:
+                before = self.file["header"]["version"] if self.file else None
+                self.file, self._body = file, body
+                self.company = {"trooth_id": h["trooth_id"], "org": h["org"], "domain": self.domain}
+                self.changed = []
+                self._log("version_adopted", f"Version {h['version']} checked out and is in use." if before is None else f"Version {h['version']} checked out and replaces version {before}.")
+        if self.file:
+            self._read_marks()
+
+    def _read_marks(self) -> None:
+        tid = urllib.parse.quote(self.file["header"]["trooth_id"], safe="")
+        try:
+            m = self._json(f"{self.api_base}/public/semanto/{tid}/facts/marks")
+            if int(m.get("version", -1)) == int(self.file["header"]["version"]):
+                self.changed = [x["fact_id"] for x in m.get("marks") or [] if x.get("mark") == "changed_since_signing"]
+        except Exception as e:  # noqa: BLE001
+            self._log("trooth_api_unreachable", f"The marks could not be read ({e}); the last ones and the date marks are used.")
+
+    def ensure_fresh(self) -> None:
+        """Read the site again when the last read is older than the refresh interval."""
+        if self.file is not None and self.checked_at is not None and self.now() - self.checked_at < self.refresh_seconds:
+            return
+        self.refresh()
+
+    def marks(self) -> Dict[str, str]:
+        """The marks in force now: the monitor's last marks for this version and the date marks."""
+        return fact_marks(self.file, self.changed, datetime.fromtimestamp(self.now(), timezone.utc)) if self.file else {}
+
+    def answer(self, fact_id: Optional[str] = None, question: Optional[str] = None) -> dict:
+        """Answer a fact ID or a plain question from the last version that checked out.
+        status "not_read" means no version has checked out yet; `events` says why."""
+        self.ensure_fresh()
+        if not self.file:
+            return {"object": "semanto.answer", "status": "not_read", "matched_by": None, "company": {"trooth_id": None, "name": None, "domain": self.domain},
+                    "version": None, "facts": [], "text": f"No signed record of {self.domain} could be read and checked yet."}
+        return _answer(self.file, self.company, fact_id=fact_id, question=question, marks=self.marks(), check_base=f"{self.api_base}/public/semanto")