@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/security/authentications/services/anonymous-session.backend.service.js

@@ -22,7 +22,7 @@ import jwt from 'jsonwebtoken';
 import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
 import { AppConfigurationService } from '../../../config/services/app-configuration.backend.service.js';
 import { describeCaughtError, projectCaughtErrorLogFields } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
-import { ANONYMOUS_SESSION_JWT_EXPIRY_STRING, ANONYMOUS_SESSION_JWT_FORMAT, AnonymousSessionJwtPayloadSchema, AnonymousUserMarketingMetadataSchema, AnonymousUserTranspositionStatus, CoreResourceOperation, CoreResourceType, CORE_APP_ROLES, ErrorCustomMessageReference, ErrorType, ResourcePrimaryScope, ResourceTranspositionPolicy, WildoHeaderKeys, } from '@wildo-ai/saas-models';
+import { ANONYMOUS_SESSION_JWT_EXPIRY_STRING, ANONYMOUS_SESSION_JWT_FORMAT, AnonymousSessionJwtPayloadSchema, AnonymousUserMarketingMetadataSchema, AnonymousUserTranspositionStatus, CoreResourceOperation, CoreResourceType, CORE_APP_ROLES, ErrorCustomMessageReference, ErrorType, ResourcePrimaryScope, ResourceTranspositionPolicy, WildoHeaderKeys, isServiceResolvableDefaultOperation, } from '@wildo-ai/saas-models';
 import { getClientIpFromRequest } from '../../../runtime/utils/request-client-ip.utils.js';
 import { AuthControllerUtils } from '../../../security/authentications/services/utils/auth-controller.utils.js';
 let AnonymousSessionBackendService = class AnonymousSessionBackendService {
@@ -257,29 +257,122 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
         const userTypePolicy = this.configService.getUserTypeAuthPolicy(userType);
         if (!userTypePolicy?.anonymousSessionsEnabled) {
             this.logDebug('Skipping transposition — anonymousSessionsEnabled is false for user type', { userType, anonymousUserId });
-            return { transposedTypes: [], failedTypes: [], status: AnonymousUserTranspositionStatus.PENDING };
+            return { transposedTypes: [], discardedTypes: [], failedTypes: [], status: AnonymousUserTranspositionStatus.PENDING };
         }
+        const { transposedTypes, discardedTypes, failedTypes } = await this.applyOwnershipTransposition(anonymousUserId, authenticatedUserId, 
+        // The CONVERSION pass is the one moment a declared REPLACE policy may be honoured — see the
+        // long note on `applyOwnershipTransposition`'s `applyReplacePolicy` for why a later
+        // reconciliation pass must NOT re-apply it.
+        { applyReplacePolicy: true });
+        // PARTIAL means "some of the work landed", and a DISCARD sweep is work: those rows are gone and
+        // no later pass will find them. Counting only `transposedTypes` here would stamp PENDING on a
+        // session whose only successful type was a DISCARD — a status that says nothing happened about a
+        // session whose data was deleted.
+        const status = failedTypes.length === 0
+            ? AnonymousUserTranspositionStatus.COMPLETE
+            : transposedTypes.length + discardedTypes.length > 0
+                ? AnonymousUserTranspositionStatus.PARTIAL
+                : AnonymousUserTranspositionStatus.PENDING;
+        await this.recordTranspositionOutcome(anonymousUserId, authenticatedUserId, status);
+        return { transposedTypes, discardedTypes, failedTypes, status };
+    }
+    /**
+     * Move every still-anonymous row this session owns onto the authenticated user, one resource type
+     * at a time. Shared by the CONVERSION pass ({@link transposeOwnership}) and the RECONCILIATION
+     * pass ({@link reconcileIncompleteTranspositions}) so the two can never drift into two different
+     * notions of what a transposition is.
+     *
+     * ### The idempotency contract, and why it is STRUCTURAL rather than a flag
+     * Every read goes through {@link listAnonymousRecords}, which filters `{ anonymousUserId, userId:
+     * null }`. The write flips a row to `{ userId: <account>, anonymousUserId: null }`. So a row that
+     * has already moved is invisible to every subsequent pass, per resource type, with no bookkeeping
+     * anywhere: re-running this method can only ever act on rows that genuinely have not moved yet.
+     *
+     * That is deliberate. A "which types have I already done?" marker on the AnonymousUser row would
+     * be a second ledger next to the data it describes, and it would be written by exactly the
+     * best-effort write whose failure created the split in the first place. The data answers the
+     * question; nothing else needs to.
+     *
+     * ### Why a per-type failure is still SWALLOWED here
+     * One resource type failing must not lose the others — a visitor whose draft notes move but whose
+     * lead capture does not is strictly better off than one where neither moved because the first
+     * throw aborted the loop. That reasoning was always sound. What was missing is what happens
+     * NEXT, and that is now {@link reconcileIncompleteTranspositions} rather than a status stamp
+     * nobody reads.
+     *
+     * @param applyReplacePolicy honour `ResourceTranspositionPolicy.REPLACE` (delete the account's
+     *   existing rows of that type before moving the anonymous ones). TRUE only on the conversion
+     *   pass. On a reconciliation pass it MUST be false: REPLACE expresses "the anonymous draft wins
+     *   over whatever the account had AT THE MOMENT OF CONVERSION", and re-applying it hours or days
+     *   later would delete rows the user authored *after* converting — turning a repair into data
+     *   loss, which is far worse than the residual it would fix.
+     *
+     *   The residual, stated plainly: if the REPLACE delete itself failed at conversion time, the
+     *   reconciliation moves the anonymous rows in ADD fashion, so the account ends up holding both
+     *   sets. That is visible, non-destructive and recoverable by the user; the alternative is not.
+     *   Rejected alternative: record "REPLACE was applied for type T" durably and let the reconcile
+     *   consult it — that is precisely the second ledger this design refuses, and it would be written
+     *   by the same fallible pass.
+     *
+     * ### DISCARD DELETES, and it deletes on BOTH passes — unlike REPLACE
+     * `DISCARD` used to `continue` past the type entirely, which left its rows carrying
+     * `{ anonymousUserId, userId: null }` FOREVER: the conversion had already set `convertedToUserId`,
+     * so the cleanup batch's phase 1 (`{ convertedToUserId: null }`) could no longer see the session,
+     * and phase 2 deletes only the `ANONYMOUS_USERS` anchor row. After the retention window the anchor
+     * was gone and the rows remained, pointing at an identity that no longer exists — an orphan with a
+     * dangling foreign key, and no population definition by which any later sweep could find it.
+     *
+     * So the delete happens HERE, at conversion time, where the anchor still exists and the population
+     * is exactly "the rows this list just returned". The rejected alternative was a later sweep, which
+     * would have to recognise the same rows AFTER phase 2 removed the only thing that names them —
+     * a recognition problem that deleting at conversion makes unnecessary.
+     *
+     * It is deliberately NOT gated on `applyReplacePolicy`, and the asymmetry with REPLACE is the
+     * whole reason that flag exists in the first place. REPLACE deletes the ACCOUNT's rows, so
+     * re-applying it later destroys work the user did after converting. DISCARD deletes the ANONYMOUS
+     * rows — rows the account has never been able to see and that the resource declared it never wants
+     * carried over. Deleting them a day late is the same act, not a destructive one, so a
+     * reconciliation pass may and must finish a DISCARD the conversion could not.
+     *
+     * A DISCARD failure is recorded in `failedTypes` and the loop continues — the same treatment as
+     * every other per-type failure, and for the stronger reason: this runs inside a live conversion,
+     * and a conversion that half-runs (the user cannot complete sign-in) is worse than a row that
+     * survives until the next reconciliation pass, which will retry it before phase 2 can retire the
+     * anchor.
+     */
+    async applyOwnershipTransposition(anonymousUserId, authenticatedUserId, { applyReplacePolicy }) {
         const transposedTypes = [];
+        const discardedTypes = [];
         const failedTypes = [];
         const anonymizableTypes = this.getAnonymizableResourceTypes();
         for (const resourceType of anonymizableTypes) {
             const resourceConfig = this.resourcesRegistry.getResourceConfiguration(resourceType);
             const policy = resourceConfig?.transpositionPolicy ?? ResourceTranspositionPolicy.ADD;
-            if (policy === ResourceTranspositionPolicy.DISCARD) {
-                this.logDebug('Skipping transposition (DISCARD policy)', { resourceType });
-                continue;
-            }
             try {
                 const records = await this.listAnonymousRecords(resourceType, anonymousUserId);
                 if (!records || records.length === 0)
                     continue;
-                if (policy === ResourceTranspositionPolicy.REPLACE) {
-                    await this.deleteExistingUserRecords(resourceType, authenticatedUserId);
+                const ids = records.map((r) => r._id);
+                if (policy === ResourceTranspositionPolicy.DISCARD) {
+                    // Same structural idempotency as the reassignment below: the read filters
+                    // `{ anonymousUserId, userId: null }`, and a deleted row matches nothing, so a re-run can
+                    // only ever act on rows that are genuinely still there.
+                    await this.deleteOwnedRecords(resourceType, ids);
+                    discardedTypes.push(resourceType);
+                    this.logDebug('Discarded anonymous records (DISCARD policy)', {
+                        resourceType, count: ids.length, anonymousUserId, authenticatedUserId,
+                    });
+                    continue;
                 }
-                if (policy === ResourceTranspositionPolicy.MERGE) {
-                    this.logger.warn('MERGE transposition policy is not yet implemented — falling back to ADD', { resourceType, anonymousUserId, authenticatedUserId });
+                if (policy === ResourceTranspositionPolicy.REPLACE && applyReplacePolicy) {
+                    await this.deleteExistingUserRecords(resourceType, authenticatedUserId);
                 }
-                const ids = records.map((r) => r._id);
+                /*
+                 * No MERGE arm: the member was removed from `ResourceTranspositionPolicy` on 2026-09-08.
+                 * It used to warn here and fall through to the reassignment below, which meant a resource
+                 * declaring MERGE silently got ADD. With the member gone this branch is unreachable, and
+                 * the warning would have been a claim about a state no config can author.
+                 */
                 await this.reassignOwnership(resourceType, ids, authenticatedUserId);
                 transposedTypes.push(resourceType);
                 this.logDebug('Transposed ownership', {
@@ -310,6 +403,12 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
         // result rolls into the same transposedTypes/failedTypes report
         // and the AnonymousUser.transpositionStatus update below reflects
         // the full conversion outcome.
+        //
+        // It has no DISCARD arm and needs none: `transpositionPolicy` is normalized to `undefined` for
+        // any resource that is not `isAnonymizable` (`resources-config.shared.factory.ts`), and
+        // `INBOUND_CONTACTS` cannot be — the flag requires USER_SELF scope. So no configuration can
+        // declare DISCARD for this type; there is no silently-ADD'ed policy here, which is the failure
+        // shape the removed MERGE member had.
         try {
             const inboundContactsTransposedCount = await this.transposeInboundContactsOwnership(anonymousUserId, authenticatedUserId);
             if (inboundContactsTransposedCount > 0) {
@@ -326,35 +425,184 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
                 anonymousUserId, authenticatedUserId, error: errorMsg,
             });
         }
-        const status = failedTypes.length === 0
-            ? AnonymousUserTranspositionStatus.COMPLETE
-            : transposedTypes.length > 0
-                ? AnonymousUserTranspositionStatus.PARTIAL
-                : AnonymousUserTranspositionStatus.PENDING;
-        try {
-            // Deliberately NOT routed through `updateAsSystem` (unlike the ownership
-            // transposition writes). `convertedToUserId` and `transpositionStatus` are
-            // ordinary fields — neither `.isBackendOnly()` nor context-auto-populated FK
-            // names — so they survive the strict-DTO parse; there is nothing for the
-            // primitive to re-attach. Migrating would only add a fail-closed opt-in and
-            // an audit row for no correctness gain, so the plain internal-EC handler
-            // stays. (ANONYMOUS_USERS opts into `systemAccessPolicy.create` only.)
-            const updateOpPath = this.resourcesRegistry.getServiceOperationPathDefault(CoreResourceType.ANONYMOUS_USERS, CoreResourceOperation.UPDATE);
-            const anonymousUserEc = await this.executionContextCreator.createForInternalOperation({
-                operation: updateOpPath,
+        return { transposedTypes, discardedTypes, failedTypes };
+    }
+    /**
+     * Write the conversion outcome onto the AnonymousUser row: `convertedToUserId` (WHICH account the
+     * session became) and `transpositionStatus` (how far the move got).
+     *
+     * ### This write REFUSES. It is the one step here that may not be best effort.
+     * Every other failure in a transposition is survivable because the DATA still says what happened:
+     * a row that moved carries the account's `userId`, a row that did not still carries the
+     * `anonymousUserId`. `convertedToUserId` is different — it is the ONLY place the anon→account
+     * mapping is ever recorded. Lose it and no later pass can know which account the leftover rows
+     * were supposed to reach, so a recoverable partial becomes permanent.
+     *
+     * It is not merely unrecoverable, it is actively destructive: `cleanupExpiredSessions` selects
+     * `{ convertedToUserId: null, createdAt < 48h }` and DELETES that session's remaining anonymous
+     * rows. So a swallowed failure here schedules the visitor's un-moved rows for deletion two days
+     * later, silently — the exact "record that it stopped and never revisit it" shape this method now
+     * refuses to produce.
+     *
+     * Throwing costs the caller nothing it was relying on. Both triggers
+     * (`handleAnonymousTransposition` / `...ForTokenExchange` in the authentication controller) already
+     * wrap the call in a non-blocking catch, so the authentication response is unaffected — and
+     * because their `clearSessionCookie` sits AFTER the call, a throw also KEEPS the continuity cookie,
+     * which is precisely the retry channel: the next login presents the same session handle and the
+     * whole transposition runs again, idempotently (see `applyOwnershipTransposition`).
+     *
+     * Deliberately NOT routed through `updateAsSystem` (unlike the ownership transposition writes).
+     * `convertedToUserId` and `transpositionStatus` are ordinary fields — neither `.isBackendOnly()`
+     * nor context-auto-populated FK names — so they survive the strict-DTO parse; there is nothing for
+     * the primitive to re-attach. Migrating would only add a fail-closed opt-in and an audit row for
+     * no correctness gain, so the plain internal-EC handler stays. (ANONYMOUS_USERS opts into
+     * `systemAccessPolicy.create` only.)
+     */
+    async recordTranspositionOutcome(anonymousUserId, authenticatedUserId, status) {
+        const updateOpPath = this.resourcesRegistry.getServiceOperationPathDefault(CoreResourceType.ANONYMOUS_USERS, CoreResourceOperation.UPDATE);
+        const anonymousUserEc = await this.executionContextCreator.createForInternalOperation({
+            operation: updateOpPath,
+            contextResourcesFieldIdentifier: new Map(),
+            initiatorIds: null,
+            initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
+        });
+        // Target the row by `{ uuidRef }`, NOT the session id directly: the session id
+        // (from the JWT) is the client `uuidRef`, while the row's `_id` is a server
+        // ObjectId — a bare id arg would resolve to `{ _id: <uuidRef> }` and match nothing.
+        await this.servicesRegistryHandler.update(CoreResourceType.ANONYMOUS_USERS, anonymousUserEc, { uuidRef: anonymousUserId }, { convertedToUserId: authenticatedUserId, transpositionStatus: status });
+    }
+    /**
+     * Finish the transpositions that stopped part-way, instead of leaving the stamp that says they
+     * did. Runs as phase 0 of the anonymous-session cleanup batch — before the deletion phases, which
+     * is the whole point: the batch that would otherwise walk past these rows repairs them first.
+     *
+     * ### What it is looking for
+     * A converted session whose data is still SPLIT: some rows on the account, some still carrying
+     * `{ anonymousUserId, userId: null }` because a resource type threw during the conversion pass.
+     * The account cannot see those rows, and nothing was ever going to come back for them.
+     *
+     * ### Why the candidate query keys on the stamp but the REPAIR keys on the data
+     * The stamp is a cheap INDEX into the population, not the authority. `{ convertedToUserId != null,
+     * transpositionStatus != COMPLETE }` is a superset of the genuinely-split sessions: after the
+     * conversion pass, `convertedToUserId` and `transpositionStatus` are written by ONE update, so a
+     * row that names an account always carries a stamp, and a stamp that is not COMPLETE means at
+     * least one type failed at that time. What the stamp cannot tell us is whether the split is
+     * STILL there — a transient repository error may since have cleared, and (before this method
+     * existed) a fully-successful move could be left stamped PENDING by a status write that failed on
+     * its own. So the stamp only selects who to LOOK at; `applyOwnershipTransposition` reads the rows
+     * and decides. A session that turns out to be whole gets its stamp corrected to COMPLETE, which
+     * is how the stamp-only split heals and how the candidate set stays small.
+     *
+     * ### The population this can NEVER repair, stated so nobody looks for it
+     * A session whose conversion-time status write failed BEFORE this change has `convertedToUserId:
+     * null`, and the account it converted into was never written down anywhere. It is indistinguishable
+     * from a visitor who never signed up, and its leftover rows were deleted by the 48h cleanup. There
+     * is no backfill for those; {@link recordTranspositionOutcome} refusing is what stops new ones.
+     */
+    async reconcileIncompleteTranspositions(options) {
+        const result = {
+            candidatesExamined: 0, sessionsRepaired: 0, sessionsStillIncomplete: 0,
+            resourceTypesTransposed: 0, resourceTypesDiscarded: 0, errors: 0,
+        };
+        if (!this.configService.anonymousSessionsEnabled) {
+            this.logDebug('Anonymous sessions not enabled — skipping transposition reconciliation');
+            return result;
+        }
+        const batchSize = options?.batchSize ?? 100;
+        const maxIterations = options?.maxIterations ?? 100;
+        const listOpPath = this.resourcesRegistry.getServiceOperationPathDefault(CoreResourceType.ANONYMOUS_USERS, CoreResourceOperation.LIST);
+        // Pagination over a set the pass itself SHRINKS. A repaired session leaves the candidate filter
+        // (its stamp becomes COMPLETE), so re-reading page 1 keeps yielding fresh work and no cursor is
+        // needed for the common case. A session that stays incomplete does NOT leave the filter, so it
+        // reappears on every read; `stuck` remembers those by handle so they are (a) attempted once per
+        // pass and (b) skipped past by the page offset once they fill a whole batch.
+        //
+        // The offset MUST be derived from a SET, not a counter. A counter incremented on every sighting
+        // grows each iteration for the same handful of stuck sessions, and once it crossed `batchSize`
+        // the page would jump forward and silently skip a batch of genuinely repairable sessions —
+        // a reconciliation that reports success while walking past the work.
+        const stuck = new Set();
+        let iteration = 0;
+        while (iteration < maxIterations) {
+            iteration++;
+            const page = Math.floor(stuck.size / batchSize) + 1;
+            const listEc = await this.executionContextCreator.createForInternalOperation({
+                operation: listOpPath,
                 contextResourcesFieldIdentifier: new Map(),
                 initiatorIds: null,
                 initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
             });
-            // Target the row by `{ uuidRef }`, NOT the session id directly: the session id
-            // (from the JWT) is the client `uuidRef`, while the row's `_id` is a server
-            // ObjectId — a bare id arg would resolve to `{ _id: <uuidRef> }` and match nothing.
-            await this.servicesRegistryHandler.update(CoreResourceType.ANONYMOUS_USERS, anonymousUserEc, { uuidRef: anonymousUserId }, { convertedToUserId: authenticatedUserId, transpositionStatus: status });
-        }
-        catch (error) {
-            this.logger.error('Failed to update AnonymousUser transposition status', { anonymousUserId, error });
+            const listResult = await this.servicesRegistryHandler.list(CoreResourceType.ANONYMOUS_USERS, listEc, { convertedToUserId: { $ne: null }, transpositionStatus: { $ne: AnonymousUserTranspositionStatus.COMPLETE } }, { page, limit: batchSize });
+            const candidates = Array.isArray(listResult) ? listResult : listResult.data;
+            if (candidates.length === 0)
+                break;
+            for (const candidate of candidates) {
+                // A session already attempted this pass is re-read but not re-attempted: retrying it inside
+                // one pass would just fail again, and counting it twice is what corrupts the page offset.
+                if (typeof candidate.uuidRef === 'string' && stuck.has(candidate.uuidRef))
+                    continue;
+                result.candidatesExamined++;
+                // `uuidRef` is the relational handle children carry in `anonymousUserId`; `_id` is a pure
+                // internal storage id that matches no child. Using `_id` here would find nothing to move and
+                // report every split session as already whole — a green reconciliation over an empty search.
+                const anonymousUserRef = candidate.uuidRef;
+                const authenticatedUserId = candidate.convertedToUserId;
+                if (!anonymousUserRef || !authenticatedUserId) {
+                    // Cannot happen through the candidate filter, but a hand-edited row would land here and a
+                    // silent `continue` is how it would stay invisible.
+                    result.errors++;
+                    this.logger.warn('Skipping transposition reconciliation candidate with no session handle or target user', {
+                        anonymousUserRowId: candidate._id, hasUuidRef: !!anonymousUserRef, hasConvertedToUserId: !!authenticatedUserId,
+                    });
+                    continue;
+                }
+                try {
+                    const { transposedTypes, discardedTypes, failedTypes } = await this.applyOwnershipTransposition(anonymousUserRef, authenticatedUserId, 
+                    // NEVER re-apply REPLACE outside the conversion moment — see `applyOwnershipTransposition`.
+                    // DISCARD is NOT subject to that restriction and runs here too: it deletes the ANONYMOUS
+                    // rows, never the account's, so finishing it late is the same act rather than a
+                    // destructive one. This is the only channel that can still reach a DISCARD row whose
+                    // conversion-time delete failed.
+                    { applyReplacePolicy: false });
+                    result.resourceTypesTransposed += transposedTypes.length;
+                    result.resourceTypesDiscarded += discardedTypes.length;
+                    if (failedTypes.length > 0) {
+                        stuck.add(anonymousUserRef);
+                        // ERROR, not WARN: a type that failed at conversion AND fails again on a later pass is a
+                        // defect in that resource's write path, not a transient. Warn level is where this kind of
+                        // finding goes to die (a level-60 FATAL gate never sees it), so the repeated failure is
+                        // the thing that must be loud.
+                        this.logger.error('Anonymous transposition still incomplete after reconciliation', {
+                            anonymousUserRef, authenticatedUserId,
+                            failedTypes: failedTypes.map((f) => ({ resourceType: f.resourceType, error: f.error })),
+                        });
+                        continue;
+                    }
+                    // Nothing left un-moved for this session. Re-stamp COMPLETE — this both records the repair
+                    // and removes the row from the candidate set, so a converged session is never re-examined.
+                    await this.recordTranspositionOutcome(anonymousUserRef, authenticatedUserId, AnonymousUserTranspositionStatus.COMPLETE);
+                    result.sessionsRepaired++;
+                    this.logDebug('Reconciled anonymous transposition', {
+                        anonymousUserRef, authenticatedUserId, transposedTypes, discardedTypes,
+                        priorStatus: candidate.transpositionStatus ?? null,
+                    });
+                }
+                catch (error) {
+                    // The stamp write refused (see `recordTranspositionOutcome`), or the EC could not be built.
+                    // The session stays in the candidate set and is retried on the next batch run — which is
+                    // safe precisely because the move itself is idempotent.
+                    result.errors++;
+                    stuck.add(anonymousUserRef);
+                    this.logger.error('Anonymous transposition reconciliation failed for a session', {
+                        anonymousUserRef, authenticatedUserId, ...projectCaughtErrorLogFields(error),
+                    });
+                }
+            }
+            if (candidates.length < batchSize)
+                break;
         }
-        return { transposedTypes, failedTypes, status };
+        result.sessionsStillIncomplete = stuck.size;
+        return result;
     }
     /**
      * Transpose ownership of `INBOUND_CONTACTS` rows owned by the given
@@ -446,6 +694,65 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
         // so no per-resource opt-in is required here.
         await this.systemAccessService.updateManyAsSystem(resourceType, ids, { userId: authenticatedUserId, anonymousUserId: null });
     }
+    /**
+     * Delete a known id set of a resource's rows, as the internal super-admin.
+     *
+     * THE single delete primitive of this service: the `DISCARD` transposition arm, the `REPLACE`
+     * pre-delete and the expired-session cleanup all route through it, so "how does this service
+     * delete rows it owns" has one answer and one place to fix.
+     *
+     * ### It resolves the operation it can actually serve, and that is not decoration
+     * `isAnonymizable` is NOW validated at config time to require a SERVICE-RESOLVABLE delete — either
+     * `DELETE_MANY` or `DELETE`, a disjunction chosen to mirror exactly what this method probes for, so
+     * the guard and the resolver cannot disagree. That was NOT true when this method was written: the
+     * factory then required only LIST and UPDATE_MANY, the two ADD needs, and said nothing about
+     * deletion at all. Measured 2026-09-09: `draftNotes`, the only
+     * `isAnonymizable` resource in this repository, declares `DELETE` and not `DELETE_MANY`. So the
+     * previous unconditional `getServiceOperationPathDefault(resourceType, DELETE_MANY)` threw
+     * `RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND` for it — which means the cleanup batch's phase 1
+     * has never been able to delete an expired anonymous draft note: the per-session catch counted an
+     * error, the `ANONYMOUS_USERS` row was never removed, and the same session was retried on every
+     * run forever. A DISCARD sweep built on the same unconditional call would have shipped equally
+     * dead.
+     *
+     * The boot guard now refuses that configuration, so the fallback below is no longer the only thing
+     * standing between an anonymizable resource and a cleanup that cannot run. Keep BOTH: the guard
+     * decides what may be DECLARED, this decides which of the two declared shapes to CALL.
+     *
+     * So: prefer `DELETE_MANY` when the resource declares a SERVICE-RESOLVABLE default for it, and
+     * fall back to per-row `DELETE` otherwise. The probe is
+     * {@link isServiceResolvableDefaultOperation} — the very predicate
+     * `getServiceOperationPathDefault` admits on — so the probe and the resolver cannot disagree
+     * (`try/catch` around the throwing resolver would also have "worked" and would have swallowed a
+     * genuine registry corruption as a fallback). If NEITHER resolves, the `DELETE` lookup throws and
+     * names the resource and the operation, which is the right outcome: a resource that can be
+     * created anonymously and can never be deleted is a configuration defect, not a case to swallow.
+     *
+     * Per-row DELETE is the same trade `transposeInboundContactsOwnership` already documents: one
+     * anonymous session owns a handful of rows, so the round trips are cheap, and requiring an
+     * application to publish a bulk-delete surface it does not want is the worse price.
+     */
+    async deleteOwnedRecords(resourceType, ids) {
+        if (ids.length === 0)
+            return;
+        const operations = this.resourcesRegistry.getResourceConfiguration(resourceType)?.operations ?? [];
+        const supportsDeleteMany = operations.some((operation) => isServiceResolvableDefaultOperation(operation, CoreResourceOperation.DELETE_MANY));
+        const operationIdentifier = supportsDeleteMany ? CoreResourceOperation.DELETE_MANY : CoreResourceOperation.DELETE;
+        const deleteOpPath = this.resourcesRegistry.getServiceOperationPathDefault(resourceType, operationIdentifier);
+        const deleteEc = await this.executionContextCreator.createForInternalOperation({
+            operation: deleteOpPath,
+            contextResourcesFieldIdentifier: new Map(),
+            initiatorIds: null,
+            initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
+        });
+        if (supportsDeleteMany) {
+            await this.servicesRegistryHandler.deleteMany(resourceType, deleteEc, ids);
+            return;
+        }
+        for (const id of ids) {
+            await this.servicesRegistryHandler.delete(resourceType, deleteEc, id);
+        }
+    }
     async deleteExistingUserRecords(resourceType, userId) {
         const listOpPath = this.resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.LIST);
         const listEc = await this.executionContextCreator.createForInternalOperation({
@@ -456,15 +763,8 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
         });
         const existing = await this.servicesRegistryHandler.list(resourceType, listEc, undefined, undefined, { paginated: false });
         if (existing && existing.length > 0) {
-            const deleteOpPath = this.resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.DELETE_MANY);
-            const deleteEc = await this.executionContextCreator.createForInternalOperation({
-                operation: deleteOpPath,
-                contextResourcesFieldIdentifier: new Map(),
-                initiatorIds: null,
-                initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
-            });
             const ids = existing.map((r) => r._id);
-            await this.servicesRegistryHandler.deleteMany(resourceType, deleteEc, ids);
+            await this.deleteOwnedRecords(resourceType, ids);
             this.logDebug('Deleted existing user records (REPLACE policy)', { resourceType, userId, count: ids.length });
         }
     }
@@ -480,9 +780,43 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
         const maxIterations = options?.maxIterations ?? 100;
         const convertedRetentionMs = options?.convertedRetentionMs ?? NINETY_DAYS_MS;
         const cutoff = new Date(Date.now() - sessionTtlMs);
+        const emptyReconciliation = {
+            candidatesExamined: 0, sessionsRepaired: 0, sessionsStillIncomplete: 0,
+            resourceTypesTransposed: 0, resourceTypesDiscarded: 0, errors: 0,
+        };
         if (!this.configService.anonymousSessionsEnabled) {
             this.logDebug('Anonymous sessions not enabled — skipping cleanup');
-            return { expiredUsersFound: 0, resourcesDeleted: 0, usersArchived: 0, convertedUsersCleaned: 0, errors: 0 };
+            return {
+                expiredUsersFound: 0, resourcesDeleted: 0, usersArchived: 0, convertedUsersCleaned: 0, errors: 0,
+                transpositionsReconciled: emptyReconciliation,
+            };
+        }
+        // ── Phase 0: finish the transpositions that stopped part-way ──
+        //
+        // BEFORE the two deletion phases, deliberately. This batch is the only recurring pass over the
+        // anonymous-session population, so it is where a half-finished conversion is either repaired or
+        // walked past forever — and phase 2 removes the converted AnonymousUser row (the sole record of
+        // which account the leftovers belong to) once retention expires. Repairing first means the row
+        // is only ever retired after its data has been asked about.
+        //
+        // Not gated on the deletion options: a reconciliation is a repair, not a cleanup, and an
+        // operator narrowing the TTL for a cleanup run has said nothing about repairs.
+        let transpositionsReconciled = emptyReconciliation;
+        try {
+            transpositionsReconciled = await this.reconcileIncompleteTranspositions({
+                batchSize: options?.batchSize,
+                maxIterations: options?.maxIterations,
+            });
+        }
+        catch (error) {
+            // Best effort ONLY at this seam, and for one reason: the deletion phases below must still run
+            // if the repair pass cannot. A repair that did not happen is retried tomorrow; a cleanup that
+            // never runs grows unbounded. Per-session failures are already surfaced at ERROR inside the
+            // reconciliation, so nothing is being hidden here — this catch only sees a failure of the pass
+            // as a whole (a LIST that could not be issued).
+            this.logger.error('Anonymous transposition reconciliation pass failed — continuing with cleanup', {
+                ...projectCaughtErrorLogFields(error),
+            });
         }
         const anonymizableTypes = this.getAnonymizableResourceTypes();
         let totalExpiredUsersFound = 0;
@@ -520,14 +854,7 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
                         const records = await this.listAnonymousRecords(resourceType, anonymousUserRef);
                         if (records && records.length > 0) {
                             const ids = records.map((r) => r._id);
-                            const deleteOpPath = this.resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.DELETE_MANY);
-                            const deleteEc = await this.executionContextCreator.createForInternalOperation({
-                                operation: deleteOpPath,
-                                contextResourcesFieldIdentifier: new Map(),
-                                initiatorIds: null,
-                                initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
-                            });
-                            await this.servicesRegistryHandler.deleteMany(resourceType, deleteEc, ids);
+                            await this.deleteOwnedRecords(resourceType, ids);
                             resourcesDeleted += ids.length;
                         }
                     }
@@ -590,8 +917,12 @@ let AnonymousSessionBackendService = class AnonymousSessionBackendService {
             expiredUsersFound: totalExpiredUsersFound, resourcesDeleted, usersArchived,
             convertedUsersCleaned, errors, iterations: iteration,
             anonymizableTypes: anonymizableTypes.length,
+            transpositionsReconciled,
         });
-        return { expiredUsersFound: totalExpiredUsersFound, resourcesDeleted, usersArchived, convertedUsersCleaned, errors };
+        return {
+            expiredUsersFound: totalExpiredUsersFound, resourcesDeleted, usersArchived, convertedUsersCleaned, errors,
+            transpositionsReconciled,
+        };
     }
     getAnonymizableResourceTypes() {
         const allTypes = this.resourcesRegistry.getResourceTypes();