@pattern-stack/codegen 0.16.0 → 0.17.0

package/dist/runtime/subsystems/jobs/index.js

@@ -2,7 +2,7 @@ import "../../../chunk-W4HOHZVF.js";
 import {
   JobWorkerModule,
   JobWorkerOrchestrator
-} from "../../../chunk-RUYLXR5F.js";
+} from "../../../chunk-GJDEPTPY.js";
 import {
   JOB_WORKER_OPTIONS,
   JobWorker,
@@ -10,41 +10,29 @@ import {
   buildStaleSweepQuery,
   classifyError,
   computeBackoff
-} from "../../../chunk-XDIIVIIK.js";
+} from "../../../chunk-OITTYGJS.js";
 import {
   JobsDomainModule
-} from "../../../chunk-3RWMQC3K.js";
-import {
-  DrizzleJobStepService
-} from "../../../chunk-DV4RV2DC.js";
-import {
-  DrizzleJobOrchestrator
-} from "../../../chunk-OTR44OH6.js";
+} from "../../../chunk-3MAZ4TQH.js";
 import {
   MemoryJobOrchestrator
 } from "../../../chunk-BULPAAD3.js";
-import {
-  MemoryJobStepService
-} from "../../../chunk-PNZSGAB2.js";
 import {
   DrizzleJobRunService
-} from "../../../chunk-VNBC3VXM.js";
+} from "../../../chunk-3VEVGL74.js";
 import {
   MemoryJobRunService
-} from "../../../chunk-BHZP6LOV.js";
+} from "../../../chunk-CDLWYZVQ.js";
+import "../../../chunk-L3LZWWSX.js";
+import {
+  DrizzleJobStepService
+} from "../../../chunk-DV4RV2DC.js";
+import {
+  MemoryJobStepService
+} from "../../../chunk-PNZSGAB2.js";
 import {
   MemoryJobStore
 } from "../../../chunk-SNQ3TOWP.js";
-import {
-  BootValidationError,
-  JobCollisionError,
-  JobNotReplayableError,
-  JobTemplateFieldMissingError,
-  JobTypeNotFoundError,
-  MissingTenantIdError,
-  ReservedPoolViolationError
-} from "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-L3LZWWSX.js";
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
@@ -59,12 +47,17 @@ import {
   loadPoolConfig
 } from "../../../chunk-RHVN6NA7.js";
 import {
-  JOBS_LISTEN_NOTIFY,
-  JOBS_MULTI_TENANT,
-  JOB_ORCHESTRATOR,
-  JOB_RUN_SERVICE,
-  JOB_STEP_SERVICE
-} from "../../../chunk-ZPL74UQN.js";
+  DrizzleJobOrchestrator
+} from "../../../chunk-OTR44OH6.js";
+import {
+  BootValidationError,
+  JobCollisionError,
+  JobNotReplayableError,
+  JobTemplateFieldMissingError,
+  JobTypeNotFoundError,
+  MissingTenantIdError,
+  ReservedPoolViolationError
+} from "../../../chunk-T4BIIU5E.js";
 import {
   HandlerRegistry,
   JOB_HANDLER_METADATA_KEY,
@@ -73,6 +66,13 @@ import {
   JobHandlerBase,
   ParentClosePolicy
 } from "../../../chunk-CO6LUM72.js";
+import {
+  JOBS_LISTEN_NOTIFY,
+  JOBS_MULTI_TENANT,
+  JOB_ORCHESTRATOR,
+  JOB_RUN_SERVICE,
+  JOB_STEP_SERVICE
+} from "../../../chunk-ZPL74UQN.js";
 import {
   collisionModeEnum,
   jobRunStatusEnum,

package/dist/runtime/subsystems/jobs/job-orchestrator.bullmq-backend.js

@@ -1,13 +1,13 @@
-import {
-  DrizzleJobOrchestrator
-} from "../../../chunk-OTR44OH6.js";
-import "../../../chunk-T4BIIU5E.js";
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
   resolvePoolQueueName
 } from "../../../chunk-I6MVCB5A.js";
 import "../../../chunk-RHVN6NA7.js";
+import {
+  DrizzleJobOrchestrator
+} from "../../../chunk-OTR44OH6.js";
+import "../../../chunk-T4BIIU5E.js";
 import {
   JOBS_MULTI_TENANT
 } from "../../../chunk-ZPL74UQN.js";

package/dist/runtime/subsystems/jobs/job-orchestrator.memory-backend.js

@@ -4,8 +4,8 @@ import {
 import "../../../chunk-PNZSGAB2.js";
 import "../../../chunk-SNQ3TOWP.js";
 import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-CO6LUM72.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";
 export {

package/dist/runtime/subsystems/jobs/job-run-service.drizzle-backend.js

@@ -1,8 +1,8 @@
 import {
   DrizzleJobRunService
-} from "../../../chunk-VNBC3VXM.js";
-import "../../../chunk-T4BIIU5E.js";
+} from "../../../chunk-3VEVGL74.js";
 import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-T4BIIU5E.js";
 import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-OKXZ63IA.js";
 import "../../../chunk-GYGNEQSC.js";

package/dist/runtime/subsystems/jobs/job-run-service.memory-backend.js

@@ -1,9 +1,9 @@
 import {
   MemoryJobRunService
-} from "../../../chunk-BHZP6LOV.js";
+} from "../../../chunk-CDLWYZVQ.js";
+import "../../../chunk-L3LZWWSX.js";
 import "../../../chunk-SNQ3TOWP.js";
 import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-L3LZWWSX.js";
 import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";

package/dist/runtime/subsystems/jobs/job-worker.js

@@ -6,9 +6,9 @@ import {
   buildStaleSweepQuery,
   classifyError,
   computeBackoff
-} from "../../../chunk-XDIIVIIK.js";
-import "../../../chunk-ZPL74UQN.js";
+} from "../../../chunk-OITTYGJS.js";
 import "../../../chunk-CO6LUM72.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-OKXZ63IA.js";
 import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";

package/dist/runtime/subsystems/jobs/job-worker.module.js

@@ -2,22 +2,22 @@ import {
   JOB_WORKER_MODULE_OPTIONS,
   JobWorkerModule,
   JobWorkerOrchestrator
-} from "../../../chunk-RUYLXR5F.js";
-import "../../../chunk-XDIIVIIK.js";
-import "../../../chunk-3RWMQC3K.js";
-import "../../../chunk-DV4RV2DC.js";
-import "../../../chunk-OTR44OH6.js";
+} from "../../../chunk-GJDEPTPY.js";
+import "../../../chunk-OITTYGJS.js";
+import "../../../chunk-3MAZ4TQH.js";
 import "../../../chunk-BULPAAD3.js";
+import "../../../chunk-3VEVGL74.js";
+import "../../../chunk-CDLWYZVQ.js";
+import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-DV4RV2DC.js";
 import "../../../chunk-PNZSGAB2.js";
-import "../../../chunk-VNBC3VXM.js";
-import "../../../chunk-BHZP6LOV.js";
 import "../../../chunk-SNQ3TOWP.js";
-import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-L3LZWWSX.js";
 import "../../../chunk-I6MVCB5A.js";
 import "../../../chunk-RHVN6NA7.js";
-import "../../../chunk-ZPL74UQN.js";
+import "../../../chunk-OTR44OH6.js";
+import "../../../chunk-T4BIIU5E.js";
 import "../../../chunk-CO6LUM72.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-OKXZ63IA.js";
 import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";

package/dist/runtime/subsystems/jobs/jobs-domain.module.js

@@ -1,19 +1,19 @@
 import {
   JobsDomainModule
-} from "../../../chunk-3RWMQC3K.js";
-import "../../../chunk-DV4RV2DC.js";
-import "../../../chunk-OTR44OH6.js";
+} from "../../../chunk-3MAZ4TQH.js";
 import "../../../chunk-BULPAAD3.js";
+import "../../../chunk-3VEVGL74.js";
+import "../../../chunk-CDLWYZVQ.js";
+import "../../../chunk-L3LZWWSX.js";
+import "../../../chunk-DV4RV2DC.js";
 import "../../../chunk-PNZSGAB2.js";
-import "../../../chunk-VNBC3VXM.js";
-import "../../../chunk-BHZP6LOV.js";
 import "../../../chunk-SNQ3TOWP.js";
-import "../../../chunk-T4BIIU5E.js";
-import "../../../chunk-L3LZWWSX.js";
 import "../../../chunk-I6MVCB5A.js";
 import "../../../chunk-RHVN6NA7.js";
-import "../../../chunk-ZPL74UQN.js";
+import "../../../chunk-OTR44OH6.js";
+import "../../../chunk-T4BIIU5E.js";
 import "../../../chunk-CO6LUM72.js";
+import "../../../chunk-ZPL74UQN.js";
 import "../../../chunk-OKXZ63IA.js";
 import "../../../chunk-MYQIQ27N.js";
 import "../../../chunk-GYGNEQSC.js";

package/dist/runtime/subsystems/storage/index.js

@@ -1,10 +1,7 @@
 import "../../../chunk-ZUMULSEQ.js";
 import {
   StorageModule
-} from "../../../chunk-BK5ICA2F.js";
-import {
-  STORAGE
-} from "../../../chunk-NYBCQZC7.js";
+} from "../../../chunk-4MVGAMUA.js";
 import {
   LocalStorageBackend
 } from "../../../chunk-JWNHNUYL.js";
@@ -12,6 +9,9 @@ import {
   MemoryStorageBackend
 } from "../../../chunk-3SZFUTXE.js";
 import "../../../chunk-J6MN42LG.js";
+import {
+  STORAGE
+} from "../../../chunk-NYBCQZC7.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";
 export {

package/dist/runtime/subsystems/storage/storage.module.js

@@ -1,10 +1,10 @@
 import {
   StorageModule
-} from "../../../chunk-BK5ICA2F.js";
-import "../../../chunk-NYBCQZC7.js";
+} from "../../../chunk-4MVGAMUA.js";
 import "../../../chunk-JWNHNUYL.js";
 import "../../../chunk-3SZFUTXE.js";
 import "../../../chunk-J6MN42LG.js";
+import "../../../chunk-NYBCQZC7.js";
 import "../../../chunk-GYGNEQSC.js";
 import "../../../chunk-2E224ZSN.js";
 export {

package/dist/src/cli/index.js

@@ -36,29 +36,29 @@ import {
   validateOrchestrationProject,
   validateProviders,
   writeManifest
-} from "../../chunk-32DOFN3T.js";
+} from "../../chunk-IOQMMH6C.js";
 import "../../chunk-KVOWSC5S.js";
-import "../../chunk-24WXSC3C.js";
-import "../../chunk-EO2QPOKH.js";
+import "../../chunk-P3AYBRP6.js";
 import "../../chunk-PRWIX6UW.js";
-import "../../chunk-XWBK3XJK.js";
-import "../../chunk-AHV4GDYM.js";
-import "../../chunk-YK5JEVLX.js";
+import "../../chunk-SR7F3TJY.js";
+import "../../chunk-EO2QPOKH.js";
 import "../../chunk-SQDOBLBP.js";
+import "../../chunk-OGIZXGPY.js";
+import "../../chunk-LG57S2SC.js";
+import "../../chunk-DCCZB4UC.js";
+import "../../chunk-MZ6GV4YF.js";
+import "../../chunk-HNWZFNKP.js";
+import "../../chunk-AHV4GDYM.js";
+import "../../chunk-43SBT72G.js";
+import "../../chunk-4MF3HKJA.js";
+import "../../chunk-TIZXQU26.js";
+import "../../chunk-36U5UGIO.js";
 import {
   isDivisibleCursor
-} from "../../chunk-3NMCDN7L.js";
+} from "../../chunk-5TK7MEN4.js";
 import "../../chunk-4KNXX6TI.js";
 import "../../chunk-3CJFPU6Q.js";
-import "../../chunk-TDEHU73T.js";
 import "../../chunk-S7C6TIIF.js";
-import "../../chunk-MZ6GV4YF.js";
-import "../../chunk-LG57S2SC.js";
-import "../../chunk-HNWZFNKP.js";
-import "../../chunk-WWGYCIJX.js";
-import "../../chunk-4MF3HKJA.js";
-import "../../chunk-YLPAPPLW.js";
-import "../../chunk-36U5UGIO.js";
 import "../../chunk-U64T4YZE.js";
 import "../../chunk-2E224ZSN.js";
 

package/dist/src/index.d.ts

@@ -1681,11 +1681,11 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     }>, z.ZodObject<{
         mode: z.ZodLiteral<"webhook">;
         webhook: z.ZodObject<{
-            eventIdField: z.ZodString;
+            eventIdField: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         }, {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         }>;
         mapping: z.ZodArray<z.ZodObject<{
             source: z.ZodString;
@@ -1715,7 +1715,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -1730,7 +1730,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     }, {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2156,7 +2156,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2366,7 +2366,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2576,7 +2576,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2786,7 +2786,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -2996,7 +2996,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[];
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -3206,7 +3206,7 @@ declare const EntityDefinitionSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | {
         webhook: {
-            eventIdField: string;
+            eventIdField?: string | undefined;
         };
         mode: "webhook";
         mapping: {
@@ -4135,17 +4135,32 @@ declare function isDomainPattern(def: AnyPatternDefinition): def is PatternDefin
 declare function defineOrchestrationPattern(def: OrchestrationPatternDefinition): OrchestrationPatternDefinition;
 
 /**
- * ActivityPattern — replaces `family: activity`.
+ * ActivityPattern — config-driven subject-scoped interaction base.
  *
- * Activity entities represent time-bounded interactions (calls, meetings,
- * emails). The base repository/service expose date-range + opportunity +
- * user-scoped lookups on top of the standard CRUD methods.
+ * Activity entities represent interactions (calls, meetings, emails, messages,
+ * transcripts) that reference a *subject* — the thing the interaction is about.
+ * Which subject is a per-entity fact, not a library constant: a CRM activity is
+ * scoped to an `opportunity`, a swe-brain interaction to a `person` (later
+ * `repo`/`team`, ADR-0006's Salesforce Activities-vs-Records shape). The base
+ * repository/service therefore expose **generic** subject-scoped finders
+ * (`findBySubjectId` / `findRecentBySubjectId`) that read the subject FK column
+ * from the entity's `config:` block, on top of the standard CRUD methods plus
+ * date-range and actor (`user_id`) scoping.
  *
- * Class names, import paths, and inherited-method strings match the
- * legacy `FAMILY_MAP` entry verbatim so PATTERN-5's template swap produces
- * byte-identical output.
+ * The subject FK column resolves from `config: { Activity: { ... } }`:
+ *   - `subjectColumn` — explicit snake_case column, OR
+ *   - `<subject>_id` — derived from the `subject` entity name.
+ * The recency-ordering column is `occurredAt` (snake_case in config), default
+ * `occurred_at`. The base reads these via `this.patternConfig` — the same
+ * ADR-031 §4 hand-off `IntegratedEntityRepository` uses for `integrationConfig`.
+ *
+ * See `docs/specs/ACTIVITY-SUBJECT-1.md`.
  */
-declare const ActivityPattern: PatternDefinition<unknown>;
+declare const ActivityPattern: PatternDefinition<{
+    subject?: string | undefined;
+    subjectColumn?: string | undefined;
+    occurredAt?: string | undefined;
+}>;
 
 /**
  * BasePattern — identity pattern for the `extends` chain.

package/dist/src/index.js

@@ -44,27 +44,27 @@ import {
   validateOrchestrationProject,
   validatePatternComposition,
   validatePatternProject
-} from "../chunk-32DOFN3T.js";
+} from "../chunk-IOQMMH6C.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-24WXSC3C.js";
-import "../chunk-EO2QPOKH.js";
+import "../chunk-P3AYBRP6.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-XWBK3XJK.js";
-import "../chunk-AHV4GDYM.js";
-import "../chunk-YK5JEVLX.js";
+import "../chunk-SR7F3TJY.js";
+import "../chunk-EO2QPOKH.js";
 import "../chunk-SQDOBLBP.js";
-import "../chunk-3NMCDN7L.js";
-import "../chunk-4KNXX6TI.js";
-import "../chunk-3CJFPU6Q.js";
-import "../chunk-TDEHU73T.js";
-import "../chunk-S7C6TIIF.js";
-import "../chunk-MZ6GV4YF.js";
+import "../chunk-OGIZXGPY.js";
 import "../chunk-LG57S2SC.js";
+import "../chunk-DCCZB4UC.js";
+import "../chunk-MZ6GV4YF.js";
 import "../chunk-HNWZFNKP.js";
-import "../chunk-WWGYCIJX.js";
+import "../chunk-AHV4GDYM.js";
+import "../chunk-43SBT72G.js";
 import "../chunk-4MF3HKJA.js";
-import "../chunk-YLPAPPLW.js";
+import "../chunk-TIZXQU26.js";
 import "../chunk-36U5UGIO.js";
+import "../chunk-5TK7MEN4.js";
+import "../chunk-4KNXX6TI.js";
+import "../chunk-3CJFPU6Q.js";
+import "../chunk-S7C6TIIF.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -138,6 +138,7 @@
     "@pattern-stack/codegen-calendar": "workspace:*",
     "@pattern-stack/codegen-crm": "workspace:*",
     "@pattern-stack/codegen-mail": "workspace:*",
+    "@pattern-stack/codegen-messaging": "workspace:*",
     "@pattern-stack/codegen-transcript": "workspace:*",
     "@cubejs-client/core": "^1.0.0",
     "@nestjs/common": "10",

package/runtime/base-classes/activity-entity-repository.ts

@@ -1,26 +1,84 @@
 /**
  * ActivityEntityRepository<TEntity>
  *
- * Family-specific base for activity entities (emails, calls, meetings, notes).
- * Adds date-range queries, user/opportunity scoping, and recency ordering.
+ * Family-specific base for activity / interaction entities (emails, calls,
+ * meetings, messages, transcripts). Adds date-range queries, actor (`user_id`)
+ * scoping, recency ordering, and **config-driven subject scoping** — the
+ * subject FK column is resolved from the concrete repo's `patternConfig`
+ * (ADR-031 §4) rather than hardcoded, so the same base serves a CRM
+ * `opportunity`-scoped activity and a swe-brain `person`-scoped interaction.
  *
- * Concrete repos extend this and declare their table + behaviors.
+ * Concrete repos extend this and declare their table + behaviors, and (when
+ * they use the subject finders) a `patternConfig` carrying `subject` /
+ * `subjectColumn` / `occurredAt`. The template emits that property from the
+ * entity's `config: { Activity: {...} }` block. See ACTIVITY-SUBJECT-1.
  */
 import { eq, between, desc } from 'drizzle-orm';
 import { BaseRepository } from './base-repository';
 
+/**
+ * Per-entity Activity config (matches `ActivityPatternConfigSchema` in
+ * `src/patterns/library/activity.pattern.ts`). Carried on the concrete repo as
+ * `patternConfig` and read here to resolve column names at runtime.
+ */
+export interface ActivityPatternConfig {
+  /** Subject entity name → derives the FK column `<subject>_id`. */
+  subject?: string;
+  /** Explicit snake_case FK column, when it does not follow `<subject>_id`. */
+  subjectColumn?: string;
+  /** snake_case recency-ordering column; defaults to `occurred_at`. */
+  occurredAt?: string;
+}
+
+const toCamel = (snake: string): string =>
+  snake.replace(/_([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
 export abstract class ActivityEntityRepository<TEntity> extends BaseRepository<TEntity> {
   /**
-   * Find activities within a date range (inclusive).
+   * Per-entity Activity config. The template emits this from `config:
+   * { Activity: {...} }`; entities that only use date-range / user scoping omit
+   * it (and must not call the subject finders).
+   */
+  protected readonly patternConfig?: ActivityPatternConfig;
+
+  /**
+   * camelCase key for the recency-ordering column. Defaults to `occurredAt`
+   * (column `occurred_at`); override via `patternConfig.occurredAt`.
+   */
+  protected get occurredAtColumn(): string {
+    const snake = this.patternConfig?.occurredAt ?? 'occurred_at';
+    return toCamel(snake);
+  }
+
+  /**
+   * camelCase key for the subject FK column, resolved from `patternConfig`:
+   * `subjectColumn` (explicit) → `<subject>_id` (derived). Throws when neither
+   * is configured — the subject finders are unusable without it, and a clear
+   * error beats a silent `undefined` column index.
+   */
+  protected get subjectColumn(): string {
+    const explicit = this.patternConfig?.subjectColumn;
+    if (explicit) return toCamel(explicit);
+    const subject = this.patternConfig?.subject;
+    if (subject) return toCamel(`${subject}_id`);
+    throw new Error(
+      'ActivityEntityRepository: subject finders require a subject column. ' +
+        "Set `config: { Activity: { subject: '<entity>' } }` (→ <entity>_id) " +
+        "or `config: { Activity: { subjectColumn: '<column>' } }` on the entity YAML.",
+    );
+  }
+
+  /**
+   * Find activities within a date range (inclusive), by the recency column.
    */
   async findByDateRange(start: Date, end: Date): Promise<TEntity[]> {
     const rows = await this.baseQuery()
-      .where(between(this.table['occurredAt'], start, end));
+      .where(between(this.table[this.occurredAtColumn], start, end));
     return rows as TEntity[];
   }
 
   /**
-   * Find all activities for a specific user.
+   * Find all activities for a specific user (actor / owner scoping).
    */
   async findByUserId(userId: string): Promise<TEntity[]> {
     const rows = await this.baseQuery()
@@ -29,21 +87,22 @@ export abstract class ActivityEntityRepository<TEntity> extends BaseRepository<T
   }
 
   /**
-   * Find all activities for a specific opportunity.
+   * Find all activities for a specific subject (config-driven FK column).
    */
-  async findByOpportunityId(opportunityId: string): Promise<TEntity[]> {
+  async findBySubjectId(subjectId: string): Promise<TEntity[]> {
     const rows = await this.baseQuery()
-      .where(eq(this.table['opportunityId'], opportunityId));
+      .where(eq(this.table[this.subjectColumn], subjectId));
     return rows as TEntity[];
   }
 
   /**
-   * Find the most recent activities for an opportunity, ordered by occurredAt desc.
+   * Find the most recent activities for a subject, ordered by the recency
+   * column descending.
    */
-  async findRecentByOpportunityId(opportunityId: string, limit = 10): Promise<TEntity[]> {
+  async findRecentBySubjectId(subjectId: string, limit = 10): Promise<TEntity[]> {
     const rows = await this.baseQuery()
-      .where(eq(this.table['opportunityId'], opportunityId))
-      .orderBy(desc(this.table['occurredAt']))
+      .where(eq(this.table[this.subjectColumn], subjectId))
+      .orderBy(desc(this.table[this.occurredAtColumn]))
       .limit(limit);
     return rows as TEntity[];
   }