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

package/build/src/drivers/database_relations_driver.js

@@ -3,14 +3,20 @@
  * (Fase 4, lote 4-3).
  *
  * Los hechos de relación viven en la tabla `authz_relations` (una fila por
- * tupla, INSERT/DELETE-ONLY, decisión (c) del dueño): NO hay `expires_at` y no
- * hay «renovar = delete+insert» (la caducidad de relaciones —R-15— quedó FUERA
- * de la 2.4, default del dueño). La resolución de `check`/`membersOf`/
- * `listObjects` —includes de un nivel y usersets de grupos anidados— es una
- * **CTE recursiva por dialecto** (mismo patrón que `sql_descendants.ts`), y el
- * cruce de particiones lo defiende, además, el trigger `relationPartitionTrigger`
- * (defensa en profundidad para el escritor «a mano»; el corte primario es la
- * columna `partition_key` en cada consulta).
+ * tupla, INSERT/DELETE-ONLY, decisión (c) del dueño). **La caducidad (R-15,
+ * 2.4.0-alpha.2)** es la columna `expires_at` (NULL = no caduca), con los
+ * MISMOS tres estados de `expiresAt` que `grant` (invariante 10), caducidad
+ * ESTRICTA (`expires_at > now`, la que vence ahora ya no cuenta), el MISMO
+ * codec por dialecto que `authz_assignments` (`sqlExpiryCodec`, 2.5-B · K2) y
+ * el reloj inyectable `withClock` (2.5 · J1). **Renovar la caducidad es
+ * delete+insert, nunca UPDATE** (decisión (c) del juez: un solo trigger por
+ * evento, menos superficie de divergencia de motor; observable: la fila cambia
+ * de `uuid`). La resolución de `check`/`membersOf`/`listObjects` —includes de
+ * un nivel y usersets de grupos anidados— es una **CTE recursiva por dialecto**
+ * (mismo patrón que `sql_descendants.ts`) que solo recorre hechos VIGENTES, y
+ * el cruce de particiones lo defiende, además, el trigger
+ * `relationPartitionTrigger` (defensa en profundidad para el escritor «a mano»;
+ * el corte primario es la columna `partition_key` en cada consulta).
  *
  * Pureza: este módulo vive en `drivers/` y NO importa `openfga` (regla 3 de
  * `check_purity.mjs`) ni el `manager`. Consume solo el puerto (`../types.js`),
@@ -19,12 +25,16 @@
  */
 import db from '@adonisjs/lucid/services/db';
 import { v7 as uuidv7 } from 'uuid';
-import { InvalidIdentityError, UnsupportedDialectError } from '../errors.js';
-import { assertScope, assertSubject, scopeKey, scopeSpellings } from '../identity.js';
+import { AuthorizationConfigError, InvalidIdentityError, UnsupportedDialectError, UnsupportedOperationError, WriteConflictError, } from '../errors.js';
+import { assertScope, assertSubject, assertExpiresAt, scopeKey, scopeSpellings } from '../identity.js';
 import { relationPartitionTrigger, relationPartitionTriggerDrops } from '../relation_partition_trigger.js';
-import { systemClock } from '../clock.js';
-import { guardSql } from '../shared/backend_guard.js';
+import { isClock, systemClock } from '../clock.js';
+import { resolveGrantExpiry, sameInstant } from '../expiry.js';
+import { sqlExpiryCodec } from '../shared/sql_expiry.js';
+import { guardSql, isDeadlock, isUniqueViolation } from '../shared/backend_guard.js';
+import { assertCallerTransaction } from '../shared/transaction_guard.js';
 import { isRelUserset } from '../types.js';
+import { assertRelationDeclared, assertObjectTypeDeclared } from '../relations/define_relations_config.js';
 const DEFAULT_TIMEOUT_MS = 5_000;
 const RELATIONS_TABLE = 'authz_relations';
 /** Longitud máxima del id de un objeto/holder de relación (columna `varchar(64)`). */
@@ -32,6 +42,15 @@ const RELATION_ID_MAX = 64;
 /** El tipo BUILT-IN portador de usersets (declarado por el generador, no por el consumidor). */
 const GROUP_TYPE = 'group';
 const GROUP_MEMBER = 'member';
+/**
+ * L-4b: lo que lleva `subject_relation` un HOLDER. Cadena vacía y no NULL
+ * porque el UNIQUE `authz_rel_tuple_uq` incluye la columna y NULL ≠ NULL en
+ * los tres motores (con NULL, dos `relate` concurrentes del mismo holder
+ * confirmaban DOS filas). Cadena vacía y no un centinela (`'-'`) porque la
+ * gramática de una relación (`[a-z0-9._-]{1,50}`) no admite la vacía: ningún
+ * userset puede colisionar con ella.
+ */
+const HOLDER_RELATION = '';
 /** Tamaño de página por defecto y tope de `enumerateRelations` (origen de reconcile). */
 const DEFAULT_ENUMERATE_LIMIT = 100;
 const MAX_ENUMERATE_LIMIT = 1_000;
@@ -67,32 +86,81 @@ export class DatabaseRelationsDriver {
      *    paginados por la PK, sin filtrar ni derivar (invariante 7 + higiene de
      *    reconcile): la caña la ve el destino tal cual la escribió el origen.
      *  - `listObjectsTruncation: false`: sin tope de servidor, `listObjects` es exhaustiva.
+     *  - `injectableClock: true` (R-15): `withClock(now)` fija el reloj que decide
+     *    la caducidad (`expires_at > now`), como el driver `database` de roles.
+     *  - `transactionalWrites: true` (L-4, default): las cuatro escrituras van
+     *    por la transacción ABIERTA del llamante (`#writer()`,
+     *    `assertCallerTransaction` contra la conexión de este driver). Lo que
+     *    NO viaja por ella: la barrera del freeze y F-05 (autoridad). Un
+     *    despliegue con pool 1 lo declara `false` (ver las opciones).
      */
-    capabilities = Object.freeze({
-        singleCheckRelations: true,
-        listObjectsInherited: false,
-        usersetSubjects: true,
-        membersOfNative: true,
-        enumerateRelations: true,
-        listObjectsTruncation: false,
-    });
+    capabilities;
+    /**
+     * Con `transactionalWrites: false` declarado por el despliegue, un
+     * `{ transaction }` que llegara igual (un llamante que se salta el manager)
+     * se rechaza aquí también: no se ignora en silencio.
+     */
+    #transactionalWrites;
     #config;
     #connectionName;
     #timeoutMs;
     #now;
     /** Inyectable para probar el dialecto ajeno sin servidor. */
     #database;
+    #expiryCodec;
     constructor(config, options = {}, database = db) {
         this.#config = config;
         this.#connectionName = options.connection;
         this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.#now = options.now ?? systemClock;
         this.#database = database;
+        this.#transactionalWrites = options.transactionalWrites ?? true;
+        this.capabilities = Object.freeze({
+            singleCheckRelations: true,
+            listObjectsInherited: false,
+            usersetSubjects: true,
+            membersOfNative: true,
+            enumerateRelations: true,
+            listObjectsTruncation: false,
+            injectableClock: true,
+            transactionalWrites: this.#transactionalWrites,
+        });
+    }
+    /**
+     * Vista de este driver con OTRO reloj de pared (R-15, paridad con
+     * `AuthorizationDriver.withClock`): misma conexión, config y deadline; solo
+     * cambia el `now` que decide la caducidad. El driver no tiene estado propio
+     * (la conexión es del servicio `db`), así que la vista es una instancia nueva.
+     */
+    withClock(now) {
+        if (!isClock(now)) {
+            throw new AuthorizationConfigError(`withClock: now debe ser una función () => Date (llegó ${typeof now})`);
+        }
+        return new DatabaseRelationsDriver(this.#config, { connection: this.#connectionName, timeoutMs: this.#timeoutMs, now, transactionalWrites: this.#transactionalWrites }, this.#database);
     }
     /* ── Infraestructura ──────────────────────────────────────────────────── */
     #connection() {
         return this.#database.connection(this.#connectionName);
     }
+    /** El codec de `expires_at` por dialecto (K2): se decide una vez por driver, sin consulta. */
+    get #expiry() {
+        this.#expiryCodec ??= sqlExpiryCodec(this.#connection());
+        return this.#expiryCodec;
+    }
+    /**
+     * El predicado SQL de VIGENCIA (R-15, caducidad ESTRICTA): sin caducidad o
+     * con caducidad FUTURA — la que vence en `now` ya no cuenta. Para el SQL
+     * crudo de las CTEs (`q` cita el identificador; la binding es `bind(now)`
+     * del codec, con UN solo `now` por operación, 2.5-B · K9).
+     */
+    #activeSql(q, alias) {
+        return `(${alias}.${q('expires_at')} IS NULL OR ${alias}.${q('expires_at')} > ?)`;
+    }
+    /** El mismo predicado, para el query builder. */
+    #whereActive(query, at) {
+        const bound = this.#expiry.bind(at);
+        return query.where((b) => b.whereNull('expires_at').orWhere('expires_at', '>', bound));
+    }
     #dialectMeta() {
         const connection = this.#connection();
         const name = connection?.dialect?.name ?? connection?.client?.driverName ?? 'desconocido';
@@ -110,8 +178,67 @@ export class DatabaseRelationsDriver {
     #raw(operation, text, bindings) {
         return this.#sql(operation, () => this.#connection().rawQuery(text, bindings));
     }
+    /** La conexión de quien ESCRIBE: la declarada, o la primaria de Lucid (`undefined` con un `db` doble sin ella). */
+    #ownerConnection() {
+        return this.#connectionName ?? this.#database.primaryConnectionName;
+    }
+    /**
+     * Por dónde escribe `operation` (L-4, el MISMO patrón que `writer()` del
+     * driver de roles, L-3): la transacción ABIERTA del llamante si llegó en
+     * `options.transaction` —validada contra la conexión de ESTE driver por
+     * `assertCallerTransaction`: otra conexión, un `QueryClient` o el `db`
+     * entero son 500 `E_AUTHZ_CONFIG` ANTES de tocar nada—, o la conexión del
+     * driver. `external` dice cuál de los dos.
+     *
+     * Solo la ESCRITURA va por ella (y la lectura «¿ya existe?» de `relate`,
+     * que forma parte de la misma escritura: un `relate` y su renovación en la
+     * misma transacción tienen que verse). La AUTORIDAD no: la barrera del
+     * freeze la lee el `RelationsManager` por la conexión del motor, y F-05 y la
+     * gramática cortan antes de llegar aquí.
+     */
+    #writer(operation, options) {
+        if (options?.transaction === undefined || options.transaction === null) {
+            return { client: this.#connection(), external: false };
+        }
+        if (!this.#transactionalWrites) {
+            throw new UnsupportedOperationError('transactionalWrites', operation, 'database', 'Este despliegue declara transactionalWrites: false en las opciones del driver de relaciones (pool 1): ' +
+                '{ transaction } no se admite. Quita la opción (exige pool ≥ 2) o no pases transaction.');
+        }
+        const trx = assertCallerTransaction(`database-relations.${operation}`, options.transaction, {
+            connection: this.#ownerConnection(),
+        });
+        return { client: trx, external: true };
+    }
+    /**
+     * Una sentencia que falla DENTRO de la transacción del llamante no se
+     * absorbe (L-4, paridad con `poisoned()` de roles): en PostgreSQL la
+     * transacción ya está ABORTADA (toda sentencia posterior es `25P02` hasta
+     * el rollback) y en REPEATABLE READ una relectura no vería al ganador. Así
+     * que un choque del UNIQUE de `authz_relations` (dos `relate` del mismo
+     * hecho en dos transacciones abiertas) y un **deadlock** (dos transacciones
+     * que escriben dos relaciones en orden cruzado: el motor elige una víctima y
+     * la deshace —PG `40P01`, MySQL `1213`—) salen como **409
+     * `E_AUTHZ_WRITE_CONFLICT`** —«envenena tu transacción: haz rollback y
+     * reintenta»—; un deadline vencido sigue siendo el 503
+     * `E_AUTHZ_BACKEND_TIMEOUT` que ya clasificó `#sql`, y cualquier otro fallo,
+     * su 503. Nunca una segunda sentencia sobre una transacción que puede estar
+     * abortada. (Medido por motor en `tests/relations_database.spec.ts`.)
+     */
+    #poisoned(operation, error) {
+        if (isUniqueViolation(error)) {
+            throw new WriteConflictError(`database-relations.${operation}: la tupla la escribió otra transacción mientras la tuya estaba abierta ` +
+                '(choque del UNIQUE dentro de tu transacción). No se puede absorber ahí dentro: la transacción queda ' +
+                'envenenada (en PostgreSQL, abortada). Haz rollback y reintenta.', { cause: error });
+        }
+        if (isDeadlock(error)) {
+            throw new WriteConflictError(`database-relations.${operation}: el motor detectó un DEADLOCK con otra transacción y eligió la tuya ` +
+                'como víctima (dos transacciones escribiendo las mismas tuplas en orden cruzado). La transacción queda ' +
+                'envenenada (PostgreSQL la aborta; MySQL la deshace entera). Haz rollback y reintenta.', { cause: error });
+        }
+        throw error;
+    }
     /* ── Validación de identidad (defensa en profundidad) ─────────────────── */
-    /** El objeto es `{ type, id }` bien formado (el `type` ya pasó F-05 en el manager). */
+    /** El objeto es `{ type, id }` bien formado (F-05 —tipo/relación declarados— la aplica `assertRelationDeclared` en las SIETE operaciones: L-0 en `relate`/`unrelate`, alpha.3 en purgas y lecturas). */
     #assertObject(object) {
         if (!object || typeof object !== 'object') {
             throw new InvalidIdentityError(`Objeto de relación inválido: llegó ${typeof object}`);
@@ -125,9 +252,17 @@ export class DatabaseRelationsDriver {
                 `(llegó ${JSON.stringify(value)})`);
         }
     }
-    /** Valida el sujeto (holder o userset) y devuelve sus columnas. */
+    /**
+     * Valida el sujeto (holder o userset) y devuelve sus columnas. L-4b: el
+     * holder lleva `relation: ''` (NUNCA NULL): es lo que hace que el UNIQUE
+     * `authz_rel_tuple_uq` lo defienda (`'' = ''`, mientras que NULL ≠ NULL).
+     */
     #subjectColumns(subject, partitionKey) {
         if (isRelUserset(subject)) {
+            // alpha.3 · F-05 también en el USERSET del sujeto (la misma función que
+            // el manager): `{ object: { type: 'role_binding' }, relation: 'role' }`
+            // como sujeto de una purga/lectura no toca ni nombra un binding real.
+            assertRelationDeclared(this.#config, subject.object, subject.relation);
             this.#assertObject(subject.object);
             this.#assertId(`la relación del userset '${subject.object.type}'`, subject.relation, RELATION_ID_MAX);
             // El userset comparte la partición de la tupla (el manager así lo exige);
@@ -135,7 +270,21 @@ export class DatabaseRelationsDriver {
             return { type: subject.object.type, uuid: subject.object.id, relation: subject.relation, partition: partitionKey };
         }
         assertSubject(subject);
-        return { type: subject.type, uuid: subject.uuid, relation: null, partition: null };
+        return { type: subject.type, uuid: subject.uuid, relation: HOLDER_RELATION, partition: null };
+    }
+    /**
+     * El WHERE por `subject_relation`. Para un userset, su relación exacta. Para
+     * un HOLDER (`''`), **tolerante a NULL**: una fila vieja con NULL (alpha.1
+     * sin el backfill de L-4b) sigue siendo el mismo hecho, y si `unrelate`/
+     * `purgeSubject` no la vieran seguiría concediendo tras retirarla
+     * (fail-open); el «¿ya existe?» de `relate` también la encuentra, así que
+     * renovar su caducidad la sustituye por una fila con `''`.
+     */
+    #whereSubjectRelation(b, relation) {
+        if (relation === HOLDER_RELATION)
+            b.where('subject_relation', HOLDER_RELATION).orWhereNull('subject_relation');
+        else
+            b.where('subject_relation', relation);
     }
     /* ── Expansión de includes (un nivel, hacia ABAJO desde la relación) ──── */
     #expandDown(objectType, relation) {
@@ -155,17 +304,33 @@ export class DatabaseRelationsDriver {
         return [...out];
     }
     /* ── Escrituras ───────────────────────────────────────────────────────── */
-    async relate(subject, relation, object, partition, _options) {
+    async relate(subject, relation, object, partition, options) {
+        // L-0 · F-05 en el DRIVER (la MISMA función que el manager): la red para
+        // quien entra por `manager.driver()` o por `reconcileRelations`. Corta
+        // ANTES de pedir la conexión. En `database` la tabla es propia (inocuo),
+        // pero el 422 es el MISMO que en `openfga`, donde el store es compartido.
+        assertRelationDeclared(this.#config, object, relation);
         assertScope(partition);
         this.#assertObject(object);
         this.#assertId(`la relación de '${object.type}'`, relation, RELATION_ID_MAX);
+        // R-15 (defensa en profundidad; el manager ya lo validó): los tres estados.
+        assertExpiresAt(options?.expiresAt);
+        const requested = options?.expiresAt;
         const partitionKey = scopeKey(partition);
         const s = this.#subjectColumns(subject, partitionKey);
-        // Transacción INTERNA: la atomicidad trigger+insert (el trigger corre en el
-        // mismo INSERT; el check-then-insert idempotente va dentro de la misma
-        // transacción). `{trx}` NO se expone en el puerto (decisión (b), diferido).
-        await this.#sql('relate', () => this.#connection().transaction(async (trx) => {
-            const existing = await trx
+        const codec = this.#expiry;
+        const now = this.#now();
+        // L-4: por la transacción del llamante si llegó (`#writer`, juzgada AQUÍ,
+        // después de F-05 y la gramática y antes de la primera sentencia).
+        const { client, external } = this.#writer('relate', options);
+        // El check-then-delete-insert idempotente. Con transacción EXTERNA corre
+        // tal cual sobre ella (el trigger de partición dispara en ESE INSERT,
+        // dentro de la trx del consumidor; NUNCA se abre una interna: la fila
+        // confirmaría sola y sobreviviría al rollback del llamante). Sin ella, en
+        // una transacción INTERNA de la conexión del driver (la atomicidad
+        // trigger+insert de 4-3). Cada sentencia lleva su deadline (`#sql`).
+        const write = async (trx) => {
+            const existing = await this.#sql('relate.select', () => trx
                 .from(RELATIONS_TABLE)
                 .where('partition_key', partitionKey)
                 .where('object_type', object.type)
@@ -173,11 +338,25 @@ export class DatabaseRelationsDriver {
                 .where('relation', relation)
                 .where('subject_type', s.type)
                 .where('subject_uuid', s.uuid)
-                .where((b) => (s.relation === null ? b.whereNull('subject_relation') : b.where('subject_relation', s.relation)))
-                .limit(1);
-            if (existing.length > 0)
-                return; // idempotente (invariante 6): no duplica.
-            await trx.table(RELATIONS_TABLE).insert({
+                .where((b) => this.#whereSubjectRelation(b, s.relation))
+                .select('uuid', codec.select('expires_at'))
+                .limit(1));
+            const current = existing[0];
+            const previous = current ? codec.fromDb(current.expires_at) : null;
+            // Los tres estados (invariante 10): omitido preserva la VIGENTE (una
+            // caducada revive sin caducidad), null la quita, Date la fija.
+            const expiresAt = resolveGrantExpiry(previous, requested, now);
+            if (current) {
+                // Idempotente (invariante 6): la misma caducidad no reescribe nada.
+                if (sameInstant(previous, expiresAt))
+                    return;
+                // **INSERT/DELETE-ONLY (decisión (c))**: cambiar la caducidad es
+                // BORRAR la fila e INSERTAR otra —nunca un UPDATE—; la fila nueva
+                // tiene otro `uuid`, que es lo que lo hace observable. Dentro de la
+                // trx del llamante, el rollback devuelve la fila (y la caducidad) VIEJA.
+                await this.#sql('relate.delete', () => trx.from(RELATIONS_TABLE).where('uuid', current.uuid).delete());
+            }
+            await this.#sql('relate.insert', () => trx.table(RELATIONS_TABLE).insert({
                 uuid: uuidv7(),
                 partition_key: partitionKey,
                 object_type: object.type,
@@ -187,29 +366,63 @@ export class DatabaseRelationsDriver {
                 subject_uuid: s.uuid,
                 subject_relation: s.relation,
                 subject_partition: s.partition,
-                created_at: this.#now(),
-            });
-        }));
+                expires_at: codec.toDb(expiresAt),
+                // Sello de auditoría, no decisión (2.5-B · K5): reloj del SISTEMA
+                // (con el reloj inyectado en 2099 un TIMESTAMP de MySQL reventaría).
+                created_at: systemClock(),
+            }));
+        };
+        if (external) {
+            try {
+                await write(client);
+            }
+            catch (error) {
+                this.#poisoned('relate', error);
+            }
+            return;
+        }
+        await this.#sql('relate', () => client.transaction(write));
     }
-    async unrelate(subject, relation, object, partition, _options) {
+    async unrelate(subject, relation, object, partition, options) {
+        // L-0 · F-05 también al RETIRAR (paridad con `openfga`).
+        assertRelationDeclared(this.#config, object, relation);
         assertScope(partition);
         this.#assertObject(object);
         this.#assertId(`la relación de '${object.type}'`, relation, RELATION_ID_MAX);
         const partitionKey = scopeKey(partition);
         const s = this.#subjectColumns(subject, partitionKey);
-        await this.#sql('unrelate', () => this.#connection()
-            .from(RELATIONS_TABLE)
-            .where('partition_key', partitionKey)
-            .where('object_type', object.type)
-            .where('object_uuid', object.id)
-            .where('relation', relation)
-            .where('subject_type', s.type)
-            .where('subject_uuid', s.uuid)
-            .where((b) => (s.relation === null ? b.whereNull('subject_relation') : b.where('subject_relation', s.relation)))
-            .delete());
+        const { client, external } = this.#writer('unrelate', options);
+        try {
+            await this.#sql('unrelate', () => client
+                .from(RELATIONS_TABLE)
+                .where('partition_key', partitionKey)
+                .where('object_type', object.type)
+                .where('object_uuid', object.id)
+                .where('relation', relation)
+                .where('subject_type', s.type)
+                .where('subject_uuid', s.uuid)
+                .where((b) => this.#whereSubjectRelation(b, s.relation))
+                .delete());
+        }
+        catch (error) {
+            if (external)
+                this.#poisoned('unrelate', error);
+            throw error;
+        }
     }
     /* ── Lecturas ─────────────────────────────────────────────────────────── */
+    /**
+     * **F-05 en las LECTURAS y las PURGAS del driver** (2.4.0-alpha.3, cierre
+     * del 🔴 1 / 🟠 2 del auditor; la MISMA función y el mismo orden que L-0 en
+     * `relate`/`unrelate`): PRIMERA línea, antes de pedir la conexión. En
+     * `database` la tabla es propia (inocuo), pero el 422 es el MISMO que en
+     * `openfga`, donde `purgeObject(role_binding)` borraba el binding real y
+     * `listSubjects(assignee, role_binding)` enumeraba sus asignados por el
+     * camino de `manager.driver()`. `check`/`listSubjects` validan el par;
+     * `listObjects`/`purgeObject` el tipo; `purgeSubject` el userset.
+     */
     async check(subject, relation, object, partition) {
+        assertRelationDeclared(this.#config, object, relation);
         assertScope(partition);
         this.#assertObject(object);
         const partitionKey = scopeKey(partition);
@@ -217,19 +430,21 @@ export class DatabaseRelationsDriver {
         const relations = this.#expandDown(object.type, relation);
         const meta = this.#dialectMeta();
         const q = (name) => `${meta.quote}${name}${meta.quote}`;
-        const { cte, bindings: cteBindings } = this.#principalCte(meta, q, s, partitionKey);
+        const at = this.#expiry.bind(this.#now());
+        const { cte, bindings: cteBindings } = this.#principalCte(meta, q, s, partitionKey, at);
         const relPlaceholders = relations.map(() => '?').join(', ');
         const sql = cte +
             ` SELECT ${meta.hint}1 FROM ${q(RELATIONS_TABLE)} r ` +
             `JOIN principal p ON r.${q('subject_type')} = p.p_type AND r.${q('subject_uuid')} = p.p_uuid ` +
             `AND COALESCE(r.${q('subject_relation')}, '') = p.p_rel ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
-            `AND r.${q('relation')} IN (${relPlaceholders}) LIMIT 1`;
-        const bindings = [...cteBindings, partitionKey, object.type, object.id, ...relations];
+            `AND r.${q('relation')} IN (${relPlaceholders}) AND ${this.#activeSql(q, 'r')} LIMIT 1`;
+        const bindings = [...cteBindings, partitionKey, object.type, object.id, ...relations, at];
         const rows = rowsOf(await this.#raw('check', sql, bindings));
         return rows.length > 0;
     }
     async listObjects(subject, relation, objectType, partition, _page) {
+        assertRelationDeclared(this.#config, { type: objectType }, relation);
         assertScope(partition);
         this.#assertId('el tipo de objeto', objectType, RELATION_ID_MAX);
         const partitionKey = scopeKey(partition);
@@ -237,15 +452,16 @@ export class DatabaseRelationsDriver {
         const relations = this.#expandDown(objectType, relation);
         const meta = this.#dialectMeta();
         const q = (name) => `${meta.quote}${name}${meta.quote}`;
-        const { cte, bindings: cteBindings } = this.#principalCte(meta, q, s, partitionKey);
+        const at = this.#expiry.bind(this.#now());
+        const { cte, bindings: cteBindings } = this.#principalCte(meta, q, s, partitionKey, at);
         const relPlaceholders = relations.map(() => '?').join(', ');
         const sql = cte +
             ` SELECT ${meta.hint}DISTINCT r.${q('object_uuid')} AS ${q('object_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
             `JOIN principal p ON r.${q('subject_type')} = p.p_type AND r.${q('subject_uuid')} = p.p_uuid ` +
             `AND COALESCE(r.${q('subject_relation')}, '') = p.p_rel ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? ` +
-            `AND r.${q('relation')} IN (${relPlaceholders})`;
-        const bindings = [...cteBindings, partitionKey, objectType, ...relations];
+            `AND r.${q('relation')} IN (${relPlaceholders}) AND ${this.#activeSql(q, 'r')}`;
+        const bindings = [...cteBindings, partitionKey, objectType, ...relations, at];
         const rows = rowsOf(await this.#raw('listObjects', sql, bindings));
         const objects = rows
             .map((row) => ({ type: objectType, id: String(row.object_uuid) }))
@@ -253,19 +469,20 @@ export class DatabaseRelationsDriver {
         return { objects };
     }
     async listSubjects(relation, object, partition, _page) {
+        assertRelationDeclared(this.#config, object, relation);
         assertScope(partition);
         this.#assertObject(object);
         const partitionKey = scopeKey(partition);
         // DIRECTOS del relation EXACTO (invariante 7): ni transitivo (eso es
         // `membersOf`) ni derivado por includes. `usersetSubjects: true` ⇒ los
-        // usersets (`group#member`) salen junto con los holders.
-        const rows = await this.#sql('listSubjects', () => this.#connection()
+        // usersets (`group#member`) salen junto con los holders. Solo VIGENTES (R-15).
+        const now = this.#now();
+        const rows = await this.#sql('listSubjects', () => this.#whereActive(this.#connection()
             .from(RELATIONS_TABLE)
             .where('partition_key', partitionKey)
             .where('object_type', object.type)
             .where('object_uuid', object.id)
-            .where('relation', relation)
-            .select('subject_type', 'subject_uuid', 'subject_relation'));
+            .where('relation', relation), now).select('subject_type', 'subject_uuid', 'subject_relation'));
         const subjects = rows.map((row) => this.#rowToSubject(row));
         return { subjects };
     }
@@ -277,6 +494,9 @@ export class DatabaseRelationsDriver {
      * los holders de g1 y `listSubjects(member, g2)` solo el userset `g1#member`.
      */
     async membersOf(object, relation, partition, _page) {
+        // Cierre-2 · 🟡 3: F-05 (par, ESTRICTA) también en `membersOf`, la octava
+        // operación del puerto; antes solo `#assertObject` (gramática).
+        assertRelationDeclared(this.#config, object, relation);
         assertScope(partition);
         this.#assertObject(object);
         const partitionKey = scopeKey(partition);
@@ -284,68 +504,96 @@ export class DatabaseRelationsDriver {
         const meta = this.#dialectMeta();
         const q = (name) => `${meta.quote}${name}${meta.quote}`;
         const relPlaceholders = relations.map(() => '?').join(', ');
+        const at = this.#expiry.bind(this.#now());
+        const active = this.#activeSql(q, 'r');
         // `grp`: los grupos alcanzables por usersets desde (object, RS) —directos y
         // anidados—. Ancla de UN solo SELECT (MySQL no mezcla UNION ALL con la
         // recursión): los usersets directos del objeto para cualquier rel de RS.
+        // Solo hechos VIGENTES en los cuatro tramos (R-15): una membresía caducada
+        // no lleva a nadie dentro.
         const sql = `WITH RECURSIVE grp(g_uuid) AS ( ` +
             `SELECT r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
             `AND r.${q('relation')} IN (${relPlaceholders}) AND r.${q('subject_type')} = '${GROUP_TYPE}' ` +
-            `AND r.${q('subject_relation')} = '${GROUP_MEMBER}' ` +
+            `AND r.${q('subject_relation')} = '${GROUP_MEMBER}' AND ${active} ` +
             `UNION ` +
             `SELECT r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
             `JOIN grp ON r.${q('object_uuid')} = grp.g_uuid ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = '${GROUP_TYPE}' ` +
             `AND r.${q('relation')} = '${GROUP_MEMBER}' AND r.${q('subject_type')} = '${GROUP_TYPE}' ` +
-            `AND r.${q('subject_relation')} = '${GROUP_MEMBER}' ` +
+            `AND r.${q('subject_relation')} = '${GROUP_MEMBER}' AND ${active} ` +
             `) ` +
             // Holders directos del objeto para RS, UNION holders directos de cualquier grupo de `grp`.
             `SELECT ${meta.hint}${q('subject_type')} AS ${q('subject_type')}, ${q('subject_uuid')} AS ${q('subject_uuid')} ` +
             `FROM ${q(RELATIONS_TABLE)} r ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = ? AND r.${q('object_uuid')} = ? ` +
-            `AND r.${q('relation')} IN (${relPlaceholders}) AND r.${q('subject_relation')} IS NULL ` +
+            `AND r.${q('relation')} IN (${relPlaceholders}) AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active} ` +
             `UNION ` +
             `SELECT r.${q('subject_type')}, r.${q('subject_uuid')} FROM ${q(RELATIONS_TABLE)} r ` +
             `JOIN grp ON r.${q('object_uuid')} = grp.g_uuid ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = '${GROUP_TYPE}' ` +
-            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND r.${q('subject_relation')} IS NULL`;
+            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND COALESCE(r.${q('subject_relation')}, '') = '' AND ${active}`;
         const bindings = [
             // grp ancla
-            partitionKey, object.type, object.id, ...relations,
+            partitionKey, object.type, object.id, ...relations, at,
             // grp recursiva
-            partitionKey,
+            partitionKey, at,
             // holders directos del objeto
-            partitionKey, object.type, object.id, ...relations,
+            partitionKey, object.type, object.id, ...relations, at,
             // holders de los grupos
-            partitionKey,
+            partitionKey, at,
         ];
         const rows = rowsOf(await this.#raw('membersOf', sql, bindings));
         const subjects = rows.map((row) => ({ type: String(row.subject_type), uuid: String(row.subject_uuid) }));
         return { subjects };
     }
     /* ── Purga (invariante 11): el DELETE demuestra el cero ───────────────── */
-    async purgeObject(object, partition) {
+    async purgeObject(object, partition, options) {
+        // alpha.3 · F-05 (solo el TIPO: una purga no nombra relación), PRIMERA línea.
+        // Cierre-2: la función de TIPO, no la estricta con relación opcional.
+        assertObjectTypeDeclared(this.#config, object);
         assertScope(partition);
         this.#assertObject(object);
         const partitionKeys = this.#partitionSpellings(partition);
-        await this.#sql('purgeObject', () => this.#connection()
-            .from(RELATIONS_TABLE)
-            .whereIn('partition_key', partitionKeys)
-            .where('object_type', object.type)
-            .where('object_uuid', object.id)
-            .delete());
+        // L-4: por la transacción del llamante si llegó — la purga borra y
+        // REVIERTE con ella (tras un rollback todo lo purgado está de vuelta).
+        const { client, external } = this.#writer('purgeObject', options);
+        try {
+            await this.#sql('purgeObject', () => client
+                .from(RELATIONS_TABLE)
+                .whereIn('partition_key', partitionKeys)
+                .where('object_type', object.type)
+                .where('object_uuid', object.id)
+                .delete());
+        }
+        catch (error) {
+            if (external)
+                this.#poisoned('purgeObject', error);
+            throw error;
+        }
     }
-    async purgeSubject(subject, partition) {
+    async purgeSubject(subject, partition, options) {
+        // alpha.3 · F-05 del USERSET (una purga por sujeto no nombra objeto), PRIMERA línea.
+        if (isRelUserset(subject))
+            assertRelationDeclared(this.#config, subject.object, subject.relation);
         assertScope(partition);
         const partitionKeys = this.#partitionSpellings(partition);
         const s = this.#subjectColumns(subject, scopeKey(partition));
-        await this.#sql('purgeSubject', () => this.#connection()
-            .from(RELATIONS_TABLE)
-            .whereIn('partition_key', partitionKeys)
-            .where('subject_type', s.type)
-            .where('subject_uuid', s.uuid)
-            .where((b) => (s.relation === null ? b.whereNull('subject_relation') : b.where('subject_relation', s.relation)))
-            .delete());
+        const { client, external } = this.#writer('purgeSubject', options);
+        try {
+            await this.#sql('purgeSubject', () => client
+                .from(RELATIONS_TABLE)
+                .whereIn('partition_key', partitionKeys)
+                .where('subject_type', s.type)
+                .where('subject_uuid', s.uuid)
+                .where((b) => this.#whereSubjectRelation(b, s.relation))
+                .delete());
+        }
+        catch (error) {
+            if (external)
+                this.#poisoned('purgeSubject', error);
+            throw error;
+        }
     }
     /* ── ORIGEN de reconcile (4-5): enumera los hechos directos ───────────── */
     /**
@@ -354,8 +602,9 @@ export class DatabaseRelationsDriver {
      * paginados por la PK (`uuid`, cursor que AVANZA), sin derivar por
      * includes/usersets (el modelo del destino lo recompone): el destino recibe
      * los hechos tal cual y decide qué escribe (invariante 7 + la higiene de
-     * reconcile — una caducada tendría que LLEGAR; aquí no hay caducidad, R-15
-     * quedó fuera). Barre las DOS ortografías del uuid de partición (🟡2,
+     * reconcile — **la caducada LLEGA con su `expiresAt`**, R-15, para contarse
+     * en `skipped`; filtrarla aquí la haría desaparecer sin rastro). Barre las
+     * DOS ortografías del uuid de partición (🟡2,
      * coherente con `purge*`): un origen que las funde no puede dejar hechos del
      * alias sin migrar.
      *
@@ -383,7 +632,7 @@ export class DatabaseRelationsDriver {
                 .limit(limit + 1);
             if (after)
                 q = q.where('uuid', '>', after);
-            return q.select('uuid', 'object_type', 'object_uuid', 'relation', 'subject_type', 'subject_uuid', 'subject_relation');
+            return q.select('uuid', 'object_type', 'object_uuid', 'relation', 'subject_type', 'subject_uuid', 'subject_relation', this.#expiry.select('expires_at'));
         });
         const hasMore = rows.length > limit;
         const pageRows = hasMore ? rows.slice(0, limit) : rows;
@@ -393,6 +642,7 @@ export class DatabaseRelationsDriver {
             object: { type: String(row.object_type), id: String(row.object_uuid) },
             // La partición canónica pedida: el barrido de ortografías ya la unificó.
             partition,
+            expiresAt: this.#expiry.fromDb(row.expires_at),
         }));
         const cursor = hasMore ? String(pageRows[pageRows.length - 1].uuid) : undefined;
         return cursor ? { tuples, cursor } : { tuples };
@@ -417,8 +667,12 @@ export class DatabaseRelationsDriver {
      * de esas identidades. Devuelve el `WITH RECURSIVE …` (sin el SELECT final) y
      * sus bindings.
      */
-    #principalCte(meta, q, s, partitionKey) {
-        const baseRel = s.relation ?? '';
+    #principalCte(meta, q, s, partitionKey, at) {
+        // L-4b: el holder ya viene con `''`; el `COALESCE(subject_relation, '')`
+        // del JOIN es la tolerancia a una fila vieja con NULL.
+        const baseRel = s.relation;
+        // Solo membresías VIGENTES suben por la recursión (R-15): una `member`
+        // caducada no convierte al sujeto en miembro de nada.
         const cte = `WITH RECURSIVE principal(p_type, p_uuid, p_rel) AS ( ` +
             `SELECT ${meta.text('?')}, ${meta.text('?')}, ${meta.text('?')} ` +
             `UNION ` +
@@ -427,11 +681,12 @@ export class DatabaseRelationsDriver {
             `JOIN principal p ON r.${q('subject_type')} = p.p_type AND r.${q('subject_uuid')} = p.p_uuid ` +
             `AND COALESCE(r.${q('subject_relation')}, '') = p.p_rel ` +
             `WHERE r.${q('partition_key')} = ? AND r.${q('object_type')} = '${GROUP_TYPE}' ` +
-            `AND r.${q('relation')} = '${GROUP_MEMBER}' )`;
-        return { cte, bindings: [s.type, s.uuid, baseRel, partitionKey] };
+            `AND r.${q('relation')} = '${GROUP_MEMBER}' AND ${this.#activeSql(q, 'r')} )`;
+        return { cte, bindings: [s.type, s.uuid, baseRel, partitionKey, at] };
     }
+    /** `''` (L-4b) o NULL (fila vieja sin backfill) ⇒ holder; con valor ⇒ userset. */
     #rowToSubject(row) {
-        if (row.subject_relation === null || row.subject_relation === undefined) {
+        if (row.subject_relation === null || row.subject_relation === undefined || row.subject_relation === HOLDER_RELATION) {
             return { type: String(row.subject_type), uuid: String(row.subject_uuid) };
         }
         return { object: { type: String(row.subject_type), id: String(row.subject_uuid) }, relation: String(row.subject_relation) };