@dappermountain/payload-plugin-achievements 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # `@dappermountain/payload-plugin-achievements`
 
-A Payload CMS plugin for a **rule-based achievements and ranking system** — tiers, badges, points, grants, review workflows, and an append-only activity log — configured in Admin, not hard-coded in your app.
+A Payload CMS plugin for a **rule-based achievements and ranking system** — tiers, badges, points, grants, review workflows, and an append-only activity log — configured in Admin.
 
 Most gamification features end up as one-off collections and scattered hooks. This plugin gives you a reusable engine: define *what* can be earned and *how* it unlocks in Payload Admin, then record events from your application code. Current tier and progress are **derived** from rules and history, so you don’t maintain a separate progress table that drifts out of sync.
 
@@ -16,8 +16,9 @@ Most gamification features end up as one-off collections and scattered hooks. Th
 
 ## Requirements
 
-- Payload `^3.88`
-- `@payloadcms/ui` `^3.88`
+- Payload `^3.89`
+- `@payloadcms/ui` `^3.89`
+- `@payloadcms/richtext-lexical` `^3.89`
 - React `^19`
 
 ## Install
@@ -120,7 +121,7 @@ Unlock (tiers), eligibility, and completion (achievements) share the same rule t
 | `event-count` / `metric-minimum` | Fraction of the target |
 | `achievement-complete` | `1` if granted; otherwise rolls up that achievement’s completion (or eligibility) rules |
 
-**Computed elapsed metrics** — `kind: computed` + `compute: elapsed` + `unit` (`seconds` | `minutes` | `hours` | `days` | `years`) + `since` (built-in `user-created-at` / `first-event`, or a host `metricAnchors` key). Gate tenure with `metric-minimum` against that metric. Years use a fixed 365-day length (not calendar years). System seed only creates stored `points` — product computed metrics (e.g. `days`) are host-seeded after registering anchors.
+**Computed elapsed metrics** — `kind: computed` + `compute: elapsed` + `unit` (`seconds` | `minutes` | `hours` | `days` | `years`) + `since` (built-in `user-created-at` / `first-event`, or a host `metricAnchors` key). Gate tenure with `metric-minimum` against that metric. Years use a fixed 365-day length. System seed only creates stored `points` — product computed metrics (e.g. `days`) are host-seeded after registering anchors.
 
 **Stored metrics** — totals live in `achievement-metric-balances`, updated by `recordMetricChange` (log + balance dual-write). Logs remain the audit/rebuild source; reconcile backfills balances.
 
@@ -230,6 +231,50 @@ achievementPlugin({
 | --- | --- | --- |
 | `includeJoins` | `true` | Injects an `achievements` group on the users collection with joins to grants and requests. Set `false` if you own that UI yourself. |
 
+### `subjects`
+
+Host documents that logs may point at via a polymorphic `subject` field (same idea as `requiresActor` / `requiresMetric`).
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `collections` | `[]` | Allowlist of collection slugs (e.g. `posts`, `comments`). Empty / omit → subject feature is off (no log field, no event-type subject flags). |
+
+When configured:
+
+- Event types gain **Requires a subject** + optional **Subject collections** (`subjectRelationTo`).
+- Logs gain a polymorphic **Subject** relationship (Admin links to the host doc).
+- `recordLog({ subject: { relationTo, value } })` (or `logSubject(relationTo, value)`) writes the ref.
+- Prefer `subject` over stuffing ids into `data` JSON.
+
+```ts
+achievementPlugin({
+  canReview,
+  subjects: {
+    collections: ['posts', 'comments', 'endorsements'],
+  },
+})
+
+await seedAchievements(payload, {
+  eventTypes: [
+    {
+      name: 'Comment created',
+      slug: 'comment.created',
+      requiresSubject: true,
+      subjectRelationTo: ['comments'],
+    },
+  ],
+})
+
+await recordLog({
+  payload,
+  userId,
+  scopeId,
+  type: 'comment.created',
+  actorId: userId,
+  subject: logSubject('comments', commentId),
+})
+```
+
 ### `endpoints`
 
 | Option | Default | Notes |
@@ -250,7 +295,7 @@ achievementPlugin({
   extensions: {
     metricAnchors: {
       'membership-granted': {
-        // Admin UI i18n (Payload label), not a CMS localized field
+        // Admin UI i18n (Payload label / OptionLabel)
         label: ({ t }) => t('custom:achievements:anchors:membershipGranted'),
         resolve: async ({ payload, userId, scopeId }) => {
           // return a Date from host data, or null
@@ -275,7 +320,7 @@ achievementPlugin({
 
 ## Server helpers
 
-Use these from hooks, jobs, and trusted endpoints — not from the public client:
+Use these from hooks, jobs, and trusted endpoints:
 
 ```ts
 import {
@@ -293,9 +338,18 @@ import {
   buildUnlockRequirementLeaves,
   submitAchievementRequest,
   reviewAchievementRequest,
+  logSubject,
 } from '@dappermountain/payload-plugin-achievements'
 
 await recordLog({ payload, userId, scopeId, type: 'host.custom-kind', actorId })
+await recordLog({
+  payload,
+  userId,
+  scopeId,
+  type: 'comment.created',
+  actorId: userId,
+  subject: logSubject('comments', commentId),
+})
 await recordMetricChange({ payload, userId, scopeId, metric: 'points', change: 10 })
 const points = await resolveMetricValue({ payload, userId, scopeId, metric: 'points' })
 const board = await getMetricLeaderboard({ payload, metric: 'points', scopeId, limit: 20 })
@@ -341,6 +395,8 @@ Engine log `data` for those system events uses a shared transition envelope:
 | `achievement.granted` | `null` | achievement |
 | `achievement.revoked` | achievement | `null` |
 
+Host document links belong on polymorphic **`subject`** (when `subjects.collections` is set), not inside `data`.
+
 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`).
@@ -372,7 +428,15 @@ import {
 await seedAchievementCatalog(payload) // system metrics + event types (English)
 
 await seedAchievements(payload, {
-  eventTypes: [{ name: 'Custom kind', slug: 'host.custom-kind', requiresActor: true }],
+  eventTypes: [
+    { name: 'Custom kind', slug: 'host.custom-kind', requiresActor: true },
+    {
+      name: 'Comment created',
+      slug: 'comment.created',
+      requiresSubject: true,
+      subjectRelationTo: ['comments'],
+    },
+  ],
   metrics: [{ name: 'Streak days', slug: 'streak-days' }],
   tiers: [
     {

package/dist/admin/SubjectField.d.ts

@@ -0,0 +1,14 @@
+import type { RelationshipFieldClientProps } from 'payload';
+import React from 'react';
+type SubjectFieldProps = RelationshipFieldClientProps & {
+    eventTypesSlug: string;
+    /** Plugin allowlist — used when the event type leaves `subjectRelationTo` empty. */
+    subjectCollections: string[];
+};
+/**
+ * Polymorphic subject — only when the selected event type requires a host document.
+ * Clears the value when the type does not require a subject.
+ */
+export declare function SubjectField(props: SubjectFieldProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=SubjectField.d.ts.map

package/dist/admin/SubjectField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubjectField.d.ts","sourceRoot":"","sources":["../../src/admin/SubjectField.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAE3D,OAAO,KAA6B,MAAM,OAAO,CAAA;AAIjD,KAAK,iBAAiB,GAAG,4BAA4B,GAAG;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,oFAAoF;IACpF,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAC7B,CAAA;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,4BAoCpD"}

package/dist/admin/SubjectField.js

@@ -0,0 +1,38 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RelationshipField, useField } from '@payloadcms/ui';
+import { useEffect, useMemo } from 'react';
+import { useEventTypeFlags } from './useEventTypeFlags.js';
+/**
+ * Polymorphic subject — only when the selected event type requires a host document.
+ * Clears the value when the type does not require a subject.
+ */
+export function SubjectField(props) {
+    const { eventTypesSlug, subjectCollections, ...fieldArgs } = props;
+    const { requiresSubject, subjectRelationTo } = useEventTypeFlags(eventTypesSlug);
+    const { setValue, value } = useField({ path: fieldArgs.path });
+    const allowedCollections = useMemo(() => {
+        if (subjectRelationTo.length > 0) {
+            return subjectRelationTo.filter((slug) => subjectCollections.includes(slug));
+        }
+        return subjectCollections;
+    }, [subjectCollections, subjectRelationTo]);
+    useEffect(() => {
+        if (!requiresSubject && value != null && value !== '') {
+            setValue(null);
+            return;
+        }
+        if (!requiresSubject || !value || typeof value !== 'object')
+            return;
+        const relationTo = value.relationTo;
+        if (typeof relationTo === 'string' && allowedCollections.length > 0 && !allowedCollections.includes(relationTo)) {
+            setValue(null);
+        }
+    }, [requiresSubject, setValue, value, allowedCollections]);
+    if (!requiresSubject || allowedCollections.length === 0)
+        return null;
+    return (_jsx(RelationshipField, { ...fieldArgs, field: {
+            ...fieldArgs.field,
+            relationTo: allowedCollections,
+        } }));
+}

package/dist/admin/useEventTypeFlags.d.ts

@@ -1,6 +1,8 @@
 export type EventTypeFlags = {
     requiresActor: boolean;
     requiresMetric: boolean;
+    requiresSubject: boolean;
+    subjectRelationTo: string[];
 };
 /** Resolve event-type flags for the selected `type` field (fetch when only an id is present). */
 export declare function useEventTypeFlags(eventTypesSlug: string): EventTypeFlags;

package/dist/admin/useEventTypeFlags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEventTypeFlags.d.ts","sourceRoot":"","sources":["../../src/admin/useEventTypeFlags.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;CACxB,CAAA;AA2BD,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,cAAc,CAyCxE"}
+{"version":3,"file":"useEventTypeFlags.d.ts","sourceRoot":"","sources":["../../src/admin/useEventTypeFlags.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;IACvB,eAAe,EAAE,OAAO,CAAA;IACxB,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B,CAAA;AAqDD,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,cAAc,CA4CxE"}

package/dist/admin/useEventTypeFlags.js

@@ -15,19 +15,35 @@ function relationId(value) {
     }
     return null;
 }
+function readSubjectRelationTo(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
 function flagsFromValue(typeValue) {
     if (!typeValue || typeof typeValue !== 'object')
         return null;
-    if (!('requiresActor' in typeValue || 'requiresMetric' in typeValue || 'slug' in typeValue)) {
+    if (!('requiresActor' in typeValue ||
+        'requiresMetric' in typeValue ||
+        'requiresSubject' in typeValue ||
+        'subjectRelationTo' in typeValue ||
+        'slug' in typeValue)) {
         return null;
     }
     const row = typeValue;
     return {
         requiresActor: Boolean(row.requiresActor),
         requiresMetric: Boolean(row.requiresMetric) || row.slug === 'metric.delta',
+        requiresSubject: Boolean(row.requiresSubject),
+        subjectRelationTo: readSubjectRelationTo(row.subjectRelationTo),
     };
 }
-const empty = { requiresActor: false, requiresMetric: false };
+const empty = {
+    requiresActor: false,
+    requiresMetric: false,
+    requiresSubject: false,
+    subjectRelationTo: [],
+};
 /** Resolve event-type flags for the selected `type` field (fetch when only an id is present). */
 export function useEventTypeFlags(eventTypesSlug) {
     const { config } = useConfig();
@@ -47,7 +63,9 @@ export function useEventTypeFlags(eventTypesSlug) {
         const controller = new AbortController();
         const api = config.routes?.api ?? '/api';
         const serverURL = config.serverURL ?? '';
-        const url = `${serverURL}${api}/${eventTypesSlug}/${typeId}?depth=0&select[requiresActor]=true&select[requiresMetric]=true&select[slug]=true`;
+        const url = `${serverURL}${api}/${eventTypesSlug}/${typeId}` +
+            `?depth=0&select[requiresActor]=true&select[requiresMetric]=true` +
+            `&select[requiresSubject]=true&select[subjectRelationTo]=true&select[slug]=true`;
         void fetch(url, { credentials: 'include', signal: controller.signal })
             .then(async (res) => {
             if (!res.ok) {

package/dist/cli/reconcile.d.ts

@@ -12,7 +12,7 @@ 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. */
+    /** When false, return the result and leave the process running. Default true. */
     exit?: boolean;
 }): Promise<ReconcileProgressionResult>;
 //# sourceMappingURL=reconcile.d.ts.map

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

@@ -1 +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,sCAAsC,CAAA;AAE7C,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,CA4BtC"}
+{"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,sCAAsC,CAAA;AAE7C,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,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4BtC"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/EventTypes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAOtD,wBAAgB,yBAAyB,IAAI,gBAAgB,CAgE5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/EventTypes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAqCtD,wBAAgB,yBAAyB,IAAI,gBAAgB,CAoE5D"}

package/dist/collections/EventTypes/index.js

@@ -1,8 +1,36 @@
+import { getAchievementOptions } from '../../options-store.js';
 import { collectionAdmin, collectionOf, columnsWithOptionalScope, optionalFields, slugOf } from '../helpers.js';
 import { localizedNameField, scopeField } from '../fields/index.js';
 import { access } from './access/index.js';
 import { hooks } from './hooks/index.js';
+function subjectCatalogFields() {
+    const collections = getAchievementOptions().subjectCollections;
+    if (collections.length === 0)
+        return [];
+    return [
+        {
+            name: 'requiresSubject',
+            type: 'checkbox',
+            defaultValue: false,
+            label: 'Requires a subject',
+            admin: {
+                description: 'Turn this on when the log points at a host document (for example a post or comment). We’ll ask for that document when it’s logged.',
+            },
+        },
+        {
+            name: 'subjectRelationTo',
+            type: 'select',
+            hasMany: true,
+            options: collections.map((slug) => ({ label: slug, value: slug })),
+            admin: {
+                condition: (_, siblingData) => Boolean(siblingData?.requiresSubject),
+                description: 'Which host collections this type may reference. Leave empty to allow any collection from the plugin subjects allowlist.',
+            },
+        },
+    ];
+}
 export function buildEventTypesCollection() {
+    const subjectFields = subjectCatalogFields();
     return {
         slug: slugOf('eventTypes'),
         access: { ...access },
@@ -14,6 +42,7 @@ export function buildEventTypesCollection() {
                 'slug',
                 'requiresActor',
                 'requiresMetric',
+                ...(subjectFields.length > 0 ? ['requiresSubject'] : []),
                 'system',
                 'scope',
             ]),
@@ -46,6 +75,7 @@ export function buildEventTypesCollection() {
                     description: 'Turn this on when the entry changes a score (like points). We’ll ask which metric and by how much.',
                 },
             },
+            ...subjectFields,
             {
                 name: 'system',
                 type: 'checkbox',

package/dist/collections/Logs/fields/validators.d.ts

@@ -2,4 +2,5 @@ import type { Validate } from 'payload';
 export declare const validateActor: Validate;
 export declare const validateMetric: Validate;
 export declare const validateChange: Validate;
+export declare const validateSubject: Validate;
 //# sourceMappingURL=validators.d.ts.map

package/dist/collections/Logs/fields/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/fields/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AASvC,eAAO,MAAM,aAAa,EAAE,QAW3B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QA0B5B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QAW5B,CAAA"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/fields/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAavC,eAAO,MAAM,aAAa,EAAE,QAW3B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QA0B5B,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,QAW5B,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,QAqC7B,CAAA"}

package/dist/collections/Logs/fields/validators.js

@@ -1,5 +1,7 @@
+import { getAchievementOptions } from '../../../options-store.js';
 import { collectionOf } from '../../../collections/helpers.js';
-import { eventTypeRequiresActor, eventTypeRequiresMetric, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { eventTypeRequiresActor, eventTypeRequiresMetric, eventTypeSubjectRelationTo, getEventTypeFlags, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { readLogSubject } from '../../../services/achievement/logSubject.js';
 import { relationId } from '../../../services/achievement/relationId.js';
 export const validateActor = async (value, { data, req }) => {
     if (!req?.payload)
@@ -55,3 +57,37 @@ export const validateChange = async (value, { data, req }) => {
     }
     return true;
 };
+export const validateSubject = async (value, { data, req }) => {
+    if (!req?.payload)
+        return true;
+    const allowlist = getAchievementOptions().subjectCollections;
+    if (allowlist.length === 0)
+        return true;
+    const typeId = relationId(data?.type);
+    if (!typeId)
+        return true;
+    const flags = await getEventTypeFlags({
+        payload: req.payload,
+        req,
+        typeIdOrDoc: typeId,
+    });
+    const subject = readLogSubject(value);
+    if (!flags.requiresSubject) {
+        return true;
+    }
+    if (!subject) {
+        return 'This log type needs a subject (the host document it is about).';
+    }
+    if (!allowlist.includes(subject.relationTo)) {
+        return `Subject collection "${subject.relationTo}" is not in the plugin subjects allowlist.`;
+    }
+    const allowed = await eventTypeSubjectRelationTo({
+        payload: req.payload,
+        req,
+        typeIdOrDoc: typeId,
+    });
+    if (allowed.length > 0 && !allowed.includes(subject.relationTo)) {
+        return `This log type only allows subjects from: ${allowed.join(', ')}.`;
+    }
+    return true;
+};

package/dist/collections/Logs/hooks/ensureTypeRequirements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensureTypeRequirements.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/hooks/ensureTypeRequirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAU3D,eAAO,MAAM,sBAAsB,EAAE,4BAmDpC,CAAA"}
+{"version":3,"file":"ensureTypeRequirements.d.ts","sourceRoot":"","sources":["../../../../src/collections/Logs/hooks/ensureTypeRequirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAA;AAc3D,eAAO,MAAM,sBAAsB,EAAE,4BA+DpC,CAAA"}

package/dist/collections/Logs/hooks/ensureTypeRequirements.js

@@ -1,6 +1,8 @@
 import { APIError } from 'payload';
+import { getAchievementOptions } from '../../../options-store.js';
 import { collectionOf } from '../../../collections/helpers.js';
-import { eventTypeRequiresActor, eventTypeRequiresMetric, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { eventTypeSubjectRelationTo, getEventTypeFlags, } from '../../../services/achievement/eventTypeRequiresActor.js';
+import { readLogSubject } from '../../../services/achievement/logSubject.js';
 import { relationId } from '../../../services/achievement/relationId.js';
 export const ensureTypeRequirements = async ({ data, req }) => {
     if (!data)
@@ -8,18 +10,11 @@ export const ensureTypeRequirements = async ({ data, req }) => {
     const typeId = relationId(data.type);
     if (!typeId)
         return data;
-    const flags = {
-        requiresActor: await eventTypeRequiresActor({
-            payload: req.payload,
-            req,
-            typeIdOrDoc: typeId,
-        }),
-        requiresMetric: await eventTypeRequiresMetric({
-            payload: req.payload,
-            req,
-            typeIdOrDoc: typeId,
-        }),
-    };
+    const flags = await getEventTypeFlags({
+        payload: req.payload,
+        req,
+        typeIdOrDoc: typeId,
+    });
     if (flags.requiresActor && !relationId(data.actor)) {
         throw new APIError('This log type needs an actor (who caused it).', 400);
     }
@@ -44,5 +39,19 @@ export const ensureTypeRequirements = async ({ data, req }) => {
             throw new APIError('Computed metrics cannot be changed with a metric delta. Use a stored metric such as Points.', 400);
         }
     }
+    if (flags.requiresSubject && getAchievementOptions().subjectCollections.length > 0) {
+        const subject = readLogSubject(data.subject);
+        if (!subject) {
+            throw new APIError('This log type needs a subject (the host document it is about).', 400);
+        }
+        const allowed = await eventTypeSubjectRelationTo({
+            payload: req.payload,
+            req,
+            typeIdOrDoc: typeId,
+        });
+        if (allowed.length > 0 && !allowed.includes(subject.relationTo)) {
+            throw new APIError(`This log type only allows subjects from: ${allowed.join(', ')}.`, 400);
+        }
+    }
     return data;
 };

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,CA6GtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collections/Logs/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAS,MAAM,SAAS,CAAA;AAqCtD,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,gBAAgB,CAuHtD"}

package/dist/collections/Logs/index.js

@@ -3,12 +3,34 @@ import { collectionAdmin, collectionOf, optionalFields, slugOf } from '../helper
 import { getAchievementOptions } from '../../options-store.js';
 import { scopeField, userField } from '../fields/index.js';
 import { access } from './access/index.js';
-import { validateActor, validateChange, validateMetric } from './fields/validators.js';
+import { validateActor, validateChange, validateMetric, validateSubject, } from './fields/validators.js';
 import { hooks } from './hooks/index.js';
+function subjectLogField(eventTypesSlug) {
+    const collections = getAchievementOptions().subjectCollections;
+    if (collections.length === 0)
+        return null;
+    return {
+        name: 'subject',
+        type: 'relationship',
+        relationTo: collections,
+        index: true,
+        validate: validateSubject,
+        admin: {
+            description: 'Host document this entry is about (post, comment, …).',
+            components: {
+                Field: {
+                    path: '@dappermountain/payload-plugin-achievements/client#SubjectField',
+                    clientProps: { eventTypesSlug, subjectCollections: collections },
+                },
+            },
+        },
+    };
+}
 /** Append-only occurrence log. `type` / `metric` are catalog relationships. */
 export function buildLogsCollection() {
     const users = getAchievementOptions().usersCollectionSlug ?? 'users';
     const eventTypesSlug = collectionOf('eventTypes');
+    const subjectField = subjectLogField(eventTypesSlug);
     return {
         slug: slugOf('logs'),
         labels: {
@@ -19,7 +41,15 @@ export function buildLogsCollection() {
         hooks,
         admin: collectionAdmin({
             useAsTitle: 'id',
-            defaultColumns: ['type', 'user', 'actor', 'metric', 'change', 'createdAt'],
+            defaultColumns: [
+                'type',
+                'user',
+                'actor',
+                ...(subjectField ? ['subject'] : []),
+                'metric',
+                'change',
+                'createdAt',
+            ],
             description: 'Member activity history — grants, revokes, score changes, tier moves, and host custom events. Not a second grant store.',
         }),
         fields: [
@@ -88,6 +118,7 @@ export function buildLogsCollection() {
                     },
                 ],
             },
+            ...(subjectField ? [subjectField] : []),
             {
                 type: 'collapsible',
                 label: 'Details',
@@ -105,7 +136,7 @@ export function buildLogsCollection() {
                         name: 'data',
                         type: 'json',
                         admin: {
-                            description: 'Engine transition envelope: `{ from, to }` each `{ id, slug? }` or null (tier.changed, achievement.granted/revoked). Hosts may add extra keys.',
+                            description: 'Engine transition envelope: `{ from, to }` each `{ id, slug? }` or null (tier.changed, achievement.granted/revoked). Prefer `subject` for host document links.',
                         },
                     },
                 ],

package/dist/defaults.d.ts

@@ -4,13 +4,15 @@ export declare const DEFAULT_USERS_COLLECTION = "users";
 export declare const DEFAULT_ME_ENDPOINT_PATH = "/achievements/me";
 export declare const DEFAULT_LEADERBOARD_ENDPOINT_PATH = "/achievements/leaderboard";
 export declare const DEFAULT_RECONCILE_ENDPOINT_PATH = "/achievements/reconcile";
-export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users' | 'endpoints'> & {
+export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users' | 'endpoints' | 'subjects'> & {
     enabled: boolean;
     seedSystemCatalog: boolean;
     usersCollectionSlug: string;
     users: {
         includeJoins: boolean;
     };
+    /** Host collections allowed as polymorphic log subjects (empty = feature off). */
+    subjectCollections: string[];
     /** Resolved collection slug map (after prefix + overrides). */
     collectionSlugs: ReturnType<typeof resolveCollectionSlugs>;
     /** Admin nav group for plugin collections (`false` = ungrouped). */
@@ -21,6 +23,8 @@ export type ResolvedAchievementOptions = Omit<AchievementPluginOptions, 'users'
         reconcile: string | false;
     };
 };
+/** Unique, non-empty collection slugs from plugin `subjects.collections`. */
+export declare function resolveSubjectCollections(options?: AchievementPluginOptions): string[];
 export declare function resolveMeEndpointPath(me?: string | false): string | false;
 export declare function resolveLeaderboardEndpointPath(path?: string | false): string | false;
 export declare function resolveReconcileEndpointPath(path?: string | false): string | false;

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAEL,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAE/B,eAAO,MAAM,wBAAwB,UAAU,CAAA;AAC/C,eAAO,MAAM,wBAAwB,qBAAqB,CAAA;AAC1D,eAAO,MAAM,iCAAiC,8BAA8B,CAAA;AAC5E,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AAExE,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,wBAAwB,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG;IAC/F,OAAO,EAAE,OAAO,CAAA;IAChB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,KAAK,EAAE;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,CAAA;IAChC,+DAA+D;IAC/D,eAAe,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;IAC1D,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;CAC1F,CAAA;AAQD,wBAAgB,qBAAqB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIzE;AAED,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIpF;AAED,wBAAgB,4BAA4B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIlF;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,wBAA6B,GAAG,0BAA0B,CAiBjG"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAEL,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAE/B,eAAO,MAAM,wBAAwB,UAAU,CAAA;AAC/C,eAAO,MAAM,wBAAwB,qBAAqB,CAAA;AAC1D,eAAO,MAAM,iCAAiC,8BAA8B,CAAA;AAC5E,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AAExE,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,wBAAwB,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,CAAC,GAAG;IAC5G,OAAO,EAAE,OAAO,CAAA;IAChB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,KAAK,EAAE;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,CAAA;IAChC,kFAAkF;IAClF,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,+DAA+D;IAC/D,eAAe,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;IAC1D,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;CAC1F,CAAA;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAWtF;AAQD,wBAAgB,qBAAqB,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIzE;AAED,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIpF;AAED,wBAAgB,4BAA4B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAIlF;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,wBAA6B,GAAG,0BAA0B,CAmBjG"}

package/dist/defaults.js

@@ -3,6 +3,20 @@ export const DEFAULT_USERS_COLLECTION = 'users';
 export const DEFAULT_ME_ENDPOINT_PATH = '/achievements/me';
 export const DEFAULT_LEADERBOARD_ENDPOINT_PATH = '/achievements/leaderboard';
 export const DEFAULT_RECONCILE_ENDPOINT_PATH = '/achievements/reconcile';
+/** Unique, non-empty collection slugs from plugin `subjects.collections`. */
+export function resolveSubjectCollections(options) {
+    const raw = options?.subjects?.collections ?? [];
+    const seen = new Set();
+    const out = [];
+    for (const slug of raw) {
+        const trimmed = typeof slug === 'string' ? slug.trim() : '';
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
 function normalizeEndpointPath(path, fallback) {
     const trimmed = path.trim();
     if (!trimmed)
@@ -31,14 +45,16 @@ export function resolveReconcileEndpointPath(path) {
     return normalizeEndpointPath(path, DEFAULT_RECONCILE_ENDPOINT_PATH);
 }
 export function resolveOptions(options = {}) {
+    const { subjects: _subjects, ...rest } = options;
     return {
-        ...options,
+        ...rest,
         enabled: options.enabled !== false,
         seedSystemCatalog: options.seedSystemCatalog !== false,
         usersCollectionSlug: options.usersCollectionSlug ?? DEFAULT_USERS_COLLECTION,
         users: {
             includeJoins: options.users?.includeJoins !== false,
         },
+        subjectCollections: resolveSubjectCollections(options),
         collectionSlugs: resolveCollectionSlugs(options),
         adminGroup: resolveAdminGroup(options),
         endpoints: {

package/dist/exports/client.d.ts

@@ -3,4 +3,5 @@ export { LucideIconField } from '../admin/LucideIconField.js';
 export { MetricChangeField } from '../admin/MetricChangeField.js';
 export { MetricField } from '../admin/MetricField.js';
 export { ReconcileProgressionButton } from '../admin/ReconcileProgressionButton.js';
+export { SubjectField } from '../admin/SubjectField.js';
 //# sourceMappingURL=client.d.ts.map

package/dist/exports/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/exports/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/exports/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAA;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/exports/client.js

@@ -3,3 +3,4 @@ export { LucideIconField } from '../admin/LucideIconField.js';
 export { MetricChangeField } from '../admin/MetricChangeField.js';
 export { MetricField } from '../admin/MetricField.js';
 export { ReconcileProgressionButton } from '../admin/ReconcileProgressionButton.js';
+export { SubjectField } from '../admin/SubjectField.js';

package/dist/index.d.ts

@@ -3,11 +3,11 @@ export type { EngineEventTypeSlug, EngineMetricSlug } from './catalog.js';
 export { achievementPlugin } from './plugin.js';
 export { seedAchievementCatalog, seedAchievements } from './seed/index.js';
 export type { AchievementSeedAchievement, AchievementSeedCatalogRow, AchievementSeedInput, AchievementSeedLocalizedText, AchievementSeedTier, } from './seed/index.js';
-export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, buildUnlockRequirementLeaves, getUserProgress, loadUserProgressReviews, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
-export type { ResolvedTier, RuleGroup, TierLadderProgress, CatalogProgressGroup, CatalogProgressItem, UnlockRequirementLeaf, UnlockRequirementRelation, GetUserProgressInclude, UserProgressMeResponse, UserProgressReviews, UserProgressTierRequest, CatalogRef, TransitionLogData, MetricLeaderboardResult, MetricLeaderboardRow, ReconcileProgressionArgs, ReconcileProgressionResult, ReleaseReviewGateResult, } from './services/achievement/index.js';
-export type { BuiltInEventType, BuiltInRuleType, AchievementCollectionKey, AchievementCollectionOverride, AchievementCollectionsOptions, AchievementEndpointsOptions, AchievementMetricAnchor, AchievementMetricAnchorConfig, AchievementMetricAnchorEntry, AchievementPluginOptions, AchievementRuleType, AchievementScopeConfig, AchievementUsersOptions, } from './types.js';
+export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, buildUnlockRequirementLeaves, getUserProgress, loadUserProgressReviews, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, logSubject, readLogSubject, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
+export type { ResolvedTier, RuleGroup, TierLadderProgress, CatalogProgressGroup, CatalogProgressItem, UnlockRequirementLeaf, UnlockRequirementRelation, GetUserProgressInclude, UserProgressMeResponse, UserProgressReviews, UserProgressTierRequest, CatalogRef, TransitionLogData, LogSubjectRef, MetricLeaderboardResult, MetricLeaderboardRow, ReconcileProgressionArgs, ReconcileProgressionResult, ReleaseReviewGateResult, } from './services/achievement/index.js';
+export type { BuiltInEventType, BuiltInRuleType, AchievementCollectionKey, AchievementCollectionOverride, AchievementCollectionsOptions, AchievementEndpointsOptions, AchievementMetricAnchor, AchievementMetricAnchorConfig, AchievementMetricAnchorEntry, AchievementPluginOptions, AchievementRuleType, AchievementScopeConfig, AchievementSubjectsOptions, AchievementUsersOptions, } from './types.js';
 export { DEFAULT_COLLECTION_BASE_SLUGS, DEFAULT_COLLECTION_PREFIX, DEFAULT_ADMIN_GROUP } from './collections/slugs.js';
-export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_LEADERBOARD_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH, } from './defaults.js';
+export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_LEADERBOARD_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH, resolveSubjectCollections, } from './defaults.js';
 export { collectionOf, slugOf } from './collections/helpers.js';
 export { eachRuleLeaf } from './collections/hooks/eachRuleLeaf.js';
 export { isAchievementPluginEnabled } from './enabled.js';

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,cAAc,CAAA;AACrB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAC1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,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,iCAAiC,CAAA;AACxC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACtH,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,GAChC,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,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,cAAc,CAAA;AACrB,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAC1E,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,iCAAiC,CAAA;AACxC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACtH,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA"}

package/dist/index.js

@@ -1,9 +1,9 @@
 export { DEFAULT_ACHIEVEMENT_METRIC, DEFAULT_ACHIEVEMENT_METRIC_SLUG, ENGINE_EVENT_TYPES, ENGINE_METRICS, } from './catalog.js';
 export { achievementPlugin } from './plugin.js';
 export { seedAchievementCatalog, seedAchievements } from './seed/index.js';
-export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, buildUnlockRequirementLeaves, getUserProgress, loadUserProgressReviews, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
+export { evaluateRules, evaluateRuleProgress, collectAchievementCompleteRefs, buildCatalogProgressGroups, buildUnlockRequirementLeaves, getUserProgress, loadUserProgressReviews, getMetricLeaderboard, grantAchievement, loadMetricDoc, recordEvent, recordLog, recordMetricChange, rebuildMetricBalance, rebuildMetricBalancesForUser, reconcileProgression, reconcileUserProgression, releasePendingAchievementReviews, releasePendingTierReviews, resolveCurrentTier, resolveElapsedAnchor, resolveMetricValue, resolveTierProgress, reviewAchievementRequest, submitAchievementRequest, syncTierChangedLog, syncTierProgression, syncCompositeProgression, catalogRef, transitionLogData, transitionToId, logSubject, readLogSubject, validateRuleGroup, validateRuleNode, } from './services/achievement/index.js';
 export { DEFAULT_COLLECTION_BASE_SLUGS, DEFAULT_COLLECTION_PREFIX, DEFAULT_ADMIN_GROUP } from './collections/slugs.js';
-export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_LEADERBOARD_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH, } from './defaults.js';
+export { DEFAULT_ME_ENDPOINT_PATH, DEFAULT_LEADERBOARD_ENDPOINT_PATH, DEFAULT_RECONCILE_ENDPOINT_PATH, resolveSubjectCollections, } from './defaults.js';
 export { collectionOf, slugOf } from './collections/helpers.js';
 export { eachRuleLeaf } from './collections/hooks/eachRuleLeaf.js';
 export { isAchievementPluginEnabled } from './enabled.js';

package/dist/seed/index.d.ts

@@ -57,6 +57,13 @@ export type AchievementSeedCatalogRow = {
     requiresActor?: boolean;
     /** Event types only — when true, logging the event requires metric + change. */
     requiresMetric?: boolean;
+    /** Event types only — when true, logging the event requires a polymorphic `subject`. */
+    requiresSubject?: boolean;
+    /**
+     * Event types only — allowed host collections for `subject.relationTo`.
+     * Empty / omit = any collection from plugin `subjects.collections`.
+     */
+    subjectRelationTo?: string[];
 };
 export type AchievementSeedInput = {
     eventTypes?: AchievementSeedCatalogRow[];

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seed/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAOtC,mGAAmG;AACnG,MAAM,MAAM,4BAA4B,GAAG,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAExG,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,4BAA4B,CAAA;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,4BAA4B,CAAA;IAC1C,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAA;CACrG,CAAA;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,4BAA4B,CAAA;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,4BAA4B,CAAA;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAA;IACzG,qGAAqG;IACrG,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAA;CACzG,CAAA;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,4BAA4B,CAAA;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kDAAkD;IAClD,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;IAC5B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAA;IACzD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,CAAC,EAAE,yBAAyB,EAAE,CAAA;IACxC,OAAO,CAAC,EAAE,yBAAyB,EAAE,CAAA;IACrC,KAAK,CAAC,EAAE,mBAAmB,EAAE,CAAA;IAC7B,YAAY,CAAC,EAAE,0BAA0B,EAAE,CAAA;IAC3C,gEAAgE;IAChE,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;CAClC,CAAA;AAwND,2FAA2F;AAC3F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB5F;AAiCD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqLnG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seed/index.ts"],"names":[],"mappings":"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"}

package/dist/seed/index.js

@@ -74,6 +74,10 @@ async function upsertCatalog(payload, key, row) {
             ? {
                 requiresActor: row.requiresActor ?? false,
                 requiresMetric: row.requiresMetric ?? false,
+                requiresSubject: row.requiresSubject ?? false,
+                ...(row.subjectRelationTo && row.subjectRelationTo.length > 0
+                    ? { subjectRelationTo: row.subjectRelationTo }
+                    : { subjectRelationTo: [] }),
             }
             : metricComputed),
     };

package/dist/services/achievement/duration.js

@@ -2,7 +2,7 @@ const MS_PER_SECOND = 1_000;
 const MS_PER_MINUTE = 60 * MS_PER_SECOND;
 const MS_PER_HOUR = 60 * MS_PER_MINUTE;
 const MS_PER_DAY = 24 * MS_PER_HOUR;
-/** Fixed-length year for elapsed floors (not calendar years). */
+/** Fixed-length year for elapsed floors (365-day year). */
 const MS_PER_YEAR = 365 * MS_PER_DAY;
 export function durationMs(amount, unit) {
     if (!(typeof amount === 'number') || !Number.isFinite(amount) || amount < 0)

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

@@ -2,6 +2,9 @@ import type { Payload, PayloadRequest } from 'payload';
 export type EventTypeFlags = {
     requiresActor: boolean;
     requiresMetric: boolean;
+    requiresSubject: boolean;
+    /** Allowed host collections for `subject.relationTo` (empty = any plugin allowlist entry). */
+    subjectRelationTo: string[];
 };
 /** Read flags from a loaded event-type document (or populated relationship). */
 export declare function readEventTypeFlags(doc: unknown): EventTypeFlags | null;
@@ -21,4 +24,18 @@ export declare function eventTypeRequiresMetric(args: {
     req?: PayloadRequest;
     typeIdOrDoc: unknown;
 }): Promise<boolean>;
+export declare function eventTypeRequiresSubject(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    typeIdOrDoc: unknown;
+}): Promise<boolean>;
+/**
+ * Allowed `subject.relationTo` values for this event type.
+ * Empty event-type list → full plugin allowlist. Feature off → [].
+ */
+export declare function eventTypeSubjectRelationTo(args: {
+    payload: Payload;
+    req?: PayloadRequest;
+    typeIdOrDoc: unknown;
+}): Promise<string[]>;
 //# sourceMappingURL=eventTypeRequiresActor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"eventTypeRequiresActor.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/eventTypeRequiresActor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAKtD,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAUtE;AAMD,wDAAwD;AACxD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsB1B;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnB;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnB"}
+{"version":3,"file":"eventTypeRequiresActor.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/eventTypeRequiresActor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAMtD,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,cAAc,EAAE,OAAO,CAAA;IACvB,eAAe,EAAE,OAAO,CAAA;IACxB,8FAA8F;IAC9F,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAC5B,CAAA;AAkBD,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAsBtE;AAMD,wDAAwD;AACxD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,cAAc,CAAC,CAwC1B;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnB;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnB;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEnB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;CACrB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAOpB"}

package/dist/services/achievement/eventTypeRequiresActor.js

@@ -1,16 +1,39 @@
+import { getAchievementOptions } from '../../options-store.js';
 import { collectionOf } from '../../collections/helpers.js';
 import { relationId } from './relationId.js';
+const emptyFlags = {
+    requiresActor: false,
+    requiresMetric: false,
+    requiresSubject: false,
+    subjectRelationTo: [],
+};
+function readSubjectRelationTo(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry === 'string' && entry.trim())
+            out.push(entry.trim());
+    }
+    return out;
+}
 /** Read flags from a loaded event-type document (or populated relationship). */
 export function readEventTypeFlags(doc) {
     if (!doc || typeof doc !== 'object')
         return null;
     const row = doc;
-    const hasFlagKeys = 'requiresActor' in row || 'requiresMetric' in row || typeof row.slug === 'string';
+    const hasFlagKeys = 'requiresActor' in row ||
+        'requiresMetric' in row ||
+        'requiresSubject' in row ||
+        'subjectRelationTo' in row ||
+        typeof row.slug === 'string';
     if (!hasFlagKeys)
         return null;
     return {
         requiresActor: Boolean(row.requiresActor),
         requiresMetric: Boolean(row.requiresMetric) || row.slug === 'metric.delta',
+        requiresSubject: Boolean(row.requiresSubject),
+        subjectRelationTo: readSubjectRelationTo(row.subjectRelationTo),
     };
 }
 function flagsFromDoc(doc) {
@@ -21,22 +44,32 @@ export async function getEventTypeFlags(args) {
     const embedded = flagsFromDoc(args.typeIdOrDoc);
     if (embedded && args.typeIdOrDoc && typeof args.typeIdOrDoc === 'object') {
         const row = args.typeIdOrDoc;
-        if ('requiresActor' in row || 'requiresMetric' in row || 'slug' in row) {
+        if ('requiresActor' in row ||
+            'requiresMetric' in row ||
+            'requiresSubject' in row ||
+            'subjectRelationTo' in row ||
+            'slug' in row) {
             return embedded;
         }
     }
     const typeId = relationId(args.typeIdOrDoc);
     if (!typeId)
-        return { requiresActor: false, requiresMetric: false };
+        return { ...emptyFlags };
     const found = (await args.payload.findByID({
         collection: collectionOf('eventTypes'),
         id: typeId,
         depth: 0,
         overrideAccess: true,
         req: args.req,
-        select: { requiresActor: true, requiresMetric: true, slug: true },
+        select: {
+            requiresActor: true,
+            requiresMetric: true,
+            requiresSubject: true,
+            subjectRelationTo: true,
+            slug: true,
+        },
     }));
-    return flagsFromDoc(found) ?? { requiresActor: false, requiresMetric: false };
+    return flagsFromDoc(found) ?? { ...emptyFlags };
 }
 export async function eventTypeRequiresActor(args) {
     return (await getEventTypeFlags(args)).requiresActor;
@@ -44,3 +77,21 @@ export async function eventTypeRequiresActor(args) {
 export async function eventTypeRequiresMetric(args) {
     return (await getEventTypeFlags(args)).requiresMetric;
 }
+export async function eventTypeRequiresSubject(args) {
+    return (await getEventTypeFlags(args)).requiresSubject;
+}
+/**
+ * Allowed `subject.relationTo` values for this event type.
+ * Empty event-type list → full plugin allowlist. Feature off → [].
+ */
+export async function eventTypeSubjectRelationTo(args) {
+    const allowlist = getAchievementOptions().subjectCollections;
+    if (allowlist.length === 0)
+        return [];
+    const flags = await getEventTypeFlags(args);
+    if (!flags.requiresSubject)
+        return [];
+    if (flags.subjectRelationTo.length === 0)
+        return [...allowlist];
+    return flags.subjectRelationTo.filter((slug) => allowlist.includes(slug));
+}

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

@@ -14,6 +14,8 @@ export { applyMetricBalanceDelta, findMetricBalance, metricBalanceKey, rebuildMe
 export { resolveMetricValue, loadMetricDoc } from './resolveMetricValue.js';
 export { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
 export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent.js';
+export { logSubject, readLogSubject } from './logSubject.js';
+export type { LogSubjectRef } from './logSubject.js';
 export { resolveCurrentTier } from './resolveCurrentTier.js';
 export type { ResolvedTier } from './resolveCurrentTier.js';
 export { resolveTierProgress } from './resolveTierProgress.js';

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,oBAAoB,CAAA;AAC5H,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAChG,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAA;AAChF,YAAY,EACV,8BAA8B,EAC9B,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AACjH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAC9F,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAC/E,YAAY,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC1F,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,GAC1B,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,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,oBAAoB,CAAA;AAC5H,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AAC5E,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAChG,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAA;AAChF,YAAY,EACV,8BAA8B,EAC9B,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AACjH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAC9F,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACjG,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC5D,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAC/E,YAAY,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC1F,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,GAC1B,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA"}

package/dist/services/achievement/index.js

@@ -8,6 +8,7 @@ export { applyMetricBalanceDelta, findMetricBalance, metricBalanceKey, rebuildMe
 export { resolveMetricValue, loadMetricDoc } from './resolveMetricValue.js';
 export { resolveElapsedAnchor } from './resolveElapsedAnchor.js';
 export { recordEvent, recordLog, recordMetricChange, syncTierChangedLog } from './recordEvent.js';
+export { logSubject, readLogSubject } from './logSubject.js';
 export { resolveCurrentTier } from './resolveCurrentTier.js';
 export { resolveTierProgress } from './resolveTierProgress.js';
 export { grantAchievement, submitAchievementRequest } from './submitAchievementRequest.js';

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

@@ -0,0 +1,13 @@
+/** Polymorphic relationship value (Payload `relationTo` + `value`). */
+export type LogSubjectRef = {
+    relationTo: string;
+    value: string;
+};
+/** Build a log subject ref for `recordLog({ subject })`. */
+export declare function logSubject(relationTo: string, value: string): LogSubjectRef;
+/**
+ * Normalize a polymorphic relationship (Admin / Local API shape) to `{ relationTo, value }`.
+ * Accepts nested docs (`value: { id }`) and plain ids under `value`.
+ */
+export declare function readLogSubject(value: unknown): LogSubjectRef | null;
+//# sourceMappingURL=logSubject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logSubject.d.ts","sourceRoot":"","sources":["../../../src/services/achievement/logSubject.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAE3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAOnE"}

package/dist/services/achievement/logSubject.js

@@ -0,0 +1,20 @@
+import { relationId } from './relationId.js';
+/** Build a log subject ref for `recordLog({ subject })`. */
+export function logSubject(relationTo, value) {
+    return { relationTo, value };
+}
+/**
+ * Normalize a polymorphic relationship (Admin / Local API shape) to `{ relationTo, value }`.
+ * Accepts nested docs (`value: { id }`) and plain ids under `value`.
+ */
+export function readLogSubject(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const row = value;
+    if (typeof row.relationTo !== 'string' || !row.relationTo.trim())
+        return null;
+    const id = relationId(row.value);
+    if (!id)
+        return null;
+    return { relationTo: row.relationTo.trim(), value: id };
+}

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

@@ -1,4 +1,5 @@
 import type { Payload, PayloadRequest } from 'payload';
+import { type LogSubjectRef } from './logSubject.js';
 export type RecordLogInput = {
     payload: Payload;
     req?: PayloadRequest;
@@ -12,6 +13,11 @@ export type RecordLogInput = {
     /** Signed amount the metric moved (for metric.delta logs). */
     change?: number;
     reason?: string;
+    /**
+     * Host document this entry is about (polymorphic).
+     * Preferred over stuffing ids into `data` when the host configured `subjects.collections`.
+     */
+    subject?: LogSubjectRef | null;
     data?: Record<string, unknown> | null;
 };
 /** Append a catalogued occurrence to the achievement log. */

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;AAatD,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,wEAsDA;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"}
+{"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;AAUtD,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,iBAAiB,CAAA;AAQpE,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;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAgBD,6DAA6D;AAC7D,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,wEA0EnD;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,wEAsDA;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

@@ -1,7 +1,9 @@
 import { APIError } from 'payload';
 import { DEFAULT_ACHIEVEMENT_METRIC_SLUG } from '../../catalog.js';
 import { collectionOf } from '../../collections/helpers.js';
-import { eventTypeRequiresActor } from './eventTypeRequiresActor.js';
+import { getAchievementOptions } from '../../options-store.js';
+import { eventTypeSubjectRelationTo, getEventTypeFlags, } from './eventTypeRequiresActor.js';
+import { readLogSubject } from './logSubject.js';
 import { applyMetricBalanceDelta } from './metricBalances.js';
 import { transitionLogData, transitionToId } from './logData.js';
 import { loadMetricDoc } from './resolveMetricValue.js';
@@ -33,9 +35,34 @@ export async function recordLog(args) {
             value: args.metric,
         })
         : undefined;
-    if (await eventTypeRequiresActor({ payload: args.payload, req: args.req, typeIdOrDoc: typeId })) {
-        if (!args.actorId) {
-            throw new APIError('This log type needs an actor (who caused it).', 400);
+    const flags = await getEventTypeFlags({
+        payload: args.payload,
+        req: args.req,
+        typeIdOrDoc: typeId,
+    });
+    if (flags.requiresActor && !args.actorId) {
+        throw new APIError('This log type needs an actor (who caused it).', 400);
+    }
+    const allowlist = getAchievementOptions().subjectCollections;
+    let subject;
+    if (args.subject) {
+        const parsed = readLogSubject(args.subject) ?? args.subject;
+        subject = parsed;
+    }
+    if (flags.requiresSubject && allowlist.length > 0) {
+        if (!subject) {
+            throw new APIError('This log type needs a subject (the host document it is about).', 400);
+        }
+        if (!allowlist.includes(subject.relationTo)) {
+            throw new APIError(`Subject collection "${subject.relationTo}" is not in the plugin subjects allowlist.`, 400);
+        }
+        const allowed = await eventTypeSubjectRelationTo({
+            payload: args.payload,
+            req: args.req,
+            typeIdOrDoc: typeId,
+        });
+        if (allowed.length > 0 && !allowed.includes(subject.relationTo)) {
+            throw new APIError(`This log type only allows subjects from: ${allowed.join(', ')}.`, 400);
         }
     }
     return args.payload.create({
@@ -48,6 +75,7 @@ export async function recordLog(args) {
             metric: metricId,
             change: args.change,
             reason: args.reason,
+            ...(subject ? { subject } : {}),
             data: args.data ?? undefined,
         },
         overrideAccess: true,

package/dist/types.d.ts

@@ -9,7 +9,7 @@ export type AchievementMetricAnchor = (args: {
 /**
  * Anchor with an Admin label.
  * `label` is a Payload Admin UI string ({@link OptionLabel}): plain string, `{ en, es, … }`,
- * or `({ t }) => t('custom:…')` — not CMS `localization`.
+ * or `({ t }) => t('custom:…')` (Admin UI / OptionLabel).
  */
 export type AchievementMetricAnchorConfig = {
     label: OptionLabel;
@@ -40,11 +40,11 @@ export type AchievementRuleType = {
     /**
      * Optional fractional progress toward this leaf (0..1).
      * When omitted, progress falls back to `evaluate` → 0 or 1.
-     * Used for next-tier ladder fill and host UIs — not for unlock boolean.
+     * Used for next-tier ladder fill and host UIs (progress display).
      */
     progress?: (args: AchievementRuleEvalArgs) => Promise<number> | number;
     /**
-     * `gate` rules (e.g. `tier-at-least`) are prerequisites, not progress.
+     * `gate` rules (e.g. `tier-at-least`) are prerequisites that must already hold.
      * They are omitted from AND averages. Default: `requirement`.
      */
     progressRole?: 'requirement' | 'gate';
@@ -110,6 +110,17 @@ export type AchievementEndpointsOptions = {
      */
     reconcile?: string | false;
 };
+/**
+ * Host documents that achievement logs may point at (polymorphic `subject`).
+ * Empty / omitted → subject field is not registered (engine stays host-agnostic).
+ */
+export type AchievementSubjectsOptions = {
+    /**
+     * Collection slugs allowed on log `subject.relationTo` (e.g. `posts`, `comments`).
+     * Event types pick a subset via `subjectRelationTo`; validation rejects anything outside this list.
+     */
+    collections?: string[];
+};
 export type AchievementPluginOptions = {
     /**
      * Whether the user may review requests and manage achievement catalogs for a scope.
@@ -121,6 +132,11 @@ export type AchievementPluginOptions = {
     enabled?: boolean;
     /** Custom root API routes registered by the plugin. */
     endpoints?: AchievementEndpointsOptions;
+    /**
+     * Polymorphic log subjects — host allowlist of collections.
+     * When set, event types gain `requiresSubject` / `subjectRelationTo` and logs gain `subject`.
+     */
+    subjects?: AchievementSubjectsOptions;
     extensions?: {
         /** Custom rule evaluators merged with built-ins. */
         ruleTypes?: AchievementRuleType[];

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dappermountain/payload-plugin-achievements",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",
@@ -69,21 +69,21 @@
     "skills:check": "bunx skills check -p"
   },
   "peerDependencies": {
-    "@payloadcms/richtext-lexical": "^3.88.0",
-    "@payloadcms/ui": "^3.88.0",
+    "@payloadcms/richtext-lexical": "^3.89.0",
+    "@payloadcms/ui": "^3.89.0",
     "lucide-react": "^0.543.0",
-    "payload": "^3.88.0",
+    "payload": "^3.89.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
     "@dappermountain/agent-payload": "^0.1.5",
     "@dappermountain/agent-practices": "^0.1.2",
-    "@payloadcms/richtext-lexical": "3.88.0",
-    "@payloadcms/ui": "3.88.0",
+    "@payloadcms/richtext-lexical": "3.89.0",
+    "@payloadcms/ui": "3.89.0",
     "@types/bun": "1.4.0",
     "@types/react": "^19.0.0",
     "lucide-react": "0.543.0",
-    "payload": "3.88.0",
+    "payload": "3.89.0",
     "prettier": "^3.6.2",
     "react": "19.2.4",
     "typescript": "5.9.2"