@jantstack/adonis-authz 2.5.0-rc.1 → 2.5.0

package/build/commands/main.d.ts

@@ -9,7 +9,8 @@ import AuthzReconcile from './authz_reconcile.js';
 import AuthzRelationsReconcile from './authz_relations_reconcile.js';
 import AuthzFreeze from './authz_freeze.js';
 import AuthzUnfreeze from './authz_unfreeze.js';
-export { OpenFgaProvision, AuthzCatalogDiff, AuthzCatalogSync, AuthzCatalogPruneOrphans, AuthzScopesRelay, AuthzScopesRequeue, AuthzReconcile, AuthzRelationsReconcile, AuthzFreeze, AuthzUnfreeze, };
+import AuthzUpgrade1x from './authz_upgrade_1x.js';
+export { OpenFgaProvision, AuthzCatalogDiff, AuthzCatalogSync, AuthzCatalogPruneOrphans, AuthzScopesRelay, AuthzScopesRequeue, AuthzReconcile, AuthzRelationsReconcile, AuthzFreeze, AuthzUnfreeze, AuthzUpgrade1x, };
 /** Contrato de loader de ace (`LoadersContract.getMetaData`). */
 export declare function getMetaData(): Promise<CommandMetaData[]>;
 /** Contrato de loader de ace (`LoadersContract.getCommand`): la clase, o `null` si el nombre no es nuestro. */

package/build/commands/main.js

@@ -10,7 +10,7 @@
  * desenvolver `default` (mismo contrato que `@adonisjs/core/commands` y
  * `@adonisjs/lucid/commands`, que leen un `commands.json` generado por el
  * assembler; aquí no hay assembler, así que el loader es un `ListLoader`
- * sobre las diez clases (nueve hasta alpha.4) y no hay índice que generar).
+ * sobre las once clases (nueve hasta alpha.4, diez hasta la rotación 3 de 2.5) y no hay índice que generar).
  *
  * Hasta alpha.3 este fichero re-exportaba las nueve clases y NADA más, de
  * modo que en un consumidor configurado con `node ace configure` **`node ace`
@@ -37,8 +37,9 @@ import AuthzReconcile from './authz_reconcile.js';
 import AuthzRelationsReconcile from './authz_relations_reconcile.js';
 import AuthzFreeze from './authz_freeze.js';
 import AuthzUnfreeze from './authz_unfreeze.js';
-export { OpenFgaProvision, AuthzCatalogDiff, AuthzCatalogSync, AuthzCatalogPruneOrphans, AuthzScopesRelay, AuthzScopesRequeue, AuthzReconcile, AuthzRelationsReconcile, AuthzFreeze, AuthzUnfreeze, };
-/** Los diez (nueve hasta alpha.4; `authz:scopes:requeue` desde alpha.5), en el orden en que `node ace list` los enseña. */
+import AuthzUpgrade1x from './authz_upgrade_1x.js';
+export { OpenFgaProvision, AuthzCatalogDiff, AuthzCatalogSync, AuthzCatalogPruneOrphans, AuthzScopesRelay, AuthzScopesRequeue, AuthzReconcile, AuthzRelationsReconcile, AuthzFreeze, AuthzUnfreeze, AuthzUpgrade1x, };
+/** Los once (nueve hasta alpha.4; `authz:scopes:requeue` desde alpha.5; `authz:upgrade-1x` desde la rotación 3 de 2.5), en el orden en que `node ace list` los enseña. */
 const loader = new ListLoader([
     OpenFgaProvision,
     AuthzCatalogDiff,
@@ -50,6 +51,7 @@ const loader = new ListLoader([
     AuthzRelationsReconcile,
     AuthzFreeze,
     AuthzUnfreeze,
+    AuthzUpgrade1x,
 ]);
 /** Contrato de loader de ace (`LoadersContract.getMetaData`). */
 export function getMetaData() {

package/build/src/shared/sql_expiry.d.ts

@@ -26,7 +26,7 @@ export interface ExpiryCodec {
     bind(at: Date): unknown;
     /** Expresión de SELECT que devuelve la columna de forma que `fromDb` la lea sin depender del cliente. */
     select(column: string, alias?: string): unknown;
-    /** Lo que devuelve el SELECT de `select(...)` → `Date | null`. */
+    /** Lo que devuelve el SELECT de `select(...)` → `Date | null` (`null` = columna NULL); presente e ilegible LANZA (RR-2). */
     fromDb(value: unknown): Date | null;
 }
 /** ¿Es MySQL? (el mismo conjunto que decide el codec). */
@@ -44,8 +44,12 @@ export declare function dialectOf(connection: any): string;
 export declare function isSqliteDialect(connection: any): boolean;
 /** `2030-06-15T12:00:00.000Z` → `2030-06-15 12:00:00.000` (UTC, con milisegundos). */
 export declare function formatUtcDatetime(at: Date): string;
-/** `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`, o `null` si no es una fecha. */
-export declare function parseUtcDatetime(value: string): Date | null;
+/**
+ * `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`. Lo que no es una fecha REAL lanza
+ * `unreadableExpiry` (RR-2): la fecha cero, un mes 13, un 31 de febrero o un `24:00:00` (que `Date` desbordaría en
+ * silencio al día o al mes siguiente) no se leen como nada.
+ */
+export declare function parseUtcDatetime(value: string): Date;
 /**
  * El codec para una conexión de Lucid (default: la primaria). Se decide por
  * dialecto una vez por driver; MySQL es el único que necesita algo distinto

package/build/src/shared/sql_expiry.js

@@ -26,20 +26,54 @@ export function isSqliteDialect(connection) {
 export function formatUtcDatetime(at) {
     return at.toISOString().slice(0, 23).replace('T', ' ');
 }
-/** `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`, o `null` si no es una fecha. */
+/**
+ * Una caducidad PRESENTE que no se puede leer (rotación 3 · cierre 2, RR-2 del re-ataque): es un error, nunca «sin
+ * caducidad». Hasta aquí `parseUtcDatetime` y el codec identidad devolvían `null` para una fecha que no lo es —la fecha
+ * cero `0000-00-00` que MySQL deja con un `sql_mode` no estricto, un `-infinity` de PostgreSQL, un texto en SQLite—, y
+ * `null` es PERMANENTE para quien lo consume: el re-grant la conservaba como «sin caducidad», `reconcile --to=openfga`
+ * y el export de `relations:reconcile` escribían una tupla permanente para una fila que en SQL ya no concede. Ahora es
+ * 500 `E_AUTHZ_INTERNAL` en la lectura: lo que lee la caducidad para reescribirla o migrarla se para antes de escribir
+ * (`reconcile --to=database` incluido, que antes la reescribía con la del origen: E1, declarado en «Limits»). La DECISIÓN
+ * de SQL (`expires_at > now`) NO pasa por aquí y no es fail-closed para todo valor (re-ataque 2 · C1, corregido): no
+ * concede con la fecha cero de MySQL ni con `-infinity`, pero SÍ concede —para siempre— con `+infinity` en PostgreSQL y
+ * con un TEXTO en SQLite (`TEXT > INTEGER` es verdadero), aunque sea una fecha pasada. El paquete nunca escribe esos
+ * valores; está declarado en «Limits» con su receta (revoke + grant) y el arreglo de fondo va a 2.6. `null`/`undefined` siguen siendo «sin
+ * caducidad»: es lo que guarda una columna NULL.
+ */
+function unreadableExpiry(value) {
+    const shown = value instanceof Date ? 'Invalid Date' : JSON.stringify(typeof value === 'string' ? value.slice(0, 40) : String(value));
+    return new AuthorizationInternalError(`expires_at ilegible (${shown}): una caducidad presente que no es un instante es un error, nunca «sin caducidad». ` +
+        'Corrige la fila (o bórrala) antes de releerla, migrarla o reescribirla.');
+}
+/**
+ * `2030-06-15 12:00:00.000000` (UTC, hasta microsegundos) → `Date`. Lo que no es una fecha REAL lanza
+ * `unreadableExpiry` (RR-2): la fecha cero, un mes 13, un 31 de febrero o un `24:00:00` (que `Date` desbordaría en
+ * silencio al día o al mes siguiente) no se leen como nada.
+ */
 export function parseUtcDatetime(value) {
-    const match = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(?:\.(\d{1,6}))?$/.exec(value.trim());
+    const match = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?$/.exec(value.trim());
     if (!match)
-        return null;
-    const millis = (match[3] ?? '').padEnd(3, '0').slice(0, 3);
-    const date = new Date(`${match[1]}T${match[2]}.${millis}Z`);
-    return Number.isNaN(date.getTime()) ? null : date;
+        throw unreadableExpiry(value);
+    const [, year, month, day, hour, minute, second, fraction] = match;
+    const wall = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+    const date = new Date(`${wall}.${(fraction ?? '').padEnd(3, '0').slice(0, 3)}Z`);
+    // Ida y vuelta: `Date` acepta `2030-02-31` (⇒ 3 de marzo) y `24:00:00` (⇒ día siguiente); una fecha real vuelve igual.
+    if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 19) !== wall)
+        throw unreadableExpiry(value);
+    return date;
 }
 const identityCodec = {
     toDb: (expiresAt) => expiresAt,
     bind: (at) => at,
     select: (column, alias) => (alias && alias !== column ? `${column} as ${alias}` : column),
-    fromDb: toExpiryDate,
+    // RR-2: `toExpiryDate` da `null` para lo que no es fecha (y deja pasar un `Date` inválido); aquí eso es un error.
+    fromDb: (value) => {
+        const date = toExpiryDate(value);
+        if (date === null ? !(value === null || value === undefined || value === '') : Number.isNaN(date.getTime())) {
+            throw unreadableExpiry(value);
+        }
+        return date;
+    },
 };
 function mysqlCodec(connection) {
     const raw = (sql, bindings) => typeof connection?.raw === 'function' ? connection.raw(sql, bindings) : db.raw(sql, bindings);

package/build/src/testing/contract.d.ts

@@ -37,6 +37,10 @@ import type { ContractScopeTree } from './scope_tree.js';
  * `truncationSignal: false` (con `exhaustiveLists`) y `hierarchyFacts: false`;
  * los demás llegan con su fase, y mientras tanto declararlos `true` hace que
  * la suite lance al registrarse: una promesa sin juez no pasa.
+ *
+ * Las claves OPCIONALES (`?:`, regla D15) se pueden omitir: entonces la cara
+ * la elige la declaración normalizada del DRIVER (`isOmittedOptionalCapability`);
+ * declararlas fija la cara y el juez exige que el driver diga lo mismo.
  */
 export interface DriverCapabilities {
     /** El driver materializa el árbol como hechos propios (Fase 3b). */
@@ -204,15 +208,18 @@ export interface DriverCapabilities {
     enumerateFacts: boolean;
     /**
      * **El driver es EXPERIMENTAL** (estrategia 2.5.0, firma 4; `AuthorizationDriverCapabilities.experimental`). Opcional
-     * (regla D15: un harness publicado de 2.4/2.5 sin la clave sigue valiendo y cuenta como `false`). Con `true` el juez fija
-     * que el driver lo declara y que `authorization.capabilities()` lo publica; con `false` (o ausente), que el driver NO lo
+     * (regla D15): si el harness la OMITE, el juez juzga la cara que el DRIVER declara (su declaración normalizada; ensayo
+     * rc.1 de COGNITIV) y un harness publicado sin la clave sigue valiendo; si la declara, manda el harness. Con `true` el
+     * juez fija que el driver lo declara y que `authorization.capabilities()` lo publica; con `false`, que el driver NO lo
      * declara y la copia normalizada dice `false`. No apaga ningún caso. `openfga` = `true` en 2.5.x; `database` = `false`.
      */
     experimental?: boolean;
     /**
      * **Toda decisión que combina concesión y deny se lee en UNA foto** (rotación 2 · cierre 3, L12;
-     * `AuthorizationDriverCapabilities.snapshotDecisions`). Opcional (regla D15: un harness publicado sin la clave sigue
-     * valiendo y cuenta como `false`). Solo tiene casos en `level: '2.1'` o superior (necesita `listDenies`). Con `true`
+     * `AuthorizationDriverCapabilities.snapshotDecisions`). Opcional (regla D15): si el harness la OMITE, el juez juzga la
+     * cara que el DRIVER declara —el `database` del paquete declara `true`, así que un harness de alpha.4 que lo registra
+     * sin la clave se juzga en la cara `true` (ensayo rc.1 de COGNITIV)—; si la declara, manda el harness y contradecir al
+     * driver es rojo. Solo tiene casos en `level: '2.1'` o superior (necesita `listDenies`). Con `true`
      * el juez fija que el driver trae `readSnapshot`, que cada lectura pedida es EXACTAMENTE la del método homónimo (y lo
      * no pedido no viene), que una pregunta mal formada es 422, y que el manager compone `effectivePermissions`,
      * `authorizedScopes` y la policy de `defineScopedRole` con UNA llamada a `readSnapshot` y ninguna a
@@ -225,6 +232,15 @@ export interface DriverCapabilities {
      */
     snapshotDecisions?: boolean;
 }
+/**
+ * **Clave D15 OMITIDA ⇒ la declaración del driver** (ensayo rc.1 de COGNITIV, día 1, hallazgo 1; firma del dueño
+ * 2026-10-23). Una clave opcional que el harness no declara (`undefined`) no es `false`: el juez la toma de la
+ * declaración NORMALIZADA del driver (`normalizeAuthorizationCapabilities`) y juzga ESA cara. Si el harness la declara,
+ * manda el harness (y contradecir al driver sigue siendo rojo). Un harness publicado antes de que la clave existiera no
+ * puede declararla: tratarla como `false` ponía rojo a un harness verde contra un driver que la declara `true` (el propio
+ * `database` con `snapshotDecisions`), que es lo que D15 prohíbe.
+ */
+export declare function isOmittedOptionalCapability(capabilities: DriverCapabilities, capability: keyof DriverCapabilities): boolean;
 export type ContractLevel = 'core' | '2.0' | '2.1' | '2.2';
 export interface DriverContractHarness {
     name: string;

package/build/src/testing/contract.js

@@ -1,12 +1,27 @@
 import '@japa/assert';
 import { test } from '@japa/runner';
 import { v7 as uuidv7 } from 'uuid';
-import { APP_SCOPE } from '../types.js';
+import { APP_SCOPE, normalizeAuthorizationCapabilities } from '../types.js';
 import { AuthorizationManager } from '../manager.js';
 import db from '@adonisjs/lucid/services/db';
 import { CatalogCache, GLOBAL_OWNER_KEY, withAuthzCatalogWrite } from '../catalog/catalog_cache.js';
 import { scopeKey } from '../identity.js';
 import { descendantsFrom, memoryScopeTree, resolveChainFrom } from './scope_tree.js';
+const OPTIONAL_DRIVER_CAPABILITIES = Object.freeze({
+    experimental: true,
+    snapshotDecisions: true,
+});
+/**
+ * **Clave D15 OMITIDA ⇒ la declaración del driver** (ensayo rc.1 de COGNITIV, día 1, hallazgo 1; firma del dueño
+ * 2026-10-23). Una clave opcional que el harness no declara (`undefined`) no es `false`: el juez la toma de la
+ * declaración NORMALIZADA del driver (`normalizeAuthorizationCapabilities`) y juzga ESA cara. Si el harness la declara,
+ * manda el harness (y contradecir al driver sigue siendo rojo). Un harness publicado antes de que la clave existiera no
+ * puede declararla: tratarla como `false` ponía rojo a un harness verde contra un driver que la declara `true` (el propio
+ * `database` con `snapshotDecisions`), que es lo que D15 prohíbe.
+ */
+export function isOmittedOptionalCapability(capabilities, capability) {
+    return Object.prototype.hasOwnProperty.call(OPTIONAL_DRIVER_CAPABILITIES, capability) && capabilities[capability] === undefined;
+}
 /** El default de `DriverContractHarness.transactions`: Lucid + `authz_*`. */
 export function lucidContractTransactions() {
     const count = async (table, subject) => {
@@ -243,6 +258,11 @@ async function rejectsWith(assert, fn, expected) {
     }
     assert.fail('debería haber rechazado');
 }
+/**
+ * Presupuesto de un caso interno sin `timeout` propio cuando una cara se juzga dentro de UN caso (clave D15 omitida):
+ * el caso que la envuelve suma los de su cara. Solo acota un cuelgue; no es una medida.
+ */
+const OMITTED_CASE_TIMEOUT_MS = 30_000;
 export function runAuthorizationDriverContract(harness) {
     return registerAuthorizationDriverContract(harness, {
         group: (title, define) => test.group(title, define),
@@ -259,7 +279,21 @@ export function registerAuthorizationDriverContract(harness, api) {
         let tree;
         /** Registra el caso solo si el harness pidió ese nivel o uno superior. */
         let registered = 0;
+        /**
+         * Mientras no es `null`, `test` NO registra: guarda el caso aquí (las caras de una clave D15 omitida, que se juzgan
+         * dentro de un único caso cuando el driver ya existe; ver `caseFromDriver`).
+         */
+        let capturing = null;
         const test = (title, fn) => {
+            if (capturing) {
+                const entry = { title, fn };
+                capturing.push(entry);
+                return {
+                    timeout(ms) {
+                        entry.timeout = ms;
+                    },
+                };
+            }
             registered += 1;
             return api.test(title, fn);
         };
@@ -273,6 +307,8 @@ export function registerAuthorizationDriverContract(harness, api) {
          * cara `whenTrue` queda sin cubrir y la suite lanza al cerrar el grupo.
          */
         function caseFor(capability, pair) {
+            if (isOmittedOptionalCapability(harness.capabilities, capability))
+                return caseFromDriver(capability, pair);
             const side = harness.capabilities[capability] ? pair.whenTrue : pair.whenFalse;
             if (!side)
                 return;
@@ -284,7 +320,66 @@ export function registerAuthorizationDriverContract(harness, api) {
             if (registered > before)
                 covered.add(capability);
         }
-        group.each.setup(async () => {
+        /** Los casos de una cara, sin registrarlos. */
+        function captureFace(side) {
+            if (!side)
+                return [];
+            const previous = capturing;
+            const into = [];
+            capturing = into;
+            try {
+                side();
+            }
+            finally {
+                capturing = previous;
+            }
+            return into;
+        }
+        /**
+         * **La cara de una clave D15 que el harness OMITE la elige el DRIVER** (ver `isOmittedOptionalCapability`). Al
+         * registrar no hay driver (lo construye `makeDriver` en cada caso, y puede ser asíncrono o tener efectos: crear un
+         * store), así que las DOS caras se capturan sin registrarse y se registra UN caso que, ya con el driver del caso,
+         * lee su declaración normalizada y corre EN SERIE todos los casos de esa cara, cada uno sobre un estado fresco
+         * (`prepareCase`, lo mismo que el `setup` de Japa). Un rojo dice la clave, la declaración del driver y el título del
+         * caso interno. Nada se relaja: con `true` se juzga la cara `true` entera, y si esa cara no tiene caso en este nivel
+         * es rojo como lo sería declararla (`uncoveredCapabilities`, la misma regla pura). Si ninguna cara tiene caso en este
+         * nivel no hay nada observable y no se registra nada (como antes).
+         */
+        function caseFromDriver(capability, pair) {
+            const faces = { true: captureFace(pair.whenTrue), false: captureFace(pair.whenFalse) };
+            if (!faces.true.length && !faces.false.length)
+                return;
+            const budget = (cases) => cases.reduce((ms, c) => ms + (c.timeout ?? OMITTED_CASE_TIMEOUT_MS), 0);
+            const title = `${capability}:(omitida en el harness ⇒ la declaración del driver) · se juzga la cara que el driver declara ` +
+                `(true: ${faces.true.length} caso(s) · false: ${faces.false.length}); un harness que la declare explícita manda (D15)`;
+            test(title, async ({ assert }) => {
+                const declared = normalizeAuthorizationCapabilities(driver.capabilities)[capability] === true;
+                const cases = declared ? faces.true : faces.false;
+                const uncovered = uncoveredCapabilities({ [capability]: declared }, new Set(cases.length ? [capability] : []));
+                if (uncovered.length) {
+                    throw new Error(`[contrato ${harness.name}] el harness omite '${capability}' y el driver declara '${capability}: ${declared}', pero el ` +
+                        `contrato no tiene caso para ese valor en el nivel '${level}'. Declara la clave en el harness con lo observable hoy.`);
+                }
+                for (const [index, entry] of cases.entries()) {
+                    if (index > 0)
+                        await prepareCase();
+                    try {
+                        await entry.fn({ assert });
+                    }
+                    catch (error) {
+                        const prefix = `[${capability}: ${declared} — declaración del driver; el harness la omite] ${entry.title}\n`;
+                        if (error && typeof error === 'object' && !Object.isFrozen(error)) {
+                            error.message = prefix + String(error.message ?? '');
+                            throw error;
+                        }
+                        throw new Error(prefix + String(error?.message ?? error), { cause: error });
+                    }
+                }
+            })?.timeout(Math.max(budget(faces.true), budget(faces.false)));
+            covered.add(capability);
+        }
+        /** El estado fresco de cada caso (el `setup` del grupo; `caseFromDriver` lo repite entre sus casos internos). */
+        async function prepareCase() {
             await harness.cleanup();
             await harness.seedCatalog(CONTRACT_CATALOG);
             tree = harness.makeTree ? await harness.makeTree() : memoryScopeTree();
@@ -341,7 +436,8 @@ export function registerAuthorizationDriverContract(harness, api) {
                     await mirror(() => driver.onScopeMoved?.(child, parent));
                 };
             }
-        });
+        }
+        group.each.setup(prepareCase);
         group.teardown(async () => {
             await harness.cleanup();
         });

package/build/src/testing/relations_contract.d.ts

@@ -47,9 +47,19 @@ export declare const RELATIONS_CONTRACT_DENY_TYPES: {
     readonly note: undefined;
 };
 export declare function contractDenyRelationsConfig(): RelationsConfig;
+/**
+ * **Clave D15 OMITIDA ⇒ la declaración del driver** (gemelo de `isOmittedOptionalCapability` del runner de roles; ensayo
+ * rc.1 de COGNITIV, día 1). Una clave opcional que el harness no declara se juzga con la declaración NORMALIZADA del
+ * driver del caso (`normalizeRelationsCapabilities`); si el harness la declara, manda el harness.
+ */
+export declare function isOmittedOptionalRelationsCapability(capabilities: RelationsDriverCapabilities, capability: keyof RelationsDriverCapabilities): boolean;
 export interface RelationsDriverContractHarness {
     name: string;
-    /** Lo que este driver DECLARA. Cada valor se juzga con su cara. */
+    /**
+     * Lo que este driver DECLARA. Cada valor se juzga con su cara. Una clave OPCIONAL (`?:`, regla D15: `relationDenies`,
+     * `atomicRenewal`, `experimental`) que el harness omite se juzga con la declaración normalizada del DRIVER
+     * (`isOmittedOptionalRelationsCapability`); declararla fija la cara y el juez exige que el driver diga lo mismo.
+     */
     capabilities: RelationsDriverCapabilities;
     /** Construye el driver sobre la config del contrato (fresco por caso). */
     makeDriver(config: RelationsConfig): RelationsDriver | Promise<RelationsDriver>;

package/build/src/testing/relations_contract.js

@@ -28,7 +28,7 @@ import { assertCheckManyObjects, distinctObjects, expandByPosition, RELATIONS_CH
 import { assertEnumeratePage, assertNoListPage } from '../relations/page.js';
 import { systemClock } from '../clock.js';
 import { resolveGrantExpiry, sameInstant } from '../expiry.js';
-import { isRelUserset } from '../types.js';
+import { isRelUserset, normalizeRelationsCapabilities } from '../types.js';
 /* ── El vocabulario del contrato ─────────────────────────────────────────── */
 /** Los holder types del contrato de relaciones. */
 export const RELATIONS_HOLDER_TYPES = ['user', 'admin', 'integration'];
@@ -101,6 +101,21 @@ export function contractDenyRelationsConfig() {
         database: { membersOf: true },
     });
 }
+const OPTIONAL_RELATIONS_CAPABILITIES = Object.freeze({
+    relationDenies: true,
+    atomicRenewal: true,
+    experimental: true,
+});
+/**
+ * **Clave D15 OMITIDA ⇒ la declaración del driver** (gemelo de `isOmittedOptionalCapability` del runner de roles; ensayo
+ * rc.1 de COGNITIV, día 1). Una clave opcional que el harness no declara se juzga con la declaración NORMALIZADA del
+ * driver del caso (`normalizeRelationsCapabilities`); si el harness la declara, manda el harness.
+ */
+export function isOmittedOptionalRelationsCapability(capabilities, capability) {
+    return Object.prototype.hasOwnProperty.call(OPTIONAL_RELATIONS_CAPABILITIES, capability) && capabilities[capability] === undefined;
+}
+/** Presupuesto de un caso interno sin `timeout` propio cuando una cara se juzga dentro de UN caso (clave D15 omitida). */
+const OMITTED_CASE_TIMEOUT_MS = 30_000;
 /** El default de `RelationsDriverContractHarness.transactions`: Lucid + `authz_relations`. */
 export function lucidRelationsContractTransactions() {
     return {
@@ -668,22 +683,94 @@ export function registerRelationsDriverContract(harness, api) {
             base,
         };
     }
+    /** El estado fresco de cada caso (el `setup` del grupo; `caseFromDriver` lo repite entre sus casos internos). */
+    async function prepareCase() {
+        // alpha.3: el manager de cada caso captura `onRelationWrite` — el par
+        // `transactionalWrites` juzga también el EVENTO (la otra cara observable
+        // de la capacidad) y R-07/R-08 juzgan el evento de la purga.
+        state.events = [];
+        const f = await freshManager({ onRelationWrite: (e) => void state.events.push(e) });
+        state.manager = f.manager;
+        state.base = f.base;
+        state.writes = f.writes;
+        state.calls = f.calls;
+    }
+    /**
+     * Lo que se JUZGA de una capacidad dentro de un caso: lo que declara el harness, o —si omite una clave opcional (D15)—
+     * la declaración normalizada del driver del caso. Lo leen los casos que dependen de otra capacidad (p. ej. los de
+     * `atomicRenewal` siembran el deny si `relationDenies`): con la clave omitida no pueden leer `undefined` como `false`.
+     */
+    function judged(capability) {
+        if (isOmittedOptionalRelationsCapability(harness.capabilities, capability)) {
+            return normalizeRelationsCapabilities(state.base?.capabilities)[capability] === true;
+        }
+        return harness.capabilities[capability] === true;
+    }
     api.group(`relations contract [${harness.name}]`, (group) => {
-        group.each.setup(async () => {
-            // alpha.3: el manager de cada caso captura `onRelationWrite` — el par
-            // `transactionalWrites` juzga también el EVENTO (la otra cara observable
-            // de la capacidad) y R-07/R-08 juzgan el evento de la purga.
-            state.events = [];
-            const f = await freshManager({ onRelationWrite: (e) => void state.events.push(e) });
-            state.manager = f.manager;
-            state.base = f.base;
-            state.writes = f.writes;
-            state.calls = f.calls;
-        });
+        group.each.setup(prepareCase);
+        /** Mientras no es `null`, `test` guarda el caso aquí en vez de registrarlo (ver `caseFromDriver`). */
+        let capturing = null;
         const test = (title, fn) => {
+            if (capturing) {
+                const entry = { title, fn };
+                capturing.push(entry);
+                return {
+                    timeout(ms) {
+                        entry.timeout = ms;
+                    },
+                };
+            }
             registered++;
             return api.test(title, fn);
         };
+        function captureFace(side) {
+            const previous = capturing;
+            const into = [];
+            capturing = into;
+            try {
+                side();
+            }
+            finally {
+                capturing = previous;
+            }
+            return into;
+        }
+        /**
+         * **La cara de una clave D15 que el harness OMITE la elige el DRIVER** (gemelo de `caseFromDriver` del runner de
+         * roles). Las dos caras se capturan sin registrarse y se registra UN caso que, con el driver del caso, lee su
+         * declaración normalizada y corre en serie todos los casos de esa cara, cada uno sobre un estado fresco
+         * (`prepareCase`). Nada se relaja: si el driver declara `true` se juzga la cara `true` entera.
+         */
+        function caseFromDriver(capability, pair) {
+            const faces = { true: captureFace(pair.whenTrue), false: captureFace(pair.whenFalse) };
+            const budget = (cases) => cases.reduce((ms, c) => ms + (c.timeout ?? OMITTED_CASE_TIMEOUT_MS), 0);
+            const title = `${capability}:(omitida en el harness ⇒ la declaración del driver) · se juzga la cara que el driver declara ` +
+                `(true: ${faces.true.length} caso(s) · false: ${faces.false.length}); un harness que la declare explícita manda (D15)`;
+            test(title, async ({ assert }) => {
+                const declared = normalizeRelationsCapabilities(state.base?.capabilities)[capability] === true;
+                const cases = declared ? faces.true : faces.false;
+                if (!cases.length) {
+                    throw new Error(`[contrato ${harness.name}] el harness omite '${capability}' y el driver declara '${capability}: ${declared}', pero ` +
+                        `esa cara no registró ningún caso: una cara vacía es un skip disfrazado.`);
+                }
+                for (const [index, entry] of cases.entries()) {
+                    if (index > 0)
+                        await prepareCase();
+                    try {
+                        await entry.fn({ assert });
+                    }
+                    catch (error) {
+                        const prefix = `[${capability}: ${declared} — declaración del driver; el harness la omite] ${entry.title}\n`;
+                        if (error && typeof error === 'object' && !Object.isFrozen(error)) {
+                            error.message = prefix + String(error.message ?? '');
+                            throw error;
+                        }
+                        throw new Error(prefix + String(error?.message ?? error), { cause: error });
+                    }
+                }
+            })?.timeout(Math.max(budget(faces.true), budget(faces.false)));
+            covered.add(capability);
+        }
         function caseFor(capability, pair) {
             // MÁS ESTRICTO que el guard de roles: las DOS caras tienen que existir
             // en el código del runner, o es un skip disfrazado (exigencia del tester).
@@ -691,6 +778,8 @@ export function registerRelationsDriverContract(harness, api) {
                 throw new Error(`[contrato ${harness.name}] la capacidad '${capability}' no declara sus dos caras ` +
                     `(whenTrue Y whenFalse): una cara ausente es un skip disfrazado.`);
             }
+            if (isOmittedOptionalRelationsCapability(harness.capabilities, capability))
+                return caseFromDriver(capability, pair);
             const before = registered;
             (harness.capabilities[capability] ? pair.whenTrue : pair.whenFalse)();
             if (registered > before)
@@ -860,7 +949,7 @@ export function registerRelationsDriverContract(harness, api) {
                 assert.notProperty(members, 'cursor', 'membersOf sin page no devuelve cursor');
                 assert.deepEqual(ids(members.subjects), expected, `membersOf devuelve los ${N}`);
             }
-            if (harness.capabilities.relationDenies) {
+            if (judged('relationDenies')) {
                 const { manager } = await denyManager();
                 const denied = { type: 'document', id: docId() };
                 for (const u of users)
@@ -1984,20 +2073,20 @@ export function registerRelationsDriverContract(harness, api) {
         }
         caseFor('atomicRenewal', {
             whenTrue: () => test('atomicRenewal:true · renovar (otra caducidad) una membresía que TRANSPORTA un deny —directa y ANIDADA— entra en UNA escritura: la caducidad cambia y el deny sigue negando', async ({ assert }) => {
-                const { manager, base } = harness.capabilities.relationDenies ? await denyManager() : { manager: state.manager, base: state.base };
-                const { u, p, x, g, h, k } = await seedRenewal(manager, harness.capabilities.relationDenies === true);
+                const { manager, base } = judged('relationDenies') ? await denyManager() : { manager: state.manager, base: state.base };
+                const { u, p, x, g, h, k } = await seedRenewal(manager, judged('relationDenies'));
                 for (const group of [g, h, k]) {
                     await manager.relate(u, 'member', group, p, { expiresAt: null });
                     const expiry = await membershipExpiry(base, u, group, p);
                     if (expiry !== undefined)
                         assert.isNull(expiry, `la membresía de ${group.id} quedó SIN caducidad`);
                 }
-                const carried = harness.capabilities.relationDenies === true && harness.capabilities.usersetSubjects === true;
+                const carried = judged('relationDenies') && harness.capabilities.usersetSubjects === true;
                 assert.equal(await manager.check(u, 'viewer', x, p), !carried, 'el deny transportado sigue negando tras renovar');
             }),
             whenFalse: () => test('atomicRenewal:false · renovar una membresía que TRANSPORTA un deny vivo —directa o por un grupo que la contiene— ⇒ 409 E_AUTHZ_RENEWAL_UNSAFE con la receta y CERO escrituras (la caducidad no cambia, el deny sigue negando); una membresía sin deny se renueva', async ({ assert }) => {
-                const denies = harness.capabilities.relationDenies === true && harness.capabilities.usersetSubjects === true;
-                const { manager, base } = harness.capabilities.relationDenies ? await denyManager() : { manager: state.manager, base: state.base };
+                const denies = judged('relationDenies') && harness.capabilities.usersetSubjects === true;
+                const { manager, base } = judged('relationDenies') ? await denyManager() : { manager: state.manager, base: state.base };
                 const { u, p, x, g, h, k, hour } = await seedRenewal(manager, denies);
                 if (denies) {
                     for (const group of [g, h]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jantstack/adonis-authz",
-  "version": "2.5.0-rc.1",
+  "version": "2.5.0",
   "description": "Driver-based authorization engine for AdonisJS + Lucid: hierarchical scopes with downward inheritance, explicit denies, expiring assignments and polymorphic holders. Ships a self-contained database driver and an OpenFGA driver, both judged by the same executable contract suite.",
   "type": "module",
   "license": "MIT",