robotic review

Feedback from my good friend Astra. I have not done any filtering.

1. **Unreliable update and delete counts: exception required versus optional.**
The [specification](/Users/gavin/Projects/data/spec/src/main/asciidoc/query-language.asciidoc:119) requires `UnsupportedOperationException` when a NoSQL database cannot reliably determine the count. [`@Query`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Query.java:68) permits returning an imprecise count instead. These prescribe different observable behavior.

2. **`@Delete` excludes parameter types explicitly supported elsewhere.**
Its [Javadoc](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Delete.java:79) requires each ordinary parameter to have exactly the corresponding attribute’s type. But the [specification](/Users/gavin/Projects/data/spec/src/main/asciidoc/repository.asciidoc:220) permits constraint parameters, and the [module Javadoc](/Users/gavin/Projects/data/api/src/main/java/module-info.java:403) explicitly demonstrates `@Delete int discontinue(@By("id") In productIds)`. The `@Delete` parameter rules need to include constraints and the conversion rules for `@Is`.

3. **Stateful repositories: all `@Delete` methods prohibited versus only lifecycle methods.**
The [stateful module Javadoc](/Users/gavin/Projects/data/stateful/src/main/java/module-info.java:53) prohibits every method annotated `@Delete`. The [specification](/Users/gavin/Projects/data/spec/src/main/asciidoc/repository.asciidoc:1048) prohibits its use specifically for lifecycle methods. This leaves conflicting answers for a stateful repository declaring `@Delete int deleteByStatus(String status)`.

4. **Wildcard parameter rules disagree in both directions.**
The [specification](/Users/gavin/Projects/data/spec/src/main/asciidoc/repository.asciidoc:324) explicitly permits `Restriction`, while the [module Javadoc](/Users/gavin/Projects/data/api/src/main/java/module-info.java:994) says its type argument must be the entity class. Conversely, [`Constraint`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/constraint/Constraint.java:40) explicitly permits `C`, while the [specification’s parameter rules](/Users/gavin/Projects/data/spec/src/main/asciidoc/repository.asciidoc:223) enumerate only `C`.

5. **An omitted `SELECT` clause has two different meanings in `@Query`.**
The [earlier paragraph](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Query.java:48) permits inferred record projections. The [later paragraph](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Query.java:83) says omission returns the queried entity. [`@Select`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Select.java:43) confirms that record projection is intended. The later statement needs that qualification.

6. **The uniqueness rules do not account for `@First`.**
[`@First` demonstrates](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/First.java:31) returning the highest-paid employee for a job title. Yet [`@Find`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Find.java:134) requires `NonUniqueResultException` whenever multiple database records satisfy the conditions. [`@Query`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/Query.java:159) repeats this wording. The rules should explicitly apply the result limit before checking uniqueness.

7. **Offset pagination requires `Page`, but `PageRequest` permits other return types.**
The [pagination requirements](/Users/gavin/Projects/data/spec/src/main/asciidoc/repository.asciidoc:528) say the method “must return `Page`”. [`PageRequest`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/page/PageRequest.java:35) permits arrays, `List`, and `Stream`, as does the specification’s special-parameter section. The requirement should distinguish returning page metadata from merely applying an offset and limit.

8. **A short cursor page does not necessarily mean there is no next page.**
[`Page.numberOfElements()`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/page/Page.java:80) states that fewer results than the requested size implies no subsequent pages. This is inherited by `CursoredPage`. For ordered keys \(1,\ldots,20\), requesting ten results before key \(5\) returns \(1,\ldots,4\), but a subsequent page certainly exists. The statement needs to account for traversal direction.

9. **The method-name sorting grammar disagrees with the documented syntax.**
The [grammar](/Users/gavin/Projects/data/spec/src/main/asciidoc/method-query.asciidoc:191) requires a direction for every item in a multi-attribute order. The [keyword table](/Users/gavin/Projects/data/spec/src/main/asciidoc/method-query.asciidoc:263) permits omitting the final direction, allowing `OrderByHeightDescId`. The grammar also lacks the `IgnoreCase` modifier for ordering that the [Javadoc explicitly supports](/Users/gavin/Projects/data/api/src/main/java/module-info.java:669).

10. **Wide-column support for `And` is required and listed as unavailable.**
The [Query by Method Name specification](/Users/gavin/Projects/data/spec/src/main/asciidoc/method-query.asciidoc:116) requires wide-column databases to support `AND`. The corresponding [Javadoc table](/Users/gavin/Projects/data/api/src/main/java/module-info.java:622) lists `And` as unavailable for wide-column databases. These need one consistent capability requirement.

There are also several smaller, definite documentation defects:

- **Obsolete sorting API:** both [the specification](/Users/gavin/Projects/data/spec/src/main/asciidoc/repository.asciidoc:719) and [`Page.content()`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/page/Page.java:50) refer to sort criteria carried by `PageRequest`. Sorting is supplied separately through `Sort` or `Order`.
- **Obsolete integration disclaimer:** the [Jakarta Persistence section](/Users/gavin/Projects/data/spec/src/main/asciidoc/jakarta-ee.adoc:168) says integration is undefined, despite the explicit query-annotation and datastore integration requirements elsewhere.
- **Invalid example return types:** the [module’s `@Update` example](/Users/gavin/Projects/data/api/src/main/java/module-info.java:356) returns `boolean`, and [`BasicRepository`’s delete example](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/repository/BasicRepository.java:64) also returns `boolean`. Neither conforms to its documented return-type rules.
- **Reversed bound terminology:** [`Restriction.negate()`](/Users/gavin/Projects/data/api/src/main/java/jakarta/data/restrict/Restriction.java:94) calls `GreaterThan` an upper bound and `AtMost` a lower bound. The intended relationship is \(x>b \mapsto x\le b\), so those labels should be lower and upper respectively.

Compare the linked specification sections with the referenced API and module Javadocs, starting with the conflicting rules for @Delete, @Query, pagination, and method-name queries. Determine the authoritative behavior with maintainers, then update the affected documentation and examples consistently, including the smaller defects listed at the end. Verify that the documentation build passes and all contradictions are resolved.

Written by the indexing model from the issue text.