@jantstack/adonis-authz 2.4.0-alpha.1 → 2.4.0-alpha.2

package/build/src/testing/relations_contract.js

@@ -19,8 +19,12 @@
  */
 import { v7 as uuidv7 } from 'uuid';
 import { test as japaTest } from '@japa/runner';
+import db from '@adonisjs/lucid/services/db';
+import { scopeKey } from '../identity.js';
 import { RelationsManager } from '../relations/manager.js';
 import { defineRelationsConfig } from '../relations/define_relations_config.js';
+import { systemClock } from '../clock.js';
+import { resolveGrantExpiry } from '../expiry.js';
 import { isRelUserset } from '../types.js';
 /* ── El vocabulario del contrato ─────────────────────────────────────────── */
 /** Los holder types del contrato de relaciones. */
@@ -45,6 +49,19 @@ export function contractRelationsConfig() {
         database: { membersOf: true },
     });
 }
+/** El default de `RelationsDriverContractHarness.transactions`: Lucid + `authz_relations`. */
+export function lucidRelationsContractTransactions() {
+    return {
+        async begin() {
+            const trx = await db.transaction();
+            return { client: trx, commit: () => trx.commit(), rollback: () => trx.rollback() };
+        },
+        async census(partition) {
+            const rows = await db.from('authz_relations').where('partition_key', scopeKey(partition)).count('* as n');
+            return Number(rows[0]?.n ?? 0);
+        },
+    };
+}
 function scopeKeyOf(scope) {
     return scope.type === 'app' ? 'app' : `${scope.type}|${scope.uuid}`;
 }
@@ -59,8 +76,19 @@ function subjectKeyOf(subject) {
  * que prueba el CONTRATO —no el MODELO fusionado (eso es el `:8101` en 4-4)—.
  */
 export function makeRelationsDriver(options) {
+    return buildRelationsDouble(options, [], systemClock);
+}
+/**
+ * El doble, sobre un conjunto de tuplas COMPARTIDO y un reloj: `withClock`
+ * (solo con `injectableClock: true`) devuelve otra vista sobre las MISMAS
+ * tuplas con otro `now`, como los drivers reales (R-15).
+ */
+function buildRelationsDouble(options, tuples, now) {
     const { config, capabilities, limits } = options;
-    const tuples = [];
+    /** Caducidad ESTRICTA (R-15): la que vence AHORA ya no cuenta. */
+    function active(t) {
+        return t.expiresAt === null || t.expiresAt.getTime() > now().getTime();
+    }
     /**
      * `viewer` ⊇ `{viewer, editor, owner}`: las relaciones cuyo hecho DIRECTO
      * satisface R. `viewer includes editor` ⇒ un `editor` es también `viewer`,
@@ -84,11 +112,13 @@ export function makeRelationsDriver(options) {
         }
         return out;
     }
+    /** Los hechos DIRECTOS vigentes (los caducados no conceden ni se enumeran, R-15). */
     function directSubjects(partition, objectType, objectId, relation) {
         return tuples.filter((t) => t.partition === partition &&
             t.objectType === objectType &&
             t.objectId === objectId &&
-            t.relation === relation);
+            t.relation === relation &&
+            active(t));
     }
     function resolves(subject, relation, object, partition, seen = new Set()) {
         const guardKey = `${subjectKeyOf(subject)}|${object.type}:${object.id}#${relation}`;
@@ -142,24 +172,30 @@ export function makeRelationsDriver(options) {
     }
     const driver = {
         capabilities,
-        async relate(subject, relation, object, partition) {
+        async relate(subject, relation, object, partition, options) {
             const partitionKey = scopeKeyOf(partition);
             const subjectKey = subjectKeyOf(subject);
-            const exists = tuples.some((t) => t.partition === partitionKey &&
+            const existing = tuples.find((t) => t.partition === partitionKey &&
                 t.objectType === object.type &&
                 t.objectId === object.id &&
                 t.relation === relation &&
                 t.subjectKey === subjectKey);
-            if (!exists) {
-                tuples.push({
-                    partition: partitionKey,
-                    objectType: object.type,
-                    objectId: object.id,
-                    relation,
-                    subject,
-                    subjectKey,
-                });
+            // R-15, los tres estados (invariante 10): omitido preserva la vigente
+            // (una caducada revive sin caducidad), null la quita, Date la fija.
+            const expiresAt = resolveGrantExpiry(existing?.expiresAt ?? null, options?.expiresAt, now());
+            if (existing) {
+                existing.expiresAt = expiresAt;
+                return;
             }
+            tuples.push({
+                partition: partitionKey,
+                objectType: object.type,
+                objectId: object.id,
+                relation,
+                subject,
+                subjectKey,
+                expiresAt,
+            });
         },
         async unrelate(subject, relation, object, partition) {
             const partitionKey = scopeKeyOf(partition);
@@ -182,7 +218,7 @@ export function makeRelationsDriver(options) {
             const partitionKey = scopeKeyOf(partition);
             const ids = new Set();
             for (const t of tuples) {
-                if (t.partition === partitionKey && t.objectType === objectType)
+                if (t.partition === partitionKey && t.objectType === objectType && active(t))
                     ids.add(t.objectId);
             }
             const matches = [];
@@ -238,6 +274,8 @@ export function makeRelationsDriver(options) {
     if (capabilities.enumerateRelations) {
         driver.enumerateRelations = async (partition) => {
             const partitionKey = scopeKeyOf(partition);
+            // SIN filtrar la caducada (R-15): llega con su `expiresAt` para que el
+            // destino de reconcile la cuente en `skipped`, no para que desaparezca.
             const out = tuples
                 .filter((t) => t.partition === partitionKey)
                 .map((t) => ({
@@ -245,12 +283,30 @@ export function makeRelationsDriver(options) {
                 relation: t.relation,
                 object: { type: t.objectType, id: t.objectId },
                 partition,
+                expiresAt: t.expiresAt,
             }));
             return { tuples: out };
         };
     }
+    if (capabilities.injectableClock) {
+        // La vista con otro reloj comparte las tuplas (como `Object.create(this)`
+        // en los drivers reales). Solo existe si se declara: la cara `false` del
+        // juez exige que un driver sin la capacidad NO traiga `withClock`.
+        driver.withClock = (next) => buildRelationsDouble(options, tuples, next);
+    }
     return driver;
 }
+/** El reloj fijo del juez (el mismo patrón que `fixedClock` del runner de roles). */
+function fixedClock(start) {
+    let current = new Date(start.getTime());
+    return {
+        now: () => new Date(current.getTime()),
+        set: (at) => {
+            current = new Date(at.getTime());
+        },
+    };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /* ── El runner ───────────────────────────────────────────────────────────── */
 function holder() {
     return { type: 'user', uuid: uuidv7() };
@@ -273,7 +329,8 @@ function spy(driver) {
     let writes = 0;
     const wrapped = new Proxy(driver, {
         get(target, prop, receiver) {
-            if (prop === 'relate' || prop === 'unrelate') {
+            // L-2: las CUATRO escrituras (también `purge*`, que reciben `{ transaction }`).
+            if (prop === 'relate' || prop === 'unrelate' || prop === 'purgeObject' || prop === 'purgeSubject') {
                 return async (...args) => {
                     writes++;
                     return target[prop](...args);
@@ -316,7 +373,13 @@ export function registerRelationsDriverContract(harness, api) {
     async function freshManager(options) {
         const base = await harness.makeDriver(contractRelationsConfig());
         const s = spy(base);
-        return { manager: new RelationsManager(s.driver, contractRelationsConfig(), options), writes: s.writes, base };
+        // L-2: el manager nombra al driver en las dos puertas de `{ transaction }`
+        // como lo haría el provider (la clave en `relations.drivers`): aquí, el harness.
+        return {
+            manager: new RelationsManager(s.driver, contractRelationsConfig(), { driverName: harness.name, ...options }),
+            writes: s.writes,
+            base,
+        };
     }
     api.group(`relations contract [${harness.name}]`, (group) => {
         group.each.setup(async () => {
@@ -327,7 +390,7 @@ export function registerRelationsDriverContract(harness, api) {
         });
         const test = (title, fn) => {
             registered++;
-            api.test(title, fn);
+            return api.test(title, fn);
         };
         function caseFor(capability, pair) {
             // MÁS ESTRICTO que el guard de roles: las DOS caras tienen que existir
@@ -503,6 +566,38 @@ export function registerRelationsDriverContract(harness, api) {
             assert.deepEqual(events[0].actor, actor);
             assert.equal(events[0].operation, 'relate');
         });
+        /* ── R-15 · caducidad de la tupla (núcleo, sin reloj): estricta y validada ── */
+        test('R-15 · relate con expiresAt pasado NO concede (check/listObjects/listSubjects); futuro sí; expiresAt inválido ⇒ 422 sin tocar el driver', async ({ assert, }) => {
+            const u = holder();
+            const doc = { type: 'document', id: docId() };
+            const p = partition();
+            // Caducada al escribirse: no concede y no se enumera (caducidad
+            // estricta; sin reloj inyectado, un instante PASADO ya lo observa).
+            await state.manager.relate(u, 'viewer', doc, p, { expiresAt: new Date(Date.now() - 60_000) });
+            assert.isFalse(await state.manager.check(u, 'viewer', doc, p), 'caducada ⇒ check false');
+            const objects = await state.manager.listObjects(u, 'viewer', 'document', p);
+            assert.isFalse(objects.objects.some((o) => o.id === doc.id), 'caducada ⇒ listObjects no la lista');
+            const subjects = await state.manager.listSubjects('viewer', doc, p);
+            assert.isFalse(subjects.subjects.some((s) => !isRelUserset(s) && s.uuid === u.uuid), 'caducada ⇒ listSubjects no la lista');
+            // Con caducidad futura concede (y `Date` sobre la caducada la FIJA: tercer estado).
+            await state.manager.relate(u, 'viewer', doc, p, { expiresAt: new Date(Date.now() + 3_600_000) });
+            assert.isTrue(await state.manager.check(u, 'viewer', doc, p), 'futura ⇒ concede');
+            // Un `expiresAt` que no es Date válida/null/omitido es 422 ANTES del driver.
+            const writes = state.writes();
+            for (const bad of ['mañana', 12345, new Date('no-es-fecha')]) {
+                let caught;
+                try {
+                    await state.manager.relate(u, 'viewer', doc, p, { expiresAt: bad });
+                    assert.fail(`debería haber lanzado con ${String(bad)}`);
+                }
+                catch (error) {
+                    caught = error;
+                }
+                assert.equal(caught.status, 422);
+                assert.equal(caught.code, 'E_AUTHZ_INVALID_IDENTITY');
+            }
+            assert.equal(state.writes(), writes, 'el driver no se tocó con un expiresAt inválido');
+        });
         /* ── Capacidades, cada una con sus DOS caras ── */
         caseFor('singleCheckRelations', {
             // whenTrue: la derivación (includes + userset anidado) resuelve — la
@@ -641,6 +736,326 @@ export function registerRelationsDriverContract(harness, api) {
                 assert.isUndefined(page.truncated);
             }),
         });
+        /* ── R-15 · el par `injectableClock` (paridad con roles, 2.5 · J1) ── */
+        caseFor('injectableClock', {
+            whenTrue: () => test('injectableClock:true · expiresAt en tres estados con el reloj inyectado, y la caducidad EXACTA (T−1 ms concede, T no, T+1 no) en check/listObjects/listSubjects y a través de un userset; renovar y revivir sin dormir', async ({ assert, }) => {
+                assert.typeOf(state.base.withClock, 'function', 'injectableClock: true exige withClock en el puerto');
+                // `T` lleva milisegundos a propósito (2.5 · J3): un motor que trunque
+                // a segundos falla aquí (DATETIME(3) en MySQL).
+                const T = new Date('2030-06-15T12:34:56.789Z');
+                const clock = fixedClock(new Date(T.getTime() - 60_000));
+                const clocked = new RelationsManager(state.base.withClock(clock.now), contractRelationsConfig());
+                const u = holder();
+                const doc = { type: 'document', id: docId() };
+                const viaGroup = { type: 'document', id: docId() };
+                const g = { type: 'group', id: docId() };
+                const p = partition();
+                await clocked.relate(u, 'viewer', doc, p, { expiresAt: T });
+                // La MEMBRESÍA caduca: g#member es editor de `viaGroup` sin plazo, pero
+                // u es member de g solo hasta T ⇒ en T deja de ser viewer de viaGroup.
+                await clocked.relate(u, 'member', g, p, { expiresAt: T });
+                await clocked.relate({ object: g, relation: 'member' }, 'editor', viaGroup, p);
+                const observe = async () => ({
+                    check: await clocked.check(u, 'viewer', doc, p),
+                    listObjects: (await clocked.listObjects(u, 'viewer', 'document', p)).objects.some((o) => o.id === doc.id),
+                    listSubjects: (await clocked.listSubjects('viewer', doc, p)).subjects.some((s) => !isRelUserset(s) && s.uuid === u.uuid),
+                    viaGroup: await clocked.check(u, 'viewer', viaGroup, p),
+                    ...(harness.capabilities.membersOfNative
+                        ? {
+                            membersOf: (await clocked.membersOf(g, 'member', p)).subjects.some((s) => !isRelUserset(s) && s.uuid === u.uuid),
+                        }
+                        : {}),
+                });
+                const alive = {
+                    check: true,
+                    listObjects: true,
+                    listSubjects: true,
+                    viaGroup: true,
+                    ...(harness.capabilities.membersOfNative ? { membersOf: true } : {}),
+                };
+                const gone = {
+                    check: false,
+                    listObjects: false,
+                    listSubjects: false,
+                    viaGroup: false,
+                    ...(harness.capabilities.membersOfNative ? { membersOf: false } : {}),
+                };
+                clock.set(new Date(T.getTime() - 1));
+                assert.deepEqual(await observe(), alive, 'T−1 ms');
+                clock.set(T);
+                assert.deepEqual(await observe(), gone, 'T: la que vence ahora ya no cuenta (estricta)');
+                clock.set(new Date(T.getTime() + 1));
+                assert.deepEqual(await observe(), gone, 'T+1 ms');
+                // Renovación: `Date` posterior vuelve a conceder hasta ESE instante.
+                const T2 = new Date(T.getTime() + 1_000);
+                await clocked.relate(u, 'viewer', doc, p, { expiresAt: T2 });
+                await clocked.relate(u, 'member', g, p, { expiresAt: T2 });
+                assert.deepEqual(await observe(), alive, 'renovada en T+1 ms');
+                clock.set(new Date(T2.getTime() - 1));
+                assert.deepEqual(await observe(), alive, 'T2−1 ms');
+                clock.set(T2);
+                assert.deepEqual(await observe(), gone, 'T2');
+                // Los tres estados (invariante 10), con el reloj en T2 (u ya caducado):
+                // omitido sobre una CADUCADA revive sin caducidad;
+                await clocked.relate(u, 'viewer', doc, p);
+                await clocked.relate(u, 'member', g, p);
+                clock.set(new Date('2099-12-31T23:59:59.999Z'));
+                assert.deepEqual(await observe(), alive, 'revivida sin caducidad: vigente en 2099');
+                // omitido sobre una VIGENTE la preserva (no la convierte en permanente);
+                const keep = holder();
+                const soon = new Date(clock.now().getTime() + 1_500);
+                await clocked.relate(keep, 'viewer', doc, p, { expiresAt: soon });
+                await clocked.relate(keep, 'viewer', doc, p);
+                // null la quita.
+                const lift = holder();
+                await clocked.relate(lift, 'viewer', doc, p, { expiresAt: soon });
+                await clocked.relate(lift, 'viewer', doc, p, { expiresAt: null });
+                clock.set(new Date(soon.getTime() - 1));
+                assert.isTrue(await clocked.check(keep, 'viewer', doc, p), 'preservada: vigente en soon−1');
+                clock.set(soon);
+                assert.isFalse(await clocked.check(keep, 'viewer', doc, p), 'preservada: vence en soon (omitido NO la hizo permanente)');
+                assert.isTrue(await clocked.check(lift, 'viewer', doc, p), 'null la quitó: sigue vigente');
+                // El driver del harness (sin reloj inyectado) no se ha tocado: para él
+                // (hoy) T2 —2030— es futuro y la relación renovada concede.
+                assert.isTrue(await state.manager.check(lift, 'viewer', doc, p));
+            }),
+            whenFalse: () => test('injectableClock:false · expiresAt en tres estados en tiempo real (1,5 s): omitido preserva, null quita, caducada revive; sin withClock', async ({ assert, }) => {
+                assert.notTypeOf(state.base.withClock, 'function', 'el harness declara injectableClock: false y el driver trae withClock: declara lo observable');
+                const doc = { type: 'document', id: docId() };
+                const p = partition();
+                const keep = holder();
+                const lift = holder();
+                const revive = holder();
+                const soon = new Date(Date.now() + 1_500);
+                await state.manager.relate(keep, 'viewer', doc, p, { expiresAt: soon });
+                await state.manager.relate(keep, 'viewer', doc, p); // omitido: preserva `soon`
+                await state.manager.relate(lift, 'viewer', doc, p, { expiresAt: soon });
+                await state.manager.relate(lift, 'viewer', doc, p, { expiresAt: null }); // la quita
+                await state.manager.relate(revive, 'viewer', doc, p, { expiresAt: new Date(Date.now() - 60_000) });
+                assert.isFalse(await state.manager.check(revive, 'viewer', doc, p), 'caducada no concede');
+                await state.manager.relate(revive, 'viewer', doc, p); // omitido sobre caducada: revive sin caducidad
+                assert.isTrue(await state.manager.check(keep, 'viewer', doc, p));
+                assert.isTrue(await state.manager.check(lift, 'viewer', doc, p));
+                assert.isTrue(await state.manager.check(revive, 'viewer', doc, p));
+                await sleep(1_700);
+                assert.isFalse(await state.manager.check(keep, 'viewer', doc, p), 'preservada: venció');
+                assert.isTrue(await state.manager.check(lift, 'viewer', doc, p), 'sin caducidad: sigue');
+                assert.isTrue(await state.manager.check(revive, 'viewer', doc, p), 'revivida sin caducidad: sigue');
+            }),
+        });
+        /* ── L-2 · el par `transactionalWrites` (panel `{trx}`, (C); mismo nombre que en roles) ── */
+        caseFor('transactionalWrites', {
+            // L-4: la cara `true`. Lo que se juzga es «los dos o ninguno con TU
+            // transacción» POR CENSO (paridad con la cara `true` de roles, L-3): el
+            // rollback deja CERO tuplas nuevas en la partición (no solo `check`
+            // false — una respuesta puede salir bien con la fila viva), el commit
+            // las deja escritas, mientras la transacción está abierta la autoridad
+            // (que lee por la conexión del motor) no ve nada, y `purgeObject`/
+            // `purgeSubject` borran y REVIERTEN juntos (tras el rollback todo lo
+            // purgado está de vuelta). Y la otra mitad: una transacción que NO es
+            // la del driver no recibe ni una sentencia. Necesita un motor con
+            // transacciones reales y pool ≥ 2: el harness `database` lo declara
+            // `true` en `sqlite-file`/PG/MySQL y `false` en `:memory:`.
+            whenTrue: () => test('transactionalWrites:true · relate/unrelate/purgeObject/purgeSubject con { transaction } + rollback ⇒ check sin cambio Y CERO tuplas nuevas (censo); + commit ⇒ aplicado; purge* borran y revierten JUNTOS; una transacción ajena, un cliente sin transacción o el `db` entero ⇒ 500 E_AUTHZ_CONFIG sin UNA sentencia por ella', async ({ assert, }) => {
+                assert.equal(state.base.capabilities?.transactionalWrites, true, 'el harness declara transactionalWrites: true y el driver no: declara lo observable');
+                const tx = harness.transactions ?? lucidRelationsContractTransactions();
+                const u = holder();
+                const v = holder();
+                const doc = { type: 'document', id: docId() };
+                const other = { type: 'document', id: docId() };
+                const p = partition();
+                const can = () => state.manager.check(u, 'viewer', doc, p);
+                const census = () => tx.census(p);
+                // Una transacción que se queda abierta tras una aserción fallida
+                // retiene una conexión del pool y arrastra a los casos siguientes:
+                // el rollback va en `finally`, y el commit solo si nada falló.
+                const rolledBack = async (fn) => {
+                    const t = await tx.begin();
+                    try {
+                        await fn(t.client);
+                    }
+                    finally {
+                        await t.rollback();
+                    }
+                };
+                const committed = async (fn) => {
+                    const t = await tx.begin();
+                    try {
+                        await fn(t.client);
+                    }
+                    catch (error) {
+                        await t.rollback();
+                        throw error;
+                    }
+                    await t.commit();
+                };
+                // relate: dentro no se ve desde fuera; rollback ⇒ nada; commit ⇒ concede.
+                let seenInside;
+                await rolledBack(async (transaction) => {
+                    await state.manager.relate(u, 'viewer', doc, p, { transaction });
+                    seenInside = await can();
+                });
+                assert.equal(await census(), 0, 'ROJO: la relación sobrevivió al rollback (la escritura NO fue por la transacción del llamante)');
+                assert.isFalse(await can(), 'relate + rollback ⇒ no concede');
+                assert.isFalse(seenInside, 'la autoridad lee por la conexión del motor: el relate sin confirmar no concede');
+                await committed(async (transaction) => {
+                    await state.manager.relate(u, 'viewer', doc, p, { transaction });
+                });
+                assert.isTrue(await can(), 'relate + commit ⇒ concede');
+                assert.equal(await census(), 1);
+                // unrelate: rollback ⇒ la tupla sigue; commit ⇒ se va.
+                await rolledBack(async (transaction) => {
+                    await state.manager.unrelate(u, 'viewer', doc, p, { transaction });
+                    seenInside = await can();
+                });
+                assert.equal(await census(), 1, 'ROJO: el unrelate sobrevivió al rollback');
+                assert.isTrue(await can(), 'unrelate + rollback ⇒ sigue concediendo');
+                assert.isTrue(seenInside, 'el unrelate sin confirmar no se ve desde la conexión del motor');
+                await committed(async (transaction) => {
+                    await state.manager.unrelate(u, 'viewer', doc, p, { transaction });
+                });
+                assert.isFalse(await can(), 'unrelate + commit ⇒ no concede');
+                assert.equal(await census(), 0);
+                // purgeObject: dos sujetos sobre `doc` + uno sobre `other`; rollback ⇒
+                // los tres siguen (borran y revierten JUNTOS); commit ⇒ quedan solo
+                // los de `other`.
+                await state.manager.relate(u, 'viewer', doc, p);
+                await state.manager.relate(v, 'editor', doc, p);
+                await state.manager.relate(u, 'owner', other, p);
+                assert.equal(await census(), 3);
+                await rolledBack(async (transaction) => {
+                    await state.manager.purgeObject(doc, p, { transaction });
+                    seenInside = await can();
+                });
+                assert.equal(await census(), 3, 'ROJO: purgeObject sobrevivió al rollback (algo de lo purgado no volvió)');
+                assert.isTrue(await can(), 'purgeObject + rollback ⇒ sigue concediendo');
+                assert.isTrue(await state.manager.check(v, 'viewer', doc, p));
+                assert.isTrue(seenInside, 'el purgeObject sin confirmar no se ve desde la conexión del motor');
+                await committed(async (transaction) => {
+                    await state.manager.purgeObject(doc, p, { transaction });
+                });
+                assert.equal(await census(), 1, 'purgeObject + commit ⇒ solo queda la tupla de `other`');
+                assert.isFalse(await can());
+                assert.isFalse(await state.manager.check(v, 'viewer', doc, p));
+                assert.isTrue(await state.manager.check(u, 'owner', other, p));
+                // purgeSubject: `u` es owner de `other` y viewer de `doc` de nuevo;
+                // rollback ⇒ las dos siguen; commit ⇒ las dos se van y `v` no se toca.
+                await state.manager.relate(u, 'viewer', doc, p);
+                await state.manager.relate(v, 'viewer', doc, p);
+                assert.equal(await census(), 3);
+                await rolledBack(async (transaction) => {
+                    await state.manager.purgeSubject(u, p, { transaction });
+                    seenInside = await can();
+                });
+                assert.equal(await census(), 3, 'ROJO: purgeSubject sobrevivió al rollback');
+                assert.isTrue(await can(), 'purgeSubject + rollback ⇒ sigue concediendo');
+                assert.isTrue(await state.manager.check(u, 'owner', other, p));
+                assert.isTrue(seenInside, 'el purgeSubject sin confirmar no se ve desde la conexión del motor');
+                await committed(async (transaction) => {
+                    await state.manager.purgeSubject(u, p, { transaction });
+                });
+                assert.equal(await census(), 1, 'purgeSubject + commit ⇒ solo queda la tupla de `v`');
+                assert.isFalse(await can());
+                assert.isFalse(await state.manager.check(u, 'owner', other, p));
+                assert.isTrue(await state.manager.check(v, 'viewer', doc, p));
+                // Una transacción que NO es la del driver (`assertCallerTransaction`):
+                // 500 `E_AUTHZ_CONFIG` y ni una sentencia por ella (espía).
+                const statements = [];
+                const spyTrx = (shape) => new Proxy(shape, {
+                    get(target, prop) {
+                        if (prop === 'from' || prop === 'table' || prop === 'raw' || prop === 'query' || prop === 'knexQuery' || prop === 'rawQuery' || prop === 'transaction') {
+                            return (...args) => {
+                                statements.push(`${String(prop)}(${String(args[0] ?? '')})`);
+                                return { where: () => ({}), select: async () => [], insert: async () => [], delete: async () => 0 };
+                            };
+                        }
+                        return Reflect.get(target, prop);
+                    },
+                });
+                const foreign = spyTrx({ isTransaction: true, connectionName: `not-${harness.name}-${uuidv7()}` });
+                const notATransaction = spyTrx({ isTransaction: false, connectionName: 'primary' });
+                const wholeDb = spyTrx({ connection() { }, primaryConnectionName: 'primary' });
+                const w = holder();
+                const writesBefore = state.writes();
+                for (const [label, transaction] of [
+                    ['otra conexión', foreign],
+                    ['un cliente sin transacción', notATransaction],
+                    ['el db entero', wholeDb],
+                ]) {
+                    for (const [operation, run] of [
+                        ['relate', () => state.manager.relate(w, 'viewer', doc, p, { transaction })],
+                        ['unrelate', () => state.manager.unrelate(w, 'viewer', doc, p, { transaction })],
+                        ['purgeObject', () => state.manager.purgeObject(doc, p, { transaction })],
+                        ['purgeSubject', () => state.manager.purgeSubject(w, p, { transaction })],
+                    ]) {
+                        let caught;
+                        try {
+                            await run();
+                            assert.fail(`${label}/${operation}: debería haber lanzado`);
+                        }
+                        catch (error) {
+                            caught = error;
+                        }
+                        assert.equal(caught.status, 500, `${label}/${operation}: ${caught.message}`);
+                        assert.equal(caught.code, 'E_AUTHZ_CONFIG', `${label}/${operation}`);
+                        assert.include(caught.message, operation, `${label}/${operation}: nombra la operación`);
+                    }
+                }
+                assert.deepEqual(statements, [], 'ni una sentencia por una transacción que no es la del driver');
+                assert.isAbove(state.writes(), writesBefore, 'la trx ajena la juzga el DRIVER (assertCallerTransaction), no la puerta 1');
+                assert.equal(await census(), 1, 'la trx ajena no escribió nada');
+                assert.isFalse(await state.manager.check(w, 'viewer', doc, p));
+            })?.timeout(30_000),
+            whenFalse: () => test('transactionalWrites:false · { transaction } en relate/unrelate/purgeObject/purgeSubject ⇒ 500 E_AUTHZ_UNSUPPORTED nombrando driver y operación, con CERO llamadas al driver (espía); y requireTransactionalWrites: true ⇒ 500 E_AUTHZ_CONFIG al construir el manager (= al resolver el driver)', async ({ assert, }) => {
+                assert.notEqual(state.base.capabilities?.transactionalWrites, true, 'el harness declara transactionalWrites: false y el driver declara true: declara lo observable');
+                const trx = { from() { }, table() { }, isTransaction: true, connectionName: 'primary' };
+                const u = holder();
+                const doc = { type: 'document', id: docId() };
+                const p = partition();
+                const writes = [
+                    ['relate', () => state.manager.relate(u, 'viewer', doc, p, { transaction: trx })],
+                    ['unrelate', () => state.manager.unrelate(u, 'viewer', doc, p, { transaction: trx })],
+                    ['purgeObject', () => state.manager.purgeObject(doc, p, { transaction: trx })],
+                    ['purgeSubject', () => state.manager.purgeSubject(u, p, { transaction: trx })],
+                ];
+                for (const [operation, run] of writes) {
+                    let caught;
+                    try {
+                        await run();
+                        assert.fail(`${operation}: debería haber lanzado`);
+                    }
+                    catch (error) {
+                        caught = error;
+                    }
+                    assert.equal(caught.status, 500, `${operation}: ${caught.message}`);
+                    assert.equal(caught.code, 'E_AUTHZ_UNSUPPORTED', operation);
+                    assert.include(caught.message, `'${harness.name}'`, `${operation}: nombra el driver`);
+                    assert.include(caught.message, operation, `${operation}: nombra la operación`);
+                    assert.include(caught.message, 'requireTransactionalWrites', `${operation}: la letra lleva la salida`);
+                }
+                assert.equal(state.writes(), 0, 'cero llamadas al driver: el rechazo va ANTES del backend');
+                // Sin `{ transaction }` la MISMA escritura entra.
+                await state.manager.relate(u, 'viewer', doc, p);
+                assert.isTrue(await state.manager.check(u, 'viewer', doc, p));
+                assert.equal(state.writes(), 1);
+                // Puerta 2, opt-in: al construir el manager (= resolver el driver).
+                let atResolve;
+                try {
+                    new RelationsManager(state.base, contractRelationsConfig(), {
+                        requireTransactionalWrites: true,
+                        driverName: harness.name,
+                    });
+                    assert.fail('requireTransactionalWrites: true sobre un driver que declara false tenía que lanzar al construir');
+                }
+                catch (error) {
+                    atResolve = error;
+                }
+                assert.equal(atResolve.status, 500, String(atResolve?.message));
+                assert.equal(atResolve.code, 'E_AUTHZ_CONFIG');
+                assert.include(atResolve.message, `'${harness.name}'`);
+                assert.include(atResolve.message, 'transactionalWrites');
+            }),
+        });
         // Al cerrar: toda capacidad declarada tiene que haber registrado su cara.
         group.teardown(async () => {
             const uncovered = Object.keys(harness.capabilities).filter((c) => !covered.has(c));