@pattern-stack/codegen 0.2.0

package/dist/runtime/base-classes/lifecycle-events.js

@@ -0,0 +1,76 @@
+// runtime/base-classes/lifecycle-events.ts
+import { randomUUID } from "crypto";
+var SYSTEM_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "createdAt",
+  "updatedAt",
+  "deletedAt"
+]);
+function entitySnapshot(entity) {
+  const snap = {};
+  for (const [key, value] of Object.entries(entity)) {
+    if (!SYSTEM_FIELDS.has(key)) {
+      snap[key] = value;
+    }
+  }
+  return snap;
+}
+function diffSnapshots(before, after) {
+  const changes = [];
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of allKeys) {
+    if (SYSTEM_FIELDS.has(key)) continue;
+    const oldVal = before[key];
+    const newVal = after[key];
+    if (oldVal !== newVal && JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+      changes.push({ field: key, oldValue: oldVal, newValue: newVal });
+    }
+  }
+  return changes;
+}
+function buildLifecycleEvent(entityName, action, entityId, snapshot) {
+  return {
+    id: randomUUID(),
+    type: `${entityName}.${action}`,
+    aggregateId: entityId,
+    aggregateType: entityName,
+    payload: snapshot ? { snapshot } : {},
+    occurredAt: /* @__PURE__ */ new Date(),
+    metadata: { category: "lifecycle" }
+  };
+}
+function buildChangeEvents(entityName, entityId, changes) {
+  return changes.map((c) => ({
+    id: randomUUID(),
+    type: `${entityName}.field_changed`,
+    aggregateId: entityId,
+    aggregateType: entityName,
+    payload: {
+      fieldName: c.field,
+      oldValue: c.oldValue,
+      newValue: c.newValue
+    },
+    occurredAt: /* @__PURE__ */ new Date(),
+    metadata: { category: "change" }
+  }));
+}
+async function emitSafely(eventBus, events) {
+  if (!eventBus || events.length === 0) return;
+  try {
+    if (events.length === 1) {
+      await eventBus.publish(events[0]);
+    } else {
+      await eventBus.publishMany(events);
+    }
+  } catch {
+    console.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);
+  }
+}
+export {
+  buildChangeEvents,
+  buildLifecycleEvent,
+  diffSnapshots,
+  emitSafely,
+  entitySnapshot
+};
+//# sourceMappingURL=lifecycle-events.js.map

package/dist/runtime/base-classes/lifecycle-events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../runtime/base-classes/lifecycle-events.ts"],"sourcesContent":["/**\n * Lifecycle event emission for BaseService.\n *\n * Ported from pattern-stack/atoms/patterns/services/base.py — the Python\n * BaseService emits LIFECYCLE and CHANGE events on every CRUD operation.\n * This module provides the same capability for the TypeScript codegen stack.\n *\n * Design:\n *   - Fire-and-forget: event emission never fails the CRUD operation.\n *   - IEventBus is optional: if no EVENT_BUS is injected, emission is silently\n *     skipped. This means base classes work in projects that haven't installed\n *     the events subsystem.\n *   - LIFECYCLE events carry an entity snapshot in payload.\n *   - CHANGE events carry per-field old/new diffs.\n *   - Controlled per-entity via `emitLifecycleEvents` flag (default: true).\n */\n\nimport { randomUUID } from 'crypto';\nimport type { IEventBus, DomainEvent } from '../subsystems/events/event-bus.protocol';\n\n// ============================================================================\n// Event categories (subset of pattern-stack's EventCategory)\n// ============================================================================\n\nexport type EventCategory = 'lifecycle' | 'change';\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\n/** System fields excluded from entity snapshots and change diffs. */\nconst SYSTEM_FIELDS = new Set([\n\t'id',\n\t'createdAt',\n\t'updatedAt',\n\t'deletedAt',\n]);\n\n/**\n * Snapshot an entity's field values, excluding system fields.\n * Mirrors pattern-stack's `_get_entity_snapshot()`.\n */\nexport function entitySnapshot(entity: Record<string, unknown>): Record<string, unknown> {\n\tconst snap: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(entity)) {\n\t\tif (!SYSTEM_FIELDS.has(key)) {\n\t\t\tsnap[key] = value;\n\t\t}\n\t}\n\treturn snap;\n}\n\n/**\n * Diff two entity snapshots, returning per-field old/new pairs.\n * Only includes fields that actually changed.\n */\nexport function diffSnapshots(\n\tbefore: Record<string, unknown>,\n\tafter: Record<string, unknown>,\n): Array<{ field: string; oldValue: unknown; newValue: unknown }> {\n\tconst changes: Array<{ field: string; oldValue: unknown; newValue: unknown }> = [];\n\tconst allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);\n\n\tfor (const key of allKeys) {\n\t\tif (SYSTEM_FIELDS.has(key)) continue;\n\t\tconst oldVal = before[key];\n\t\tconst newVal = after[key];\n\t\t// Simple equality — good enough for primitives and nulls.\n\t\t// For deep objects, JSON.stringify comparison.\n\t\tif (oldVal !== newVal && JSON.stringify(oldVal) !== JSON.stringify(newVal)) {\n\t\t\tchanges.push({ field: key, oldValue: oldVal, newValue: newVal });\n\t\t}\n\t}\n\n\treturn changes;\n}\n\n// ============================================================================\n// Event builders\n// ============================================================================\n\nexport function buildLifecycleEvent(\n\tentityName: string,\n\taction: 'created' | 'updated' | 'deleted',\n\tentityId: string,\n\tsnapshot?: Record<string, unknown>,\n): DomainEvent {\n\treturn {\n\t\tid: randomUUID(),\n\t\ttype: `${entityName}.${action}`,\n\t\taggregateId: entityId,\n\t\taggregateType: entityName,\n\t\tpayload: snapshot ? { snapshot } : {},\n\t\toccurredAt: new Date(),\n\t\tmetadata: { category: 'lifecycle' as EventCategory },\n\t};\n}\n\nexport function buildChangeEvents(\n\tentityName: string,\n\tentityId: string,\n\tchanges: Array<{ field: string; oldValue: unknown; newValue: unknown }>,\n): DomainEvent[] {\n\treturn changes.map((c) => ({\n\t\tid: randomUUID(),\n\t\ttype: `${entityName}.field_changed`,\n\t\taggregateId: entityId,\n\t\taggregateType: entityName,\n\t\tpayload: {\n\t\t\tfieldName: c.field,\n\t\t\toldValue: c.oldValue,\n\t\t\tnewValue: c.newValue,\n\t\t},\n\t\toccurredAt: new Date(),\n\t\tmetadata: { category: 'change' as EventCategory },\n\t}));\n}\n\n// ============================================================================\n// Emission helper (fire-and-forget)\n// ============================================================================\n\n/**\n * Emit events to the bus, swallowing errors.\n * Mirrors pattern-stack's `_emit_lifecycle_event()` try/except.\n */\nexport async function emitSafely(\n\teventBus: IEventBus | undefined,\n\tevents: DomainEvent[],\n): Promise<void> {\n\tif (!eventBus || events.length === 0) return;\n\ttry {\n\t\tif (events.length === 1) {\n\t\t\tawait eventBus.publish(events[0]);\n\t\t} else {\n\t\t\tawait eventBus.publishMany(events);\n\t\t}\n\t} catch {\n\t\t// Log but never fail the CRUD operation.\n\t\t// In production, this would use a structured logger.\n\t\tconsole.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);\n\t}\n}\n"],"mappings":";AAiBA,SAAS,kBAAkB;AAc3B,IAAM,gBAAgB,oBAAI,IAAI;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD,CAAC;AAMM,SAAS,eAAe,QAA0D;AACxF,QAAM,OAAgC,CAAC;AACvC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AAClD,QAAI,CAAC,cAAc,IAAI,GAAG,GAAG;AAC5B,WAAK,GAAG,IAAI;AAAA,IACb;AAAA,EACD;AACA,SAAO;AACR;AAMO,SAAS,cACf,QACA,OACiE;AACjE,QAAM,UAA0E,CAAC;AACjF,QAAM,UAAU,oBAAI,IAAI,CAAC,GAAG,OAAO,KAAK,MAAM,GAAG,GAAG,OAAO,KAAK,KAAK,CAAC,CAAC;AAEvE,aAAW,OAAO,SAAS;AAC1B,QAAI,cAAc,IAAI,GAAG,EAAG;AAC5B,UAAM,SAAS,OAAO,GAAG;AACzB,UAAM,SAAS,MAAM,GAAG;AAGxB,QAAI,WAAW,UAAU,KAAK,UAAU,MAAM,MAAM,KAAK,UAAU,MAAM,GAAG;AAC3E,cAAQ,KAAK,EAAE,OAAO,KAAK,UAAU,QAAQ,UAAU,OAAO,CAAC;AAAA,IAChE;AAAA,EACD;AAEA,SAAO;AACR;AAMO,SAAS,oBACf,YACA,QACA,UACA,UACc;AACd,SAAO;AAAA,IACN,IAAI,WAAW;AAAA,IACf,MAAM,GAAG,UAAU,IAAI,MAAM;AAAA,IAC7B,aAAa;AAAA,IACb,eAAe;AAAA,IACf,SAAS,WAAW,EAAE,SAAS,IAAI,CAAC;AAAA,IACpC,YAAY,oBAAI,KAAK;AAAA,IACrB,UAAU,EAAE,UAAU,YAA6B;AAAA,EACpD;AACD;AAEO,SAAS,kBACf,YACA,UACA,SACgB;AAChB,SAAO,QAAQ,IAAI,CAAC,OAAO;AAAA,IAC1B,IAAI,WAAW;AAAA,IACf,MAAM,GAAG,UAAU;AAAA,IACnB,aAAa;AAAA,IACb,eAAe;AAAA,IACf,SAAS;AAAA,MACR,WAAW,EAAE;AAAA,MACb,UAAU,EAAE;AAAA,MACZ,UAAU,EAAE;AAAA,IACb;AAAA,IACA,YAAY,oBAAI,KAAK;AAAA,IACrB,UAAU,EAAE,UAAU,SAA0B;AAAA,EACjD,EAAE;AACH;AAUA,eAAsB,WACrB,UACA,QACgB;AAChB,MAAI,CAAC,YAAY,OAAO,WAAW,EAAG;AACtC,MAAI;AACH,QAAI,OAAO,WAAW,GAAG;AACxB,YAAM,SAAS,QAAQ,OAAO,CAAC,CAAC;AAAA,IACjC,OAAO;AACN,YAAM,SAAS,YAAY,MAAM;AAAA,IAClC;AAAA,EACD,QAAQ;AAGP,YAAQ,KAAK,qCAAqC,OAAO,MAAM,WAAW;AAAA,EAC3E;AACD;","names":[]}

package/dist/runtime/base-classes/metadata-entity-repository.d.ts

@@ -0,0 +1,27 @@
+import { PgTableWithColumns } from 'drizzle-orm/pg-core';
+import { BaseRepository } from './base-repository.js';
+import 'drizzle-orm';
+import '../types/drizzle.js';
+import 'drizzle-orm/node-postgres';
+
+declare abstract class MetadataEntityRepository<TEntity> extends BaseRepository<TEntity> {
+    /**
+     * Bulk upsert with a caller-specified conflict target.
+     * Uses Drizzle's onConflictDoUpdate to merge records.
+     */
+    upsertMany(inputs: Array<Partial<TEntity>>, conflictTarget?: keyof PgTableWithColumns<any>['_']['columns']): Promise<TEntity[]>;
+    /**
+     * Find metadata by entity ID and entity type (compound lookup).
+     */
+    findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]>;
+    /**
+     * List all metadata records for an entity.
+     */
+    listByEntityId(entityId: string): Promise<TEntity[]>;
+    /**
+     * List metadata history for an entity, ordered by validFrom descending.
+     */
+    listHistoryByEntityId(entityId: string): Promise<TEntity[]>;
+}
+
+export { MetadataEntityRepository };

package/dist/runtime/base-classes/metadata-entity-repository.js

@@ -0,0 +1,212 @@
+// runtime/base-classes/metadata-entity-repository.ts
+import { eq as eq2, and, desc } from "drizzle-orm";
+
+// runtime/base-classes/base-repository.ts
+import { eq, inArray, isNull, sql } from "drizzle-orm";
+var BaseRepository = class {
+  // eslint-disable-line @typescript-eslint/no-explicit-any
+  /**
+   * Behavior flags controlling automatic behavior injection.
+   * Override in concrete repositories to enable behaviors.
+   */
+  behaviors = {
+    timestamps: false,
+    softDelete: false,
+    userTracking: false
+  };
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  // ============================================================================
+  // Read Operations
+  // ============================================================================
+  /**
+   * Find a single entity by its primary key.
+   * Returns null if not found (or soft-deleted when softDelete=true).
+   */
+  async findById(id) {
+    const rows = await this.baseQuery().where(eq(this.table["id"], id)).limit(1);
+    return rows[0] ?? null;
+  }
+  /**
+   * Find multiple entities by their primary keys.
+   * Returns empty array immediately for empty input (avoids DB errors).
+   */
+  async findByIds(ids) {
+    if (ids.length === 0) return [];
+    const rows = await this.baseQuery().where(inArray(this.table["id"], ids));
+    return rows;
+  }
+  /**
+   * List entities with optional filtering, pagination, and ordering.
+   */
+  async list(options) {
+    let query = this.baseQuery();
+    if (options?.where) {
+      query = query.where(options.where);
+    }
+    if (options?.orderBy) {
+      query = query.orderBy(options.orderBy);
+    }
+    if (options?.limit !== void 0) {
+      query = query.limit(options.limit);
+    }
+    if (options?.offset !== void 0) {
+      query = query.offset(options.offset);
+    }
+    const rows = await query;
+    return rows;
+  }
+  /**
+   * Count entities matching an optional WHERE clause.
+   * Soft-deleted rows are always excluded when softDelete=true.
+   */
+  async count(where) {
+    let query = this.db.select({ count: sql`cast(count(*) as integer)` }).from(this.table);
+    const conditions = [];
+    if (this.behaviors.softDelete) {
+      conditions.push(isNull(this.table["deletedAt"]));
+    }
+    if (where) {
+      conditions.push(where);
+    }
+    if (conditions.length === 1) {
+      query = query.where(conditions[0]);
+    } else if (conditions.length > 1) {
+      const { and: and2 } = await import("drizzle-orm");
+      query = query.where(and2(...conditions));
+    }
+    const rows = await query;
+    return rows[0]?.count ?? 0;
+  }
+  /**
+   * Check whether an entity with the given id exists.
+   */
+  async exists(id) {
+    const result = await this.findById(id);
+    return result !== null;
+  }
+  // ============================================================================
+  // Write Operations
+  // ============================================================================
+  /**
+   * Insert a new entity. Timestamps are auto-injected when timestamps=true.
+   */
+  async create(input) {
+    const data = this.withTimestamps(input, "create");
+    const rows = await this.db.insert(this.table).values(data).returning();
+    return rows[0];
+  }
+  /**
+   * Update an existing entity by id. updatedAt is auto-injected when timestamps=true.
+   * Returns the updated entity.
+   */
+  async update(id, input) {
+    const data = this.withTimestamps(input, "update");
+    const rows = await this.db.update(this.table).set(data).where(eq(this.table["id"], id)).returning();
+    return rows[0];
+  }
+  /**
+   * Delete an entity by id.
+   * - softDelete=true: sets deletedAt to current timestamp
+   * - softDelete=false: hard-deletes the row
+   */
+  async delete(id) {
+    if (this.behaviors.softDelete) {
+      await this.db.update(this.table).set({ deletedAt: /* @__PURE__ */ new Date() }).where(eq(this.table["id"], id));
+    } else {
+      await this.db.delete(this.table).where(eq(this.table["id"], id));
+    }
+  }
+  /**
+   * Insert or update multiple entities.
+   * Default naive implementation — family repositories override with
+   * proper conflict-target upsert (e.g., CrmEntityRepository).
+   */
+  async upsertMany(inputs) {
+    return Promise.all(inputs.map((input) => this.create(input)));
+  }
+  // ============================================================================
+  // Protected Helpers
+  // ============================================================================
+  /**
+   * Base SELECT query that automatically excludes soft-deleted rows
+   * when softDelete behavior is enabled.
+   */
+  baseQuery() {
+    const query = this.db.select().from(this.table).$dynamic();
+    if (this.behaviors.softDelete) {
+      return query.where(isNull(this.table["deletedAt"]));
+    }
+    return query;
+  }
+  /**
+   * Merge timestamp fields into an input object.
+   * - mode='create': adds createdAt and updatedAt
+   * - mode='update': adds updatedAt only
+   *
+   * No-op when timestamps behavior is disabled.
+   */
+  withTimestamps(input, mode) {
+    if (!this.behaviors.timestamps) return input;
+    const now = /* @__PURE__ */ new Date();
+    if (mode === "create") {
+      return { ...input, createdAt: now, updatedAt: now };
+    }
+    return { ...input, updatedAt: now };
+  }
+};
+
+// runtime/base-classes/metadata-entity-repository.ts
+var MetadataEntityRepository = class extends BaseRepository {
+  /**
+   * Bulk upsert with a caller-specified conflict target.
+   * Uses Drizzle's onConflictDoUpdate to merge records.
+   */
+  async upsertMany(inputs, conflictTarget) {
+    if (inputs.length === 0) return [];
+    if (!conflictTarget) {
+      return super.upsertMany(inputs);
+    }
+    const data = inputs.map(
+      (input) => this.withTimestamps(input, "create")
+    );
+    const rows = await this.db.insert(this.table).values(data).onConflictDoUpdate({
+      target: this.table[conflictTarget],
+      set: data[0]
+      // eslint-disable-line @typescript-eslint/no-explicit-any
+    }).returning();
+    return rows;
+  }
+  /**
+   * Find metadata by entity ID and entity type (compound lookup).
+   */
+  async findByEntityIdAndType(entityId, entityType) {
+    const rows = await this.baseQuery().where(
+      and(
+        eq2(this.table["entityId"], entityId),
+        eq2(this.table["entityType"], entityType)
+      )
+    );
+    return rows;
+  }
+  /**
+   * List all metadata records for an entity.
+   */
+  async listByEntityId(entityId) {
+    const rows = await this.baseQuery().where(eq2(this.table["entityId"], entityId));
+    return rows;
+  }
+  /**
+   * List metadata history for an entity, ordered by validFrom descending.
+   */
+  async listHistoryByEntityId(entityId) {
+    const rows = await this.baseQuery().where(eq2(this.table["entityId"], entityId)).orderBy(desc(this.table["validFrom"]));
+    return rows;
+  }
+};
+export {
+  MetadataEntityRepository
+};
+//# sourceMappingURL=metadata-entity-repository.js.map

package/dist/runtime/base-classes/metadata-entity-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../runtime/base-classes/metadata-entity-repository.ts","../../../runtime/base-classes/base-repository.ts"],"sourcesContent":["/**\n * MetadataEntityRepository<TEntity>\n *\n * Family-specific base for metadata entities (field values, field history, tags).\n * Adds entity-scoped lookups, type filtering, history ordering, and bulk upsert.\n *\n * Concrete repos extend this and declare their table + behaviors.\n */\nimport { eq, and, desc } from 'drizzle-orm';\nimport type { PgTableWithColumns } from 'drizzle-orm/pg-core';\nimport { BaseRepository } from './base-repository';\n\nexport abstract class MetadataEntityRepository<TEntity> extends BaseRepository<TEntity> {\n  /**\n   * Bulk upsert with a caller-specified conflict target.\n   * Uses Drizzle's onConflictDoUpdate to merge records.\n   */\n  async upsertMany(\n    inputs: Array<Partial<TEntity>>,\n    conflictTarget?: keyof PgTableWithColumns<any>['_']['columns'], // eslint-disable-line @typescript-eslint/no-explicit-any\n  ): Promise<TEntity[]> {\n    if (inputs.length === 0) return [];\n\n    // Fall back to base class naive upsert when no conflict target provided\n    if (!conflictTarget) {\n      return super.upsertMany(inputs);\n    }\n\n    const data = inputs.map((input) =>\n      this.withTimestamps(input as Record<string, unknown>, 'create'),\n    );\n\n    const rows = await this.db\n      .insert(this.table)\n      .values(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n      .onConflictDoUpdate({\n        target: this.table[conflictTarget as string],\n        set: data[0] as any, // eslint-disable-line @typescript-eslint/no-explicit-any\n      })\n      .returning();\n\n    return rows as TEntity[];\n  }\n\n  /**\n   * Find metadata by entity ID and entity type (compound lookup).\n   */\n  async findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]> {\n    const rows = await this.baseQuery()\n      .where(\n        and(\n          eq(this.table['entityId'], entityId),\n          eq(this.table['entityType'], entityType),\n        ),\n      );\n    return rows as TEntity[];\n  }\n\n  /**\n   * List all metadata records for an entity.\n   */\n  async listByEntityId(entityId: string): Promise<TEntity[]> {\n    const rows = await this.baseQuery()\n      .where(eq(this.table['entityId'], entityId));\n    return rows as TEntity[];\n  }\n\n  /**\n   * List metadata history for an entity, ordered by validFrom descending.\n   */\n  async listHistoryByEntityId(entityId: string): Promise<TEntity[]> {\n    const rows = await this.baseQuery()\n      .where(eq(this.table['entityId'], entityId))\n      .orderBy(desc(this.table['validFrom']));\n    return rows as TEntity[];\n  }\n}\n","/**\n * BaseRepository<TEntity>\n *\n * Abstract base class providing standard CRUD operations via Drizzle ORM.\n * Every generated repository extends this class.\n *\n * Family-specific bases (CrmEntityRepository, etc.) extend this in v0.1\n * without any changes to BaseRepository.\n *\n * NOT @Injectable — concrete repositories are @Injectable and inject DRIZZLE.\n */\nimport { eq, inArray, isNull, sql } from 'drizzle-orm';\nimport type { PgTableWithColumns, PgColumn } from 'drizzle-orm/pg-core';\nimport type { SQL } from 'drizzle-orm';\nimport type { DrizzleClient } from '../types/drizzle';\n\n// ============================================================================\n// Interfaces\n// ============================================================================\n\n/**\n * Behavior flags for the repository. Controls automatic timestamp injection\n * and soft-delete filtering.\n */\nexport interface BehaviorConfig {\n  timestamps: boolean;\n  softDelete: boolean;\n  userTracking: boolean;\n}\n\n/**\n * Options for the list() method.\n */\nexport interface ListOptions {\n  where?: SQL;\n  limit?: number;\n  offset?: number;\n  orderBy?: PgColumn | SQL;\n}\n\n// ============================================================================\n// BaseRepository\n// ============================================================================\n\nexport abstract class BaseRepository<TEntity> {\n  /**\n   * The Drizzle table schema for this entity.\n   * Concrete repositories declare this as a class property.\n   */\n  protected abstract readonly table: PgTableWithColumns<any>; // eslint-disable-line @typescript-eslint/no-explicit-any\n\n  /**\n   * Behavior flags controlling automatic behavior injection.\n   * Override in concrete repositories to enable behaviors.\n   */\n  protected readonly behaviors: BehaviorConfig = {\n    timestamps: false,\n    softDelete: false,\n    userTracking: false,\n  };\n\n  protected readonly db: DrizzleClient;\n\n  constructor(db: DrizzleClient) {\n    this.db = db;\n  }\n\n  // ============================================================================\n  // Read Operations\n  // ============================================================================\n\n  /**\n   * Find a single entity by its primary key.\n   * Returns null if not found (or soft-deleted when softDelete=true).\n   */\n  async findById(id: string): Promise<TEntity | null> {\n    const rows = await this.baseQuery()\n      .where(eq(this.table['id'], id))\n      .limit(1);\n    return (rows[0] as TEntity) ?? null;\n  }\n\n  /**\n   * Find multiple entities by their primary keys.\n   * Returns empty array immediately for empty input (avoids DB errors).\n   */\n  async findByIds(ids: string[]): Promise<TEntity[]> {\n    if (ids.length === 0) return [];\n    const rows = await this.baseQuery().where(inArray(this.table['id'], ids));\n    return rows as TEntity[];\n  }\n\n  /**\n   * List entities with optional filtering, pagination, and ordering.\n   */\n  async list(options?: ListOptions): Promise<TEntity[]> {\n    let query = this.baseQuery();\n\n    if (options?.where) {\n      query = query.where(options.where) as typeof query;\n    }\n    if (options?.orderBy) {\n      query = query.orderBy(options.orderBy as SQL) as typeof query;\n    }\n    if (options?.limit !== undefined) {\n      query = query.limit(options.limit) as typeof query;\n    }\n    if (options?.offset !== undefined) {\n      query = query.offset(options.offset) as typeof query;\n    }\n\n    const rows = await query;\n    return rows as TEntity[];\n  }\n\n  /**\n   * Count entities matching an optional WHERE clause.\n   * Soft-deleted rows are always excluded when softDelete=true.\n   */\n  async count(where?: SQL): Promise<number> {\n    let query = this.db\n      .select({ count: sql<number>`cast(count(*) as integer)` })\n      .from(this.table);\n\n    const conditions: SQL[] = [];\n    if (this.behaviors.softDelete) {\n      conditions.push(isNull(this.table['deletedAt']));\n    }\n    if (where) {\n      conditions.push(where);\n    }\n\n    if (conditions.length === 1) {\n      query = query.where(conditions[0]) as typeof query;\n    } else if (conditions.length > 1) {\n      // Combine with AND by building the condition inline\n      const { and } = await import('drizzle-orm');\n      query = query.where(and(...conditions)) as typeof query;\n    }\n\n    const rows = await query;\n    return rows[0]?.count ?? 0;\n  }\n\n  /**\n   * Check whether an entity with the given id exists.\n   */\n  async exists(id: string): Promise<boolean> {\n    const result = await this.findById(id);\n    return result !== null;\n  }\n\n  // ============================================================================\n  // Write Operations\n  // ============================================================================\n\n  /**\n   * Insert a new entity. Timestamps are auto-injected when timestamps=true.\n   */\n  async create(input: Partial<TEntity>): Promise<TEntity> {\n    const data = this.withTimestamps(input as Record<string, unknown>, 'create');\n    const rows = await this.db\n      .insert(this.table)\n      .values(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n      .returning();\n    return rows[0] as TEntity;\n  }\n\n  /**\n   * Update an existing entity by id. updatedAt is auto-injected when timestamps=true.\n   * Returns the updated entity.\n   */\n  async update(id: string, input: Partial<TEntity>): Promise<TEntity> {\n    const data = this.withTimestamps(input as Record<string, unknown>, 'update');\n    const rows = await this.db\n      .update(this.table)\n      .set(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n      .where(eq(this.table['id'], id))\n      .returning();\n    return rows[0] as TEntity;\n  }\n\n  /**\n   * Delete an entity by id.\n   * - softDelete=true: sets deletedAt to current timestamp\n   * - softDelete=false: hard-deletes the row\n   */\n  async delete(id: string): Promise<void> {\n    if (this.behaviors.softDelete) {\n      await this.db\n        .update(this.table)\n        .set({ deletedAt: new Date() } as any) // eslint-disable-line @typescript-eslint/no-explicit-any\n        .where(eq(this.table['id'], id));\n    } else {\n      await this.db\n        .delete(this.table)\n        .where(eq(this.table['id'], id));\n    }\n  }\n\n  /**\n   * Insert or update multiple entities.\n   * Default naive implementation — family repositories override with\n   * proper conflict-target upsert (e.g., CrmEntityRepository).\n   */\n  async upsertMany(inputs: Array<Partial<TEntity>>): Promise<TEntity[]> {\n    return Promise.all(inputs.map((input) => this.create(input)));\n  }\n\n  // ============================================================================\n  // Protected Helpers\n  // ============================================================================\n\n  /**\n   * Base SELECT query that automatically excludes soft-deleted rows\n   * when softDelete behavior is enabled.\n   */\n  protected baseQuery() {\n    const query = this.db.select().from(this.table).$dynamic();\n    if (this.behaviors.softDelete) {\n      return query.where(isNull(this.table['deletedAt']));\n    }\n    return query;\n  }\n\n  /**\n   * Merge timestamp fields into an input object.\n   * - mode='create': adds createdAt and updatedAt\n   * - mode='update': adds updatedAt only\n   *\n   * No-op when timestamps behavior is disabled.\n   */\n  protected withTimestamps(\n    input: Record<string, unknown>,\n    mode: 'create' | 'update',\n  ): Record<string, unknown> {\n    if (!this.behaviors.timestamps) return input;\n    const now = new Date();\n    if (mode === 'create') {\n      return { ...input, createdAt: now, updatedAt: now };\n    }\n    return { ...input, updatedAt: now };\n  }\n}\n"],"mappings":"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","names":["eq","and","eq"]}

package/dist/runtime/base-classes/metadata-entity-service.d.ts

@@ -0,0 +1,39 @@
+import { IBaseRepository, BaseService } from './base-service.js';
+import '../subsystems/events/event-bus.protocol.js';
+import '../types/drizzle.js';
+import 'drizzle-orm/node-postgres';
+
+/**
+ * MetadataEntityService<TRepo, TEntity>
+ *
+ * Family-specific base service for metadata entities.
+ * Delegates to a metadata repository that provides entity-scoped
+ * lookups, history, and bulk upsert.
+ */
+
+interface IMetadataEntityRepository<TEntity> extends IBaseRepository<TEntity> {
+    findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]>;
+    listByEntityId(entityId: string): Promise<TEntity[]>;
+    listHistoryByEntityId(entityId: string): Promise<TEntity[]>;
+    upsertMany(inputs: Array<Partial<TEntity>>, conflictTarget: string): Promise<TEntity[]>;
+}
+declare abstract class MetadataEntityService<TRepo extends IMetadataEntityRepository<TEntity>, TEntity> extends BaseService<TRepo, TEntity> {
+    /**
+     * Find metadata records by entity ID and entity type (EAV polymorphic lookup).
+     */
+    findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]>;
+    /**
+     * List all metadata records for an entity.
+     */
+    listByEntity(entityId: string): Promise<TEntity[]>;
+    /**
+     * List metadata history for an entity, ordered by validFrom desc.
+     */
+    listHistory(entityId: string): Promise<TEntity[]>;
+    /**
+     * Bulk upsert metadata values.
+     */
+    upsertValues(inputs: Array<Partial<TEntity>>, conflictTarget: string): Promise<TEntity[]>;
+}
+
+export { type IMetadataEntityRepository, MetadataEntityService };

package/dist/runtime/base-classes/metadata-entity-service.js

@@ -0,0 +1,214 @@
+// runtime/base-classes/lifecycle-events.ts
+import { randomUUID } from "crypto";
+var SYSTEM_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "createdAt",
+  "updatedAt",
+  "deletedAt"
+]);
+function entitySnapshot(entity) {
+  const snap = {};
+  for (const [key, value] of Object.entries(entity)) {
+    if (!SYSTEM_FIELDS.has(key)) {
+      snap[key] = value;
+    }
+  }
+  return snap;
+}
+function diffSnapshots(before, after) {
+  const changes = [];
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of allKeys) {
+    if (SYSTEM_FIELDS.has(key)) continue;
+    const oldVal = before[key];
+    const newVal = after[key];
+    if (oldVal !== newVal && JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+      changes.push({ field: key, oldValue: oldVal, newValue: newVal });
+    }
+  }
+  return changes;
+}
+function buildLifecycleEvent(entityName, action, entityId, snapshot) {
+  return {
+    id: randomUUID(),
+    type: `${entityName}.${action}`,
+    aggregateId: entityId,
+    aggregateType: entityName,
+    payload: snapshot ? { snapshot } : {},
+    occurredAt: /* @__PURE__ */ new Date(),
+    metadata: { category: "lifecycle" }
+  };
+}
+function buildChangeEvents(entityName, entityId, changes) {
+  return changes.map((c) => ({
+    id: randomUUID(),
+    type: `${entityName}.field_changed`,
+    aggregateId: entityId,
+    aggregateType: entityName,
+    payload: {
+      fieldName: c.field,
+      oldValue: c.oldValue,
+      newValue: c.newValue
+    },
+    occurredAt: /* @__PURE__ */ new Date(),
+    metadata: { category: "change" }
+  }));
+}
+async function emitSafely(eventBus, events) {
+  if (!eventBus || events.length === 0) return;
+  try {
+    if (events.length === 1) {
+      await eventBus.publish(events[0]);
+    } else {
+      await eventBus.publishMany(events);
+    }
+  } catch {
+    console.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);
+  }
+}
+
+// runtime/base-classes/base-service.ts
+var BaseService = class {
+  constructor(repository) {
+    this.repository = repository;
+  }
+  repository;
+  /**
+   * Entity name for event types (e.g., 'account' → 'account.created').
+   * Set by generated services. If empty, lifecycle events are skipped.
+   */
+  entityName;
+  /**
+   * Event bus for lifecycle/change event emission.
+   * Injected via @Inject(EVENT_BUS) @Optional() on generated services.
+   * If undefined (no events subsystem installed), emission is silently skipped.
+   */
+  eventBus;
+  /**
+   * Whether to emit lifecycle events. Default: true.
+   * Override to false in entity YAML via behaviors or in the service class.
+   */
+  emitLifecycleEvents = true;
+  /**
+   * Find a single entity by its primary key.
+   * Returns null if not found.
+   */
+  findById(id) {
+    return this.repository.findById(id);
+  }
+  /**
+   * Find multiple entities by their primary keys.
+   */
+  findByIds(ids) {
+    return this.repository.findByIds(ids);
+  }
+  /**
+   * List entities with optional filtering/pagination options.
+   */
+  list(options) {
+    return this.repository.list(options);
+  }
+  /**
+   * Count entities matching an optional filter.
+   */
+  count(where) {
+    return this.repository.count(where);
+  }
+  /**
+   * Check whether an entity with the given id exists.
+   */
+  exists(id) {
+    return this.repository.exists(id);
+  }
+  /**
+   * Insert a new entity.
+   * Emits a LIFECYCLE 'created' event with entity snapshot.
+   */
+  async create(input) {
+    const result = await this.repository.create(input);
+    if (this._shouldEmit()) {
+      const snap = entitySnapshot(result);
+      const id = result.id;
+      const event = buildLifecycleEvent(this.entityName, "created", id, snap);
+      void emitSafely(this.eventBus, [event]);
+    }
+    return result;
+  }
+  /**
+   * Update an existing entity by id.
+   * Emits a LIFECYCLE 'updated' event + CHANGE events for each modified field.
+   */
+  async update(id, input) {
+    let before;
+    if (this._shouldEmit()) {
+      const existing = await this.repository.findById(id);
+      if (existing) {
+        before = entitySnapshot(existing);
+      }
+    }
+    const result = await this.repository.update(id, input);
+    if (this._shouldEmit()) {
+      const after = entitySnapshot(result);
+      const events = [
+        buildLifecycleEvent(this.entityName, "updated", id, after)
+      ];
+      if (before) {
+        const changes = diffSnapshots(before, after);
+        if (changes.length > 0) {
+          events.push(...buildChangeEvents(this.entityName, id, changes));
+        }
+      }
+      void emitSafely(this.eventBus, events);
+    }
+    return result;
+  }
+  /**
+   * Delete an entity by id.
+   * Emits a LIFECYCLE 'deleted' event.
+   */
+  async delete(id) {
+    await this.repository.delete(id);
+    if (this._shouldEmit()) {
+      const event = buildLifecycleEvent(this.entityName, "deleted", id);
+      void emitSafely(this.eventBus, [event]);
+    }
+  }
+  /** Check whether lifecycle event emission is active. */
+  _shouldEmit() {
+    return Boolean(
+      this.emitLifecycleEvents && this.entityName && this.eventBus
+    );
+  }
+};
+
+// runtime/base-classes/metadata-entity-service.ts
+var MetadataEntityService = class extends BaseService {
+  /**
+   * Find metadata records by entity ID and entity type (EAV polymorphic lookup).
+   */
+  findByEntityIdAndType(entityId, entityType) {
+    return this.repository.findByEntityIdAndType(entityId, entityType);
+  }
+  /**
+   * List all metadata records for an entity.
+   */
+  listByEntity(entityId) {
+    return this.repository.listByEntityId(entityId);
+  }
+  /**
+   * List metadata history for an entity, ordered by validFrom desc.
+   */
+  listHistory(entityId) {
+    return this.repository.listHistoryByEntityId(entityId);
+  }
+  /**
+   * Bulk upsert metadata values.
+   */
+  upsertValues(inputs, conflictTarget) {
+    return this.repository.upsertMany(inputs, conflictTarget);
+  }
+};
+export {
+  MetadataEntityService
+};
+//# sourceMappingURL=metadata-entity-service.js.map

package/dist/runtime/base-classes/metadata-entity-service.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../runtime/base-classes/lifecycle-events.ts","../../../runtime/base-classes/base-service.ts","../../../runtime/base-classes/metadata-entity-service.ts"],"sourcesContent":["/**\n * Lifecycle event emission for BaseService.\n *\n * Ported from pattern-stack/atoms/patterns/services/base.py — the Python\n * BaseService emits LIFECYCLE and CHANGE events on every CRUD operation.\n * This module provides the same capability for the TypeScript codegen stack.\n *\n * Design:\n *   - Fire-and-forget: event emission never fails the CRUD operation.\n *   - IEventBus is optional: if no EVENT_BUS is injected, emission is silently\n *     skipped. This means base classes work in projects that haven't installed\n *     the events subsystem.\n *   - LIFECYCLE events carry an entity snapshot in payload.\n *   - CHANGE events carry per-field old/new diffs.\n *   - Controlled per-entity via `emitLifecycleEvents` flag (default: true).\n */\n\nimport { randomUUID } from 'crypto';\nimport type { IEventBus, DomainEvent } from '../subsystems/events/event-bus.protocol';\n\n// ============================================================================\n// Event categories (subset of pattern-stack's EventCategory)\n// ============================================================================\n\nexport type EventCategory = 'lifecycle' | 'change';\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\n/** System fields excluded from entity snapshots and change diffs. */\nconst SYSTEM_FIELDS = new Set([\n\t'id',\n\t'createdAt',\n\t'updatedAt',\n\t'deletedAt',\n]);\n\n/**\n * Snapshot an entity's field values, excluding system fields.\n * Mirrors pattern-stack's `_get_entity_snapshot()`.\n */\nexport function entitySnapshot(entity: Record<string, unknown>): Record<string, unknown> {\n\tconst snap: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(entity)) {\n\t\tif (!SYSTEM_FIELDS.has(key)) {\n\t\t\tsnap[key] = value;\n\t\t}\n\t}\n\treturn snap;\n}\n\n/**\n * Diff two entity snapshots, returning per-field old/new pairs.\n * Only includes fields that actually changed.\n */\nexport function diffSnapshots(\n\tbefore: Record<string, unknown>,\n\tafter: Record<string, unknown>,\n): Array<{ field: string; oldValue: unknown; newValue: unknown }> {\n\tconst changes: Array<{ field: string; oldValue: unknown; newValue: unknown }> = [];\n\tconst allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);\n\n\tfor (const key of allKeys) {\n\t\tif (SYSTEM_FIELDS.has(key)) continue;\n\t\tconst oldVal = before[key];\n\t\tconst newVal = after[key];\n\t\t// Simple equality — good enough for primitives and nulls.\n\t\t// For deep objects, JSON.stringify comparison.\n\t\tif (oldVal !== newVal && JSON.stringify(oldVal) !== JSON.stringify(newVal)) {\n\t\t\tchanges.push({ field: key, oldValue: oldVal, newValue: newVal });\n\t\t}\n\t}\n\n\treturn changes;\n}\n\n// ============================================================================\n// Event builders\n// ============================================================================\n\nexport function buildLifecycleEvent(\n\tentityName: string,\n\taction: 'created' | 'updated' | 'deleted',\n\tentityId: string,\n\tsnapshot?: Record<string, unknown>,\n): DomainEvent {\n\treturn {\n\t\tid: randomUUID(),\n\t\ttype: `${entityName}.${action}`,\n\t\taggregateId: entityId,\n\t\taggregateType: entityName,\n\t\tpayload: snapshot ? { snapshot } : {},\n\t\toccurredAt: new Date(),\n\t\tmetadata: { category: 'lifecycle' as EventCategory },\n\t};\n}\n\nexport function buildChangeEvents(\n\tentityName: string,\n\tentityId: string,\n\tchanges: Array<{ field: string; oldValue: unknown; newValue: unknown }>,\n): DomainEvent[] {\n\treturn changes.map((c) => ({\n\t\tid: randomUUID(),\n\t\ttype: `${entityName}.field_changed`,\n\t\taggregateId: entityId,\n\t\taggregateType: entityName,\n\t\tpayload: {\n\t\t\tfieldName: c.field,\n\t\t\toldValue: c.oldValue,\n\t\t\tnewValue: c.newValue,\n\t\t},\n\t\toccurredAt: new Date(),\n\t\tmetadata: { category: 'change' as EventCategory },\n\t}));\n}\n\n// ============================================================================\n// Emission helper (fire-and-forget)\n// ============================================================================\n\n/**\n * Emit events to the bus, swallowing errors.\n * Mirrors pattern-stack's `_emit_lifecycle_event()` try/except.\n */\nexport async function emitSafely(\n\teventBus: IEventBus | undefined,\n\tevents: DomainEvent[],\n): Promise<void> {\n\tif (!eventBus || events.length === 0) return;\n\ttry {\n\t\tif (events.length === 1) {\n\t\t\tawait eventBus.publish(events[0]);\n\t\t} else {\n\t\t\tawait eventBus.publishMany(events);\n\t\t}\n\t} catch {\n\t\t// Log but never fail the CRUD operation.\n\t\t// In production, this would use a structured logger.\n\t\tconsole.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);\n\t}\n}\n","/**\n * BaseService<TRepo, TEntity>\n *\n * Abstract base class providing 8 CRUD pass-through methods delegating to\n * an injected repository. Every generated service extends this class.\n *\n * Lifecycle event emission (LIFECYCLE + CHANGE categories) is built into\n * create/update/delete — matching pattern-stack's BaseService. Events are\n * fire-and-forget: emission never fails the CRUD operation. If no IEventBus\n * is injected (eventBus is undefined), emission is silently skipped.\n *\n * Generated services set `entityName` and optionally inject `eventBus` via\n * NestJS property injection (@Inject(EVENT_BUS) @Optional()).\n *\n * Note: @Injectable() is applied on concrete services (not here) so that\n * NestJS DI metadata is emitted at the concrete class level. This matches\n * the pattern established by BaseRepository.\n */\n\nimport type { IEventBus } from '../subsystems/events/event-bus.protocol';\nimport {\n  entitySnapshot,\n  diffSnapshots,\n  buildLifecycleEvent,\n  buildChangeEvents,\n  emitSafely,\n} from './lifecycle-events';\n\n// ============================================================================\n// IBaseRepository interface\n// ============================================================================\n\n/**\n * Structural interface that BaseRepository satisfies.\n * Use this as the TRepo constraint so BaseService is not coupled to the\n * concrete Drizzle-backed BaseRepository.\n */\nexport interface IBaseRepository<TEntity> {\n  findById(id: string): Promise<TEntity | null>;\n  findByIds(ids: string[]): Promise<TEntity[]>;\n  list(options?: unknown): Promise<TEntity[]>;\n  count(where?: unknown): Promise<number>;\n  exists(id: string): Promise<boolean>;\n  create(input: Partial<TEntity>): Promise<TEntity>;\n  update(id: string, input: Partial<TEntity>): Promise<TEntity>;\n  delete(id: string): Promise<void>;\n}\n\n// ============================================================================\n// BaseService\n// ============================================================================\n\nexport abstract class BaseService<TRepo extends IBaseRepository<TEntity>, TEntity> {\n  /**\n   * Entity name for event types (e.g., 'account' → 'account.created').\n   * Set by generated services. If empty, lifecycle events are skipped.\n   */\n  protected entityName?: string;\n\n  /**\n   * Event bus for lifecycle/change event emission.\n   * Injected via @Inject(EVENT_BUS) @Optional() on generated services.\n   * If undefined (no events subsystem installed), emission is silently skipped.\n   */\n  protected eventBus?: IEventBus;\n\n  /**\n   * Whether to emit lifecycle events. Default: true.\n   * Override to false in entity YAML via behaviors or in the service class.\n   */\n  protected emitLifecycleEvents = true;\n\n  constructor(protected readonly repository: TRepo) {}\n\n  /**\n   * Find a single entity by its primary key.\n   * Returns null if not found.\n   */\n  findById(id: string): Promise<TEntity | null> {\n    return this.repository.findById(id);\n  }\n\n  /**\n   * Find multiple entities by their primary keys.\n   */\n  findByIds(ids: string[]): Promise<TEntity[]> {\n    return this.repository.findByIds(ids);\n  }\n\n  /**\n   * List entities with optional filtering/pagination options.\n   */\n  list(options?: unknown): Promise<TEntity[]> {\n    return this.repository.list(options);\n  }\n\n  /**\n   * Count entities matching an optional filter.\n   */\n  count(where?: unknown): Promise<number> {\n    return this.repository.count(where);\n  }\n\n  /**\n   * Check whether an entity with the given id exists.\n   */\n  exists(id: string): Promise<boolean> {\n    return this.repository.exists(id);\n  }\n\n  /**\n   * Insert a new entity.\n   * Emits a LIFECYCLE 'created' event with entity snapshot.\n   */\n  async create(input: Partial<TEntity>): Promise<TEntity> {\n    const result = await this.repository.create(input);\n\n    if (this._shouldEmit()) {\n      const snap = entitySnapshot(result as Record<string, unknown>);\n      const id = (result as Record<string, unknown>).id as string;\n      const event = buildLifecycleEvent(this.entityName!, 'created', id, snap);\n      void emitSafely(this.eventBus, [event]);\n    }\n\n    return result;\n  }\n\n  /**\n   * Update an existing entity by id.\n   * Emits a LIFECYCLE 'updated' event + CHANGE events for each modified field.\n   */\n  async update(id: string, input: Partial<TEntity>): Promise<TEntity> {\n    // Snapshot before for change diffing\n    let before: Record<string, unknown> | undefined;\n    if (this._shouldEmit()) {\n      const existing = await this.repository.findById(id);\n      if (existing) {\n        before = entitySnapshot(existing as Record<string, unknown>);\n      }\n    }\n\n    const result = await this.repository.update(id, input);\n\n    if (this._shouldEmit()) {\n      const after = entitySnapshot(result as Record<string, unknown>);\n      const events = [\n        buildLifecycleEvent(this.entityName!, 'updated', id, after),\n      ];\n      // Append per-field CHANGE events\n      if (before) {\n        const changes = diffSnapshots(before, after);\n        if (changes.length > 0) {\n          events.push(...buildChangeEvents(this.entityName!, id, changes));\n        }\n      }\n      void emitSafely(this.eventBus, events);\n    }\n\n    return result;\n  }\n\n  /**\n   * Delete an entity by id.\n   * Emits a LIFECYCLE 'deleted' event.\n   */\n  async delete(id: string): Promise<void> {\n    await this.repository.delete(id);\n\n    if (this._shouldEmit()) {\n      const event = buildLifecycleEvent(this.entityName!, 'deleted', id);\n      void emitSafely(this.eventBus, [event]);\n    }\n  }\n\n  /** Check whether lifecycle event emission is active. */\n  private _shouldEmit(): boolean {\n    return Boolean(\n      this.emitLifecycleEvents &&\n      this.entityName &&\n      this.eventBus,\n    );\n  }\n}\n","/**\n * MetadataEntityService<TRepo, TEntity>\n *\n * Family-specific base service for metadata entities.\n * Delegates to a metadata repository that provides entity-scoped\n * lookups, history, and bulk upsert.\n */\nimport { BaseService, type IBaseRepository } from './base-service';\n\nexport interface IMetadataEntityRepository<TEntity> extends IBaseRepository<TEntity> {\n  findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]>;\n  listByEntityId(entityId: string): Promise<TEntity[]>;\n  listHistoryByEntityId(entityId: string): Promise<TEntity[]>;\n  upsertMany(inputs: Array<Partial<TEntity>>, conflictTarget: string): Promise<TEntity[]>;\n}\n\nexport abstract class MetadataEntityService<\n  TRepo extends IMetadataEntityRepository<TEntity>,\n  TEntity,\n> extends BaseService<TRepo, TEntity> {\n  /**\n   * Find metadata records by entity ID and entity type (EAV polymorphic lookup).\n   */\n  findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]> {\n    return this.repository.findByEntityIdAndType(entityId, entityType);\n  }\n\n  /**\n   * List all metadata records for an entity.\n   */\n  listByEntity(entityId: string): Promise<TEntity[]> {\n    return this.repository.listByEntityId(entityId);\n  }\n\n  /**\n   * List metadata history for an entity, ordered by validFrom desc.\n   */\n  listHistory(entityId: string): Promise<TEntity[]> {\n    return this.repository.listHistoryByEntityId(entityId);\n  }\n\n  /**\n   * Bulk upsert metadata values.\n   */\n  upsertValues(inputs: Array<Partial<TEntity>>, conflictTarget: string): Promise<TEntity[]> {\n    return this.repository.upsertMany(inputs, conflictTarget);\n  }\n}\n"],"mappings":"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","names":[]}