0.5.0: backward-compat + discoverability fixes for the generic authority tools

[Azdaroth]

Backward-compatibility and discoverability fixes for the generic tools (resources / resource_schema / get / list), driven by an adopting host's parity review against the API contract the gem replaced — plus a follow-up adversarial review pass whose findings are all fixed on this branch.

Discoverability

• resource_schema surfaces custom filters under resource_filters ([{name, type, description}]). They worked but were advertised nowhere.
• resources returns filterable + note alongside name/description, so a resource's usage caveat surfaces at browse time. One resource's failing lazy filterable resolution degrades to an omitted key (logged) instead of failing the whole discovery index, and Resource's lazy source is now cleared only after a successful call, so a transient failure is retried instead of silently resolving the allowlist to {}.
• The list tool description documents the full filter grammar — bare equality, comma/array IN sets, the "null" token, { op:, value: } conditions, AND-ed ranges, resource-specific top-level filters.
• Prose follows tool names everywhere: config.generic_tool_name_prefix is threaded into descriptions and input schemas (shared ToolReferenceRewriter), and the gateway aggregator applies the same rewrite with the upstream namespace, so a proxied <app>__list no longer points clients at the upstream's bare tool names.
• Satellite parity: the satellite generic tools share the executors/schema builder, so they get the same enriched resources output and the same grammar/resource_filters descriptions.

Filter semantics (explicit over silent — each previously returned a wrong or empty result)

• An Array of scalars is an IN set (was to_s-ed and comma-split into fragments matching nothing); same for { op: "eq"/"in" } values.
• eq/in against "null"/null renders IS NULL, not IN (NULL).
• A JSON null filter value means IS NULL (was silently ignored); the empty string still means "no filter".
• IN-set elements must be non-null scalars: nil/Hash/nested-Array elements raise InvalidParams (was: query-time TypeError / never-matching SQL). The "null" token is scalar-only — SQL IN cannot match NULL.
• Null with a non-eq/in/not_eq operator raises InvalidParams (was: matches + null LIKE-NULL'd to zero rows; comparisons silently matched nothing).
• An op-less Hash as a bare value raises InvalidParams; mixed condition/bare arrays raise regardless of element order.
• { op: "eq", value: "" } matches empty-string rows (was: nothing).

Ordering

• Non-numeric-PK resources order by created_at with the model's PK as tiebreaker (offset pagination needs the total order; bulk-inserted rows share timestamps).

Verification

• 427 examples, 0 failures; RuboCop + Brakeman clean; no-host-coupling guard passes
• The real Arel path is now CI-pinned (filtering_arel_spec renders actual Arel SQL for the eq/in/null/array matrix)
• Mutation-review follow-ups spec'd: in+null, {op: eq, value: null}, bare-first mixed arrays, PK-name-driven tiebreaker, per-tool prefix rewrites, schema-walk value preservation, raising-source retry, grammar pinning
• Verified end-to-end on the adopting host: 289 MCP specs green + runtime SQL checks against real models

🤖 Generated with Claude Code

Host-compatibility seams (full pre-gem contract parity)

A follow-up backwards-compatibility audit against the pre-gem contract surfaced five remaining client-visible deltas; all are closed by config seams (gem defaults unchanged — satellites keep their current contract; the migrating host opts in):

• session_key_prefix + session_payload_dumper/loader — keep the pre-gem session namespace and wire format, so live sessions survive the deploy and old/new instances share sessions during a rolling deploy (no forced re-initialization). The sliding-TTL bump rewrites the raw payload untouched.
• bare_filter_value_semantics = :literal — bare values verbatim ("a,b" one literal string, "null" the literal string, "" matches empty strings, arrays incl. nil elements get the adapter's native IN / OR-IS-NULL). Default :tokenized unchanged; operator conditions identical in both modes.
• non_numeric_pk_order = :primary_key — preserves a pre-gem ORDER BY id contract for uuid-PK resources; default :created_at+tiebreaker unchanged.
• Resource#filter_requirements — companion-key validation restores safe polymorphic-FK filtering ("filter attribute X requires Y to also be provided"); resource_schema advertises the requirement under relationships[].filter.requires.
• resource_schema full shape parity — restores sparse_fieldsets, filter_examples, nullable relationships[].resource (keeping target_resource as the resolved alias) and relationships[].filter (keys/type/operators/requires); top-level nils compacted.
• Operator conditions work on ANY column type (eq/in fallback for uuid/enum/jsonb/...; date accepts in again), and the list input schemas declare additionalProperties: true explicitly.

Verification: 448 gem examples / 0 failures; RuboCop + Brakeman clean; on the adopting host, 291 MCP specs green plus 25 runtime compat checks against real models (literal SQL, ORDER BY id, session round-trip in the old wire format in both directions).

Final-audit fixes (post-parity verification round)

A last independent audit against the pre-gem contract surfaced residual deltas; all fixed:

• Config-aware served docs: the authority list description now states the bare-value grammar the host actually configured (:literal hosts no longer serve tokenization advice that would silently match nothing).
• Order parity: tools/list advertises get, list, resource_schema, resources (pre-gem alphabetical order); string/text operator lists keep the pre-gem order.
• Strict arguments: get/resource_schema/resources reject unknown arguments with InvalidParams again (account_id tolerated); list keeps accepting extras (custom filters).
• Companion-skip guard: an empty-string companion under :tokenized semantics no longer bypasses filter_requirements pairing.
• Shape details: resource_filters keeps nil type/description keys; relationship filter_examples companion sample is "User" (pre-gem values).
• Documented the one accepted op-path delta: {op: "in", value: "a,b"} now splits into an IN set (old matched the literal string).

454 examples / 0 failures; RuboCop + Brakeman clean. Adopting host re-verified: 291 MCP specs + runtime checks per fix (including the host-side guests fields regression guard).

Host-boilerplate ports (final round)

A fifth independent audit confirmed full compatibility (modulo the documented list) and identified host plumbing every authority adopter would re-write; it is now first-class gem API:

• config.session_payload_key_map — declarative legacy session codec (flat renamed-keys format; unmapped keys pass through; string-keyed cache rows symbolized on read). Replaces hand-written dumper/loader lambdas for the common case.
• config.register_upstreams_from_env(map, env: ENV) — reset-first (reload-idempotent) + blank-skip upstream registration from a {key => env var} map.
• Composed default config.tool_provider — RegistryToolProvider (only when resources are registered; pure gateways still contribute nothing) + config.extra_tool_providers, with bare tool classes wrapped in the new Authority::SingleToolProvider.
• McpToolkit::Serializer::AssociationDescriptor / TargetRef — exported structs for the association duck-type, so serializer adapters stop re-deriving the field names.

474 examples / 0 failures; RuboCop + Brakeman clean. The adopting host swapped onto all four (deleting 3 plumbing files) with 291 specs green and 10 runtime checks pinning wire-format and tools/list byte-parity across the swap.

[Azdaroth]

💪 🐉 Opa!

[Azdaroth]

💪 🐉 Opa!

[Azdaroth]

💪 🐉 Opa!