spec(governance): allow category-only webhook subscriptions (v0.1.25.39)

[amavashev]

Summary

Governance spec revision v0.1.25.39: reconciles the spec to the shipped-and-released reference admin behavior (cycles-server-admin 0.1.25.50) by allowing category-only webhook subscriptions — event_types: [] with a non-empty event_categories ("subscribe to all budget.* by category"). Additive/relaxing on the wire; semantic_base stays 0.1.25.9.

Reviewer finding this fixes

The v0.1.25.38 changelog claimed the empty-both "match-ALL" state was unreachable because event_types carried minItems: 1 on all three webhook schemas. That was wrong for the update path: the shipped admin WebhookUpdateRequest.eventTypes has no bean-validation annotation, so PATCH accepts event_types: []. The real guarantee is a server-side empty-both guard. Decision (Option 1): category-only subscriptions are a legitimate feature, and the spec's minItems: 1 on the UPDATE schema is the stale side.

Verified against admin source (cycles-server-admin main)

• WebhookCreateRequest.eventTypes → @NotEmpty (create still requires non-empty event_types).
• WebhookUpdateRequest.eventTypes → no annotation (PATCH accepts []).
• WebhookService.update empty-both guard on both planes: rejects a resulting state with both event_types and event_categories empty — 400 INVALID_REQUEST "Subscription must retain at least one event_type or event_category" (comment cites governance v0.1.25.38).
• WebhookSubscription.eventTypes model field has no @JsonInclude(NON_NULL) → always serialized, including as [], so keeping the spec field required-present is correct.

Exact schema diff

Schema.field	Before	After
WebhookUpdateRequest.event_types	minItems: 1, optional (no required list)	minItems removed, optional; SELECTOR CLEARING note (MAY be [] for category-only, provided event_categories non-empty)
WebhookSubscription.event_types	in required, minItems: 1	minItems removed, stays in required (required-present, MAY be empty)
WebhookCreateRequest.event_types	in required, minItems: 1	UNCHANGED (matches shipped @NotEmpty create; not relaxed — that would be a server code change)

Normative invariant text (verbatim)

Added to WebhookSubscription.event_types and the createTenantWebhook prose:

SUBSCRIPTION SELECTOR INVARIANT (NORMATIVE): a persisted subscription MUST always match at least one event selector — at least one of event_types / event_categories MUST be non-empty. A create or update whose resulting state would leave BOTH empty MUST be rejected with 400 INVALID_REQUEST. This invariant is what makes category-only subscriptions valid and what makes the empty-both "match ALL event classes" state unreachable (the earlier assumption that event_types minItems: 1 alone guaranteed this was incorrect for the update path — the guarantee is this server-side invariant, now normative).

WebhookUpdateRequest SELECTOR CLEARING note (verbatim):

SELECTOR CLEARING (NORMATIVE): unlike WebhookCreateRequest (where event_types is required and non-empty), an update MAY set event_types to an empty array to convert the subscription to CATEGORY-ONLY — PROVIDED event_categories is (or remains) non-empty. The resulting persisted state is still subject to the SUBSCRIPTION SELECTOR INVARIANT (WebhookSubscription.event_types): an update whose resulting state would leave BOTH event_types and event_categories empty MUST be rejected with 400 INVALID_REQUEST. Because this is a partial update, the resulting state combines the provided fields with the existing subscription's unchanged fields …

WebhookSubscription.required decision

event_types stays in required. A persisted category-only subscription carries event_types: [] — an empty array still satisfies required presence (it was minItems that forbade empty), and the reference admin model serializes the field unconditionally (no @JsonInclude(NON_NULL)). So the field is required-present-but-possibly-empty; only the minItems: 1 was removed. required: [subscription_id, tenant_id, url, event_types, status, created_at] is unchanged.

Also in this revision

• Corrects the v0.1.25.38 changelog empty-both note (its minItems: 1 reasoning was wrong for the update path; the guarantee is the server-side guard, now spec-normative).
• OPEN DESIGN note (not fixed here): the create/update asymmetry — create requires non-empty event_types, update allows clearing to category-only — is real and matches shipped behavior. Allowing category-only on create too is a candidate future enhancement (coordinated server + spec change), deliberately out of scope.
• info.summary / SPEC FAMILY CONTEXT document-revision self-references bumped to 0.1.25.39; summary chronicle extended.

Validation

• YAML parse OK; validate_changelogs.py green (v0.1.25.39 heading matches info.version).
• merged/cycles-openapi-admin-merged.yaml regenerated (byte-stable second run — merge-check passes; source metadata picks up v0.1.25.39 dynamically). Protocol merged artifact unaffected.
• Spectral runs in CI.

[amavashev]

Editorial fix (6bf0286)

Codex's one editorial finding applied: the corrected v0.1.25.38 changelog entry said "see the CORRECTION in v0.1.25.39 below", but in newest-first (Keep a Changelog) order the .39 entry sits above .38 — changed "below" → "above". validate_changelogs.py green.

Open question (considered and declined): schema-level enforcement of the empty-both invariant

Codex noted (non-blocking) that an anyOf could make the SUBSCRIPTION SELECTOR INVARIANT machine-enforceable in the schema rather than prose-only. Declined for this revision, for the record:

• OpenAPI/JSON Schema can't cleanly express "at least one of two arrays is non-empty." An anyOf over minItems: 1 on each of event_types / event_categories is awkward, and — more importantly — it cannot capture the create/update asymmetry this revision hinges on (create requires non-empty event_types; update permits event_types: [] for a category-only subscription). A single cross-field anyOf on the shared WebhookSubscription shape would flatten that distinction.
• The invariant is a resulting-state rule that also spans a partial update (provided fields combined with the existing subscription's unchanged fields) — not something a static request-body schema can evaluate. The reference server enforces it in code (WebhookService empty-both guard), which is the correct enforcement point.
• Normative prose is how the rest of these cross-field webhook invariants are expressed in this spec (e.g. the tenant-accessible boundary added in v0.1.25.38), so prose keeps the family consistent.

So the invariant stays normative prose, enforced server-side; no schema anyOf added.

[amavashev]

External review (codex): SHIP after the editorial fix. Normative behavior verified to match cycles-server-admin 0.1.25.50 exactly (codex ran representative schema validations: category-only valid, create-empty invalid, missing invalid, update-empty valid); wire-compat confirmed (relaxing minItems only widens accepted cardinality); no regressions in the merged artifacts. The anyOf machine-enforcement suggestion was considered and declined (recorded above). Reconciles the spec to the shipped category-only webhook behavior.