@jantstack/adonis-authz 2.5.0-alpha.4 → 2.5.0-rc.2

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();
         });
@@ -3017,7 +3113,7 @@ export function registerAuthorizationDriverContract(harness, api) {
                         // dejaba vivo un mutante que convertía la colisión en un 503.
                         const raceOfDefines = (serialized) => since('2.2', serialized
                             ? 'dos defineScopedRole del MISMO (slug, nivel) con owners de la misma cadena, en paralelo y con memos distintos: EXACTAMENTE uno gana y el perdedor es 422 E_AUTHZ_CATALOG_CONFLICT — la unicidad no es una carrera'
-                            : 'dos defineScopedRole del MISMO (slug, nivel) con owners de la misma cadena, en paralelo y con memos distintos: nunca dos ganadores y el perdedor no escribe (sin escrituras de catálogo serializadas su transacción puede morir con 503)', async ({ assert }) => {
+                            : 'dos defineScopedRole del MISMO (slug, nivel) con owners de la misma cadena, en paralelo y con memos distintos: nunca dos ganadores con el MISMO owner (el del ancestro puede ensombrecer al del descendiente) y el perdedor no escribe (sin escrituras de catálogo serializadas su transacción puede morir con 503)', async ({ assert }) => {
                             // 3D · M2 (auditor V2 🔴 A, reproducido en PG: los dos se insertaban
                             // porque el unique de la base es (slug, scope_type, owner_scope_key)
                             // y cada uno comprobaba la colisión contra SU foto del memo). Ahora
@@ -3060,11 +3156,21 @@ export function registerAuthorizationDriverContract(harness, api) {
                                 assert.oneOf(ok.length, [1, 2], `un ganador, o el del ancestro ensombreciendo al del descendiente (${estado})`);
                             }
                             else {
-                                // Sin serialización garantizada: nunca dos. Cuántos confirman
-                                // depende del motor — SQLite bloquea la base entera y el segundo
-                                // escritor puede recibir `SQLITE_BUSY`, un fallo de backend
-                                // legítimo (503) porque su transacción NO se aplicó.
-                                assert.isAtMost(ok.length, 1, `nunca dos ganadores (${estado})`);
+                                // Sin serialización garantizada cuántos confirman depende del
+                                // motor — SQLite bloquea la base entera y el segundo escritor
+                                // puede recibir `SQLITE_BUSY`, un fallo de backend legítimo (503)
+                                // porque su transacción NO se aplicó—, así que cero también vale.
+                                // Y los mismos DOS finales legales que la cara `true` (rotación 2 ·
+                                // cierre 2 · T-07): desde R2-05 el re-chequeo en la transacción
+                                // decide por AUTORIDAD, así que si el del descendiente confirma
+                                // mientras el del ancestro valida, el del ancestro ENTRA y lo
+                                // ensombrece (final 2 de 3G · Y1). Hasta alpha.4 aquí se afirmaba
+                                // «como mucho uno», que un backend sin el bloqueo de SQLite podía
+                                // poner rojo sin defecto (aserción flaky en el artefacto
+                                // publicado). Lo innegociable se afirma abajo igual que en la
+                                // cara `true`: nunca dos con el MISMO owner y, si son dos, el
+                                // extra es el del ANCESTRO.
+                                assert.isAtMost(ok.length, 2, `nunca dos ganadores con el MISMO owner (${estado})`);
                             }
                             for (const rejected of results.filter((r) => r.status === 'rejected')) {
                                 const error = rejected.reason;
@@ -3161,22 +3267,18 @@ export function registerAuthorizationDriverContract(harness, api) {
                             await insertRoleUnseen({ slug: 'sigiloso', scopeType: 'unit', owner: scopeKey(orgA) });
                             await rejectsWith(assert, () => here.defineScopedRole(admin, unitA1, { ...spec, slug: 'sigiloso' }), conflicto);
                             assert.lengthOf(await rowsNamed('sigiloso', 'unit'), 1, 'no se escribe a ciegas sobre lo que el memo no vio');
-                            // Y la rama del re-chequeo que NO se puede juzgar ahí dentro (3F ·
-                            // U3, tester 3E · §4.2): un homónimo cuyo owner no es global ni
-                            // ancestro-o-igual del owner pedido —una unit HERMANA— no se
-                            // clasifica sin resolver su cadena, y resolverla con el cerrojo del
-                            // catálogo sostenido sería un abrazo mortal con un pool de 1. Se
-                            // rechaza igual, con el 422 que pide REINTENTAR, y no escribe.
-                            // Hasta 3F esa rama solo la observaba la carrera de arriba, y solo
-                            // en el harness cuyo árbol SQL ensancha la ventana: aquí va EN
-                            // SERIE (el memo se recalienta primero, así que la fila nueva le es
-                            // invisible y solo la relectura de la BASE la ve).
+                            // Y la rama del re-chequeo de un owner que NO es global ni ancestro-o-igual del owner pedido —una unit
+                            // HERMANA— (3F · U3, tester 3E · §4.2; volteada en la rotación 2 de M4 · R2-05). Hasta 2.5.0-alpha.4 se
+                            // rechazaba con un 422 «reintenta» que NOMBRABA el owner del hermano (otro tenant) y la colisión era falsa:
+                            // dos hermanos pueden compartir slug. Ahora se juzga con la MISMA regla de autoridad que la comprobación
+                            // previa y entra. EN SERIE: el memo se recalienta primero, así que la fila nueva le es invisible y solo la
+                            // relectura de la BASE la ve.
                             const unitA2 = await unitUnder(tree, orgA);
                             assert.deepEqual(await here.listRoles(admin, orgA), ['org-admin'], 'memo recalentado tras el fallo anterior');
                             await insertRoleUnseen({ slug: 'lateral', scopeType: 'unit', owner: scopeKey(unitA2) });
-                            const cambio = await rejectsWith(assert, () => here.defineScopedRole(admin, unitA1, { ...spec, slug: 'lateral' }), conflicto);
-                            assert.include(String(cambio?.message), 'El catálogo cambió mientras se validaba');
-                            assert.lengthOf(await rowsNamed('lateral', 'unit'), 1, 'el 422 genérico tampoco escribe a ciegas');
+                            const lateral = await here.defineScopedRole(admin, unitA1, { ...spec, slug: 'lateral' });
+                            assert.equal(lateral.owner, scopeKey(unitA1), 'el homónimo de un HERMANO no es colisión: entra');
+                            assert.lengthOf(await rowsNamed('lateral', 'unit'), 2, 'los dos hermanos tienen su lateral@unit');
                         });
                         caseFor('serializedCatalogWrites', {
                             whenTrue: () => raceOfDefines(true),
@@ -3815,6 +3917,162 @@ export function registerAuthorizationDriverContract(harness, api) {
                 });
             },
         });
+        // ── Rotación 2 · cierre 3 · `snapshotDecisions` (regla D15, linaje L12) ─────────
+        // Una decisión que combina lo que el holder TIENE con lo que tiene DENEGADO, leída en dos métodos del puerto sin
+        // foto común, puede responder lo que ningún estado real responde (un offboarding entre las dos lecturas). La
+        // capacidad dice que el driver lee las dos mitades de una vez; lo que el juez observa es el MÉTODO (`readSnapshot`):
+        // su respuesta es la de los métodos homónimos, y el manager lo usa en vez de componer.
+        const snapshotSeed = async () => {
+            const alice = subject();
+            const orgA = await orgUnder(tree, APP_SCOPE);
+            const unitA1 = await unitUnder(tree, orgA);
+            await driver.grant(alice, 'org-editor', orgA);
+            await driver.grant(alice, 'unit-editor', unitA1);
+            await driver.grant(alice, 'viewer', APP_SCOPE);
+            await driver.deny(alice, 'docs:read', unitA1);
+            await driver.deny(alice, 'billing:read', orgA);
+            return { alice, orgA, unitA1 };
+        };
+        const canonical = (items) => items.map((item) => JSON.stringify(item)).sort();
+        /**
+         * El espía del par (rotación 2 · cierre 3b, tester 🟡 6): cuenta SOLO las llamadas que hace el MANAGER al driver. Cada
+         * método se reenvía con `this` = el driver de verdad (no el proxy), así que lo que un `readSnapshot` llame por dentro
+         * (`this.rolesInChain()` dentro de una transacción REPEATABLE READ, p. ej.) no se cuenta: el juez fija el contrato
+         * (UNA llamada del manager), no la implementación.
+         */
+        const watchManagerCalls = (target) => {
+            const touched = [];
+            // El proxy va sobre un objeto VACÍO (no sobre el driver): un driver congelado o con métodos no configurables no
+            // choca con las invariantes de `Proxy`, y todo se lee del driver de verdad. Una VISTA que devuelve el driver
+            // (`withChainResolver`, `withClock`: el manager las pide por request) se vigila igual, con la misma cuenta.
+            const watch = (real) => new Proxy({}, {
+                get: (_shell, prop) => {
+                    const value = Reflect.get(real, prop, real);
+                    if (typeof value === 'function' && typeof prop === 'string') {
+                        return (...args) => {
+                            touched.push(prop);
+                            const out = value.apply(real, args);
+                            const isView = out !== null && typeof out === 'object' && typeof out.then !== 'function' && typeof out.authorize === 'function';
+                            return isView ? watch(out) : out;
+                        };
+                    }
+                    return value;
+                },
+                has: (_shell, prop) => prop in real,
+            });
+            const watched = watch(target);
+            const reads = () => touched.filter((name) => ['readSnapshot', 'rolesInChain', 'listScopes', 'listDenies', 'listRoles'].includes(name));
+            return { watched, touched, reads };
+        };
+        /**
+         * La parte de DELEGACIÓN de las dos caras (rotación 2 · cierre 3c, A/J1 del auditor y del tester): la policy de
+         * `defineScopedRole` solo se juzga si el harness declara `purgeRole: true`. Sin `purgeRole` el manager no delega
+         * (`defineScopedRole` es 500 `E_AUTHZ_UNSUPPORTED` ANTES de la policy, 3E · P4), y `purgeRole` es un par de `'2.2'`:
+         * un tercero `'2.1'` con `listDenies` y sin `purgeRole` —legítimo, D15— salía ROJO con un caso nuevo. Decide la
+         * DECLARACIÓN del harness, no la presencia del método, por el patrón del juez (como `listDenies` aquí mismo): una
+         * declaración `true` solo es posible en `'2.2'` (en `'2.1'` el juez lanza al registrar un `true` sin caso) y ahí la
+         * juzga su propio par —método presente y purga total, o ausente y 500—, mientras que un método presente en un
+         * harness `'2.1'` no lo juzga nadie. El título de cada cara dice cuál de las dos se registró.
+         */
+        const snapshotDelegation = harness.capabilities.purgeRole === true;
+        caseFor('snapshotDecisions', {
+            whenTrue: () => {
+                since('2.1', 'snapshotDecisions:true · readSnapshot responde cada lectura pedida EXACTAMENTE como el método homónimo (rolesInChain, listScopes, listDenies), lo no pedido no viene, un permiso fuera del catálogo da listScopes [] y una pregunta mal formada es 422', async ({ assert, }) => {
+                    assert.typeOf(driver.readSnapshot, 'function', 'snapshotDecisions: true exige readSnapshot en el puerto');
+                    assert.strictEqual(driver.capabilities?.snapshotDecisions, true, 'el harness declara snapshotDecisions: true y el driver no');
+                    assert.strictEqual((await managerOver().capabilities()).snapshotDecisions, true);
+                    const { alice, unitA1 } = await snapshotSeed();
+                    const chain = (await tree.chainOf(unitA1));
+                    const all = await driver.readSnapshot(alice, { rolesInChain: chain, listScopes: 'docs:write', listDenies: true });
+                    assert.sameMembers(Object.keys(all), ['rolesInChain', 'listScopes', 'listDenies']);
+                    assert.deepEqual(canonical(all.rolesInChain), canonical(await driver.rolesInChain(alice, chain)));
+                    assert.deepEqual(canonical(all.listScopes), canonical(await driver.listScopes(alice, 'docs:write')));
+                    assert.deepEqual(canonical(all.listDenies), canonical(await driver.listDenies(alice)));
+                    assert.lengthOf(all.listDenies, 2);
+                    assert.isAbove(all.rolesInChain.length, 0);
+                    // Con el deny de docs:read en la unit, listScopes de docs:read no lista la unit (ni lo que bloquea).
+                    const reads = await driver.readSnapshot(alice, { listScopes: 'docs:read' });
+                    assert.deepEqual(Object.keys(reads), ['listScopes'], 'lo no pedido no viene');
+                    assert.deepEqual(canonical(reads.listScopes), canonical(await driver.listScopes(alice, 'docs:read')));
+                    assert.deepEqual(await driver.readSnapshot(alice, { listScopes: 'no:existe' }), { listScopes: [] });
+                    for (const bad of [{}, { foo: true }, { listDenies: false }, { rolesInChain: 'x' }, null]) {
+                        await rejectsWith(assert, () => driver.readSnapshot(alice, bad), { status: 422, code: 'E_AUTHZ_INVALID_IDENTITY' });
+                    }
+                });
+                since('2.1', snapshotDelegation
+                    ? 'snapshotDecisions:true · el manager compone effectivePermissions, authorizedScopes y la policy de defineScopedRole con UNA llamada a readSnapshot y CERO a rolesInChain/listScopes/listDenies, con el mismo resultado'
+                    : 'snapshotDecisions:true · el manager compone effectivePermissions y authorizedScopes con UNA llamada a readSnapshot y CERO a rolesInChain/listScopes/listDenies, con el mismo resultado (sin purgeRole: el manager no delega y la policy de defineScopedRole no se juzga aquí)', async ({ assert, }) => {
+                    const { alice, orgA, unitA1 } = await snapshotSeed();
+                    const { watched: spied, touched, reads } = watchManagerCalls(driver);
+                    const watched = managerOver({ delegablePermissions: ['docs:read', 'docs:write'] }, spied);
+                    assert.sameMembers(await watched.effectivePermissions(alice, unitA1), ['docs:write']);
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                    touched.length = 0;
+                    // docs:write: org-editor en la org y unit-editor en la unit (viewer en app solo da docs:read) ⇒ la unit.
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:write', 'unit'), { kind: 'some', scopes: [unitA1] });
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                    touched.length = 0;
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:read', 'unit'), { kind: 'all', excludedSubtrees: [{ scope: unitA1, includesDescendants: true }] });
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                    if (!snapshotDelegation)
+                        return;
+                    assert.typeOf(driver.purgeRole, 'function', 'el harness declara purgeRole: true y el puerto no lo trae');
+                    // La policy de delegación: el actor tiene docs:read DENEGADO en la unit (owner) ⇒ 422 con UNA foto.
+                    const admin = subject();
+                    await driver.grant(admin, 'org-admin', orgA);
+                    await driver.deny(admin, 'docs:read', orgA);
+                    touched.length = 0;
+                    await rejectsWith(assert, () => watched.defineScopedRole(admin, orgA, { slug: 'lead', scopeType: 'unit', rank: 10, permissions: ['docs:read'] }), {
+                        status: 422,
+                        code: 'E_AUTHZ_PERMISSION_NOT_DELEGABLE',
+                    });
+                    assert.deepEqual(reads(), ['readSnapshot']);
+                });
+            },
+            whenFalse: () => {
+                // Rotación 2 · cierre 3b (H3 del auditor): el manager decide por la CAPACIDAD, no por la presencia del método, así
+                // que esta cara NO exige que el puerto no traiga `readSnapshot` (un tercero puede tener un método con ese nombre
+                // para otra cosa): exige que el manager NO lo llame. Sin `listDenies` no hay composición que juzgar y la cara
+                // se queda en la declaración —lo dice su título (tester 🟡 6)—.
+                if (!harness.capabilities.listDenies) {
+                    since('2.1', 'snapshotDecisions:false · (sin listDenies: solo la declaración) authorization.capabilities().snapshotDecisions es false y el driver no declara true; sin listDenies el manager no compone ninguna decisión con deny que juzgar', async ({ assert, }) => {
+                        assert.notStrictEqual(driver.capabilities?.snapshotDecisions, true, 'el harness declara snapshotDecisions: false y el driver declara true');
+                        assert.strictEqual((await managerOver().capabilities()).snapshotDecisions, false);
+                    });
+                    return;
+                }
+                since('2.1', snapshotDelegation
+                    ? 'snapshotDecisions:false · authorization.capabilities().snapshotDecisions es false y el manager compone effectivePermissions, authorizedScopes y la policy de defineScopedRole con rolesInChain/listScopes + listDenies SIN llamar a readSnapshot (aunque el driver traiga un método con ese nombre: decide la capacidad), restando los denies (el hueco DECLARADO de un driver sin la capacidad)'
+                    : 'snapshotDecisions:false · authorization.capabilities().snapshotDecisions es false y el manager compone effectivePermissions y authorizedScopes con rolesInChain/listScopes + listDenies SIN llamar a readSnapshot (aunque el driver traiga un método con ese nombre: decide la capacidad), restando los denies (el hueco DECLARADO de un driver sin la capacidad; sin purgeRole: el manager no delega y la policy de defineScopedRole no se juzga aquí)', async ({ assert, }) => {
+                    assert.notStrictEqual(driver.capabilities?.snapshotDecisions, true, 'el harness declara snapshotDecisions: false y el driver declara true');
+                    assert.strictEqual((await managerOver().capabilities()).snapshotDecisions, false);
+                    const { alice, orgA, unitA1 } = await snapshotSeed();
+                    const { watched: spied, touched, reads } = watchManagerCalls(driver);
+                    const watched = managerOver({ delegablePermissions: ['docs:read', 'docs:write'] }, spied);
+                    assert.sameMembers(await watched.effectivePermissions(alice, unitA1), ['docs:write'], 'el deny de docs:read en la unit se resta');
+                    assert.include(reads(), 'listDenies');
+                    assert.notInclude(reads(), 'readSnapshot');
+                    touched.length = 0;
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:read', 'unit'), { kind: 'all', excludedSubtrees: [{ scope: unitA1, includesDescendants: true }] });
+                    assert.deepEqual(await watched.authorizedScopes(alice, 'docs:write', 'unit'), { kind: 'some', scopes: [unitA1] });
+                    assert.include(reads(), 'listDenies');
+                    assert.notInclude(reads(), 'readSnapshot');
+                    if (!snapshotDelegation)
+                        return;
+                    assert.typeOf(driver.purgeRole, 'function', 'el harness declara purgeRole: true y el puerto no lo trae');
+                    const admin = subject();
+                    await driver.grant(admin, 'org-admin', orgA);
+                    await driver.deny(admin, 'docs:read', orgA);
+                    touched.length = 0;
+                    await rejectsWith(assert, () => watched.defineScopedRole(admin, orgA, { slug: 'lead', scopeType: 'unit', rank: 10, permissions: ['docs:read'] }), {
+                        status: 422,
+                        code: 'E_AUTHZ_PERMISSION_NOT_DELEGABLE',
+                    });
+                    assert.include(reads(), 'listDenies');
+                    assert.notInclude(reads(), 'readSnapshot');
+                });
+            },
+        });
         // ── 3b-2e · E2 · `roleInheritanceNative` ─────────────────────────────
         caseFor('roleInheritanceNative', {
             whenFalse: () => {

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]) {