diff --git a/api/scripts/verify_skills_filters.py b/api/scripts/verify_skills_filters.py new file mode 100644 index 0000000..de7bf28 --- /dev/null +++ b/api/scripts/verify_skills_filters.py @@ -0,0 +1,206 @@ +"""Check `GET /skills` search, filter and sort against a running API (STE-34). + +Nothing here trusts the filtered endpoint to grade itself. The expected answer for +every query is computed client-side from the plain registration-order listing, and +every filtered row's verdict is confirmed against `/check`, which reads the chain. + + uv run python scripts/verify_skills_filters.py --api http://127.0.0.1:8765 + +Exits non-zero on the first disagreement. +""" + +from __future__ import annotations + +import argparse +import sys + +import httpx +from sterish_pipeline.namespaces import is_test_skill_id + +VERDICTS = ("SAFE", "WARNING", "DANGEROUS", "UNAUDITED") +UA = {"User-Agent": "sterish-verify/1.0"} + + +class Mismatch(Exception): + pass + + +def check(condition: bool, message: str) -> None: + if not condition: + raise Mismatch(message) + print(f" ok {message}") + + +def all_rows(http: httpx.Client, api: str, **params) -> list[dict]: + rows, start = [], 0 + while True: + body = http.get(f"{api}/skills", params={**params, "start": start, "limit": 100}).json() + rows.extend(body["skills"]) + start += 100 + if start >= body["total"]: + return rows + + +def filtered(http: httpx.Client, api: str, **params) -> tuple[list[dict], dict]: + rows, start, body = [], 0, {} + while True: + body = http.get(f"{api}/skills", params={**params, "start": start, "limit": 100}).json() + rows.extend(body["skills"]) + start += 100 + if start >= body["total"]: + return rows, body + + +def expected_order(rows: list[dict], sort: str, order: str) -> list[str]: + desc = order == "desc" + by_id = sorted(rows, key=lambda r: r["skill_id"]) + if sort == "skill_id": + by_id = list(reversed(by_id)) if desc else by_id + return [r["skill_id"] for r in by_id] + if sort == "registered_at": + return [ + r["skill_id"] for r in sorted(by_id, key=lambda r: r["registered_at"], reverse=desc) + ] + scored = [r for r in by_id if r["latest_audited_trust_score"] is not None] + unscored = [r for r in by_id if r["latest_audited_trust_score"] is None] + scored = sorted(scored, key=lambda r: r["latest_audited_trust_score"], reverse=desc) + return [r["skill_id"] for r in scored + unscored] + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--api", required=True) + parser.add_argument("--check-rows", type=int, default=100, help="rows to confirm via /check") + args = parser.parse_args() + api = args.api.rstrip("/") + http = httpx.Client(timeout=120, headers=UA) + + base = all_rows(http, api) + print(f"registry: {len(base)} skills\n") + + print("1. verdict filter == client-side filter of the full listing, and /check agrees") + for verdict in VERDICTS: + want = sorted( + r["skill_id"] for r in base if (r["latest_audited_verdict"] or "UNAUDITED") == verdict + ) + rows, body = filtered(http, api, verdict=verdict) + got = sorted(r["skill_id"] for r in rows) + check(got == want, f"verdict={verdict}: {len(got)} rows match the full listing") + check(body["total"] == len(want), f"verdict={verdict}: total {body['total']} == rows") + check(body["excluded_stale"] == 0, f"verdict={verdict}: nothing excluded as stale") + for row in rows[: args.check_rows]: + if not row["latest_audited_version"]: + continue + onchain = http.get( + f"{api}/check/{row['skill_id']}/{row['latest_audited_version']}" + ).json()["verdict"] + if onchain != verdict: + raise Mismatch(f"{row['skill_id']} listed under {verdict} but chain says {onchain}") + print(f" ok verdict={verdict}: every row confirmed by /check") + + print("\n2. q and stale_audit") + for needle in ("stellar", "EVIL", "fixtures.safe", "zzz-no-such-skill"): + want = sorted(r["skill_id"] for r in base if needle.lower() in r["skill_id"].lower()) + got = sorted(r["skill_id"] for r in filtered(http, api, q=needle)[0]) + check(got == want, f"q={needle}: {len(got)} rows") + for flag in ("true", "false"): + want = sorted( + r["skill_id"] + for r in base + if (r["latest_version"] != r["latest_audited_version"]) == (flag == "true") + ) + got = sorted(r["skill_id"] for r in filtered(http, api, stale_audit=flag)[0]) + check(got == want, f"stale_audit={flag}: {len(got)} rows") + + print("\n3. sort orders") + for sort in ("registered_at", "trust_score", "skill_id"): + for order in ("asc", "desc"): + rows, _ = filtered(http, api, sort=sort, order=order) + got = [r["skill_id"] for r in rows] + want = expected_order(base, sort, order) + if sort == "registered_at": + # Ties on registered_at are ordered by skill_id; compare as groups. + got_keys = [(r["registered_at"]) for r in rows] + check( + got_keys == sorted(got_keys, reverse=order == "desc"), + f"sort={sort}&order={order}: monotonic", + ) + check(sorted(got) == sorted(want), f"sort={sort}&order={order}: same rows") + else: + check(got == want, f"sort={sort}&order={order}: exact order") + + print("\n4. paging a filter covers it exactly once") + whole = [r["skill_id"] for r in filtered(http, api, sort="skill_id", order="asc")[0]] + paged = [] + for start in range(0, len(whole), 7): + body = http.get( + f"{api}/skills", params={"sort": "skill_id", "order": "asc", "start": start, "limit": 7} + ).json() + paged.extend(r["skill_id"] for r in body["skills"]) + check(paged == whole, f"{len(whole)} rows in pages of 7, no overlap, no gap") + + print("\n5. invalid parameters are refused") + for query in ( + {"verdict": "safe"}, + {"sort": "verdict"}, + {"order": "up"}, + {"stale_audit": "yes"}, + {"q": ""}, + {"verified": "true"}, + ): + r = http.get(f"{api}/skills", params=query) + check(r.status_code == 400 and r.json()["error"] == "INVALID_PARAMETER", f"{query} -> 400") + + print("\n6. the plain listing is unchanged") + plain = http.get(f"{api}/skills", params={"limit": 5}).json() + check(plain["as_of"] is None, "no as_of without filter parameters") + check( + [r["skill_id"] for r in plain["skills"]] == [r["skill_id"] for r in base[:5]], + "registration order preserved", + ) + + print("\n7. test namespaces: hidden under a filter exactly as in the plain listing (STE-18)") + everything = all_rows(http, api, include_test="true") + tests = [r for r in everything if is_test_skill_id(r["skill_id"])] + check( + sorted(r["skill_id"] for r in base) + == sorted(r["skill_id"] for r in everything if not is_test_skill_id(r["skill_id"])), + f"plain listing = include_test listing minus {len(tests)} test rows", + ) + check(not any(is_test_skill_id(r["skill_id"]) for r in base), "no test id in the plain listing") + for verdict in VERDICTS: + matching_tests = [ + r for r in tests if (r["latest_audited_verdict"] or "UNAUDITED") == verdict + ] + rows, body = filtered(http, api, verdict=verdict) + check( + not any(is_test_skill_id(r["skill_id"]) for r in rows), + f"verdict={verdict}: no test id served", + ) + check( + body["hidden_test_entries"] == len(matching_tests), + f"verdict={verdict}: hidden_test_entries {body['hidden_test_entries']} " + "== matching test rows", + ) + check(body["chain_total"] == plain["chain_total"], f"verdict={verdict}: same chain_total") + with_tests, body = filtered(http, api, verdict=verdict, include_test="true") + want = sorted( + r["skill_id"] + for r in everything + if (r["latest_audited_verdict"] or "UNAUDITED") == verdict + ) + check( + sorted(r["skill_id"] for r in with_tests) == want and body["hidden_test_entries"] == 0, + f"verdict={verdict}&include_test=true: {len(want)} rows, nothing hidden", + ) + + print("\nPASS") + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except Mismatch as exc: + print(f"\nFAIL: {exc}") + sys.exit(1) diff --git a/api/src/sterish_api/config.py b/api/src/sterish_api/config.py index 207cc05..d4bd6a7 100644 --- a/api/src/sterish_api/config.py +++ b/api/src/sterish_api/config.py @@ -70,6 +70,10 @@ class Settings: # bucket and generated URLs said http://. Only proxies are trusted, never clients: # the port is not published outside the compose network. trusted_proxies: str + # Max age of the chain-read registry view used to filter and sort /skills (STE-34). + # Inside the 60 s per-version caching api-spec section 6 allows; dropped early when + # the indexer sees a new registry event. + skills_snapshot_ttl_seconds: int @property def network(self) -> str: @@ -128,6 +132,7 @@ def load_settings() -> Settings: skills_dir=os.getenv("STERISH_SKILLS_DIR", "").strip(), reports_dir=os.getenv("STERISH_REPORTS_DIR", "").strip(), chain_concurrency=_env_int("STERISH_CHAIN_CONCURRENCY", fanout.DEFAULT_CONCURRENCY), + skills_snapshot_ttl_seconds=_env_int("STERISH_SKILLS_SNAPSHOT_TTL", 30), rpc_url=os.getenv("STELLAR_RPC_URL", "https://soroban-testnet.stellar.org").strip(), network_passphrase=os.getenv("STELLAR_NETWORK_PASSPHRASE", TESTNET_PASSPHRASE), db_path=os.getenv("STERISH_DB_PATH", "sterish_index.db"), diff --git a/api/src/sterish_api/indexer.py b/api/src/sterish_api/indexer.py index eee56fd..188ab3d 100644 --- a/api/src/sterish_api/indexer.py +++ b/api/src/sterish_api/indexer.py @@ -33,6 +33,7 @@ from stellar_sdk.soroban_rpc import EventFilter, EventFilterType from sterish_pipeline.namespaces import LEGACY_TEST_SKILL_IDS, TEST_SKILL_ID_PREFIXES +from . import registry_snapshot from .chain import address_str, decode_verdict from .config import settings @@ -319,7 +320,12 @@ def poll_once() -> int: break rows = [r for r in (_decode_event(e) for e in res.events) if r] - stored += _store(rows) + new_rows = _store(rows) + if new_rows: + # A registration, a new version or a verdict landed: the filtered /skills + # view (STE-34) may now be wrong, so drop it rather than wait out its TTL. + registry_snapshot.invalidate() + stored += new_rows start = min(start + chunk, latest + 1) _meta_set("last_indexed_ledger", str(min(start - 1, latest))) diff --git a/api/src/sterish_api/models.py b/api/src/sterish_api/models.py index 5f84833..c911406 100644 --- a/api/src/sterish_api/models.py +++ b/api/src/sterish_api/models.py @@ -97,6 +97,8 @@ class SkillListResponse(BaseModel): """ skills: list[SkillListItem] + # With any filter or sort parameter, the number of rows AFTER filtering; without, + # the contract's skill count (api-spec 3.4). total: int start: int limit: int @@ -107,6 +109,12 @@ class SkillListResponse(BaseModel): hidden_test_entries: int #: Echo of the request, so a cached body is self-describing. include_test: bool = False + # STE-34, filtered listings only: when the snapshot the rows were chosen from was + # read from chain (unix seconds). Null for the listing without STE-34 parameters. + as_of: int | None = None + # STE-34: rows chosen from the snapshot whose live verdict no longer matched the + # verdict filter, left out of this page. Non-zero means the next page may shift. + excluded_stale: int = 0 class FeedItem(BaseModel): diff --git a/api/src/sterish_api/registry_snapshot.py b/api/src/sterish_api/registry_snapshot.py new file mode 100644 index 0000000..1339c17 --- /dev/null +++ b/api/src/sterish_api/registry_snapshot.py @@ -0,0 +1,168 @@ +"""The whole registry, read from chain, for filtering and sorting `GET /skills` (STE-34). + +A filter has to run over every row before a page is cut, or it lies: "highest trust +first" that only ranks the twenty rows that happened to be fetched is worse than no +sort at all. So the server needs a view of the whole registry. + +That view is built from the **chain**, not from the SQLite index, although the ticket +suggested the index. The index is filled from `getEvents`, which only reaches back +as far as the RPC node retains events; a rebuilt index silently lacks every skill +registered before that window, and `verdict=SAFE` would quietly return fewer rows +than exist. That is the failure `test_cache_is_not_source_of_truth.py` exists to +forbid: delete the cache and the answers must stay correct. + +Freshness. The view is at most `STERISH_SKILLS_SNAPSHOT_TTL` seconds old (default 30, +inside the 60 s per-version caching api-spec §6 already allows), and is dropped +early whenever the indexer stores a new registry event. It is only used to **choose** +rows: the rows actually returned are re-read from chain on every request, and a row +whose live verdict no longer matches the filter is left out (see routes/check.py). + +Test namespaces (STE-18). The view keeps every row the registry holds and marks the +test-namespace ones with `is_test`; the route hides them unless `include_test`. The +scan goes through `skills.scan_registry`, so the filtered and the plain listing share +one `MAX_SCAN` cap and report the same `chain_total`. + +Cost: one `query_all_skills` per scan page plus one `get_version` per audited skill, +overlapped (STE-33), at most once per TTL and only while requests arrive. +""" + +from __future__ import annotations + +import threading +import time +from dataclasses import dataclass + +from sterish_pipeline.namespaces import is_test_skill_id + +from . import chain, fanout, skills +from .config import settings + + +@dataclass(frozen=True) +class Row: + skill_id: str + owner: str + registered_at: int + version_count: int + latest_version: str + latest_audited_version: str | None + verdict: str | None + trust_score: int | None + is_verified: bool | None + # The latest audited version exists but could not be read. Not the same as + # UNAUDITED, and never matched as such. + read_failed: bool + + @property + def is_test(self) -> bool: + """Registered under a test namespace, hidden by default (STE-18).""" + return is_test_skill_id(self.skill_id) + + @property + def stale_audit(self) -> bool: + """The newest version is not the audited one (including never audited).""" + return self.latest_version != self.latest_audited_version + + def as_entry(self) -> dict: + return { + "skill_id": self.skill_id, + "owner": self.owner, + "registered_at": self.registered_at, + "versions": [None] * self.version_count, + "latest_version": self.latest_version, + "latest_audited_version": self.latest_audited_version, + } + + +@dataclass(frozen=True) +class Snapshot: + rows: tuple[Row, ...] + built_at: float + # get_skill_count() as read with these rows; always the real on-chain number. + chain_total: int + + +_current: Snapshot | None = None +_generation = 0 +_state_lock = threading.Lock() +_build_lock = threading.Lock() + + +def invalidate() -> None: + """Drop the view. The next request rebuilds it from chain.""" + global _current, _generation + with _state_lock: + _current = None + _generation += 1 + + +def _fresh(snapshot: Snapshot | None) -> bool: + return ( + snapshot is not None + and time.time() - snapshot.built_at < settings.skills_snapshot_ttl_seconds + ) + + +def get() -> Snapshot: + """The current view, rebuilding it if stale. One build at a time. + + A ChainError while building propagates (502 at the edge): an unreadable registry + must never be served as an empty one. + """ + with _state_lock: + if _fresh(_current): + return _current # type: ignore[return-value] + + with _build_lock: + with _state_lock: + if _fresh(_current): + return _current # type: ignore[return-value] + generation = _generation + + snapshot = _build() + + with _state_lock: + # Invalidated while we were reading: this view may already be stale, so + # serve it to the caller that waited for it but do not keep it. + if _generation == generation: + _set(snapshot) + return snapshot + + +def _set(snapshot: Snapshot) -> None: + global _current + _current = snapshot + + +def _read_latest(entry: dict) -> tuple[dict | None, bool]: + version = entry["latest_audited_version"] + if not version: + return None, False + try: + return chain.get_version(entry["skill_id"], version), False + except chain.ContractError: + return None, True + + +def _build() -> Snapshot: + entries, chain_total = skills.scan_registry() + + results = fanout.map_bounded(_read_latest, entries, settings.chain_concurrency) + + rows = [] + for entry, (record, failed) in zip(entries, results, strict=True): + rows.append( + Row( + skill_id=entry["skill_id"], + owner=entry["owner"], + registered_at=entry["registered_at"], + version_count=len(entry["versions"]), + latest_version=entry["latest_version"], + latest_audited_version=entry["latest_audited_version"], + verdict=record["verdict"] if record else None, + trust_score=record["trust_score"] if record else None, + is_verified=record["is_verified"] if record else None, + read_failed=failed, + ) + ) + return Snapshot(rows=tuple(rows), built_at=time.time(), chain_total=chain_total) diff --git a/api/src/sterish_api/routes/check.py b/api/src/sterish_api/routes/check.py index 00a4109..eeb44b0 100644 --- a/api/src/sterish_api/routes/check.py +++ b/api/src/sterish_api/routes/check.py @@ -6,9 +6,9 @@ import re -from fastapi import APIRouter, Query +from fastapi import APIRouter, Query, Request -from .. import chain, fanout, indexer, skills +from .. import chain, fanout, indexer, registry_snapshot, skills from ..config import settings from ..errors import ApiError from ..models import ( @@ -196,8 +196,26 @@ def skill_detail(skill_id: str): ) +VERDICTS = ("SAFE", "WARNING", "DANGEROUS", "UNAUDITED") +SORTS = ("registered_at", "trust_score", "skill_id") +ORDERS = ("asc", "desc") +MAX_QUERY_LENGTH = 200 + +# Parameters the ticket considered and rejected. Answered with a pointer to what to +# use instead, rather than silently ignored and returning an unfiltered page. +REJECTED_PARAMETERS = { + "verified": "is_verified is true exactly when the verdict is SAFE; use verdict=SAFE", + "owner": "the registry has one owner today; filtering by owner is not supported", +} + + +def _invalid(detail: str) -> ApiError: + return ApiError(400, "INVALID_PARAMETER", detail) + + @router.get("/skills", response_model=SkillListResponse) def list_skills( + request: Request, start: int = Query(default=0, ge=0), limit: int = Query(default=20, ge=1, le=100), include_test: bool = Query( @@ -206,7 +224,156 @@ def list_skills( "default; `hidden_test_entries` says how many, and `chain_total` is always " "the real on-chain count.", ), + verdict: str | None = Query(default=None), + q: str | None = Query(default=None), + stale_audit: str | None = Query(default=None), + sort: str | None = Query(default=None), + order: str | None = Query(default=None), ): + for name, why in REJECTED_PARAMETERS.items(): + if name in request.query_params: + raise _invalid(f"{name} is not a supported parameter: {why}") + + if all(p is None for p in (verdict, q, stale_audit, sort, order)): + return _list_plain(start, limit, include_test) + return _list_filtered(start, limit, include_test, verdict, q, stale_audit, sort, order) + + +def _list_filtered( + start: int, + limit: int, + include_test: bool, + verdict: str | None, + q: str | None, + stale_audit: str | None, + sort: str | None, + order: str | None, +) -> SkillListResponse: + """Filter and sort the whole registry, then page (STE-34, api-spec 3.4). + + Rows are chosen from a chain-read snapshot (registry_snapshot.py) and then the + returned page is re-read live. A row whose live verdict no longer matches the + `verdict` filter is left out and counted in `excluded_stale`, and the snapshot is + dropped so the next request agrees with the chain again. + + Test namespaces are hidden exactly as in the plain listing (STE-18), and the three + counts stay honest: `total` is what the filters leave, `chain_total` the contract's + own count, and `hidden_test_entries` the test-namespace rows that matched every + other filter and were hidden only because of their namespace. + """ + if verdict is not None and verdict not in VERDICTS: + raise _invalid(f"verdict must be one of {', '.join(VERDICTS)}") + if q is not None and not q.strip(): + raise _invalid("q must not be empty") + if q is not None and len(q) > MAX_QUERY_LENGTH: + raise _invalid(f"q must be at most {MAX_QUERY_LENGTH} characters") + if stale_audit is not None and stale_audit not in ("true", "false"): + raise _invalid("stale_audit must be true or false") + if sort is not None and sort not in SORTS: + raise _invalid(f"sort must be one of {', '.join(SORTS)}") + if order is not None and order not in ORDERS: + raise _invalid("order must be asc or desc") + + snapshot = registry_snapshot.get() + needle = q.strip().lower() if q is not None else None + want_stale = None if stale_audit is None else stale_audit == "true" + + def matches(row: registry_snapshot.Row) -> bool: + if needle is not None and needle not in row.skill_id.lower(): + return False + if want_stale is not None and row.stale_audit is not want_stale: + return False + if verdict is not None: + if row.read_failed: + return False # unknown is not UNAUDITED, and not anything else either + if (row.verdict or "UNAUDITED") != verdict: + return False + return True + + matched = [row for row in snapshot.rows if matches(row)] + hidden = 0 if include_test else sum(1 for row in matched if row.is_test) + rows = matched if include_test else [row for row in matched if not row.is_test] + rows = _sorted(rows, sort or "registered_at", order or "desc") + + total = len(rows) + page = rows[start : start + limit] + + def live(row: registry_snapshot.Row) -> dict | None: + if not row.latest_audited_version: + return None + return _version_record_or_none(row.skill_id, row.latest_audited_version) + + records = fanout.map_bounded(live, page, settings.chain_concurrency) + + items: list[SkillListItem] = [] + excluded = 0 + for row, record in zip(page, records, strict=True): + if verdict is not None: + live_verdict = record["verdict"] if record else None + unreadable = record is None and row.latest_audited_version is not None + if unreadable or (live_verdict or "UNAUDITED") != verdict: + excluded += 1 + continue + items.append(_list_item(row.as_entry(), record)) + + if excluded: + registry_snapshot.invalidate() + + return SkillListResponse( + skills=items, + total=total, + start=start, + limit=limit, + chain_total=snapshot.chain_total, + hidden_test_entries=hidden, + include_test=include_test, + as_of=int(snapshot.built_at), + excluded_stale=excluded, + ) + + +def _sorted( + rows: list[registry_snapshot.Row], sort: str, order: str +) -> list[registry_snapshot.Row]: + """Stable, deterministic ordering. Ties break on skill_id ascending. + + Rows with no trust score (never audited, or unreadable) sort LAST in both + directions: "lowest trust first" must not open with rows that have no trust score. + """ + descending = order == "desc" + by_id = sorted(rows, key=lambda r: r.skill_id) + if sort == "skill_id": + return list(reversed(by_id)) if descending else by_id + if sort == "registered_at": + return sorted(by_id, key=lambda r: r.registered_at, reverse=descending) + + scored = [r for r in by_id if r.trust_score is not None] + unscored = [r for r in by_id if r.trust_score is None] + return sorted(scored, key=lambda r: r.trust_score, reverse=descending) + unscored + + +def _list_item(entry: dict, record: dict | None) -> SkillListItem: + verdict = score = verified = None + if record is not None: + verdict = record["verdict"] + score = record["trust_score"] + verified = record["is_verified"] + return SkillListItem( + skill_id=entry["skill_id"], + owner=entry["owner"], + registered_at=entry["registered_at"], + version_count=len(entry["versions"]), + latest_version=entry["latest_version"], + latest_audited_version=entry["latest_audited_version"], + latest_audited_verdict=verdict, + latest_audited_trust_score=score, + latest_audited_is_verified=verified, + ) + + +def _list_plain(start: int, limit: int, include_test: bool) -> SkillListResponse: + """The listing without STE-34 parameters: registration order, test namespaces + hidden unless asked for (STE-18). Unchanged by STE-34.""" entries, total, chain_total, hidden = skills.visible_page(start, limit, include_test) def _latest_audited_record(entry: dict) -> dict | None: @@ -219,27 +386,7 @@ def _latest_audited_record(entry: dict) -> dict | None: # trip per row in series (STE-33). Order is preserved, so this zips back cleanly. records = fanout.map_bounded(_latest_audited_record, entries, settings.chain_concurrency) - items: list[SkillListItem] = [] - for entry, record in zip(entries, records, strict=True): - latest_audited = entry["latest_audited_version"] - verdict = score = verified = None - if record is not None: - verdict = record["verdict"] - score = record["trust_score"] - verified = record["is_verified"] - items.append( - SkillListItem( - skill_id=entry["skill_id"], - owner=entry["owner"], - registered_at=entry["registered_at"], - version_count=len(entry["versions"]), - latest_version=entry["latest_version"], - latest_audited_version=latest_audited, - latest_audited_verdict=verdict, - latest_audited_trust_score=score, - latest_audited_is_verified=verified, - ) - ) + items = [_list_item(entry, record) for entry, record in zip(entries, records, strict=True)] return SkillListResponse( skills=items, diff --git a/api/tests/conftest.py b/api/tests/conftest.py index 7c49178..f34237f 100644 --- a/api/tests/conftest.py +++ b/api/tests/conftest.py @@ -38,7 +38,7 @@ def _isolated_db(tmp_path): so the one shared object is mutated in place via `object.__setattr__` and restored afterwards — patching `config.settings` itself would not reach those modules. """ - from sterish_api import config, indexer, payments + from sterish_api import config, indexer, payments, registry_snapshot db = tmp_path / "index.db" previous = config.settings.db_path @@ -49,11 +49,15 @@ def _isolated_db(tmp_path): object.__setattr__(config.settings, "payments_db_path", str(tmp_path / "payments.db")) indexer.init_db() payments.init_db() + # The /skills snapshot (STE-34) is module state: one test's registry must never + # be served to the next. + registry_snapshot.invalidate() try: yield db finally: object.__setattr__(config.settings, "db_path", previous) object.__setattr__(config.settings, "payments_db_path", previous_payments) + registry_snapshot.invalidate() @pytest.fixture diff --git a/api/tests/test_skills_filter.py b/api/tests/test_skills_filter.py new file mode 100644 index 0000000..832005f --- /dev/null +++ b/api/tests/test_skills_filter.py @@ -0,0 +1,553 @@ +"""`GET /skills` search, filter and sort (STE-34), with the chain stubbed. + +The registry below is deliberately awkward: a never-audited skill, a stale audit, a +row whose record cannot be read, duplicate trust scores and duplicate registration +times, so that every ordering rule and every "unknown is not UNAUDITED" rule has +something to bite on. +""" + +import threading +import time + +import pytest + +from sterish_api import chain, indexer, registry_snapshot +from tests.conftest import SAFE_RECORD + +OWNER = "G" + "A" * 55 + + +def _entry(skill_id, registered_at, latest="1.0.0", audited="1.0.0", versions=1): + return { + "skill_id": skill_id, + "owner": OWNER, + "versions": [f"1.0.{n}" for n in range(versions)], + "latest_version": latest, + "latest_audited_version": audited, + "registered_at": registered_at, + } + + +# skill_id -> (entry, record-or-exception) +REGISTRY = { + "com.acme.pdf-suite": (_entry("com.acme.pdf-suite", 100), ("SAFE", 88)), + "com.acme.weather": (_entry("com.acme.weather", 200), ("SAFE", 95)), + "com.evil.wallet-drainer": (_entry("com.evil.wallet-drainer", 300), ("DANGEROUS", 10)), + "com.evil.pdf-stealer": (_entry("com.evil.pdf-stealer", 300), ("DANGEROUS", 10)), + "org.example.half-sure": (_entry("org.example.half-sure", 400), ("WARNING", 60)), + "org.example.never-audited": ( + _entry("org.example.never-audited", 500, audited=None), + None, + ), + "org.example.stale": ( + _entry("org.example.stale", 600, latest="2.0.0", audited="1.0.0", versions=2), + ("SAFE", 70), + ), + "org.example.unreadable": (_entry("org.example.unreadable", 700), "unreadable"), +} +ORDER = list(REGISTRY) # registration order + + +class Chain: + """A fake registry that counts its reads.""" + + def __init__(self, monkeypatch, registry=None): + self.registry = dict(registry or REGISTRY) + self.order = list(self.registry) + self.count_calls = 0 + self.page_calls: list[tuple[int, int]] = [] + self.version_calls = 0 + self.overrides: dict[str, tuple[str, int]] = {} + self.lock = threading.Lock() + monkeypatch.setattr(chain, "get_skill_count", self.get_skill_count) + monkeypatch.setattr(chain, "query_all_skills", self.query_all_skills) + monkeypatch.setattr(chain, "get_version", self.get_version) + + def get_skill_count(self): + with self.lock: + self.count_calls += 1 + return len(self.order) + + def query_all_skills(self, start, limit): + with self.lock: + self.page_calls.append((start, limit)) + return [self.registry[s][0] for s in self.order[start : start + limit]] + + def get_version(self, skill_id, version): + with self.lock: + self.version_calls += 1 + spec = self.overrides.get(skill_id) or self.registry[skill_id][1] + if spec == "unreadable": + raise chain.ContractError(4) + verdict, score = spec + return dict( + SAFE_RECORD, + skill_id=skill_id, + version=version, + verdict=verdict, + trust_score=score, + is_verified=verdict == "SAFE", + ) + + +@pytest.fixture +def registry(monkeypatch): + return Chain(monkeypatch) + + +def ids(response): + return [row["skill_id"] for row in response.json()["skills"]] + + +# --- the plain listing is unchanged ---------------------------------------------------------- + + +def test_no_parameters_keeps_registration_order_and_contract_total(client, registry): + r = client.get("/skills?limit=100") + body = r.json() + assert ids(r) == ORDER + assert body["total"] == len(ORDER) + assert body["as_of"] is None and body["excluded_stale"] == 0 + + +def test_plain_start_and_limit_page_the_scanned_registry_as_on_main(client, registry): + # Since STE-18 the plain listing scans the registry and pages the visible rows, so + # that hiding test namespaces cannot leave holes in a page. STE-34 leaves that path + # exactly as it is. + r = client.get("/skills?start=2&limit=3") + assert ids(r) == ORDER[2:5] + assert registry.page_calls == [(0, 100)] + + +# --- filters ----------------------------------------------------------------------------------- + + +def test_verdict_filter_returns_only_that_verdict_and_counts_after_filtering(client, registry): + r = client.get("/skills?verdict=DANGEROUS") + body = r.json() + assert sorted(ids(r)) == ["com.evil.pdf-stealer", "com.evil.wallet-drainer"] + assert body["total"] == 2 # not the registry's 8 + assert all(row["latest_audited_verdict"] == "DANGEROUS" for row in body["skills"]) + assert body["as_of"] is not None + + +def test_a_filter_with_no_matches_is_an_empty_page_not_an_error(client, registry): + registry.registry.pop("org.example.half-sure") + registry.order.remove("org.example.half-sure") + r = client.get("/skills?verdict=WARNING") + assert r.status_code == 200 + assert r.json() == { + "skills": [], + "total": 0, + "start": 0, + "limit": 20, + "chain_total": len(registry.order), + "hidden_test_entries": 0, + "include_test": False, + "as_of": r.json()["as_of"], + "excluded_stale": 0, + } + + +def test_unaudited_means_never_audited_not_unreadable(client, registry): + """A row whose record failed to read is unknown. Calling it UNAUDITED would be a + claim about the registry that the registry never made.""" + r = client.get("/skills?verdict=UNAUDITED") + assert ids(r) == ["org.example.never-audited"] + + +def test_an_unreadable_row_matches_no_verdict_at_all(client, registry): + for verdict in ("SAFE", "WARNING", "DANGEROUS", "UNAUDITED"): + assert "org.example.unreadable" not in ids(client.get(f"/skills?verdict={verdict}")) + + +def test_an_unreadable_row_still_appears_without_a_verdict_filter(client, registry): + r = client.get("/skills?q=unreadable") + assert ids(r) == ["org.example.unreadable"] + assert r.json()["skills"][0]["latest_audited_verdict"] is None + + +def test_q_is_a_case_insensitive_substring_of_skill_id(client, registry): + assert sorted(ids(client.get("/skills?q=PDF"))) == [ + "com.acme.pdf-suite", + "com.evil.pdf-stealer", + ] + assert ids(client.get("/skills?q=nothing-like-this")) == [] + + +def test_q_is_trimmed(client, registry): + assert ids(client.get("/skills?q=%20weather%20")) == ["com.acme.weather"] + + +def test_stale_audit_true_includes_never_audited(client, registry): + r = client.get("/skills?stale_audit=true") + assert sorted(ids(r)) == ["org.example.never-audited", "org.example.stale"] + + +def test_stale_audit_false_is_the_complement(client, registry): + stale = set(ids(client.get("/skills?stale_audit=true&limit=100"))) + fresh = set(ids(client.get("/skills?stale_audit=false&limit=100"))) + assert stale.isdisjoint(fresh) and stale | fresh == set(ORDER) + + +def test_filters_combine(client, registry): + r = client.get("/skills?verdict=SAFE&stale_audit=true") + assert ids(r) == ["org.example.stale"] + r = client.get("/skills?verdict=SAFE&q=acme&sort=trust_score&order=desc") + assert ids(r) == ["com.acme.weather", "com.acme.pdf-suite"] + + +# --- sorting ------------------------------------------------------------------------------------ + + +def test_filtered_default_order_is_newest_registration_first(client, registry): + r = client.get("/skills?q=com.") + # 300 twice: ties break on skill_id ascending. + assert ids(r) == [ + "com.evil.pdf-stealer", + "com.evil.wallet-drainer", + "com.acme.weather", + "com.acme.pdf-suite", + ] + + +def test_registered_at_ascending(client, registry): + r = client.get("/skills?sort=registered_at&order=asc&limit=100") + assert ids(r)[:2] == ["com.acme.pdf-suite", "com.acme.weather"] + assert ids(r)[-1] == "org.example.unreadable" + + +@pytest.mark.parametrize("order", ["asc", "desc"]) +def test_rows_without_a_trust_score_sort_last_in_both_directions(client, registry, order): + r = client.get(f"/skills?sort=trust_score&order={order}&limit=100") + assert ids(r)[-2:] == ["org.example.never-audited", "org.example.unreadable"] + scores = [row["latest_audited_trust_score"] for row in r.json()["skills"][:-2]] + assert scores == sorted(scores, reverse=order == "desc") + + +def test_equal_trust_scores_break_on_skill_id(client, registry): + r = client.get("/skills?sort=trust_score&order=asc&limit=2") + assert ids(r) == ["com.evil.pdf-stealer", "com.evil.wallet-drainer"] + + +def test_skill_id_sort_both_ways(client, registry): + asc = ids(client.get("/skills?sort=skill_id&order=asc&limit=100")) + assert asc == sorted(ORDER) + assert ids(client.get("/skills?sort=skill_id&order=desc&limit=100")) == list(reversed(asc)) + + +def test_order_alone_applies_to_the_default_sort(client, registry): + assert ids(client.get("/skills?order=asc&limit=100")) == ids( + client.get("/skills?sort=registered_at&order=asc&limit=100") + ) + + +# --- paging over filtered results --------------------------------------------------------------- + + +def test_pages_over_a_filter_do_not_overlap_and_cover_everything(client, registry): + whole = ids(client.get("/skills?sort=skill_id&order=asc&limit=100")) + pages = [] + for start in range(0, len(whole), 3): + r = client.get(f"/skills?sort=skill_id&order=asc&start={start}&limit=3") + assert r.json()["total"] == len(whole) + pages.extend(ids(r)) + assert pages == whole + + +def test_start_past_the_end_is_an_empty_page_with_the_real_total(client, registry): + body = client.get("/skills?verdict=SAFE&start=50").json() + assert body["skills"] == [] and body["total"] == 3 + + +def test_only_the_returned_page_is_read_live(client, registry): + client.get("/skills?sort=skill_id&limit=100") # build the snapshot + before = registry.version_calls + client.get("/skills?sort=skill_id&limit=2") + assert registry.version_calls - before == 2 + + +# --- invalid parameters --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "query", + [ + "verdict=safe", + "verdict=VERIFIED", + "verdict=", + "sort=verdict", + "sort=owner", + "order=up", + "stale_audit=yes", + "stale_audit=1", + "q=", + "q=%20%20", + "q=" + "x" * 201, + "verified=true", + "owner=" + OWNER, + ], +) +def test_invalid_parameters_are_400_never_ignored(client, registry, query): + r = client.get(f"/skills?{query}") + assert r.status_code == 400, r.text + assert r.json()["error"] == "INVALID_PARAMETER" + + +def test_rejected_parameters_say_what_to_use_instead(client, registry): + assert "verdict=SAFE" in client.get("/skills?verified=true").json()["detail"] + + +# --- snapshot versus chain ------------------------------------------------------------------------ + + +def test_a_row_whose_live_verdict_changed_is_left_out_and_the_view_refreshed(client, registry): + """The edge case the ticket names: chosen as SAFE, reads DANGEROUS now.""" + assert "com.acme.weather" in ids(client.get("/skills?verdict=SAFE")) + + registry.overrides["com.acme.weather"] = ("DANGEROUS", 5) # re-audited on chain + r = client.get("/skills?verdict=SAFE") + body = r.json() + assert "com.acme.weather" not in ids(r) + assert body["excluded_stale"] == 1 + assert all(row["latest_audited_verdict"] == "SAFE" for row in body["skills"]) + + # The next request rebuilds and agrees with the chain everywhere. + assert "com.acme.weather" not in ids(client.get("/skills?verdict=SAFE")) + assert "com.acme.weather" in ids(client.get("/skills?verdict=DANGEROUS")) + assert client.get("/skills?verdict=SAFE").json()["excluded_stale"] == 0 + + +def test_without_a_verdict_filter_the_live_verdict_is_shown(client, registry): + client.get("/skills?q=weather") + registry.overrides["com.acme.weather"] = ("DANGEROUS", 5) + row = client.get("/skills?q=weather").json()["skills"][0] + assert row["latest_audited_verdict"] == "DANGEROUS" + + +def test_a_row_that_becomes_unreadable_is_excluded_from_a_verdict_filter(client, registry): + client.get("/skills?verdict=SAFE") + registry.overrides["com.acme.weather"] = "unreadable" + r = client.get("/skills?verdict=SAFE") + assert "com.acme.weather" not in ids(r) + assert r.json()["excluded_stale"] == 1 + + +def test_the_snapshot_is_reused_within_its_ttl(client, registry): + client.get("/skills?verdict=SAFE") + client.get("/skills?verdict=DANGEROUS") + client.get("/skills?q=acme") + assert registry.count_calls == 1 + + +def test_the_snapshot_expires(client, registry, monkeypatch): + client.get("/skills?verdict=SAFE") + real = time.time + monkeypatch.setattr(registry_snapshot.time, "time", lambda: real() + 3600) + client.get("/skills?verdict=SAFE") + assert registry.count_calls == 2 + + +def test_a_new_indexed_event_drops_the_snapshot(client, registry): + client.get("/skills?verdict=SAFE") + registry.registry["com.new.skill"] = (_entry("com.new.skill", 900), ("SAFE", 99)) + registry.order.append("com.new.skill") + assert "com.new.skill" not in ids(client.get("/skills?verdict=SAFE&limit=100")) + + stored = indexer._store( + [ + { + "event": "skill_registered", + "skill_id": "com.new.skill", + "version": "", + "content_hash": None, + "verdict": None, + "trust_score": None, + "owner": OWNER, + "auditor": None, + "ledger": 1, + "tx_hash": "f" * 64, + "occurred_at": 1, + } + ] + ) + assert stored == 1 + # _store only writes; poll_once is what drops the view. Exercise that path. + registry_snapshot.invalidate() + assert "com.new.skill" in ids(client.get("/skills?verdict=SAFE&limit=100")) + + +def test_poll_once_drops_the_snapshot_when_it_stores_events(client, registry, monkeypatch): + client.get("/skills?verdict=SAFE") + dropped = [] + monkeypatch.setattr(registry_snapshot, "invalidate", lambda: dropped.append(1)) + + class Health: + oldest_ledger = 10 + + class Server: + def __init__(self, url): + pass + + def get_health(self): + return Health() + + def get_latest_ledger(self): + return type("L", (), {"sequence": 10})() + + event_row = { + "event": "verdict_flipped", + "skill_id": "com.acme.weather", + "version": "1.0.0", + "content_hash": None, + "verdict": "DANGEROUS", + "trust_score": 5, + "owner": None, + "auditor": None, + "ledger": 10, + "tx_hash": "e" * 64, + "occurred_at": 1, + } + from sterish_api.config import settings + + object.__setattr__(settings, "registry_contract_id", settings.registry_contract_id or "C") + monkeypatch.setattr(indexer, "SorobanServer", Server) + monkeypatch.setattr( + indexer, "_get_events", lambda server, start: type("R", (), {"events": [1]})() + ) + monkeypatch.setattr(indexer, "_decode_event", lambda ev: dict(event_row)) + + indexer.poll_once() + assert dropped == [1] + + dropped.clear() + indexer.poll_once() # same event again: INSERT OR IGNORE stores nothing + assert dropped == [] + + +def test_the_snapshot_reads_the_registry_in_pages_of_100(client, monkeypatch): + big = { + f"com.bulk.skill-{n:03d}": (_entry(f"com.bulk.skill-{n:03d}", n), ("SAFE", n % 100)) + for n in range(250) + } + fake = Chain(monkeypatch, registry=big) + r = client.get("/skills?sort=skill_id&order=asc&start=240&limit=100") + assert r.json()["total"] == 250 + assert ids(r)[0] == "com.bulk.skill-240" + assert fake.page_calls == [(0, 100), (100, 100), (200, 100)] + + +def test_concurrent_requests_build_the_snapshot_once(client, registry, monkeypatch): + real = registry.get_skill_count + + def slow_count(): + time.sleep(0.2) + return real() + + monkeypatch.setattr(chain, "get_skill_count", slow_count) + results = [] + + def fetch(): + results.append(client.get("/skills?verdict=SAFE").status_code) + + threads = [threading.Thread(target=fetch) for _ in range(6)] + for t in threads: + t.start() + for t in threads: + t.join() + assert results == [200] * 6 + assert registry.count_calls == 1 + + +def test_a_view_invalidated_during_its_build_is_not_kept(registry, monkeypatch): + real = registry.get_skill_count + + def count_then_invalidate(): + n = real() + registry_snapshot.invalidate() # an event lands mid-build + return n + + monkeypatch.setattr(chain, "get_skill_count", count_then_invalidate) + first = registry_snapshot.get() + assert len(first.rows) == len(ORDER) # the waiting caller still gets an answer + monkeypatch.setattr(chain, "get_skill_count", real) + registry_snapshot.get() + assert registry.count_calls == 2 # ...but it was not cached + + +def test_an_unreadable_registry_is_502_not_an_empty_page(client, monkeypatch): + def down(): + raise chain.ChainError("rpc down") + + monkeypatch.setattr(chain, "get_skill_count", down) + r = client.get("/skills?verdict=SAFE") + assert r.status_code == 502 + assert r.json()["error"] == "RPC_UNAVAILABLE" + + +# --- test namespaces stay hidden under a filter too (STE-18) ---------------------------------- + +TEST_ROWS = { + "com.sterish.e2e-safe-probe": (_entry("com.sterish.e2e-safe-probe", 800), ("SAFE", 99)), + "com.sterish.weather-lookup": (_entry("com.sterish.weather-lookup", 900), ("DANGEROUS", 5)), +} + + +@pytest.fixture +def mixed(monkeypatch): + return Chain(monkeypatch, registry={**REGISTRY, **TEST_ROWS}) + + +def test_a_filter_hides_test_namespaces_and_says_how_many_it_hid(client, mixed): + body = client.get("/skills?verdict=SAFE&sort=trust_score&order=desc").json() + returned = [row["skill_id"] for row in body["skills"]] + assert "com.sterish.e2e-safe-probe" not in returned + assert returned == ["com.acme.weather", "com.acme.pdf-suite", "org.example.stale"] + assert body["total"] == 3 + assert body["hidden_test_entries"] == 1 # the SAFE test row; the DANGEROUS one did not match + assert body["chain_total"] == len(REGISTRY) + len(TEST_ROWS) + assert body["include_test"] is False + + +def test_include_test_brings_test_namespaces_back_into_a_filtered_listing(client, mixed): + body = client.get("/skills?verdict=SAFE&sort=trust_score&order=desc&include_test=true").json() + assert [row["skill_id"] for row in body["skills"]][0] == "com.sterish.e2e-safe-probe" + assert body["total"] == 4 + assert body["hidden_test_entries"] == 0 + assert body["include_test"] is True + + +def test_a_legacy_test_id_is_hidden_by_a_search_that_names_it(client, mixed): + body = client.get("/skills?q=weather").json() + assert [row["skill_id"] for row in body["skills"]] == ["com.acme.weather"] + assert body["hidden_test_entries"] == 1 + + +def test_the_plain_listing_still_hides_every_test_row(client, mixed): + body = client.get("/skills?limit=100").json() + assert [row["skill_id"] for row in body["skills"]] == ORDER + assert body["hidden_test_entries"] == len(TEST_ROWS) + assert body["as_of"] is None + + +def test_filtered_and_plain_listings_agree_on_what_is_visible(client, mixed): + plain = client.get("/skills?limit=100").json() + sorted_ = client.get("/skills?sort=registered_at&order=asc&limit=100").json() + # Same rows; the order differs only where registered_at ties (sorted breaks on skill_id). + assert sorted(r["skill_id"] for r in plain["skills"]) == sorted( + r["skill_id"] for r in sorted_["skills"] + ) + assert plain["total"] == sorted_["total"] + assert plain["chain_total"] == sorted_["chain_total"] + assert plain["hidden_test_entries"] == sorted_["hidden_test_entries"] + + +def test_the_snapshot_shares_the_plain_listings_scan_cap(client, monkeypatch): + from sterish_api import skills + + monkeypatch.setattr(skills, "MAX_SCAN", 5) + fake = Chain(monkeypatch) + body = client.get("/skills?sort=skill_id&limit=100").json() + assert body["total"] == 5 + assert body["chain_total"] == len(ORDER) + assert fake.page_calls == [(0, 5)] diff --git a/docs/api-spec.md b/docs/api-spec.md index cb5931c..52b0b8f 100644 --- a/docs/api-spec.md +++ b/docs/api-spec.md @@ -243,15 +243,62 @@ this (see §6) and, once the indexer (STE-13) exists, serves it from the index i ### 3.4 `GET /skills` -Paginated catalogue. Backed by `query_all_skills(start, limit)`. +Paginated catalogue, searchable, filterable and sortable (STE-34). **Query parameters** | Parameter | Type | Default | Notes | |---|---|---|---| -| `start` | integer ≥ 0 | `0` | Offset into the **filtered** list, not into the raw on-chain index. | +| `start` | integer ≥ 0 | `0` | Offset into the **filtered** (and, with `sort`, sorted) list, not into the raw on-chain index. | | `limit` | integer 1–100 | `20` | Clamped to 100. | -| `include_test` | boolean | `false` | Include skills registered under a test namespace. | +| `include_test` | boolean | `false` | Include skills registered under a test namespace. Applies to both listings. | +| `verdict` | `SAFE` \| `WARNING` \| `DANGEROUS` \| `UNAUDITED` | — | Verdict of the **latest audited** version. `UNAUDITED` = no audited version. Uppercase only. | +| `q` | string, 1–200 chars | — | Case-insensitive substring of `skill_id`, trimmed. `skill_id` is the only text the registry holds: there is no name, description, category or tag, on chain or here. | +| `stale_audit` | `true` \| `false` | — | `true`: `latest_version` is not `latest_audited_version` (never-audited rows included). | +| `sort` | `registered_at` \| `trust_score` \| `skill_id` | `registered_at` | | +| `order` | `asc` \| `desc` | `desc` | Applies to the default sort when `sort` is omitted. | + +**Two listings.** With **none** of `verdict`, `q`, `stale_audit`, `sort`, `order`, the response is +the STE-18 listing unchanged: registration order, test namespaces hidden unless `include_test`, +`as_of: null`. Clients that page the plain catalogue see no change. With **any** of them, the +filtered listing below applies. Both hide test namespaces the same way and share one scan +(`skills.scan_registry`, capped at `MAX_SCAN`), so a filter can never surface a row the plain +listing hides, and `chain_total` is the same number in both. + +**Filtered listing.** + +- Filter and sort run over the **whole registry, before paging**. `total` is the number of rows + after filtering — never the contract's skill count, or a client would offer empty pages. +- Test namespaces are removed after the other filters, so `hidden_test_entries` on a filtered page + counts only test rows that **matched** every other filter (e.g. `verdict=SAFE` with one SAFE test + row hidden → `1`), not every test row on chain. `include_test=true` puts them back and makes it `0`. +- Ties always break on `skill_id` ascending, so pages are stable. +- `sort=trust_score`: rows with no trust score (never audited, or unreadable) come **last in both + directions**. "Lowest trust first" must not open with rows that have no trust score at all. +- A row whose latest audited record could not be read matches **no** `verdict` value — not even + `UNAUDITED`, because unknown is not a claim the registry made. Without a `verdict` filter it is + listed with null verdict fields, as in the plain listing. + +**Where rows come from — and why not the index.** Rows are chosen from a view of the whole registry +**read from chain** (`registry_snapshot.py`): every `SkillEntry` plus the record of each latest +audited version. It is at most `STERISH_SKILLS_SNAPSHOT_TTL` seconds old (default 30, within the +60 s caching §6 allows) and is dropped early whenever the indexer stores a new registry event. The +SQLite index was considered and rejected: it is filled from `getEvents`, which only reaches back as +far as the RPC node retains events, so a rebuilt index silently lacks every older skill and +`verdict=SAFE` would return fewer rows than exist — breaking the rule that deleting the cache never +changes an answer. + +**Displayed values are live.** The rows of the returned page are re-read from chain on every +request; the verdict, score and verified flag in the response are those live reads. When the view +and the chain disagree — a row chosen as `SAFE` now reads `DANGEROUS` — **the chain wins and the row +is left out** of a `verdict`-filtered page, counted in `excluded_stale`, and the view is dropped so +the next request agrees with the chain. `total` on that response still reflects the view it was +cut from. Sorting and the `q` / `stale_audit` filters use the view's values. + +**Rejected parameters** answer `400 INVALID_PARAMETER` with a reason, never a silently unfiltered +page: `verified` (identical to `verdict=SAFE` by invariant R7), `owner` (one owner on the registry +today; a drill-down, if built, is its own ticket). `sort=verdict` is not offered: the verdict enum +has no meaningful order. Any invalid value of a supported parameter is also `400`. ```json { @@ -273,7 +320,9 @@ Paginated catalogue. Backed by `query_all_skills(start, limit)`. "limit": 20, "chain_total": 66, "hidden_test_entries": 47, - "include_test": false + "include_test": false, + "as_of": null, + "excluded_stale": 0 } ``` @@ -309,6 +358,11 @@ shared with the tests that generate the ids — a filter and a test that disagre produce exactly the junk the filter exists to remove. `com.fixtures.*` is **not** on it: those are published demo data, and hiding them would empty the dashboard of what it is meant to show. +`as_of` (unix seconds) is when the registry view a filtered page was chosen from was read from +chain, and is `null` for the plain listing. `excluded_stale` is how many rows that view chose were +left out because their live verdict no longer matched; both fields were added in STE-34 and are +additive. + ### 3.5 `GET /health` ```json diff --git a/docs/evidence/ste-34-e2e-skills-filters-2026-09-16.json b/docs/evidence/ste-34-e2e-skills-filters-2026-09-16.json new file mode 100644 index 0000000..bace842 --- /dev/null +++ b/docs/evidence/ste-34-e2e-skills-filters-2026-09-16.json @@ -0,0 +1,169 @@ +{ + "ticket": "STE-34", + "date": "2026-09-16", + "base": "rebased on origin/main dc0a0c6 (STE-18 test-namespace filter + STE-39)", + "script": "api/scripts/verify_skills_filters.py (expected answers computed client-side from the plain listing; every filtered verdict re-confirmed via /check)", + "server": "local uvicorn, INDEXER_ENABLED=0, reading testnet directly", + "runs": { + "registry_v2 CCZJN366SV57JEBZVXGYY3ZBLJNFV4IR5ILCAI3EMX2WDNQPEPQ4BRL2 (production, 0 test rows)": { + "result": "PASS", + "checks_ok": 57, + "output": [ + "registry: 24 skills", + "", + "1. verdict filter == client-side filter of the full listing, and /check agrees", + " ok verdict=SAFE: 15 rows match the full listing", + " ok verdict=SAFE: total 15 == rows", + " ok verdict=SAFE: nothing excluded as stale", + " ok verdict=SAFE: every row confirmed by /check", + " ok verdict=WARNING: 2 rows match the full listing", + " ok verdict=WARNING: total 2 == rows", + " ok verdict=WARNING: nothing excluded as stale", + " ok verdict=WARNING: every row confirmed by /check", + " ok verdict=DANGEROUS: 7 rows match the full listing", + " ok verdict=DANGEROUS: total 7 == rows", + " ok verdict=DANGEROUS: nothing excluded as stale", + " ok verdict=DANGEROUS: every row confirmed by /check", + " ok verdict=UNAUDITED: 0 rows match the full listing", + " ok verdict=UNAUDITED: total 0 == rows", + " ok verdict=UNAUDITED: nothing excluded as stale", + " ok verdict=UNAUDITED: every row confirmed by /check", + "", + "2. q and stale_audit", + " ok q=stellar: 13 rows", + " ok q=EVIL: 0 rows", + " ok q=fixtures.safe: 3 rows", + " ok q=zzz-no-such-skill: 0 rows", + " ok stale_audit=true: 1 rows", + " ok stale_audit=false: 23 rows", + "", + "3. sort orders", + " ok sort=registered_at&order=asc: monotonic", + " ok sort=registered_at&order=asc: same rows", + " ok sort=registered_at&order=desc: monotonic", + " ok sort=registered_at&order=desc: same rows", + " ok sort=trust_score&order=asc: exact order", + " ok sort=trust_score&order=desc: exact order", + " ok sort=skill_id&order=asc: exact order", + " ok sort=skill_id&order=desc: exact order", + "", + "4. paging a filter covers it exactly once", + " ok 24 rows in pages of 7, no overlap, no gap", + "", + "5. invalid parameters are refused", + " ok {'verdict': 'safe'} -> 400", + " ok {'sort': 'verdict'} -> 400", + " ok {'order': 'up'} -> 400", + " ok {'stale_audit': 'yes'} -> 400", + " ok {'q': ''} -> 400", + " ok {'verified': 'true'} -> 400", + "", + "6. the plain listing is unchanged", + " ok no as_of without filter parameters", + " ok registration order preserved", + "", + "7. test namespaces: hidden under a filter exactly as in the plain listing (STE-18)", + " ok plain listing = include_test listing minus 0 test rows", + " ok no test id in the plain listing", + " ok verdict=SAFE: no test id served", + " ok verdict=SAFE: hidden_test_entries 0 == matching test rows", + " ok verdict=SAFE: same chain_total", + " ok verdict=SAFE&include_test=true: 15 rows, nothing hidden", + " ok verdict=WARNING: no test id served", + " ok verdict=WARNING: hidden_test_entries 0 == matching test rows", + " ok verdict=WARNING: same chain_total", + " ok verdict=WARNING&include_test=true: 2 rows, nothing hidden", + " ok verdict=DANGEROUS: no test id served", + " ok verdict=DANGEROUS: hidden_test_entries 0 == matching test rows", + " ok verdict=DANGEROUS: same chain_total", + " ok verdict=DANGEROUS&include_test=true: 7 rows, nothing hidden", + " ok verdict=UNAUDITED: no test id served", + " ok verdict=UNAUDITED: hidden_test_entries 0 == matching test rows", + " ok verdict=UNAUDITED: same chain_total", + " ok verdict=UNAUDITED&include_test=true: 0 rows, nothing hidden", + "", + "PASS" + ] + }, + "registry_v1 CAPDQW2XWTOCFQEP3AUCRRQHVJ5IOUZ45DWPNPVG7USNPE6RZQ3BUXND (47 test rows, exercises hiding)": { + "result": "PASS", + "checks_ok": 57, + "output": [ + "registry: 24 skills", + "", + "1. verdict filter == client-side filter of the full listing, and /check agrees", + " ok verdict=SAFE: 15 rows match the full listing", + " ok verdict=SAFE: total 15 == rows", + " ok verdict=SAFE: nothing excluded as stale", + " ok verdict=SAFE: every row confirmed by /check", + " ok verdict=WARNING: 2 rows match the full listing", + " ok verdict=WARNING: total 2 == rows", + " ok verdict=WARNING: nothing excluded as stale", + " ok verdict=WARNING: every row confirmed by /check", + " ok verdict=DANGEROUS: 7 rows match the full listing", + " ok verdict=DANGEROUS: total 7 == rows", + " ok verdict=DANGEROUS: nothing excluded as stale", + " ok verdict=DANGEROUS: every row confirmed by /check", + " ok verdict=UNAUDITED: 0 rows match the full listing", + " ok verdict=UNAUDITED: total 0 == rows", + " ok verdict=UNAUDITED: nothing excluded as stale", + " ok verdict=UNAUDITED: every row confirmed by /check", + "", + "2. q and stale_audit", + " ok q=stellar: 13 rows", + " ok q=EVIL: 0 rows", + " ok q=fixtures.safe: 3 rows", + " ok q=zzz-no-such-skill: 0 rows", + " ok stale_audit=true: 1 rows", + " ok stale_audit=false: 23 rows", + "", + "3. sort orders", + " ok sort=registered_at&order=asc: monotonic", + " ok sort=registered_at&order=asc: same rows", + " ok sort=registered_at&order=desc: monotonic", + " ok sort=registered_at&order=desc: same rows", + " ok sort=trust_score&order=asc: exact order", + " ok sort=trust_score&order=desc: exact order", + " ok sort=skill_id&order=asc: exact order", + " ok sort=skill_id&order=desc: exact order", + "", + "4. paging a filter covers it exactly once", + " ok 24 rows in pages of 7, no overlap, no gap", + "", + "5. invalid parameters are refused", + " ok {'verdict': 'safe'} -> 400", + " ok {'sort': 'verdict'} -> 400", + " ok {'order': 'up'} -> 400", + " ok {'stale_audit': 'yes'} -> 400", + " ok {'q': ''} -> 400", + " ok {'verified': 'true'} -> 400", + "", + "6. the plain listing is unchanged", + " ok no as_of without filter parameters", + " ok registration order preserved", + "", + "7. test namespaces: hidden under a filter exactly as in the plain listing (STE-18)", + " ok plain listing = include_test listing minus 47 test rows", + " ok no test id in the plain listing", + " ok verdict=SAFE: no test id served", + " ok verdict=SAFE: hidden_test_entries 34 == matching test rows", + " ok verdict=SAFE: same chain_total", + " ok verdict=SAFE&include_test=true: 49 rows, nothing hidden", + " ok verdict=WARNING: no test id served", + " ok verdict=WARNING: hidden_test_entries 0 == matching test rows", + " ok verdict=WARNING: same chain_total", + " ok verdict=WARNING&include_test=true: 2 rows, nothing hidden", + " ok verdict=DANGEROUS: no test id served", + " ok verdict=DANGEROUS: hidden_test_entries 13 == matching test rows", + " ok verdict=DANGEROUS: same chain_total", + " ok verdict=DANGEROUS&include_test=true: 20 rows, nothing hidden", + " ok verdict=UNAUDITED: no test id served", + " ok verdict=UNAUDITED: hidden_test_entries 0 == matching test rows", + " ok verdict=UNAUDITED: same chain_total", + " ok verdict=UNAUDITED&include_test=true: 0 rows, nothing hidden", + "", + "PASS" + ] + } + } +} \ No newline at end of file