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

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

@@ -1,6 +1,6 @@
 import '@japa/assert';
 import type { Assert } from '@japa/assert';
-import type { AuthorizationDriver, CatalogSpec } from '../types.js';
+import type { AuthorizationDriver, CatalogSpec, SubjectRef } from '../types.js';
 import type { ContractScopeTree } from './scope_tree.js';
 /**
  * Suite de contrato del sistema de autorización — EL JUEZ.
@@ -12,7 +12,7 @@ import type { ContractScopeTree } from './scope_tree.js';
  *   runAuthorizationDriverContract({
  *     name: 'mi-driver',
  *     level: '2.0',                      // omitido = 'core': solo los casos de 1.x
- *     capabilities: { hierarchyFacts: false, transactions: false, truncationSignal: false,
+ *     capabilities: { hierarchyFacts: false, transactionalWrites: false, truncationSignal: false,
  *                     singleCheckAuthorize: false, injectableClock: false },
  *     seedCatalog: (catalog) => ...,     // materializa roles/permisos
  *     makeDriver: (tree) => new MiDriver({ resolveChain: ... }), // recibe el árbol
@@ -41,8 +41,29 @@ import type { ContractScopeTree } from './scope_tree.js';
 export interface DriverCapabilities {
     /** El driver materializa el árbol como hechos propios (Fase 3b). */
     hierarchyFacts: boolean;
-    /** Acepta `{ trx }` externa en las escrituras (Fase 2.5). */
-    transactions: boolean;
+    /**
+     * **`{ transaction }` en `grant`/`revoke`/`deny`/`removeDeny` ESCRIBE en
+     * la transacción del consumidor** — «los dos o ninguno con TU transacción»,
+     * nunca «no se pierde» (L-2, panel `{trx}` (C); mismo nombre que
+     * `AuthorizationDriverCapabilities.transactionalWrites` y que su par de
+     * relaciones). Es el ÚNICO par del juez con las DOS caras obligatorias:
+     * `true` sin caso `whenTrue` Y `false` sin caso `whenFalse` hacen que la
+     * suite lance al registrarse (los demás pares solo exigen la cara `true`;
+     * la lección de 4-2 es que una `whenFalse` ausente se salta en silencio).
+     * Con `false` el juez fija que `{ transaction }` es 500 `E_AUTHZ_UNSUPPORTED`
+     * nombrando driver y operación con CERO llamadas al driver (espía), y que
+     * `requireTransactionalWrites: true` lo convierte en 500 `E_AUTHZ_CONFIG`
+     * al RESOLVER. Con `true` (L-3) el juez abre una transacción de la conexión
+     * del driver (`DriverContractHarness.transactions`, default Lucid +
+     * `authz_*`) y fija, para las cuatro escrituras, que **rollback ⇒ CERO
+     * filas por CENSO** (no solo `authorize`), commit ⇒ aplicado, la escritura
+     * sin confirmar invisible para la autoridad, y que una transacción ajena es
+     * 500 `E_AUTHZ_CONFIG` sin una sentencia. `database` declara `true` (con
+     * pool ≥ 2; en `:memory:` el harness del paquete declara `false` porque la
+     * autoridad no tendría por dónde leer); `openfga` no puede ser otra cosa que
+     * `false`: una tupla no entra en una transacción SQL.
+     */
+    transactionalWrites: boolean;
     /**
      * Los `list*` lanzan si el backend trunca. Ningún driver del paquete trunca
      * (L0.7 se cerró enumerando con `Read` paginado), así que no hay caso para
@@ -207,7 +228,31 @@ export interface DriverContractHarness {
      */
     makeTwin?(driver: AuthorizationDriver, tree: ContractScopeTree): AuthorizationDriver | Promise<AuthorizationDriver>;
     cleanup(): Promise<void>;
+    /**
+     * Solo con `transactionalWrites: true` (L-3): cómo abre el juez una
+     * transacción de LA CONEXIÓN DEL DRIVER y cómo cuenta los hechos de un
+     * holder en el backend — el CENSO: el rollback se juzga por filas, no solo
+     * por la respuesta de `authorize` (la lección del contrato de migración).
+     * Default: `db.transaction()` de Lucid (conexión primaria) y
+     * `authz_assignments`/`authz_denies`, lo que vale para el driver `database`.
+     * Un driver de terceros con otra conexión u otras tablas trae el suyo.
+     */
+    transactions?: ContractTransactions;
 }
+/** Ver `DriverContractHarness.transactions`. */
+export interface ContractTransactions {
+    begin(): Promise<{
+        client: unknown;
+        commit(): Promise<unknown>;
+        rollback(): Promise<unknown>;
+    }>;
+    census(subject: SubjectRef): Promise<{
+        assignments: number;
+        denies: number;
+    }>;
+}
+/** El default de `DriverContractHarness.transactions`: Lucid + `authz_*`. */
+export declare function lucidContractTransactions(): ContractTransactions;
 /**
  * Lo mínimo que el juez necesita del runner. En producción es el `test` de
  * Japa; en `tests/contract_harness.spec.ts` es una API falsa que solo anota
@@ -229,4 +274,10 @@ export interface ContractTestApi {
 }
 export declare function runAuthorizationDriverContract(harness: DriverContractHarness): void;
 export declare function registerAuthorizationDriverContract(harness: DriverContractHarness, api: ContractTestApi): void;
+/**
+ * La regla del guard, PURA (para que `contract_harness.spec.ts` la juzgue sin
+ * borrar caras): una capacidad `true` sin caso registrado queda sin cubrir;
+ * y una de `BOTH_FACES_REQUIRED` queda sin cubrir con CUALQUIER valor.
+ */
+export declare function uncoveredCapabilities(capabilities: DriverCapabilities, covered: ReadonlySet<keyof DriverCapabilities>): (keyof DriverCapabilities)[];
 //# sourceMappingURL=contract.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/testing/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/testing/contract.ts"],"names":[],"mappings":"AAAA,OAAO,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAG1C,OAAO,KAAK,EACV,mBAAmB,EAEnB,WAAW,EAIX,UAAU,EACX,MAAM,aAAa,CAAA;AAQpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAA;IACvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,mBAAmB,EAAE,OAAO,CAAA;IAC5B;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAA;IACzB,uEAAuE;IACvE,oBAAoB,EAAE,OAAO,CAAA;IAC7B;;;;;;;OAOG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB;;;;;;;OAOG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;;;;;;;OASG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;OAWG;IACH,oBAAoB,EAAE,OAAO,CAAA;IAC7B;;;;;;;;;;;;;;OAcG;IACH,uBAAuB,EAAE,OAAO,CAAA;IAChC;;;;;;;;;OASG;IACH,qBAAqB,EAAE,OAAO,CAAA;IAC9B;;;;;;;OAOG;IACH,oBAAoB,EAAE,OAAO,CAAA;IAC7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,mBAAmB,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;;;;;;OAeG;IACH,cAAc,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;AAE1D,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,kLAAkL;IAClL,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,kBAAkB,CAAA;IAChC,wFAAwF;IACxF,MAAM,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACvC,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACvF;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACnH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAA;CACpC;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,KAAK,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QAAC,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC,CAAA;IAC/F,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC9E;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,IAAI,oBAAoB,CAkBhE;AAoPD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CACH,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,KAAK,EAAE;QACd,IAAI,EAAE;YAAE,KAAK,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;SAAE,CAAA;QACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;KAC3C,KAAK,IAAI,GACT,OAAO,CAAA;IACV,IAAI,CACF,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC7C;QAAE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI,CAAA;CACvD;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,qBAAqB,QAK5E;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,eAAe,QAsiIrB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,kBAAkB,EAChC,OAAO,EAAE,WAAW,CAAC,MAAM,kBAAkB,CAAC,GAC7C,CAAC,MAAM,kBAAkB,CAAC,EAAE,CAI9B"}

package/build/src/testing/contract.js

@@ -7,6 +7,26 @@ 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';
+/** El default de `DriverContractHarness.transactions`: Lucid + `authz_*`. */
+export function lucidContractTransactions() {
+    const count = async (table, subject) => {
+        const rows = await db
+            .from(table)
+            .where('holder_type', subject.type)
+            .where('holder_uuid', subject.uuid)
+            .count('* as n');
+        return Number(rows[0]?.n ?? 0);
+    };
+    return {
+        async begin() {
+            const trx = await db.transaction();
+            return { client: trx, commit: () => trx.commit(), rollback: () => trx.rollback() };
+        },
+        async census(subject) {
+            return { assignments: await count('authz_assignments', subject), denies: await count('authz_denies', subject) };
+        },
+    };
+}
 /**
  * Catálogo de prueba: roles a nivel app y a nivel organization. Los dos
  * últimos existen solo para el invariante 8: `rank` es metadata y el motor no
@@ -1689,8 +1709,9 @@ export function registerAuthorizationDriverContract(harness, api) {
             }
         });
         // ── Concurrencia (2.5 · J4) ──────────────────────────────────────────
-        // Sin `{trx}` en el puerto (`transactions: false` sigue; es el diferido
-        // 2.6): lo que se fija es que dos escrituras solapadas nunca dejan un
+        // Sin `{trx}` en estos casos (la escritura en la transacción del
+        // llamante tiene su par, `transactionalWrites`, abajo): lo que se fija
+        // es que dos escrituras solapadas nunca dejan un
         // estado que ninguna de las dos habría dejado sola. Con el harness en
         // memoria (pool 1) se solapan a nivel de consulta; con `sqlite-file`, PG
         // y MySQL (pool ≥ 2) a nivel de conexión.
@@ -3255,9 +3276,201 @@ export function registerAuthorizationDriverContract(harness, api) {
         // `hierarchyFacts: false` → lo observan N1b/N2/N4/N5 (arriba): el driver
         // responde según el árbol que le resuelve el consumidor, y `tree.move`
         // cambia la respuesta sin escritura. `true` llega en Fase 3b.
-        // `injectableClock` tiene su par arriba (2.5 · J1). `transactions` (2.6)
-        // y `singleCheckAuthorize` (Fase 3b): pares en su fase; hoy solo pueden
-        // declararse `false`.
+        // `injectableClock` tiene su par arriba (2.5 · J1). `transactionalWrites`
+        // (L-2) tiene su par al final: la cara `false` hoy, la `true` con L-3.
+        // ── L-2 · `transactionalWrites` (panel `{trx}`, (C)) ──────────────────
+        // Las DOS caras son obligatorias en este par (`BOTH_FACES_REQUIRED`): una
+        // `whenFalse` ausente se saltaba en silencio y «rechazo activo» sería
+        // una etiqueta. Lo que la cara `false` fija es la PUERTA 1 (por llamada,
+        // siempre activa) y la PUERTA 2 (por config, opt-in), las dos con el
+        // manager construido sobre el driver del harness, en TODOS los niveles:
+        // son composición del manager sobre `driver.capabilities`, así que un
+        // driver de terceros de nivel `core` también las observa.
+        caseFor('transactionalWrites', {
+            // L-3: la cara `true`. Lo que se juzga es «los dos o ninguno con TU
+            // transacción» POR CENSO: el rollback deja CERO filas nuevas (no solo
+            // `authorize` false — una respuesta puede salir bien con la fila viva),
+            // el commit las deja escritas, y mientras la transacción está abierta
+            // la autoridad (que lee por la conexión del motor) no ve nada. Y la
+            // otra mitad de la regla: una transacción que NO es la del driver no
+            // recibe ni una sentencia. Cuatro escrituras, las dos caras cada una.
+            whenTrue: () => {
+                test('transactionalWrites: true · grant/revoke/deny/removeDeny con { transaction } + rollback ⇒ authorize sin cambio Y CERO filas (censo); + commit ⇒ aplicado; 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(driver.capabilities?.transactionalWrites, true, 'el harness declara transactionalWrites: true y el driver no: declara lo observable');
+                    const tx = harness.transactions ?? lucidContractTransactions();
+                    const alice = subject();
+                    const org = await orgUnder(tree, APP_SCOPE);
+                    const authz = managerOver({});
+                    const can = () => driver.authorize(alice, 'docs:read', org);
+                    const census = () => tx.census(alice);
+                    // 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();
+                    };
+                    // grant: dentro no se ve desde fuera; rollback ⇒ nada; commit ⇒ concede.
+                    let seenInside;
+                    await rolledBack(async (transaction) => {
+                        await authz.grant(alice, 'org-editor', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 0, denies: 0 }, 'ROJO: la asignación sobrevivió al rollback (la escritura NO fue por la transacción del llamante)');
+                    assert.isFalse(await can(), 'grant + rollback ⇒ no concede');
+                    assert.isFalse(seenInside, 'la autoridad lee por la conexión del motor: el grant sin confirmar no concede');
+                    await committed(async (transaction) => {
+                        await authz.grant(alice, 'org-editor', org, { transaction });
+                    });
+                    assert.isTrue(await can(), 'grant + commit ⇒ concede');
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 });
+                    // revoke: rollback ⇒ la asignación sigue; commit ⇒ se va.
+                    await rolledBack(async (transaction) => {
+                        await authz.revoke(alice, 'org-editor', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 }, 'ROJO: el revoke sobrevivió al rollback');
+                    assert.isTrue(await can(), 'revoke + rollback ⇒ sigue concediendo');
+                    assert.isTrue(seenInside, 'el revoke sin confirmar no se ve desde la conexión del motor');
+                    await committed(async (transaction) => {
+                        await authz.revoke(alice, 'org-editor', org, { transaction });
+                    });
+                    assert.isFalse(await can(), 'revoke + commit ⇒ no concede');
+                    assert.deepEqual(await census(), { assignments: 0, denies: 0 });
+                    // deny (sobre un grant confirmado): rollback ⇒ sigue concediendo; commit ⇒ deniega.
+                    await authz.grant(alice, 'org-editor', org);
+                    await rolledBack(async (transaction) => {
+                        await authz.deny(alice, 'docs:read', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 }, 'ROJO: el deny sobrevivió al rollback');
+                    assert.isTrue(await can(), 'deny + rollback ⇒ sigue concediendo');
+                    assert.isTrue(seenInside, 'el deny sin confirmar no se ve desde la conexión del motor');
+                    await committed(async (transaction) => {
+                        await authz.deny(alice, 'docs:read', org, { transaction });
+                    });
+                    assert.isFalse(await can(), 'deny + commit ⇒ deniega');
+                    assert.deepEqual(await census(), { assignments: 1, denies: 1 });
+                    // removeDeny: rollback ⇒ el deny sigue; commit ⇒ restaura.
+                    await rolledBack(async (transaction) => {
+                        await authz.removeDeny(alice, 'docs:read', org, { transaction });
+                        seenInside = await can();
+                    });
+                    assert.deepEqual(await census(), { assignments: 1, denies: 1 }, 'ROJO: el removeDeny sobrevivió al rollback');
+                    assert.isFalse(await can(), 'removeDeny + rollback ⇒ sigue denegando');
+                    assert.isFalse(seenInside, 'el removeDeny sin confirmar no se ve desde la conexión del motor');
+                    await committed(async (transaction) => {
+                        await authz.removeDeny(alice, 'docs:read', org, { transaction });
+                    });
+                    assert.isTrue(await can(), 'removeDeny + commit ⇒ restaura');
+                    assert.deepEqual(await census(), { assignments: 1, denies: 0 });
+                    // 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 spy = (shape) => new Proxy(shape, {
+                        get(target, prop) {
+                            if (prop === 'from' || prop === 'table' || prop === 'raw' || prop === 'query' || prop === 'knexQuery') {
+                                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 = spy({ isTransaction: true, connectionName: `not-${harness.name}-${uuidv7()}` });
+                    const notATransaction = spy({ isTransaction: false, connectionName: 'primary' });
+                    const wholeDb = spy({ connection() { }, primaryConnectionName: 'primary' });
+                    const bob = subject();
+                    for (const [label, transaction] of [
+                        ['otra conexión', foreign],
+                        ['un cliente sin transacción', notATransaction],
+                        ['el db entero', wholeDb],
+                    ]) {
+                        for (const [operation, run] of [
+                            ['grant', () => authz.grant(bob, 'org-editor', org, { transaction })],
+                            ['revoke', () => authz.revoke(bob, 'org-editor', org, { transaction })],
+                            ['deny', () => authz.deny(bob, 'docs:read', org, { transaction })],
+                            ['removeDeny', () => authz.removeDeny(bob, 'docs:read', org, { transaction })],
+                        ]) {
+                            const error = await rejectsWith(assert, run, { status: 500, code: 'E_AUTHZ_CONFIG' });
+                            assert.include(error.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.deepEqual(await tx.census(bob), { assignments: 0, denies: 0 });
+                    assert.isFalse(await driver.authorize(bob, 'docs:read', org));
+                })?.timeout(30_000);
+            },
+            whenFalse: () => {
+                test('transactionalWrites: false · { transaction } en grant/revoke/deny/removeDeny es 500 E_AUTHZ_UNSUPPORTED nombrando driver y operación, con CERO llamadas al driver (espía); y requireTransactionalWrites: true ⇒ 500 E_AUTHZ_CONFIG al RESOLVER el driver', async ({ assert, }) => {
+                    // El harness declara `false`: el driver tiene que decir lo mismo
+                    // (el manager lee `driver.capabilities`, no el harness).
+                    assert.notEqual(driver.capabilities?.transactionalWrites, true, 'el harness declara transactionalWrites: false y el driver declara true: declara lo observable');
+                    const touched = [];
+                    const spied = new Proxy(driver, {
+                        get(target, prop, receiver) {
+                            const value = Reflect.get(target, prop, receiver);
+                            if (typeof value === 'function' && typeof prop === 'string') {
+                                return (...args) => {
+                                    touched.push(prop);
+                                    return value.apply(receiver, args);
+                                };
+                            }
+                            return value;
+                        },
+                    });
+                    // La forma de un `TransactionClientContract` de Lucid: la puerta
+                    // decide por la CAPACIDAD, antes de mirar qué transacción es.
+                    const trx = { from() { }, table() { }, isTransaction: true, connectionName: 'primary' };
+                    const alice = subject();
+                    const org = await orgUnder(tree, APP_SCOPE);
+                    const authz = managerOver({}, spied);
+                    const writes = [
+                        ['grant', () => authz.grant(alice, 'org-editor', org, { transaction: trx })],
+                        ['revoke', () => authz.revoke(alice, 'org-editor', org, { transaction: trx })],
+                        ['deny', () => authz.deny(alice, 'docs:read', org, { transaction: trx })],
+                        ['removeDeny', () => authz.removeDeny(alice, 'docs:read', org, { transaction: trx })],
+                    ];
+                    for (const [operation, run] of writes) {
+                        const error = await rejectsWith(assert, run, { status: 500, code: 'E_AUTHZ_UNSUPPORTED' });
+                        assert.include(error.message, `'${harness.name}'`, `${operation}: nombra el driver`);
+                        assert.include(error.message, operation, `${operation}: nombra la operación`);
+                        assert.include(error.message, 'requireTransactionalWrites', `${operation}: la letra lleva la salida`);
+                    }
+                    assert.deepEqual(touched, [], 'cero llamadas al driver: el rechazo va ANTES del backend');
+                    // Sin `{ transaction }` la MISMA escritura entra: la puerta es del
+                    // parámetro, no del driver.
+                    await authz.grant(alice, 'org-editor', org);
+                    assert.isTrue(await driver.authorize(alice, 'docs:read', org));
+                    assert.include(touched, 'grant');
+                    // Puerta 2, opt-in: quien quiera fallar al ARRANCAR lo pide, y
+                    // entonces el driver ni se resuelve (tampoco para leer).
+                    const strict = managerOver({ requireTransactionalWrites: true }, spied);
+                    const atResolve = await rejectsWith(assert, () => strict.driver(), { status: 500, code: 'E_AUTHZ_CONFIG' });
+                    assert.include(atResolve.message, `'${harness.name}'`);
+                    assert.include(atResolve.message, 'transactionalWrites');
+                    await rejectsWith(assert, () => strict.authorize(alice, 'docs:read', org), { status: 500, code: 'E_AUTHZ_CONFIG' });
+                    await rejectsWith(assert, () => strict.grant(alice, 'org-editor', org), { status: 500, code: 'E_AUTHZ_CONFIG' });
+                });
+            },
+        });
         // ── 3b-2e · E6 · `singleCheckAuthorize` ──────────────────────────────
         caseFor('singleCheckAuthorize', {
             whenTrue: () => {
@@ -3626,11 +3839,30 @@ export function registerAuthorizationDriverContract(harness, api) {
         });
     });
     // Al cerrar el grupo: toda capacidad declarada `true` tiene que haber
-    // registrado su par. Es la regla "jamás un skip" hecha ejecutable.
-    const uncovered = Object.keys(harness.capabilities).filter((capability) => harness.capabilities[capability] && !covered.has(capability));
+    // registrado su par — y las de `BOTH_FACES_REQUIRED`, también con `false`.
+    // Es la regla "jamás un skip" hecha ejecutable.
+    const uncovered = uncoveredCapabilities(harness.capabilities, covered);
     if (uncovered.length) {
-        throw new Error(`[contrato ${harness.name}] declara ${uncovered.map((c) => `'${c}: true'`).join(', ')} ` +
+        throw new Error(`[contrato ${harness.name}] declara ${uncovered.map((c) => `'${c}: ${String(harness.capabilities[c])}'`).join(', ')} ` +
             `pero el contrato no tiene caso para ese valor todavía. Declara lo observable hoy.`);
     }
 }
+/**
+ * La regla del guard, PURA (para que `contract_harness.spec.ts` la juzgue sin
+ * borrar caras): una capacidad `true` sin caso registrado queda sin cubrir;
+ * y una de `BOTH_FACES_REQUIRED` queda sin cubrir con CUALQUIER valor.
+ */
+export function uncoveredCapabilities(capabilities, covered) {
+    return Object.keys(capabilities).filter((capability) => (capabilities[capability] || BOTH_FACES_REQUIRED.has(capability)) && !covered.has(capability));
+}
+/**
+ * Capacidades cuyas DOS caras son obligatorias (L-2): declarar `false` sin
+ * un caso `whenFalse` registrado lanza igual que declarar `true` sin
+ * `whenTrue`. El guard general solo obliga a la cara `true` porque los pares
+ * de nivel (`listDenies`, `purgeRole`…) no registran nada en un harness
+ * `core` y `false` ahí es legítimo; `transactionalWrites` es composición del
+ * manager y se observa en todos los niveles, así que su `false` sin caso es
+ * un skip disfrazado — «rechazo activo» sería una etiqueta.
+ */
+const BOTH_FACES_REQUIRED = new Set(['transactionalWrites']);
 //# sourceMappingURL=contract.js.map