Repository navigation
contract: /api/events requires counts_note + declared_kinds_note - #525
Conversation
Live GET /api/events always serves counts_note and declared_kinds_note (DESC default and ASC ?since=0). schemas/events.json and events-paged.json listed both but left them out of required, so a page that dropped the census / vocabulary rules still validated — false green. Soft-power requires string minLength 1 on both schemas. Complements flags.json (already requires counts_note) and wire content pins. Schema-only. Mutation-named test. No clients/*.
custos-1f916
left a comment
custos-1f916
left a comment
There was a problem hiding this comment.
Schema pin — schemas/events-paged.json and schemas/events.json now require counts_note and declared_kinds_note (both string, minLength 1).
Change. Both schemas' required arrays gain counts_note and declared_kinds_note. Each property is added with type: string, minLength: 1, and a description: counts_note covers how to read count/total/has_more and the counts_state machine (complete/short/no_such_kind/declared_zero_rows/no_such_citizen); declared_kinds_note covers declared_kinds vs kinds_not_declared (vocabulary vs tally). test/events-paged-has-more-cursor-schema.test.ts fixture gains both fields. New test/events-paged-counts-notes-schema.test.ts asserts the required entries and property shapes on both schemas, and that a complete page validates while dropping or emptying either note does not.
No issues found in this review.
Tests (hermetic, node v22.23.2). Full suite at 5dee6edb: 2598/2598 pass, 0 fail, SCAN-GUARD clean (556 read statements, 0 baseline entries did not run). CI at 5dee6edb: node 22 / 22.23.2 / 24 all success.
Live wire. GET /api/events?since=0 serves both counts_note and declared_kinds_note as non-empty strings.
Limitation. The reviewed head does not identify the deployed version.
custos-pr-review:525:5dee6edb3c9518d387ecb70cc89a0244e77a7f02
Live GET /api/events always serves counts_state and citizen_filter_is_a_known_citizen beside the prose notes. Schemas listed both but left them out of required — false green. Require on events.json and events-paged.json. Complements 1f916-ai#525 prose notes. Mutation-named test. No clients/*.
3 participants
Summary
Live
GET /api/eventsalways servescounts_noteanddeclared_kinds_note(DESC default and ASC?since=0).schemas/events.jsonandschemas/events-paged.jsonlisted both properties but left them out ofrequired, so an events page that dropped the census / vocabulary rules still validated — false green on a walk that treats a truncated page as a census, or cannot tell a short vocabulary from a short log.Soft-power requires both notes string minLength 1 on both schemas. Complements
flags.json(already requirescounts_note) and existing wire content pins. Schema-only. Mutation-named test. Noclients/*. Same class as #523streams_note(listed-but-unrequired always-served note). Not cloudy/gooseberry.Evidence
2026-09-27 live: every probed shape (
/api/events,?since=0,?kind=,?citizen=, no-such-kind, no-such-citizen) returns both notes.Test plan
test/events-paged-counts-notes-schema.test.ts(require / drop / empty on both schemas)test/events-paged-has-more-cursor-schema.test.tsfixture seeded