AUSUS v0.2.0-beta.1 — Pagination, filtrage, tri

Première beta de la ligne v0.2. Ferme les trois features runtime identifiées comme bloqueurs beta dans le roadmap v0.2.0-beta.1, plus les durcissements DX et release-engineering parallèles. Le format de fil ViewSchema passe de 1.0.0 à 1.2.0 — additif, rétro- compatible avec tout renderer 1.x.

Vue d'ensemble

La ligne v0.2 alpha a stabilisé la chaîne de publication et la taxonomie runtime des erreurs. v0.2.0-beta.1 ferme le gap fonctionnel :

• Pagination sans curseur — ?limit=N&offset=M avec écho totalCount.
• Filtrage whitelisté — trois opérateurs (eq, in, contains), SQL paramétré, sans arbre booléen imbriqué.
• Tri multi-colonnes — ?sort=<field>:<dir>,… avec brise-égalité déterministe id ASC.

Chaque primitive embarque une whitelist colonne en défense en profondeur côté adapter SQL, une couverture de test end-to-end incluant des tentatives d'injection SQL, et une surface HTTP qui fail-closed avec 400 BadRequest sur tout input malformé.

Runtime — nouveautés

Pagination

GET /projections/{fqn}?limit=N&offset=M

• limit borné à [1, 1000], défaut 50.
• offset non-négatif, défaut 0.
• Mode subject (?subject=…) ignore les deux.
• Écho fil : data.pagination = {limit, offset, totalCount, pageSize, nextCursor} où nextCursor reste réservé à null pour l'axe curseur futur.

Filtrage

?filter.<field>.<op>=<value>

Trois opérateurs whitelistés :

Op	Sémantique	Forme de la valeur
eq	match exact scalaire	scalaire
contains	sous-chaîne insensible à la casse (champs string)	scalaire, méta-caractères LIKE échappés
in	appartenance à une liste	virgules, ≤ 100 entrées

Refusés au constructor ou couche HTTP :

• arbres booléens imbriqués, groupes OR, fragments SQL arbitraires, regex, opérateurs dynamiques ;
• noms de champs inconnus (contre la liste déclarée par la projection) ;
• clés de query malformées (forme filter.<field>.<op> enforcée) ;
• listes in vides, entrées in vides.

La traduction SQL utilise exclusivement des prepared statements ; les méta-caractères LIKE dans les valeurs contains sont échappés pour qu'un % littéral ne puisse pas élargir le match. Trois vecteurs d'injection SQL classiques ('OR 1=1, DROP TABLE, backslash-escape) sont pinnés dans apps/playground/filtering-test.php.

Tri

?sort=<field>:<dir>[,<field>:<dir>]

• dir doit être exactement asc ou desc (formes en majuscules refusées).
• Multi-colonne compose dans l'ordre déclaré.
• Un brise-égalité déterministe id ASC est toujours appendé, donc la pagination sur clé de tri en égalité reste stable.

ViewSchema fil — 1.2.0

Additif par-dessus 1.0.0. Un renderer 1.0.0 voit les nouvelles clés et les ignore sans risque.

{
  "schemaVersion": "1.2.0",
  "filters": [
    { "field": "status",   "op": "eq",       "value": "ISSUED" }
  ],
  "sort": [
    { "field": "createdAt", "direction": "desc" }
  ],
  "data": {
    "items": [ /* ... */ ],
    "pagination": {
      "limit":      50,
      "offset":     0,
      "totalCount": 42,
      "pageSize":   42,
      "nextCursor": null
    }
  }
}

Compatibilité renderer : @ausus/renderer-react@0.2.0-beta.1 garde peerSchemaVersion: ^1.0.0. Tout backend 1.x reste consommable.

Expérience développeur

• composer serve sur le scaffold starter démarre un serveur de dev sur http://localhost:8000 via le nouveau packages/starter/bin/server.php.
• La façade ausus/standard-stack gagne Application::renderProjection(string $fqn, ?Reference, int $limit, int $offset, list<Filter>, list<Sort>): array qui miroitisera les defaults de l'API HTTP — les callers non-HTTP peuvent paginer / filtrer / trier sans saisir le renderer directement.

CI / release engineering

Les durcissements de la chaîne de publication issus de l'hotfix alpha.5 sont désormais permanents :

• scripts/generate-release-manifest.sh — manifest JSON immuable par tag committé à côté de la release.
• scripts/archive-release-evidence.sh — chaque log de gate capturé par tag sous artifacts/releases/<version>/ pour audit a posteriori.
• .github/workflows/release-replay.yml — workflow workflow_dispatch qui rejoue le release-gate live contre n'importe quel tag publié, read-only (aucun git push, aucun npm publish, aucun git tag).
• scripts/release-gate.sh Step 4b — pre-flight provenance npm renderer, défaite la classe de régressions BUG-A4-2.
• scripts/release-gate.sh Step 5 — les bursts HEAD homepage sont désormais pacés + retry-budgétés ; défaite l'intermittence GitHub HEAD rate-limit observée fin alpha.5.
• scripts/release-gate.sh Step 9 — gate clean-room starter install (5 sous-gates A–E).
• scripts/public-install.sh Step 7 — assertion forme fil pilotée par EXPECTED_SCHEMA_VERSION, défaut 1.2.0 pour v0.2.0-beta.*.
• scripts/integration-http.sh — 14 assertions renderer live-trace PLUS 25 assertions HTTP live filter+sort.
• .github/workflows/release-gate.yml — matrix PHP 8.3 + 8.4.

Installation

Commande d'installation canonique pour la ligne beta :

composer create-project "ausus/starter:^0.2@beta" myapp --stability=beta
cd myapp
composer boot
composer serve   # → http://localhost:8000

Si vous aviez installé la ligne alpha avec --stability=alpha, votre composer.json existant résout v0.2.0-beta.1 automatiquement parce que le flag @alpha de Composer accepte beta. Aucune mise à jour manuelle de contrainte requise.

Renderer

@ausus/renderer-react@0.2.0-beta.1 est la release npm appairée avec ce backend.

• Aucun changement TypeScript / build / peer-dependency.
• peerSchemaVersion reste à ^1.0.0 (couvre 1.0.0, 1.1.0, 1.2.0).
• repository.url et homepage identifient correctement le repo adonko3xBitters/ausus-framework pour la provenance sigstore.

Limitations connues

• Pagination par curseur est réservée à un minor futur — le champ data.pagination.nextCursor est le placeholder.
• Arbres de filtre booléens (groupes AND/OR imbriqués) sont explicitement hors scope ; les multiples conditions sur la même projection AND-combinent mais ne peuvent pas se combiner en OR.
• Tri par expressions calculées (e.g. LOWER(name), created_at + interval) est rejeté par la whitelist colonne.
• Drivers MySQL / PostgreSQL restent un travail post-1.0.
• scripts/public-install.sh step 7 asserte la forme du fil contre le plugin embarqué — le support curseur côté adapter nécessitera son propre pin de contrat le moment venu.

Artefacts publiés

Package	Version
ausus/kernel	v0.2.0-beta.1
ausus/runtime-default	v0.2.0-beta.1
ausus/persistence-sql	v0.2.0-beta.1
ausus/api-http	v0.2.0-beta.1
ausus/standard-stack	v0.2.0-beta.1
ausus/starter	v0.2.0-beta.1
ausus/tenancy-row	v0.2.0-beta.1 (réservé par nom)
ausus/audit-database	v0.2.0-beta.1 (réservé par nom)
ausus/auth-bridge	v0.2.0-beta.1 (réservé par nom)
ausus/presentation-default	v0.2.0-beta.1 (réservé par nom)
@ausus/renderer-react	0.2.0-beta.1