Skip to content

STE-34: search, filter and sort /skills on the server, over the whole registry - #54

Merged
Lin1er merged 4 commits into
mainfrom
feat/34-skills-search-filter-sort
Sep 17, 2026
Merged

Lin1er merged 4 commits into
mainfrom
feat/34-skills-search-filter-sort

Conversation

@Lin1er

@Lin1er Lin1er commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Linear: STE-34 · ACC by Axel 2026-09-17 · reviewers @axelmatsama @fable

Problem

GET /skills could only page the registry in registration order. On production today, ?verdict=SAFE answers 200 but ignores the filter and returns every row.

Fix

  • verdict, q (substring of skill_id), stale_audit, sort (registered_at / trust_score / skill_id) and order are applied over the whole registry, before paging. total is the filtered count.
  • Rows are chosen from a chain-read snapshot. Not the event index: the RPC event window would silently drop old skills after a rebuild. The snapshot TTL is 30 s, and it is dropped early when the indexer sees a new registry event.
  • The rows on the returned page are re-read live. If a row's live verdict no longer matches the filter, it is left out and counted in excluded_stale.
  • Test namespaces stay hidden under a filter exactly as in the plain listing (STE-18). hidden_test_entries counts only test rows that matched the other filters.
  • verified and owner are refused with 400 INVALID_PARAMETER and a reason, instead of being silently ignored.
  • With no filter parameters, the listing is unchanged.

Tests

  • API: 231 passed.
  • Rebased onto main with STE-48/49/50/53. The only conflicts were additive settings, resolved by keeping both sides.

E2E

api/scripts/verify_skills_filters.py computes the expected answer client-side and confirms every filtered verdict through /check:

  • Registry v2: PASS, 57 checks.
  • Registry v1, which has 47 test rows so the hiding is exercised: PASS, 57 checks.

Evidence: docs/evidence/ste-34-e2e-skills-filters-2026-09-16.json.

… 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.
…ient-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.
…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.
…try 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.
@vercel

vercel Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sterish Ready Ready Preview Sep 17, 2026 11:55am UTC

@Lin1er
Lin1er merged commit 22b262d into main Sep 17, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — bb99edc0 Deployed Sep 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant