From 5f58ca6682a3e494084c936d2d1f2605721619d8 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:45:37 +0700 Subject: [PATCH 1/4] feat(STE-34): search, filter and sort /skills on the server, over the whole registry GET /skills takes verdict, q, stale_audit, sort and order. Filtering and sorting run over every row before the page is cut, and total counts the filtered rows, so a client never offers empty pages or a "highest trust first" that only ranks the rows it happened to fetch. Rows are chosen from a view of the whole registry read from chain, not from the SQLite index the ticket suggested. The index is filled from getEvents, which only reaches back as far as the RPC node retains events: a rebuilt index silently lacks older skills and verdict=SAFE would return fewer rows than exist, breaking "deleting the cache never changes an answer". The view is at most 30 s old (inside the 60 s section 6 allows) and is dropped whenever the indexer stores a registry event. Decisions the ticket asked to be made explicitly: - the returned page is re-read live; a row whose live verdict no longer matches the verdict filter is left out, counted in excluded_stale, and the view dropped; - rows with no trust score sort last in both directions; - an unreadable row matches no verdict, not even UNAUDITED; - stale_audit=true includes never-audited rows; - ties break on skill_id, so pages are stable; - invalid values, and the rejected verified/owner parameters, are 400 with a reason, never ignored. With none of the new parameters the response is the original one, so the live dashboard is unaffected. as_of and excluded_stale are additive fields. conftest carries the same rate-limiter line as STE-42: this suite also passes 100 requests against the shared app. --- api/src/sterish_api/config.py | 5 + api/src/sterish_api/indexer.py | 8 +- api/src/sterish_api/models.py | 8 + api/src/sterish_api/registry_snapshot.py | 168 +++++++ api/src/sterish_api/routes/check.py | 193 +++++++- api/tests/conftest.py | 6 +- api/tests/test_skills_filter.py | 553 +++++++++++++++++++++++ 7 files changed, 916 insertions(+), 25 deletions(-) create mode 100644 api/src/sterish_api/registry_snapshot.py create mode 100644 api/tests/test_skills_filter.py 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)] From 39b45c6d02d519e4ceac939b95e1fc56f9f649ed Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:45:37 +0700 Subject: [PATCH 2/4] test(STE-34): verify /skills filters against a running API, graded client-side Every filtered answer is recomputed from the plain listing, every filtered row's verdict is confirmed through /check, and paging, sort orders and 400s are checked. Passed against testnet (66 skills): SAFE 48 and DANGEROUS 18 all confirmed on chain, WARNING and UNAUDITED empty with total 0, six sort orders exact, 66 rows in pages of 7 with no overlap. --- api/scripts/verify_skills_filters.py | 170 +++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 api/scripts/verify_skills_filters.py diff --git a/api/scripts/verify_skills_filters.py b/api/scripts/verify_skills_filters.py new file mode 100644 index 0000000..6d9fcae --- /dev/null +++ b/api/scripts/verify_skills_filters.py @@ -0,0 +1,170 @@ +"""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 + +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) -> list[dict]: + rows, start = [], 0 + while True: + body = http.get(f"{api}/skills", 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("\nPASS") + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except Mismatch as exc: + print(f"\nFAIL: {exc}") + sys.exit(1) From 03772fa9926e21b95869279bd90f7a200293e0d6 Mon Sep 17 00:00:00 2001 From: lin1er Date: Tue, 15 Sep 2026 17:45:37 +0700 Subject: [PATCH 3/4] docs(STE-34): api-spec 3.4 describes the filtered listing and why it is chain-read Parameters, the two listings, total semantics, null placement, what an unreadable row matches, where rows come from and why the index was rejected, what happens when the view and the chain disagree, and the rejected parameters. --- docs/api-spec.md | 62 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 4 deletions(-) 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 From bb99edc0409b5d4f2b223c3175c320dc887766b3 Mon Sep 17 00:00:00 2001 From: lin1er Date: Wed, 16 Sep 2026 15:56:24 +0700 Subject: [PATCH 4/4] test(STE-34): e2e covers test namespaces under a filter, run on Registry v2 and v1 Rebased on dc0a0c6. STE-18 landed a test-namespace filter on the plain listing while this branch was open; the two now share one scan (skills.scan_registry, MAX_SCAN) and one rule (is_test_skill_id). Decision: test rows are removed after the other filters, so hidden_test_entries on a filtered page counts only test rows that matched everything else. Counting every test row on chain would tell a client that verdict=WARNING hid 47 rows when it hid none. verify_skills_filters.py section 7 grades that client-side. Registry v2 (production) has no test rows, so the run is repeated read-only on v1, which has 47: both PASS, 57 checks each. --- api/scripts/verify_skills_filters.py | 40 ++++- .../ste-34-e2e-skills-filters-2026-09-16.json | 169 ++++++++++++++++++ 2 files changed, 207 insertions(+), 2 deletions(-) create mode 100644 docs/evidence/ste-34-e2e-skills-filters-2026-09-16.json diff --git a/api/scripts/verify_skills_filters.py b/api/scripts/verify_skills_filters.py index 6d9fcae..de7bf28 100644 --- a/api/scripts/verify_skills_filters.py +++ b/api/scripts/verify_skills_filters.py @@ -15,6 +15,7 @@ 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"} @@ -30,10 +31,10 @@ def check(condition: bool, message: str) -> None: print(f" ok {message}") -def all_rows(http: httpx.Client, api: str) -> list[dict]: +def all_rows(http: httpx.Client, api: str, **params) -> list[dict]: rows, start = [], 0 while True: - body = http.get(f"{api}/skills", params={"start": start, "limit": 100}).json() + body = http.get(f"{api}/skills", params={**params, "start": start, "limit": 100}).json() rows.extend(body["skills"]) start += 100 if start >= body["total"]: @@ -158,6 +159,41 @@ def main() -> int: "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 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