robsonkades/agent-skills/cross-service-query-design

Cross-Service Query Design

Choose a read path that can answer the consumer's actual question under change and failure. A joined response is a new contract: successful calls to every owner do not establish a common snapshot, an exact global page, or permission to return every field.

This skill owns the choice and contract of the cross-service query. Keep an adequate existing API, local query or reporting solution when it satisfies that contract. It does not require extracting services or replacing mutable state with an event store.

Discover the question before choosing the mechanism

Inspect the endpoint and its consumers, domain rules, API/event contracts, ADRs, query plans, traces, access policies, incidents and recovery runbooks. Capture only evidence that changes the choice:

• Purpose and authority: display, search, reconciliation, export or a decision authorizing

an effect? Who owns each fact and who may change it? Can a missing/stale fact change eligibility?

• Query semantics: predicates, join keys and cardinality, null/absence meaning, duplicates,

sort/ties, totals, pagination and expected data growth. Which owner can identify candidates before enrichment? A sample response does not establish the complete query contract.

• Visibility: required freshness per fact, read-your-writes, coherent snapshot or permitted

mixed versions, completeness, and the response when a source is late or unavailable.

• Access: caller/tenant, row and field permissions, revocation/deletion visibility, caches,

background consumers and exports. Authentication of a service is not end-user authorization.

• Cost and recovery: request/byte/concurrency budgets, measured joint dependency latency,

update volume, source replay/backfill support, retention and acceptable rebuild/outage time.

• Target stack: JDK/toolchain, resolved Spring/driver versions, transaction managers, actual

datasource routing, client deadlines and deployment constraints. Inspect build and runtime evidence; do not infer deployed behavior from annotations or a starter dependency.

Separate found requirements from conventions and hypotheses. If the allowed delay or partial answer policy is absent, inspect consumers first; ask only when the missing policy changes the decision. Continue a query inventory or bounded experiment while the decision stays conditional. Never turn an unknown freshness guarantee into an assumed number.

The architectural guidance is framework-independent. The partial Java/Spring example uses Java 25 without preview and Spring Framework 7.0.9 as an authoring baseline; it is not a tested application or permission to upgrade the target. Spring Data Commons 4.1.1 and PostgreSQL 17 sources support conditional pagination guidance. Match target versions before adapting APIs or configuration.

Establish what an answer proves

1. Separate a display from a command precondition. A dashboard can show stock observed

earlier. An order command must enforce its stock invariant through the authoritative owner, for example an atomic reservation under that owner's rules. Even a freshly composed read followed by a write has a race. Revalidate at the effect boundary or use a proven protocol covering all affected invariants; moving the query to the primary alone does not close it.

1. Define freshness and completeness independently. All required sources may answer with

old state; recent returned rows may omit an unavailable owner. Distinguish not found, not visible under policy, unavailable, pending projection and known deleted. Do not leak existence when the public authorization contract intentionally merges some of these cases.

1. Name the coherence requirement. Independent owner reads or projection checkpoints are

not a distributed snapshot. If a parent and its dependent record must appear together, specify the required causal/version relationship and how the query enforces it. A timestamp on each row or the newest event timestamp is not that proof.

1. Make degraded behavior consumable. Return an explicitly contracted partial/stale result,

delay within budget, or fail. An absent payment answer must not become zero debt. An all-required query cannot silently switch to partial success to satisfy a latency target. Expose authorized status/coverage information without publishing private service topology.

1. Keep permissions valid on every path. Apply tenant/row/field policy to primary reads,

projections, caches, fallback paths and pagination. A projection of mutable permissions needs its own accepted revocation bound; zero-delay revocation cannot rest on an asynchronous copy without another enforcing mechanism. Keep effect authorization at its authoritative owner.

For cross-service predicates, exact totals or cursor semantics, read query semantics and Java/Spring boundaries.

Choose the least complex sufficient read path

CQRS separates command and query models; it does not require separate services, separate databases or event sourcing. A projection can be maintained from ordinary state plus supported change contracts. A local read model updated in the same transaction differs from an asynchronous cross-service projection. Use the smallest separation that resolves the query; do not announce system-wide CQRS merely because one reporting view is useful. Fowler's CQRS discussion explains the distinction and complexity trade-off.

For composition, record candidate/leaf limits, maximum bytes, batch sizes, end-to-end deadline, admission and behavior after timeout. Measure the root request with realistic concurrency and data skew. Parallel calls, virtual threads and a GraphQL resolver do not remove query work or the need for bounds. Use existing batch APIs when their semantics fit; do not convert one list request into an unnoticed call per row.

For a read model, read projection lifecycle before approving the design. Name its owner, authoritative inputs, query/index shape, progress evidence, deletion handling, rebuild source and cutover criterion. Eventual consistency alone supplies neither a delay deadline nor a repair mechanism.

Execute the requested scope

• Decision/design: deliver the query contract, alternatives including retention of the

current path, chosen path with evidence, resource/visibility budgets and a discriminating validation plan. Include projection recovery only when a projection is chosen.

• Review/diagnosis: report the failing contract and its consequence, observed evidence,

proposed correction and remaining uncertainty. Do not infer a capacity fix from one trace.

• Implementation: change the query boundary and actual consumers together when authorized.

Add only justified DTOs, adapters, indexes or feeds; preserve domain ownership and existing framework conventions. Wire authentication/authorization, configuration, error/degraded responses, metrics and recovery for the chosen path. Do not leave the new contract as an unused interface or move business-command rules into the query assembler.

Use an immutable query representation or explicit result state where it prevents accidental mutation or ambiguity. Do not expose ORM entities, provider errors or raw cursor payloads as the public contract. Avoid a universal query engine when a specific bounded use case suffices.

Validate the contract

Select checks for the changed claim, reusing adequate evidence. A design may end with a reproducible test plan; implementation should execute the available relevant checks.

• Compare joined results against a controlled authoritative fixture: empty, one-to-many,

duplicate, deleted and missing inputs. Exercise filters/order across page boundaries.

• Reach a scan cap with no eligible rows and overflow a response with batch matches. Verify

consumer continuation preserves the remaining matches without declaring premature exhaustion.

• Change a sort/filter field between pages; verify the promised snapshot or live traversal

semantics, cursor expiry and behavior after a projection generation changes.

• Delay/fail one required source and one optional enrichment. Verify that missing data is not

converted to a favorable business value, and work remains bounded after caller timeout.

• Replay duplicates and reordered updates; interrupt projection processing at its commit

boundary. Verify visible state, durable progress and recovery rather than process health.

• Use hostile tenant IDs, copied cursors, revoked permissions and a stale cache/projection.

Check rows, fields, totals and metadata for leaks, including fallback and export paths.

• For an effect-authorizing consumer, race two commands after the same observed state. The

owner's invariant must hold even if both clients saw an acceptable read.