@dappermountain/payload-plugin-achievements 0.2.0 → 0.2.2

package/README.md

@@ -261,10 +261,38 @@ const tier = await resolveCurrentTier({ payload, userId, scopeId })
 
 // Repair users whose grants predate side-effect hooks (idempotent)
 await reconcileProgression({ payload })
+
+// Optional filters (ids or slugs)
+await reconcileProgression({
+  payload,
+  userId: '…',
+  scopeId: '…',
+  achievementSlug: 'ring-grim',
+  tierSlug: 'ring-solid',
+})
+
+// Host CLI (only boot config in the app — flags live in the plugin):
+//   bun --env-file=.env ./scripts/reconcile-achievements.ts -- --user=<id> --achievement=ring-grim
+import { runReconcileCli } from '@dappermountain/payload-plugin-achievements/cli'
+await runReconcileCli({ config })
 ```
 
 Pass catalog **slugs** (or ids) for `type` and `metric`. Metric totals are the sum of `change` on matching logs. Creating or deleting **grants** (Admin or API) writes `achievement.granted` / `achievement.revoked`, syncs composed achievements, and may open tier requests / write `tier.changed`.
 
+Engine log `data` for those system events uses a shared transition envelope:
+
+```ts
+{ from: { id, slug? } | null, to: { id, slug? } | null }
+```
+
+| type | `from` | `to` |
+| --- | --- | --- |
+| `tier.changed` | previous tier (null on first climb) | current tier |
+| `achievement.granted` | `null` | achievement |
+| `achievement.revoked` | achievement | `null` |
+
+Turning **Requires review** off on a definition or tier **approves pending requests** for that row only (each waiting user goes through the existing request hooks).
+
 **Admin:** Grants list includes **Repair progression**, which `POST`s the reconcile endpoint (requires `canReview`).
 
 ## REST surface
@@ -272,7 +300,7 @@ Pass catalog **slugs** (or ids) for `type` and `metric`. Metric totals are the s
 | Goal | Request |
 | --- | --- |
 | Current user snapshot | `GET /api/achievements/me?scope=<scopeId>&limit=10&page=1` |
-| Repair progression | `POST /api/achievements/reconcile` (reviewer; optional `{ userId, scopeId, limit }`) |
+| Repair progression | `POST /api/achievements/reconcile` (reviewer; optional `{ userId, scopeId, achievementId\|achievementSlug, tierId\|tierSlug, limit }`) |
 | List grants | `GET /api/achievement-grants?where[user][equals]=<userId>` |
 | Log history | `GET /api/achievement-logs?where[user][equals]=<userId>` |
 | Request an achievement | `POST /api/achievement-requests` with `{ achievement }` |

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+export { parseReconcileCliArgs, printReconcileCliHelp, runReconcileCli, } from './reconcile';
+export type { ReconcileCliFilters } from './reconcile';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA"}

package/dist/cli/index.js

@@ -0,0 +1 @@
+export { parseReconcileCliArgs, printReconcileCliHelp, runReconcileCli, } from './reconcile';

package/dist/cli/reconcile.d.ts

@@ -0,0 +1,18 @@
+import { type SanitizedConfig } from 'payload';
+import { type ReconcileProgressionArgs, type ReconcileProgressionResult } from '../services/achievement/reconcile';
+export type ReconcileCliFilters = Omit<ReconcileProgressionArgs, 'payload' | 'req'>;
+/** Parse `--user`, `--achievement`, `--tier`, `--scope`, `--limit` (ids or slugs). */
+export declare function parseReconcileCliArgs(argv?: string[]): ReconcileCliFilters;
+export declare function printReconcileCliHelp(): void;
+/**
+ * Boot Payload from the host config and repair progression.
+ * Host scripts should only import config and call this (filters via argv or `filters`).
+ */
+export declare function runReconcileCli(args: {
+    config: SanitizedConfig | Promise<SanitizedConfig>;
+    argv?: string[];
+    filters?: ReconcileCliFilters;
+    /** When false, return the result instead of exiting the process. Default true. */
+    exit?: boolean;
+}): Promise<ReconcileProgressionResult>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/cli/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/cli/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE1D,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,mCAAmC,CAAA;AAE1C,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,KAAK,CAAC,CAAA;AA2BnF,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,mBAAmB,CAUjG;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAc5C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA2BtC"}

package/dist/cli/reconcile.js

@@ -0,0 +1,90 @@
+import { getPayload } from 'payload';
+import { reconcileProgression, } from '../services/achievement/reconcile';
+function readFlag(argv, names) {
+    for (const name of names) {
+        const prefix = `${name}=`;
+        for (const arg of argv) {
+            if (arg === name) {
+                const idx = argv.indexOf(arg);
+                const next = argv[idx + 1];
+                if (next && !next.startsWith('-'))
+                    return next;
+            }
+            if (arg.startsWith(prefix)) {
+                const value = arg.slice(prefix.length);
+                if (value)
+                    return value;
+            }
+        }
+    }
+    return undefined;
+}
+function readLimit(argv) {
+    const raw = readFlag(argv, ['--limit', '-n']);
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? Math.floor(n) : undefined;
+}
+/** Parse `--user`, `--achievement`, `--tier`, `--scope`, `--limit` (ids or slugs). */
+export function parseReconcileCliArgs(argv = process.argv.slice(2)) {
+    return {
+        userId: readFlag(argv, ['--user', '--userId']),
+        scopeId: readFlag(argv, ['--scope', '--scopeId']) ?? null,
+        achievementId: readFlag(argv, ['--achievementId']),
+        achievementSlug: readFlag(argv, ['--achievement', '--achievementSlug']),
+        tierId: readFlag(argv, ['--tierId']),
+        tierSlug: readFlag(argv, ['--tier', '--tierSlug']),
+        limit: readLimit(argv),
+    };
+}
+export function printReconcileCliHelp() {
+    // eslint-disable-next-line no-console -- CLI help
+    console.log(`Usage: achievements reconcile [options]
+
+Options:
+  --user, --userId <id>
+  --scope, --scopeId <id>
+  --achievement, --achievementSlug <slug>
+  --achievementId <id>
+  --tier, --tierSlug <slug>
+  --tierId <id>
+  --limit, -n <number>
+  --help, -h
+`);
+}
+/**
+ * Boot Payload from the host config and repair progression.
+ * Host scripts should only import config and call this (filters via argv or `filters`).
+ */
+export async function runReconcileCli(args) {
+    const argv = args.argv ?? process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        printReconcileCliHelp();
+        if (args.exit !== false)
+            process.exit(0);
+        return {
+            usersScanned: 0,
+            grantedLogsBackfilled: 0,
+            compositesGranted: 0,
+            achievementRequestsEnsured: 0,
+            tierRequestsEnsured: 0,
+            tierLogsWritten: 0,
+        };
+    }
+    const filters = args.filters ?? parseReconcileCliArgs(argv);
+    const payload = await getPayload({ config: args.config });
+    try {
+        const result = await reconcileProgression({ payload, ...filters });
+        payload.logger.info({ msg: 'achievements reconcile complete', ...filters, ...result });
+        if (args.exit !== false)
+            process.exit(0);
+        return result;
+    }
+    catch (error) {
+        payload.logger.error({ err: error, msg: 'achievements reconcile failed' });
+        if (args.exit !== false)
+            process.exit(1);
+        throw error;
+    }
+}

package/dist/collections/Achievements/hooks/afterRequiresReviewDisabled.d.ts

@@ -0,0 +1,7 @@
+import type { CollectionAfterChangeHook } from 'payload';
+/**
+ * When Requires review is turned off, approve pending requests for this achievement
+ * so each waiting user is granted via existing request hooks.
+ */
+export declare const afterRequiresReviewDisabled: CollectionAfterChangeHook;
+//# sourceMappingURL=afterRequiresReviewDisabled.d.ts.map

package/dist/collections/Achievements/hooks/afterRequiresReviewDisabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afterRequiresReviewDisabled.d.ts","sourceRoot":"","sources":["../../../../src/collections/Achievements/hooks/afterRequiresReviewDisabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAOxD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,yBAmBzC,CAAA"}

package/dist/collections/Achievements/hooks/afterRequiresReviewDisabled.js

@@ -0,0 +1,15 @@
+import { didDisableRequiresReview, releasePendingAchievementReviews, } from '../../../services/achievement/releaseReviewGate';
+/**
+ * When Requires review is turned off, approve pending requests for this achievement
+ * so each waiting user is granted via existing request hooks.
+ */
+export const afterRequiresReviewDisabled = async ({ doc, operation, previousDoc, req, }) => {
+    if (operation !== 'update')
+        return doc;
+    if (!didDisableRequiresReview(previousDoc, doc)) {
+        return doc;
+    }
+    const achievementId = String(doc.id);
+    await releasePendingAchievementReviews({ req, achievementId });
+    return doc;
+};

package/dist/collections/Achievements/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Achievements/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C,eAAO,MAAM,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAE3C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Achievements/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAK/C,eAAO,MAAM,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAG3C,CAAA"}

package/dist/collections/Achievements/hooks/index.js

@@ -1,4 +1,6 @@
+import { afterRequiresReviewDisabled } from './afterRequiresReviewDisabled';
 import { validateAchievementRules } from './validateEligibilityRules';
 export const hooks = {
     beforeValidate: [validateAchievementRules],
+    afterChange: [afterRequiresReviewDisabled],
 };

package/dist/collections/Achievements/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Achievements/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAO/C,wBAAgB,2BAA2B,IAAI,gBAAgB,CA0D9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Achievements/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAO/C,wBAAgB,2BAA2B,IAAI,gBAAgB,CA8D9D"}

package/dist/collections/Achievements/index.js

@@ -38,6 +38,9 @@ export function buildAchievementsCollection() {
                 type: 'checkbox',
                 defaultValue: true,
                 label: 'Requires review',
+                admin: {
+                    description: 'When turned off, any pending requests for this achievement are approved automatically (one user at a time via existing grant hooks).',
+                },
             },
             {
                 name: 'eligibilityRules',

package/dist/collections/Logs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Logs/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAUtD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,gBAAgB,CA0GtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Logs/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAUtD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,gBAAgB,CA6GtD"}

package/dist/collections/Logs/index.js

@@ -104,7 +104,9 @@ export function buildLogsCollection() {
                     {
                         name: 'data',
                         type: 'json',
-                        admin: { description: 'Any extra structured details.' },
+                        admin: {
+                            description: 'Engine transition envelope: `{ from, to }` each `{ id, slug? }` or null (tier.changed, achievement.granted/revoked). Hosts may add extra keys.',
+                        },
                     },
                 ],
             },

package/dist/collections/Tiers/hooks/afterRequiresReviewDisabled.d.ts

@@ -0,0 +1,7 @@
+import type { CollectionAfterChangeHook } from 'payload';
+/**
+ * When Requires review is turned off, approve pending tier requests for this step
+ * so each waiting user gets a tier.changed audit via existing request hooks.
+ */
+export declare const afterRequiresReviewDisabled: CollectionAfterChangeHook;
+//# sourceMappingURL=afterRequiresReviewDisabled.d.ts.map

package/dist/collections/Tiers/hooks/afterRequiresReviewDisabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afterRequiresReviewDisabled.d.ts","sourceRoot":"","sources":["../../../../src/collections/Tiers/hooks/afterRequiresReviewDisabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAOxD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,yBAmBzC,CAAA"}

package/dist/collections/Tiers/hooks/afterRequiresReviewDisabled.js

@@ -0,0 +1,15 @@
+import { didDisableRequiresReview, releasePendingTierReviews, } from '../../../services/achievement/releaseReviewGate';
+/**
+ * When Requires review is turned off, approve pending tier requests for this step
+ * so each waiting user gets a tier.changed audit via existing request hooks.
+ */
+export const afterRequiresReviewDisabled = async ({ doc, operation, previousDoc, req, }) => {
+    if (operation !== 'update')
+        return doc;
+    if (!didDisableRequiresReview(previousDoc, doc)) {
+        return doc;
+    }
+    const tierId = String(doc.id);
+    await releasePendingTierReviews({ req, tierId });
+    return doc;
+};

package/dist/collections/Tiers/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Tiers/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C,eAAO,MAAM,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAE3C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/collections/Tiers/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAK/C,eAAO,MAAM,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAG3C,CAAA"}

package/dist/collections/Tiers/hooks/index.js

@@ -1,4 +1,6 @@
+import { afterRequiresReviewDisabled } from './afterRequiresReviewDisabled';
 import { validateUnlockRules } from './validateUnlockRules';
 export const hooks = {
     beforeValidate: [validateUnlockRules],
+    afterChange: [afterRequiresReviewDisabled],
 };

package/dist/collections/Tiers/index.js

@@ -72,7 +72,7 @@ export function buildTiersCollection() {
                 type: 'checkbox',
                 defaultValue: false,
                 admin: {
-                    description: 'When enabled, unlock rules alone are not enough — an approved tier request is required before this step becomes the member’s current tier.',
+                    description: 'When enabled, unlock rules alone are not enough — an approved tier request is required before this step becomes the member’s current tier. Turning it off approves pending requests for this tier automatically.',
                 },
             },
             {

package/dist/endpoints/reconcile.d.ts

@@ -1,7 +1,7 @@
 import type { Endpoint } from 'payload';
 /**
- * `POST` repair progression from existing grants.
- * Body (optional): `{ userId?, scopeId?, limit? }`.
+ * `POST` repair progression from existing grants / requests.
+ * Body (optional): `{ userId?, scopeId?, achievementId?, achievementSlug?, tierId?, tierSlug?, limit? }`.
  * Requires host `canReview`.
  */
 export declare function buildReconcileEndpoint(path: string): Endpoint;

package/dist/endpoints/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/endpoints/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAA;AAsBvD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAsD7D"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/endpoints/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAA;AAoCvD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CA2C7D"}

package/dist/endpoints/reconcile.js

@@ -1,6 +1,6 @@
 import { getUserId } from '../access/helpers/index';
 import { getAchievementOptions } from '../options-store';
-import { reconcileProgression, reconcileUserProgression } from '../services/achievement/reconcile';
+import { reconcileProgression } from '../services/achievement/reconcile';
 function requestUrl(req) {
     return req.url ? new URL(req.url, 'http://local') : null;
 }
@@ -17,9 +17,20 @@ async function readBody(req) {
     }
     return {};
 }
+function stringParam(body, url, keys) {
+    for (const key of keys) {
+        const fromBody = body[key];
+        if (typeof fromBody === 'string' && fromBody.length > 0)
+            return fromBody;
+        const fromUrl = url?.searchParams.get(key);
+        if (fromUrl && fromUrl.length > 0)
+            return fromUrl;
+    }
+    return null;
+}
 /**
- * `POST` repair progression from existing grants.
- * Body (optional): `{ userId?, scopeId?, limit? }`.
+ * `POST` repair progression from existing grants / requests.
+ * Body (optional): `{ userId?, scopeId?, achievementId?, achievementSlug?, tierId?, tierSlug?, limit? }`.
  * Requires host `canReview`.
  */
 export function buildReconcileEndpoint(path) {
@@ -37,31 +48,23 @@ export function buildReconcileEndpoint(path) {
             }
             const body = await readBody(req);
             const url = requestUrl(req);
-            const scopeIdRaw = (typeof body.scopeId === 'string' && body.scopeId) ||
-                url?.searchParams.get('scopeId') ||
-                url?.searchParams.get('scope') ||
-                null;
-            const scopeId = scopeIdRaw && scopeIdRaw.length > 0 ? scopeIdRaw : null;
+            const scopeId = stringParam(body, url, ['scopeId', 'scope']);
             if (!(await canReview(req.user, scopeId))) {
                 return Response.json({ errors: [{ message: 'Forbidden' }] }, { status: 403 });
             }
-            const userId = typeof body.userId === 'string' && body.userId.length > 0 ? body.userId : null;
-            const limit = typeof body.limit === 'number' && Number.isFinite(body.limit)
-                ? Math.floor(body.limit)
+            const limitRaw = body.limit;
+            const limit = typeof limitRaw === 'number' && Number.isFinite(limitRaw)
+                ? Math.floor(limitRaw)
                 : undefined;
-            if (userId) {
-                const result = await reconcileUserProgression({
-                    payload: req.payload,
-                    req,
-                    userId,
-                    scopeId,
-                });
-                return Response.json({ ok: true, usersScanned: 1, ...result });
-            }
             const result = await reconcileProgression({
                 payload: req.payload,
                 req,
                 scopeId,
+                userId: stringParam(body, url, ['userId', 'user']),
+                achievementId: stringParam(body, url, ['achievementId']),
+                achievementSlug: stringParam(body, url, ['achievementSlug', 'achievement']),
+                tierId: stringParam(body, url, ['tierId']),
+                tierSlug: stringParam(body, url, ['tierSlug', 'tier']),
                 limit,
             });
             return Response.json({ ok: true, ...result });

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export type { EngineEventTypeSlug, EngineMetricSlug } from './catalog';
 export { achievementPlugin } from './plugin';
 export { seedAchievementCatalog, seedAchievements } from './seed/index';
 export type { AchievementSeedAchievement, AchievementSeedCatalogRow, AchievementSeedInput, AchievementSeedLocalizedText, AchievementSeedTier, } from './seed/index';
-export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, getUserProgress, grantAchievement, recordEvent, recordLog, recordMetricChange, reconcileProgression, reconcileUserProgression, resolveCurrentTier, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, validateRuleGroup, validateRuleNode, } from './services/achievement/index';
-export type { ResolvedTier, RuleGroup, TierLadderProgress, CatalogProgressGroup, CatalogProgressItem, ReconcileProgressionResult, } from './services/achievement/index';
+export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, getUserProgress, grantAchievement, recordEvent, recordLog, recordMetricChange, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index';
+export type { ResolvedTier, RuleGroup, TierLadderProgress, CatalogProgressGroup, CatalogProgressItem, CatalogRef, TransitionLogData, ReconcileProgressionArgs, ReconcileProgressionResult, ReleaseReviewGateResult, } from './services/achievement/index';
 export type { BuiltInEventType, BuiltInRuleType, AchievementCollectionKey, AchievementCollectionOverride, AchievementCollectionsOptions, AchievementEndpointsOptions, AchievementPluginOptions, AchievementRuleType, AchievementScopeConfig, AchievementUsersOptions, } from './types';
 export { DEFAULT_COLLECTION_BASE_SLUGS, DEFAULT_COLLECTION_PREFIX, DEFAULT_ADMIN_GROUP } from './collections/slugs';
 export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH } from './defaults';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,kBAAkB,EAClB,cAAc,GACf,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACvE,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,8BAA8B,EAC9B,0BAA0B,EAC1B,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACnH,OAAO,EAAE,wBAAwB,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,+BAA+B,EAC/B,kBAAkB,EAClB,cAAc,GACf,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACvE,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,8BAA8B,EAC9B,0BAA0B,EAC1B,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EACjB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACnH,OAAO,EAAE,wBAAwB,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -1,7 +1,7 @@
 export { DEFAULT_ACHIEVEMENT_METRIC, DEFAULT_ACHIEVEMENT_METRIC_SLUG, ENGINE_EVENT_TYPES, ENGINE_METRICS, } from './catalog';
 export { achievementPlugin } from './plugin';
 export { seedAchievementCatalog, seedAchievements } from './seed/index';
-export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, getUserProgress, grantAchievement, recordEvent, recordLog, recordMetricChange, reconcileProgression, reconcileUserProgression, resolveCurrentTier, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, validateRuleGroup, validateRuleNode, } from './services/achievement/index';
+export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, getUserProgress, grantAchievement, recordEvent, recordLog, recordMetricChange, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index';
 export { DEFAULT_COLLECTION_BASE_SLUGS, DEFAULT_COLLECTION_PREFIX, DEFAULT_ADMIN_GROUP } from './collections/slugs';
 export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH } from './defaults';
 export { collectionOf, slugOf } from './collections/helpers';

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

@@ -1 +1 @@
-{"version":3,"file":"grantSideEffects.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/grantSideEffects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAUpD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAStG,wEAAwE;AACxE,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+BnC;AAED,6EAA6E;AAC7E,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAuC9D;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAsElD;AAED,oFAAoF;AACpF,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB"}
+{"version":3,"file":"grantSideEffects.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/grantSideEffects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,SAAS,CAAA;AAWpD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAStG,wEAAwE;AACxE,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+BnC;AAED,6EAA6E;AAC7E,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAuC9D;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAsElD;AAED,oFAAoF;AACpF,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB"}

package/dist/services/achievement/grantSideEffects.js

@@ -1,6 +1,7 @@
 import { collectionOf } from '../../collections/helpers';
 import { CTX_CASCADING_REVOKE, CTX_SYSTEM_REQUEST } from './contextFlags';
 import { evaluateRules, ruleGroupHasProgressRequirements } from './evaluateRules';
+import { transitionLogData } from './logData';
 import { recordLog, syncTierChangedLog } from './recordEvent';
 import { relationId } from './relationId';
 import { syncTierProgression } from './tierProgression';
@@ -209,10 +210,10 @@ export async function runAfterGrantCreated(args) {
         userId: args.userId,
         scopeId: args.scopeId,
         type: 'achievement.granted',
-        data: {
-            achievement: args.achievementId,
-            ...(args.achievementSlug ? { achievementSlug: args.achievementSlug } : {}),
-        },
+        data: transitionLogData({
+            from: null,
+            to: { id: args.achievementId, slug: args.achievementSlug },
+        }),
     });
     await syncCompositeProgression({
         req: args.req,
@@ -238,10 +239,10 @@ export async function runAfterGrantDeleted(args) {
         userId: args.userId,
         scopeId: args.scopeId,
         type: 'achievement.revoked',
-        data: {
-            achievement: args.achievementId,
-            ...(args.achievementSlug ? { achievementSlug: args.achievementSlug } : {}),
-        },
+        data: transitionLogData({
+            from: { id: args.achievementId, slug: args.achievementSlug },
+            to: null,
+        }),
     });
     if (args.cascading)
         return;

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

@@ -14,5 +14,9 @@ export { validateRuleGroup, validateRuleNode } from './validateRules';
 export { syncCompositeProgression } from './grantSideEffects';
 export { syncTierProgression } from './tierProgression';
 export { reconcileProgression, reconcileUserProgression } from './reconcile';
-export type { ReconcileProgressionResult } from './reconcile';
+export type { ReconcileProgressionArgs, ReconcileProgressionResult } from './reconcile';
+export { didDisableRequiresReview, releasePendingAchievementReviews, releasePendingTierReviews, } from './releaseReviewGate';
+export type { ReleaseReviewGateResult } from './releaseReviewGate';
+export { catalogRef, transitionLogData, transitionToId, } from './logData';
+export type { CatalogRef, TransitionLogData } from './logData';
 //# 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;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,0BAA0B,EAAE,MAAM,aAAa,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;AAClE,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA"}

package/dist/services/achievement/index.js

@@ -10,3 +10,5 @@ export { validateRuleGroup, validateRuleNode } from './validateRules';
 export { syncCompositeProgression } from './grantSideEffects';
 export { syncTierProgression } from './tierProgression';
 export { reconcileProgression, reconcileUserProgression } from './reconcile';
+export { didDisableRequiresReview, releasePendingAchievementReviews, releasePendingTierReviews, } from './releaseReviewGate';
+export { catalogRef, transitionLogData, transitionToId, } from './logData';

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

@@ -0,0 +1,31 @@
+/**
+ * Shared engine shape for achievement-log `data` on system event types.
+ * Hosts may add extra keys; readers should treat unknown keys as opaque.
+ *
+ * Transition events always use `from` / `to` (either side may be null):
+ * - `tier.changed` — previous ladder step → current step
+ * - `achievement.granted` — `from: null`, `to: achievement`
+ * - `achievement.revoked` — `from: achievement`, `to: null`
+ */
+export type CatalogRef = {
+    id: string;
+    slug?: string;
+};
+export type TransitionLogData = {
+    from: CatalogRef | null;
+    to: CatalogRef | null;
+};
+export declare function catalogRef(id: string, slug?: string | null): CatalogRef;
+export declare function transitionLogData(args: {
+    from?: {
+        id: string;
+        slug?: string | null;
+    } | null;
+    to?: {
+        id: string;
+        slug?: string | null;
+    } | null;
+}): TransitionLogData;
+/** Read the “current” catalog id from a log `data` blob (new or legacy shapes). */
+export declare function transitionToId(data: unknown): string | null;
+//# sourceMappingURL=logData.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logData.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/logData.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IACvB,EAAE,EAAE,UAAU,GAAG,IAAI,CAAA;CACtB,CAAA;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,CAKvE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;IAClD,EAAE,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;CACjD,GAAG,iBAAiB,CAKpB;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAY3D"}

package/dist/services/achievement/logData.js

@@ -0,0 +1,30 @@
+export function catalogRef(id, slug) {
+    return {
+        id,
+        ...(typeof slug === 'string' && slug.length > 0 ? { slug } : {}),
+    };
+}
+export function transitionLogData(args) {
+    return {
+        from: args.from ? catalogRef(args.from.id, args.from.slug) : null,
+        to: args.to ? catalogRef(args.to.id, args.to.slug) : null,
+    };
+}
+/** Read the “current” catalog id from a log `data` blob (new or legacy shapes). */
+export function transitionToId(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const record = data;
+    const to = record.to;
+    if (to && typeof to === 'object' && !Array.isArray(to)) {
+        const id = to.id;
+        if (typeof id === 'string' && id)
+            return id;
+    }
+    // Legacy tier.changed / achievement.* shapes
+    if (typeof record.tier === 'string' && record.tier)
+        return record.tier;
+    if (typeof record.achievement === 'string' && record.achievement)
+        return record.achievement;
+    return null;
+}

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

@@ -7,6 +7,20 @@ export type ReconcileProgressionResult = {
     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;
@@ -14,11 +28,9 @@ export declare function reconcileUserProgression(args: {
     userId: string;
     scopeId?: string | null;
 }): Promise<Omit<ReconcileProgressionResult, 'usersScanned'>>;
-/** Scan grants and reconcile each distinct (user, scope) pair. */
-export declare function reconcileProgression(args: {
-    payload: Payload;
-    req?: PayloadRequest;
-    scopeId?: string | null;
-    limit?: number;
-}): Promise<ReconcileProgressionResult>;
+/**
+ * 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

@@ -1 +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;AAoFD,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;AAOD,kEAAkE;AAClE,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyDtC"}
+{"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;AAa7D,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;AAwFD,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

@@ -1,5 +1,6 @@
 import { collectionOf } from '../../collections/helpers';
 import { syncCompositeProgression, } from './grantSideEffects';
+import { transitionLogData, transitionToId } from './logData';
 import { recordLog, syncTierChangedLog } from './recordEvent';
 import { relationId } from './relationId';
 import { resolveCatalogId } from './resolveCatalog';
@@ -33,7 +34,7 @@ async function backfillGrantedLogs(args) {
         },
     });
     const logged = new Set(logs.docs
-        .map((log) => relationId(log.data?.achievement))
+        .map((log) => transitionToId(log.data))
         .filter((id) => Boolean(id)));
     let written = 0;
     for (const grant of grants.docs) {
@@ -63,10 +64,12 @@ async function backfillGrantedLogs(args) {
             scopeId: args.scopeId,
             type: 'achievement.granted',
             data: {
-                achievement: achievementId,
-                ...(slug ? { achievementSlug: slug } : {}),
-                backfilled: true,
+                ...transitionLogData({
+                    from: null,
+                    to: { id: achievementId, slug },
+                }),
                 ...(completedAt ? { completedAt } : {}),
+                backfilled: true,
             },
         });
         logged.add(achievementId);
@@ -113,7 +116,140 @@ function scopeKey(scope) {
     const id = relationId(scope);
     return id ?? '';
 }
-/** Scan grants and reconcile each distinct (user, scope) pair. */
+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 ??
         {
@@ -122,28 +258,17 @@ export async function reconcileProgression(args) {
         };
     if (!req.context)
         req.context = {};
-    const where = args.scopeId
-        ? { scope: { equals: args.scopeId } }
-        : undefined;
-    const grants = await args.payload.find({
-        collection: collectionOf('grants'),
-        depth: 0,
-        limit: args.limit ?? 5000,
-        pagination: false,
-        overrideAccess: true,
+    const pairs = await collectPairs({
+        payload: args.payload,
         req,
-        ...(where ? { where } : {}),
+        userId: args.userId,
+        scopeId: args.scopeId,
+        achievementId: args.achievementId,
+        achievementSlug: args.achievementSlug,
+        tierId: args.tierId,
+        tierSlug: args.tierSlug,
+        limit: args.limit ?? 5000,
     });
-    const pairs = new Map();
-    for (const grant of grants.docs) {
-        const userId = relationId(grant.user);
-        if (!userId)
-            continue;
-        const scopeId = relationId(grant.scope);
-        const key = `${userId}::${scopeKey(scopeId)}`;
-        if (!pairs.has(key))
-            pairs.set(key, { userId, scopeId });
-    }
     const totals = {
         usersScanned: 0,
         grantedLogsBackfilled: 0,
@@ -152,7 +277,7 @@ export async function reconcileProgression(args) {
         tierRequestsEnsured: 0,
         tierLogsWritten: 0,
     };
-    for (const pair of pairs.values()) {
+    for (const pair of pairs) {
         const result = await reconcileUserProgression({
             payload: args.payload,
             req,

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,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"}
+{"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,iFA0DA"}

package/dist/services/achievement/recordEvent.js

@@ -2,8 +2,8 @@ import { APIError } from 'payload';
 import { DEFAULT_ACHIEVEMENT_METRIC_SLUG } from '../../catalog';
 import { collectionOf } from '../../collections/helpers';
 import { eventTypeRequiresActor } from './eventTypeRequiresActor';
+import { transitionLogData, transitionToId } from './logData';
 import { resolveCatalogId } from './resolveCatalog';
-import { relationId } from './relationId';
 import { resolveCurrentTier } from './resolveCurrentTier';
 import { userScopeWhere } from './where';
 async function catalogId(args) {
@@ -113,22 +113,35 @@ export async function syncTierChangedLog(args) {
             and: [userScopeWhere(args.userId, scopeId), { type: { equals: typeId } }],
         },
     });
-    const lastTierId = relationId(latest.docs[0]?.data?.tier);
+    const latestData = latest.docs[0]?.data;
+    const lastTierId = transitionToId(latestData);
     const currentId = current?.id ?? null;
     if (lastTierId === currentId)
         return null;
     if (!currentId)
         return null;
+    let fromSlug;
+    if (latestData && typeof latestData === 'object' && !Array.isArray(latestData)) {
+        const record = latestData;
+        const to = record.to;
+        if (to && typeof to === 'object' && !Array.isArray(to)) {
+            const slug = to.slug;
+            if (typeof slug === 'string')
+                fromSlug = slug;
+        }
+        else if (typeof record.tierSlug === 'string') {
+            fromSlug = record.tierSlug;
+        }
+    }
     return recordLog({
         payload: args.payload,
         req: args.req,
         userId: args.userId,
         scopeId,
         type: 'tier.changed',
-        data: {
-            tier: currentId,
-            ...(current?.slug ? { tierSlug: current.slug } : {}),
-            ...(lastTierId ? { previousTier: lastTierId } : {}),
-        },
+        data: transitionLogData({
+            from: lastTierId ? { id: lastTierId, slug: fromSlug } : null,
+            to: { id: currentId, slug: current?.slug },
+        }),
     });
 }

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"}

package/dist/services/achievement/releaseReviewGate.js

@@ -0,0 +1,71 @@
+import { collectionOf } from '../../collections/helpers';
+import { relationId } from './relationId';
+/**
+ * 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 async function releasePendingAchievementReviews(args) {
+    const pending = await args.req.payload.find({
+        collection: collectionOf('achievementRequests'),
+        depth: 0,
+        limit: 5000,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            and: [
+                { achievement: { equals: args.achievementId } },
+                { status: { equals: 'pending' } },
+            ],
+        },
+    });
+    let requestsApproved = 0;
+    for (const doc of pending.docs) {
+        const id = relationId(doc.id);
+        if (!id)
+            continue;
+        await args.req.payload.update({
+            collection: collectionOf('achievementRequests'),
+            id,
+            data: { status: 'approved' },
+            depth: 0,
+            overrideAccess: true,
+            req: args.req,
+        });
+        requestsApproved += 1;
+    }
+    return { requestsApproved };
+}
+export async function releasePendingTierReviews(args) {
+    const pending = await args.req.payload.find({
+        collection: collectionOf('tierRequests'),
+        depth: 0,
+        limit: 5000,
+        pagination: false,
+        overrideAccess: true,
+        req: args.req,
+        where: {
+            and: [{ tier: { equals: args.tierId } }, { status: { equals: 'pending' } }],
+        },
+    });
+    let requestsApproved = 0;
+    for (const doc of pending.docs) {
+        const id = relationId(doc.id);
+        if (!id)
+            continue;
+        await args.req.payload.update({
+            collection: collectionOf('tierRequests'),
+            id,
+            data: { status: 'approved' },
+            depth: 0,
+            overrideAccess: true,
+            req: args.req,
+        });
+        requestsApproved += 1;
+    }
+    return { requestsApproved };
+}
+/** True when `requiresReview` flipped from required → not required. */
+export function didDisableRequiresReview(previousDoc, doc) {
+    return previousDoc?.requiresReview === true && doc?.requiresReview !== true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dappermountain/payload-plugin-achievements",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A robust, Admin-configured achievements engine for Payload: composable unlock rules, derived rank progress, request/review grants, metrics, and scoped multi-tenant support.",
   "license": "MIT",
   "type": "module",
@@ -28,6 +28,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js",
+      "default": "./dist/cli/index.js"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js",