@dappermountain/payload-plugin-achievements 0.1.0 → 0.2.1

package/dist/services/achievement/grantSideEffects.js

@@ -0,0 +1,269 @@
+import { collectionOf } from '../../collections/helpers';
+import { CTX_CASCADING_REVOKE, CTX_SYSTEM_REQUEST } from './contextFlags';
+import { evaluateRules, ruleGroupHasProgressRequirements } from './evaluateRules';
+import { recordLog, syncTierChangedLog } from './recordEvent';
+import { relationId } from './relationId';
+import { syncTierProgression } from './tierProgression';
+import { userScopeWhere } from './where';
+export { CTX_CASCADING_REVOKE, CTX_SKIP_GRANT_SIDE_EFFECTS, CTX_SYSTEM_REQUEST } from './contextFlags';
+/** Create a grant row only — side effects run in Grants afterChange. */
+export async function createGrantRow(args) {
+    const scopeId = args.scopeId ?? null;
+    const clauses = [
+        { user: { equals: args.userId } },
+        { achievement: { equals: args.achievementId } },
+    ];
+    if (scopeId)
+        clauses.push({ scope: { equals: scopeId } });
+    else
+        clauses.push({ scope: { exists: false } });
+    const existing = await args.req.payload.find({
+        collection: collectionOf('grants'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { and: clauses },
+    });
+    if (existing.docs[0])
+        return existing.docs[0];
+    return (await args.req.payload.create({
+        collection: collectionOf('grants'),
+        data: {
+            user: args.userId,
+            scope: scopeId ?? undefined,
+            achievement: args.achievementId,
+            completedAt: args.completedAt ?? new Date().toISOString(),
+            ...(args.note ? { note: args.note } : {}),
+        },
+        overrideAccess: true,
+        req: args.req,
+    }));
+}
+/** Ensure a pending achievement request exists (system / reconcile path). */
+export async function ensureAchievementRequest(args) {
+    const scopeId = args.scopeId ?? null;
+    const clauses = [
+        { user: { equals: args.userId } },
+        { achievement: { equals: args.achievementId } },
+        { status: { in: ['pending', 'approved'] } },
+    ];
+    if (scopeId)
+        clauses.push({ scope: { equals: scopeId } });
+    else
+        clauses.push({ scope: { exists: false } });
+    const existing = await args.req.payload.find({
+        collection: collectionOf('achievementRequests'),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { and: clauses },
+    });
+    if (existing.docs[0]) {
+        return { doc: existing.docs[0], created: false };
+    }
+    args.req.context[CTX_SYSTEM_REQUEST] = true;
+    try {
+        const doc = (await args.req.payload.create({
+            collection: collectionOf('achievementRequests'),
+            data: {
+                user: args.userId,
+                scope: scopeId ?? undefined,
+                achievement: args.achievementId,
+                status: 'pending',
+            },
+            overrideAccess: true,
+            req: args.req,
+        }));
+        return { doc, created: true };
+    }
+    finally {
+        delete args.req.context[CTX_SYSTEM_REQUEST];
+    }
+}
+/**
+ * Auto-grant or open a request for composed achievements whose completion rules pass.
+ */
+export async function syncCompositeProgression(args) {
+    const where = args.scopeId
+        ? { or: [{ scope: { equals: args.scopeId } }, { scope: { exists: false } }] }
+        : undefined;
+    const catalog = await args.req.payload.find({
+        collection: collectionOf('achievements'),
+        depth: 0,
+        limit: 500,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        ...(where ? { where } : {}),
+    });
+    let granted = 0;
+    let requested = 0;
+    for (const doc of catalog.docs) {
+        const def = doc;
+        if (!ruleGroupHasProgressRequirements(def.completionRules))
+            continue;
+        const complete = await evaluateRules({
+            payload: args.req.payload,
+            req: args.req,
+            rules: def.completionRules,
+            userId: args.userId,
+            scopeId: args.scopeId,
+        });
+        if (!complete)
+            continue;
+        if (def.requiresReview !== false) {
+            const { created } = await ensureAchievementRequest({
+                req: args.req,
+                userId: args.userId,
+                achievementId: String(def.id),
+                scopeId: args.scopeId,
+            });
+            if (created)
+                requested += 1;
+            continue;
+        }
+        const before = await args.req.payload.find({
+            collection: collectionOf('grants'),
+            depth: 0,
+            limit: 1,
+            overrideAccess: true,
+            req: args.req,
+            where: {
+                and: [
+                    { user: { equals: args.userId } },
+                    { achievement: { equals: String(def.id) } },
+                    ...(args.scopeId
+                        ? [{ scope: { equals: args.scopeId } }]
+                        : [{ scope: { exists: false } }]),
+                ],
+            },
+        });
+        if (before.docs[0])
+            continue;
+        await createGrantRow({
+            req: args.req,
+            userId: args.userId,
+            achievementId: String(def.id),
+            scopeId: args.scopeId,
+        });
+        granted += 1;
+    }
+    return { granted, requested };
+}
+/** Delete grants for composed achievements that no longer pass completion rules. */
+export async function revokeIncompleteComposites(args) {
+    const grants = await args.req.payload.find({
+        collection: collectionOf('grants'),
+        depth: 0,
+        limit: 500,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: userScopeWhere(args.userId, args.scopeId),
+    });
+    let revoked = 0;
+    for (const grant of grants.docs) {
+        const achievementId = relationId(grant.achievement);
+        if (!achievementId)
+            continue;
+        const def = (await args.req.payload.findByID({
+            collection: collectionOf('achievements'),
+            id: achievementId,
+            depth: 0,
+            overrideAccess: true,
+            req: args.req,
+        }));
+        if (!def || !ruleGroupHasProgressRequirements(def.completionRules))
+            continue;
+        const complete = await evaluateRules({
+            payload: args.req.payload,
+            req: args.req,
+            rules: def.completionRules,
+            userId: args.userId,
+            scopeId: args.scopeId,
+        });
+        if (complete)
+            continue;
+        args.req.context[CTX_CASCADING_REVOKE] = true;
+        try {
+            await args.req.payload.delete({
+                collection: collectionOf('grants'),
+                id: String(grant.id),
+                overrideAccess: true,
+                req: args.req,
+            });
+            revoked += 1;
+        }
+        finally {
+            delete args.req.context[CTX_CASCADING_REVOKE];
+        }
+    }
+    return revoked;
+}
+export async function runAfterGrantCreated(args) {
+    await recordLog({
+        payload: args.req.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+        type: 'achievement.granted',
+        data: {
+            achievement: args.achievementId,
+            ...(args.achievementSlug ? { achievementSlug: args.achievementSlug } : {}),
+        },
+    });
+    await syncCompositeProgression({
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+    await syncTierProgression({
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+    await syncTierChangedLog({
+        payload: args.req.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+}
+export async function runAfterGrantDeleted(args) {
+    await recordLog({
+        payload: args.req.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+        type: 'achievement.revoked',
+        data: {
+            achievement: args.achievementId,
+            ...(args.achievementSlug ? { achievementSlug: args.achievementSlug } : {}),
+        },
+    });
+    if (args.cascading)
+        return;
+    await revokeIncompleteComposites({
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+    await syncCompositeProgression({
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+    await syncTierProgression({
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+    await syncTierChangedLog({
+        payload: args.req.payload,
+        req: args.req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+    });
+}

package/dist/services/achievement/index.d.ts

@@ -11,4 +11,10 @@ export type { TierLadderProgress } from './resolveTierProgress';
 export { grantAchievement, submitAchievementRequest } from './submitAchievementRequest';
 export { reviewAchievementRequest } from './reviewAchievementRequest';
 export { validateRuleGroup, validateRuleNode } from './validateRules';
+export { syncCompositeProgression } from './grantSideEffects';
+export { syncTierProgression } from './tierProgression';
+export { reconcileProgression, reconcileUserProgression } from './reconcile';
+export type { ReconcileProgressionArgs, ReconcileProgressionResult } from './reconcile';
+export { didDisableRequiresReview, releasePendingAchievementReviews, releasePendingTierReviews, } from './releaseReviewGate';
+export type { ReleaseReviewGateResult } from './releaseReviewGate';
 //# sourceMappingURL=index.d.ts.map

package/dist/services/achievement/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAA;AACzH,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACxE,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AACzE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAA;AACzH,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACxE,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AACzE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAC5E,YAAY,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/services/achievement/index.js

@@ -7,3 +7,7 @@ export { resolveTierProgress } from './resolveTierProgress';
 export { grantAchievement, submitAchievementRequest } from './submitAchievementRequest';
 export { reviewAchievementRequest } from './reviewAchievementRequest';
 export { validateRuleGroup, validateRuleNode } from './validateRules';
+export { syncCompositeProgression } from './grantSideEffects';
+export { syncTierProgression } from './tierProgression';
+export { reconcileProgression, reconcileUserProgression } from './reconcile';
+export { didDisableRequiresReview, releasePendingAchievementReviews, releasePendingTierReviews, } from './releaseReviewGate';

package/dist/services/achievement/reconcile.d.ts

@@ -0,0 +1,36 @@
+import type { Payload, PayloadRequest } from 'payload';
+export type ReconcileProgressionResult = {
+    usersScanned: number;
+    grantedLogsBackfilled: number;
+    compositesGranted: number;
+    achievementRequestsEnsured: number;
+    tierRequestsEnsured: number;
+    tierLogsWritten: number;
+};
+export type ReconcileProgressionArgs = {
+    payload: Payload;
+    req?: PayloadRequest;
+    /** Limit to one member. */
+    userId?: string | null;
+    scopeId?: string | null;
+    /** Limit discovery to grants / requests for this achievement (id or slug). */
+    achievementId?: string | null;
+    achievementSlug?: string | null;
+    /** Limit discovery to tier requests for this tier (id or slug). */
+    tierId?: string | null;
+    tierSlug?: string | null;
+    limit?: number;
+};
+/** Repair progression for one user (+ optional scope) from current grants + catalog. */
+export declare function reconcileUserProgression(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    userId: string;
+    scopeId?: string | null;
+}): Promise<Omit<ReconcileProgressionResult, 'usersScanned'>>;
+/**
+ * Scan matching (user, scope) pairs and repair progression.
+ * Optional filters: `userId`, `scopeId`, `achievementId`/`achievementSlug`, `tierId`/`tierSlug`.
+ */
+export declare function reconcileProgression(args: ReconcileProgressionArgs): Promise<ReconcileProgressionResult>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/services/achievement/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAY7D,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAA;IACpB,qBAAqB,EAAE,MAAM,CAAA;IAC7B,iBAAiB,EAAE,MAAM,CAAA;IACzB,0BAA0B,EAAE,MAAM,CAAA;IAClC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAsFD,wFAAwF;AACxF,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC,CAAC,CAoC5D;AA2LD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,0BAA0B,CAAC,CA8CrC"}

package/dist/services/achievement/reconcile.js

@@ -0,0 +1,292 @@
+import { collectionOf } from '../../collections/helpers';
+import { syncCompositeProgression, } from './grantSideEffects';
+import { recordLog, syncTierChangedLog } from './recordEvent';
+import { relationId } from './relationId';
+import { resolveCatalogId } from './resolveCatalog';
+import { syncTierProgression } from './tierProgression';
+import { userScopeWhere } from './where';
+async function backfillGrantedLogs(args) {
+    const typeId = await resolveCatalogId({
+        payload: args.req.payload,
+        req: args.req,
+        key: 'eventTypes',
+        slugOrId: 'achievement.granted',
+    });
+    const grants = await args.req.payload.find({
+        collection: collectionOf('grants'),
+        depth: 0,
+        limit: 500,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: userScopeWhere(args.userId, args.scopeId),
+    });
+    const logs = await args.req.payload.find({
+        collection: collectionOf('logs'),
+        depth: 0,
+        limit: 500,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            and: [userScopeWhere(args.userId, args.scopeId), { type: { equals: typeId } }],
+        },
+    });
+    const logged = new Set(logs.docs
+        .map((log) => relationId(log.data?.achievement))
+        .filter((id) => Boolean(id)));
+    let written = 0;
+    for (const grant of grants.docs) {
+        const achievementId = relationId(grant.achievement);
+        if (!achievementId || logged.has(achievementId))
+            continue;
+        let slug;
+        try {
+            const def = (await args.req.payload.findByID({
+                collection: collectionOf('achievements'),
+                id: achievementId,
+                depth: 0,
+                overrideAccess: true,
+                req: args.req,
+                select: { slug: true },
+            }));
+            slug = def?.slug;
+        }
+        catch {
+            // ignore
+        }
+        const completedAt = grant.completedAt;
+        await recordLog({
+            payload: args.req.payload,
+            req: args.req,
+            userId: args.userId,
+            scopeId: args.scopeId,
+            type: 'achievement.granted',
+            data: {
+                achievement: achievementId,
+                ...(slug ? { achievementSlug: slug } : {}),
+                backfilled: true,
+                ...(completedAt ? { completedAt } : {}),
+            },
+        });
+        logged.add(achievementId);
+        written += 1;
+    }
+    return written;
+}
+/** Repair progression for one user (+ optional scope) from current grants + catalog. */
+export async function reconcileUserProgression(args) {
+    const scopeId = args.scopeId ?? null;
+    const req = args.req ??
+        {
+            payload: args.payload,
+            context: {},
+        };
+    if (!req.context)
+        req.context = {};
+    const grantedLogsBackfilled = await backfillGrantedLogs({ req, userId: args.userId, scopeId });
+    const composites = await syncCompositeProgression({
+        req,
+        userId: args.userId,
+        scopeId,
+    });
+    const tiers = await syncTierProgression({
+        req,
+        userId: args.userId,
+        scopeId,
+    });
+    const tierLog = await syncTierChangedLog({
+        payload: args.payload,
+        req,
+        userId: args.userId,
+        scopeId,
+    });
+    return {
+        grantedLogsBackfilled,
+        compositesGranted: composites.granted,
+        achievementRequestsEnsured: composites.requested,
+        tierRequestsEnsured: tiers.requested,
+        tierLogsWritten: tierLog ? 1 : 0,
+    };
+}
+function scopeKey(scope) {
+    const id = relationId(scope);
+    return id ?? '';
+}
+function addPair(pairs, userId, scopeId, filterUserId, filterScopeId) {
+    if (!userId)
+        return;
+    if (filterUserId && userId !== filterUserId)
+        return;
+    if (filterScopeId != null && filterScopeId !== '' && scopeId !== filterScopeId)
+        return;
+    const key = `${userId}::${scopeKey(scopeId)}`;
+    if (!pairs.has(key))
+        pairs.set(key, { userId, scopeId });
+}
+async function resolveDefinitionId(args) {
+    if (args.id && args.id.length > 0)
+        return args.id;
+    if (!args.slug || args.slug.length === 0)
+        return null;
+    const found = await args.payload.find({
+        collection: collectionOf(args.collection),
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        req: args.req,
+        where: { slug: { equals: args.slug } },
+    });
+    return relationId(found.docs[0]?.id) ?? null;
+}
+async function collectPairs(args) {
+    const pairs = new Map();
+    const filterUserId = args.userId?.trim() || null;
+    const filterScopeId = args.scopeId ?? null;
+    const achievementId = await resolveDefinitionId({
+        payload: args.payload,
+        req: args.req,
+        collection: 'achievements',
+        id: args.achievementId,
+        slug: args.achievementSlug,
+    });
+    const tierId = await resolveDefinitionId({
+        payload: args.payload,
+        req: args.req,
+        collection: 'tiers',
+        id: args.tierId,
+        slug: args.tierSlug,
+    });
+    if (filterUserId && !achievementId && !tierId) {
+        addPair(pairs, filterUserId, filterScopeId);
+        return [...pairs.values()];
+    }
+    if (achievementId) {
+        const grantWhere = {
+            and: [
+                { achievement: { equals: achievementId } },
+                ...(filterUserId ? [{ user: { equals: filterUserId } }] : []),
+                ...(filterScopeId
+                    ? [{ scope: { equals: filterScopeId } }]
+                    : []),
+            ],
+        };
+        const grants = await args.payload.find({
+            collection: collectionOf('grants'),
+            depth: 0,
+            limit: args.limit,
+            pagination: false,
+            overrideAccess: true,
+            req: args.req,
+            where: grantWhere,
+        });
+        for (const grant of grants.docs) {
+            addPair(pairs, relationId(grant.user), relationId(grant.scope), filterUserId, filterScopeId);
+        }
+        const requestWhere = {
+            and: [
+                { achievement: { equals: achievementId } },
+                ...(filterUserId ? [{ user: { equals: filterUserId } }] : []),
+                ...(filterScopeId ? [{ scope: { equals: filterScopeId } }] : []),
+            ],
+        };
+        const requests = await args.payload.find({
+            collection: collectionOf('achievementRequests'),
+            depth: 0,
+            limit: args.limit,
+            pagination: false,
+            overrideAccess: true,
+            req: args.req,
+            where: requestWhere,
+        });
+        for (const request of requests.docs) {
+            addPair(pairs, relationId(request.user), relationId(request.scope), filterUserId, filterScopeId);
+        }
+    }
+    if (tierId) {
+        const requestWhere = {
+            and: [
+                { tier: { equals: tierId } },
+                ...(filterUserId ? [{ user: { equals: filterUserId } }] : []),
+                ...(filterScopeId ? [{ scope: { equals: filterScopeId } }] : []),
+            ],
+        };
+        const requests = await args.payload.find({
+            collection: collectionOf('tierRequests'),
+            depth: 0,
+            limit: args.limit,
+            pagination: false,
+            overrideAccess: true,
+            req: args.req,
+            where: requestWhere,
+        });
+        for (const request of requests.docs) {
+            addPair(pairs, relationId(request.user), relationId(request.scope), filterUserId, filterScopeId);
+        }
+    }
+    if (!achievementId && !tierId) {
+        const where = filterScopeId
+            ? { scope: { equals: filterScopeId } }
+            : undefined;
+        const grants = await args.payload.find({
+            collection: collectionOf('grants'),
+            depth: 0,
+            limit: args.limit,
+            pagination: false,
+            overrideAccess: true,
+            req: args.req,
+            ...(where ? { where } : {}),
+        });
+        for (const grant of grants.docs) {
+            addPair(pairs, relationId(grant.user), relationId(grant.scope), filterUserId, filterScopeId);
+        }
+    }
+    return [...pairs.values()];
+}
+/**
+ * Scan matching (user, scope) pairs and repair progression.
+ * Optional filters: `userId`, `scopeId`, `achievementId`/`achievementSlug`, `tierId`/`tierSlug`.
+ */
+export async function reconcileProgression(args) {
+    const req = args.req ??
+        {
+            payload: args.payload,
+            context: {},
+        };
+    if (!req.context)
+        req.context = {};
+    const pairs = await collectPairs({
+        payload: args.payload,
+        req,
+        userId: args.userId,
+        scopeId: args.scopeId,
+        achievementId: args.achievementId,
+        achievementSlug: args.achievementSlug,
+        tierId: args.tierId,
+        tierSlug: args.tierSlug,
+        limit: args.limit ?? 5000,
+    });
+    const totals = {
+        usersScanned: 0,
+        grantedLogsBackfilled: 0,
+        compositesGranted: 0,
+        achievementRequestsEnsured: 0,
+        tierRequestsEnsured: 0,
+        tierLogsWritten: 0,
+    };
+    for (const pair of pairs) {
+        const result = await reconcileUserProgression({
+            payload: args.payload,
+            req,
+            userId: pair.userId,
+            scopeId: pair.scopeId,
+        });
+        totals.usersScanned += 1;
+        totals.grantedLogsBackfilled += result.grantedLogsBackfilled;
+        totals.compositesGranted += result.compositesGranted;
+        totals.achievementRequestsEnsured += result.achievementRequestsEnsured;
+        totals.tierRequestsEnsured += result.tierRequestsEnsured;
+        totals.tierLogsWritten += result.tierLogsWritten;
+    }
+    return totals;
+}

package/dist/services/achievement/recordEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recordEvent.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/recordEvent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAWtD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAgBD,6DAA6D;AAC7D,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,wEAuCnD;AAED,4CAA4C;AAC5C,eAAO,MAAM,WAAW,kBAAY,CAAA;AAEpC;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,wEAwBA;AAED,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,iFAgDA"}
+{"version":3,"file":"recordEvent.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/recordEvent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAWtD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAgBD,6DAA6D;AAC7D,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,wEAuCnD;AAED,4CAA4C;AAC5C,eAAO,MAAM,WAAW,kBAAY,CAAA;AAEpC;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,wEAiCA;AAED,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,iFAgDA"}

package/dist/services/achievement/recordEvent.js

@@ -71,6 +71,14 @@ export async function recordMetricChange(args) {
         change: args.change,
         reason: args.reason,
     });
+    if (args.req) {
+        const { syncTierProgression } = await import('./tierProgression');
+        await syncTierProgression({
+            req: args.req,
+            userId: args.userId,
+            scopeId,
+        });
+    }
     await syncTierChangedLog({
         payload: args.payload,
         req: args.req,

package/dist/services/achievement/releaseReviewGate.d.ts

@@ -0,0 +1,23 @@
+import type { PayloadRequest } from 'payload';
+export type ReleaseReviewGateResult = {
+    requestsApproved: number;
+};
+/**
+ * When a definition stops requiring review, approve each pending request for that
+ * definition so existing grant / tier.changed hooks run for that user + scope only.
+ */
+export declare function releasePendingAchievementReviews(args: {
+    req: PayloadRequest;
+    achievementId: string;
+}): Promise<ReleaseReviewGateResult>;
+export declare function releasePendingTierReviews(args: {
+    req: PayloadRequest;
+    tierId: string;
+}): Promise<ReleaseReviewGateResult>;
+/** True when `requiresReview` flipped from required → not required. */
+export declare function didDisableRequiresReview(previousDoc: {
+    requiresReview?: boolean | null;
+} | null | undefined, doc: {
+    requiresReview?: boolean | null;
+} | null | undefined): boolean;
+//# sourceMappingURL=releaseReviewGate.d.ts.map

package/dist/services/achievement/releaseReviewGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"releaseReviewGate.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/releaseReviewGate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAK7C,MAAM,MAAM,uBAAuB,GAAG;IACpC,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;;;GAGG;AACH,wBAAsB,gCAAgC,CAAC,IAAI,EAAE;IAC3D,GAAG,EAAE,cAAc,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAgCnC;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA6BnC;AAED,uEAAuE;AACvE,wBAAgB,wBAAwB,CACtC,WAAW,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EACnE,GAAG,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC1D,OAAO,CAET"}