@classytic/party 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,592 @@
+import { OperationOptions, PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
+import { Connection, Model, Schema, SchemaDefinitionProperty, Types } from "mongoose";
+import { DomainEvent, EventHandler, EventMeta, EventTransport } from "@classytic/primitives/events";
+import { z } from "zod";
+import { OutboxStore } from "@classytic/primitives/outbox";
+import { OperationContext } from "@classytic/primitives/context";
+import { ExternalRef, ExternalRef as ExternalRef$1 } from "@classytic/primitives/reference";
+import { PersonName, PersonName as PersonName$1 } from "@classytic/primitives/person";
+import { ContactAddress } from "@classytic/primitives/address";
+import { HttpError } from "@classytic/repo-core/errors";
+//#region src/domain/enums.d.ts
+/**
+ * Party-native enumerations.
+ *
+ * These are identity-kernel concepts (kind, role, lifecycle) — they have no
+ * one-to-one primitive to subset, so they are declared here as the source of
+ * truth. Domain FACETS (finance terms, CRM stage, loyalty tier) live in their
+ * OWN packages keyed by `partyId`; they are deliberately NOT modelled here —
+ * that separation is the whole point of the SAP-style thin identity kernel
+ * (vs. Odoo's `res.partner` god-object).
+ */
+/** What kind of real-world entity a party is. */
+declare const PARTY_KINDS: readonly ['person', 'company', 'group'];
+type PartyKind = (typeof PARTY_KINDS)[number];
+/**
+ * Roles a party plays. NON-exclusive — one party can be a customer AND a
+ * supplier AND a contact simultaneously (the exact de-duplication a shared
+ * identity buys you). Roles are additive flags, never separate entities.
+ */
+declare const PARTY_ROLES: readonly ['customer', 'supplier', 'contact', 'employee', 'partner'];
+type PartyRole = (typeof PARTY_ROLES)[number];
+/**
+ * Identity lifecycle. `merged` is terminal — the row survives as a redirect
+ * (`mergedInto`) so historical references (orders, invoices) still resolve.
+ */
+declare const PARTY_STATUSES: readonly ['active', 'archived', 'merged'];
+type PartyStatus = (typeof PARTY_STATUSES)[number];
+/** Channel kind for a contact point. Drives normalization + dedup keys. */
+declare const CONTACT_POINT_TYPES: readonly ['email', 'phone'];
+type ContactPointType = (typeof CONTACT_POINT_TYPES)[number];
+/**
+ * Address role. Mirrors Odoo's `type` (contact/invoice/delivery/other) but
+ * as a first-class enum. A party carries many; `isDefault` picks the fallback.
+ */
+declare const ADDRESS_TYPES: readonly ['billing', 'shipping', 'contact', 'other'];
+type AddressType = (typeof ADDRESS_TYPES)[number];
+//#endregion
+//#region src/domain/value-objects.d.ts
+/**
+ * A postal address on a party. Extends primitives' `ContactAddress` (recipient
+ * name/phone/email over the base `Address`) with a role + default flag —
+ * mirrors Odoo's per-address `type` without the child-partner overhead.
+ */
+interface PartyAddress extends ContactAddress {
+  type: AddressType;
+  isDefault: boolean;
+  /** Human label ("Head office", "Warehouse 2"). */
+  label?: string;
+}
+/**
+ * A reachable identity channel. `value` is what the user typed; `key` is the
+ * normalized dedup form (`email:ada@x.com`, `phone:+8801...`). Structurally a
+ * normalized, verifiable superset of primitives' flat `ContactInfo` (§P5) — the
+ * kernel dedups on `key` but never mangles the display `value`.
+ */
+interface ContactPoint {
+  type: ContactPointType;
+  value: string;
+  /** Normalized dedup key — the `identityKeys` index entry. */
+  key: string;
+  isPrimary: boolean;
+  verified: boolean;
+}
+/**
+ * Statutory tax identity. Country-agnostic slots — a BD deployment fills
+ * `bin`/`vat`; `fiscalPositionCode` is an opaque host-policy string the active
+ * jurisdiction pack interprets. Finance TERMS (AR/AP accounts, credit, payment
+ * terms) are NOT here — they are the finance facet keyed by `partyId`, not
+ * identity.
+ */
+interface TaxIdentity {
+  vat?: string;
+  /** Business Identification Number (BD) or equivalent national registry id. */
+  bin?: string;
+  /** Opaque fiscal-position code the active jurisdiction pack resolves. */
+  fiscalPositionCode?: string;
+  /** ISO 3166-1 alpha-2 tax residence country. */
+  countryCode?: string;
+}
+/**
+ * The read-model a consuming domain freezes onto its own document (orders,
+ * invoices) at write time — the party equivalent of order's `customerSnapshot`.
+ * Never a live join; capture-at-time so a later merge/rename can't rewrite
+ * history.
+ */
+interface PartySnapshot {
+  partyId: string;
+  kind: PartyKind;
+  displayName: string;
+  legalName?: string;
+  primaryEmail?: string;
+  primaryPhone?: string;
+  roles: PartyRole[];
+  status: PartyStatus;
+  taxIdentity?: TaxIdentity;
+}
+//#endregion
+//#region src/domain/ports.d.ts
+/**
+ * Operation context threaded through every domain verb. Extends primitives'
+ * `OperationContext`; narrows the id fields to what Mongoose stores cleanly.
+ */
+interface PartyContext extends OperationContext {
+  organizationId?: string | Types.ObjectId;
+  actorId?: string | Types.ObjectId;
+  /** Mongo transaction session, passed straight to mongokit. */
+  session?: unknown;
+  /** Cooperative cancellation — threaded to mongokit at choke points. */
+  signal?: AbortSignal;
+  /** Retry policy for driver round-trips (mongokit `RetryPolicy`). */
+  retryPolicy?: unknown;
+}
+/**
+ * Identity signals a consumer already knows about a party. `resolveOrCreate`
+ * matches on ANY of the normalized keys derived from `emails`/`phones`/`vat`/
+ * `bin`/`externalRefs` and falls back to creating a fresh party from the
+ * display fields. At least one identity signal OR `displayName` is required.
+ */
+interface ResolvePartyInput {
+  kind?: PartyKind;
+  displayName?: string;
+  legalName?: string;
+  /** Structured name for `kind: 'person'` — primitives' `PersonName` (§P3). */
+  personName?: PersonName$1;
+  emails?: string[];
+  phones?: string[];
+  addresses?: PartyAddress[];
+  taxIdentity?: TaxIdentity;
+  /** Roles to ensure on the resolved/created party (additive, deduped). */
+  roles?: PartyRole[];
+  /** External-store links to attach (migration seam) — primitives' `ExternalRef`. */
+  externalRefs?: ExternalRef$1[];
+  /** Auth user id to link (1:many — a company party has many portal users). */
+  userId?: string;
+  parentId?: string;
+  metadata?: Record<string, unknown>;
+}
+/** Result of a resolve — the party plus whether this call created it. */
+interface ResolveResult<TParty> {
+  party: TParty;
+  created: boolean;
+}
+/**
+ * The reusable identity resolver. Domains depend on THIS, not on the party
+ * models — so the kernel can evolve its storage without touching consumers, and
+ * a non-Mongo host could implement the same port over a different backend.
+ *
+ * The kernel's `PartyRepository` implements it; hosts wire it into order / crm /
+ * ledger / commerce as the single identity source.
+ */
+interface PartyPort<TParty = unknown> {
+  /** Find an existing party by any identity signal, else create one. Race-safe. */
+  resolveOrCreate(input: ResolvePartyInput, ctx: PartyContext): Promise<ResolveResult<TParty>>;
+  /** Batch identity resolution — avoids N+1 when enriching a list. */
+  resolveMany(inputs: ResolvePartyInput[], ctx: PartyContext): Promise<Array<ResolveResult<TParty>>>;
+  /** The capture-at-time read model to freeze onto a consuming document. */
+  snapshot(partyId: string, ctx: PartyContext): Promise<PartySnapshot>;
+}
+/** Minimal logger surface the in-process bus + repositories log through. */
+interface PartyLogger {
+  info?(msg: string, meta?: Record<string, unknown>): void;
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+  error?(msg: string, meta?: Record<string, unknown>): void;
+  debug?(msg: string, meta?: Record<string, unknown>): void;
+}
+//#endregion
+//#region src/models/tenant-field.d.ts
+type TenantFieldType = 'objectId' | 'string';
+interface SchemaBuildConfig {
+  /** Schema type for the tenant column. Engine plumbs this everywhere. */
+  tenantFieldType: TenantFieldType;
+  /**
+   * When `false`, models carry NO tenant column (company-wide identity). The
+   * engine wires no `multiTenantPlugin` either. Default `true`.
+   */
+  multiTenant: boolean;
+}
+/**
+ * Tenant-column schema definition, or `undefined` when the engine is
+ * company-wide (`multiTenant: false`) so the field is simply not added.
+ */
+declare function tenantFieldDef(config: SchemaBuildConfig): SchemaDefinitionProperty | undefined;
+//#endregion
+//#region src/models/party.model.d.ts
+interface IPartyDocument {
+  _id: Types.ObjectId;
+  /** Present only when the engine runs multi-tenant; absent for company-wide identity. */
+  organizationId?: Types.ObjectId | string;
+  kind: PartyKind;
+  displayName: string;
+  legalName?: string;
+  personName?: PersonName$1;
+  contactPoints: ContactPoint[];
+  /** Normalized dedup keys derived from contactPoints + taxIdentity — the resolve index. */
+  identityKeys: string[];
+  addresses: PartyAddress[];
+  taxIdentity?: TaxIdentity;
+  roles: PartyRole[];
+  externalRefs: ExternalRef$1[];
+  /** Auth user ids linked to this party (1:many — a company has many portal logins). */
+  userLinks: string[];
+  parentId?: Types.ObjectId | string;
+  status: PartyStatus;
+  /** Set when `status: 'merged'` — the survivor this party redirects to. */
+  mergedInto?: Types.ObjectId | string;
+  tags: string[];
+  metadata?: Record<string, unknown>;
+  /** Optimistic-concurrency counter (drives `claimVersion`). */
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+declare function buildPartySchema(config: SchemaBuildConfig): Schema<IPartyDocument>;
+//#endregion
+//#region src/models/create-models.d.ts
+interface PartyModels {
+  Party: Model<IPartyDocument>;
+}
+/** Mongoose model names this package registers — drives the §21 collision check. */
+declare const PARTY_MODEL_NAMES: readonly ['Party'];
+interface CreateModelsOptions extends SchemaBuildConfig {
+  /** On a name collision: `false` (default) throws; `true` deletes + re-registers (tests). */
+  forceRecreate?: boolean;
+  /** Mongoose auto-index builds. Default `true` (dev); `false` in prod (§35). */
+  autoIndex?: boolean;
+}
+declare function createPartyModels(connection: Connection, config: CreateModelsOptions): PartyModels;
+//#endregion
+//#region src/events/dispatch.d.ts
+/** Context key carrying a post-commit publish queue (attached by `withTransaction`). */
+declare const PENDING_EVENTS: unique symbol;
+interface PartyEventDispatcherOptions {
+  transport: EventTransport;
+  outbox?: OutboxStore | undefined;
+  logger?: PartyLogger | undefined;
+}
+declare class PartyEventDispatcher {
+  readonly name: string;
+  private readonly transport;
+  private readonly outbox;
+  private readonly logger;
+  constructor(opts: PartyEventDispatcherOptions);
+  /** Raw publish — hosts and the unit-of-work flush use this. */
+  publish(event: DomainEvent): Promise<void>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  /**
+   * Route a domain event with full §P8 discipline. Reads the pending queue and
+   * session off `ctx`.
+   */
+  dispatch(event: DomainEvent, ctx: PartyContext): Promise<void>;
+  close(): Promise<void>;
+}
+/**
+ * Drain a pending-events queue to the transport AFTER the owning transaction
+ * commits. Per-event failures are swallowed — durable delivery is the outbox's
+ * job (PACKAGE_RULES §P8.1).
+ */
+declare function flushPending(dispatcher: PartyEventDispatcher, queue: DomainEvent[], logger?: PartyLogger): Promise<void>;
+//#endregion
+//#region src/repositories/party.repository.d.ts
+interface PartyRepositoryDeps {
+  events: PartyEventDispatcher;
+  logger?: PartyLogger | undefined;
+}
+declare class PartyRepository extends Repository<IPartyDocument> implements PartyPort<IPartyDocument> {
+  private readonly events;
+  constructor(model: Model<IPartyDocument>, deps: PartyRepositoryDeps, plugins?: PluginType[]);
+  /** `update` that never returns null — the party was loaded first; a null means a concurrent delete. */
+  private mustUpdate;
+  resolveOrCreate(input: ResolvePartyInput, ctx: PartyContext): Promise<ResolveResult<IPartyDocument>>;
+  resolveMany(inputs: ResolvePartyInput[], ctx: PartyContext): Promise<Array<ResolveResult<IPartyDocument>>>;
+  snapshot(partyId: string, ctx: PartyContext): Promise<PartySnapshot>;
+  /**
+   * Sync identity onto a party — the canonical "identity changed" verb. The
+   * party OWNS identity mutation (name, contact points, addresses, tax), so
+   * hosts push a facet's current identity here instead of editing it locally.
+   * NEW contact points fold in (deduped, deriving their keys + extending
+   * `identityKeys`); existing primaries are preserved. Idempotent — syncing the
+   * same identity is a no-op. Emits `party:party.updated`.
+   */
+  syncIdentity(id: string, input: ResolvePartyInput, ctx: PartyContext): Promise<IPartyDocument>;
+  addRole(id: string, role: PartyRole, ctx: PartyContext): Promise<IPartyDocument>;
+  removeRole(id: string, role: PartyRole, ctx: PartyContext): Promise<IPartyDocument>;
+  linkUser(id: string, userId: string, ctx: PartyContext): Promise<IPartyDocument>;
+  attachExternalRef(id: string, ref: ExternalRef, ctx: PartyContext): Promise<IPartyDocument>;
+  archive(id: string, ctx: PartyContext): Promise<IPartyDocument>;
+  restore(id: string, ctx: PartyContext): Promise<IPartyDocument>;
+  /**
+   * Merge `sourceId` into `targetId`: the survivor absorbs the loser's identity
+   * keys, contact points, addresses, roles, external refs, and user links; the
+   * loser becomes a terminal `merged` redirect (`mergedInto`). Two-document
+   * write → runs in a transaction (falls back to sequential on standalone Mongo).
+   */
+  merge(sourceId: string, targetId: string, ctx: PartyContext): Promise<IPartyDocument>;
+  /** Load a party by ObjectId hex, or throw the typed not-found (§P9-style). */
+  loadParty(id: string, ctx: PartyContext): Promise<IPartyDocument>;
+  /** Add any new roles/refs/user/keys from `input` onto an already-resolved party. */
+  private enrich;
+  /** Route a domain event with meta stamped from ctx + the party's org. */
+  private dispatch;
+}
+//#endregion
+//#region src/engine/engine-types.d.ts
+interface PartyConfig {
+  /** Mongoose connection — the package creates its model on this connection. */
+  connection: Connection;
+  /**
+   * Multi-tenant scoping. Identity is FREQUENTLY company-wide (one customer is
+   * the same person in every branch) — such hosts pass `false` and the model
+   * carries no tenant column. SaaS / true-isolation hosts pass `true` (default).
+   */
+  multiTenant?: boolean;
+  /**
+   * Tenant column shape when `multiTenant` is on. `'objectId'` (default)
+   * matches Better Auth orgs (unlocks `$lookup`/`.populate()`); `'string'`
+   * matches UUID/slug hosts. Threaded into schema + plugin (§9.2).
+   */
+  tenantFieldType?: TenantFieldType;
+  /** Arc-compatible event transport. Default: in-process bus. */
+  eventTransport?: EventTransport;
+  /** Transactional outbox (§P8). When wired, events persist in the write's session. */
+  outbox?: OutboxStore;
+  /** Logger surface for the in-process bus + repository. */
+  logger?: PartyLogger;
+  /** Pagination defaults for the repository (mongokit). */
+  pagination?: PaginationConfig;
+  /** Extra mongokit plugins applied after the defaults. */
+  plugins?: PluginType[];
+  /** On a model-name collision: `false` (default) throws; `true` re-registers (tests, §21). */
+  forceRecreate?: boolean;
+  /** Mongoose auto-index builds. Default `true` (dev); `false` in prod (§35). */
+  autoIndex?: boolean;
+  /** Downgrade the boot `transactions` capability requirement to a warning (standalone Mongo). */
+  allowNonTransactional?: boolean;
+}
+interface ResolvedPartyConfig {
+  connection: Connection;
+  multiTenant: boolean;
+  tenantFieldType: TenantFieldType;
+  forceRecreate: boolean;
+  autoIndex: boolean;
+  allowNonTransactional: boolean;
+  logger?: PartyLogger;
+  pagination?: PaginationConfig;
+  plugins: PluginType[];
+}
+interface PartyRepositories {
+  party: PartyRepository;
+}
+interface PartyEngine {
+  /** Repositories ARE the API surface (§1). */
+  readonly repositories: Readonly<PartyRepositories>;
+  /**
+   * The reusable identity contract other domains depend on (order / crm /
+   * ledger / commerce resolve identity through THIS, not the models). It IS the
+   * party repository, narrowed to the port — swap the storage without touching
+   * a single consumer.
+   */
+  readonly port: PartyPort<IPartyDocument>;
+  /** Arc-compatible event transport (a dispatcher wrapping the configured one). */
+  readonly events: PartyEventDispatcher;
+  /** Mongoose models — for arc adapter wiring. */
+  readonly models: Readonly<PartyModels>;
+  /** Resolved configuration (frozen). */
+  readonly config: Readonly<ResolvedPartyConfig>;
+  /**
+   * Run `body` inside a transaction with post-commit event discipline (§P8.1):
+   * events dispatched through `txCtx` flush to the transport only after commit.
+   */
+  withTransaction<T>(ctx: PartyContext, body: (txCtx: PartyContext) => Promise<T>): Promise<T>;
+  /** Build/align indexes. Call once per deploy when booted `autoIndex: false` (§35). */
+  syncIndexes(): Promise<void>;
+  /** Release resources. Idempotent. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/engine/create-party.d.ts
+declare function createParty(config: PartyConfig): Promise<PartyEngine>;
+//#endregion
+//#region src/repositories/repo-options.d.ts
+declare function repoOptionsFromCtx(ctx: PartyContext): OperationOptions;
+//#endregion
+//#region src/domain/state-machine.d.ts
+/**
+ * Party identity lifecycle FSM — the compile-time twin of the `repo.claim()`
+ * CAS the repository uses for status transitions (PACKAGE_RULES §Concurrency).
+ *
+ *   active  ──archive──▶ archived ──restore──▶ active
+ *   active  ──merge────▶ merged (terminal; row survives as a `mergedInto` redirect)
+ *
+ * `merged` is terminal: a merged party is never resurrected — historical
+ * references resolve THROUGH it to the survivor, so the identity graph stays
+ * append-only and auditable.
+ */
+declare const PARTY_STATE_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"active" | "archived" | "merged">;
+//#endregion
+//#region src/domain/identity.d.ts
+/** De-duplicate an array preserving first-seen order. */
+declare function dedupe<T>(arr: readonly T[]): T[];
+/**
+ * Turn the input's `emails[]` / `phones[]` into normalized `ContactPoint`s. The
+ * first email and first phone are marked primary; blanks are skipped.
+ */
+declare function buildContactPoints(input: ResolvePartyInput): ContactPoint[];
+/**
+ * The de-dup keys a party is resolved on: normalized emails/phones, VAT/BIN
+ * statutory ids, and external-store refs. Blank/degenerate keys are dropped so
+ * they never poison the unique index.
+ */
+declare function deriveIdentityKeys(contactPoints: readonly ContactPoint[], input: ResolvePartyInput): string[];
+/** Best display name from the available signals — never empty. */
+declare function resolveDisplayName(input: ResolvePartyInput, contactPoints: readonly ContactPoint[]): string;
+/** The primary (or first) contact-point value of a channel type. */
+declare function pickPrimary(contactPoints: readonly ContactPoint[], type: 'email' | 'phone'): string | undefined;
+//#endregion
+//#region src/domain/merge.d.ts
+/** Union two string arrays, first-seen order, no duplicates. */
+declare function unionStrings(a: readonly string[], b: readonly string[]): string[];
+/** Union external refs by `(sourceModel, sourceId)` identity. */
+declare function unionRefs(a: readonly ExternalRef[], b: readonly ExternalRef[]): ExternalRef[];
+/**
+ * Union contact points by their normalized `key`. The survivor keeps its own
+ * primaries; absorbed points come in as non-primary (a merge must never create
+ * two primaries of the same channel).
+ */
+declare function unionContacts(a: readonly ContactPoint[], b: readonly ContactPoint[]): ContactPoint[];
+//#endregion
+//#region src/domain/normalize.d.ts
+/** Lowercase + trim an email. Conservative — never strips dots/plus tags. */
+declare function normalizeEmail(raw: string): string;
+/**
+ * Canonical phone form for dedup. Uses primitives' `parsePhone`: a valid E.164
+ * input collapses to its canonical `+<cc><national>`; anything the strict parser
+ * rejects (local formats without a country code) falls back to a digit-only
+ * key so at least same-format duplicates still collapse. Hosts wanting global
+ * dedup pass already-E.164 numbers.
+ */
+declare function normalizePhone(raw: string): string;
+/** The stable dedup key for a contact point (`email:ada@x.com`, `phone:+8801...`). */
+declare function contactPointKey(type: ContactPointType, value: string): string;
+/** A tax-identity dedup key (`vat:...` / `bin:...`) — cross-scope-stable statutory id. */
+declare function taxIdentityKey(kind: 'vat' | 'bin', value: string): string;
+//#endregion
+//#region src/domain/errors.d.ts
+/** Base class so hosts can `instanceof PartyError` across every party throwable. */
+declare class PartyError extends Error implements HttpError {
+  readonly status: number;
+  readonly code: string;
+  readonly meta?: Record<string, unknown>;
+  constructor(status: number, code: string, message: string, meta?: Record<string, unknown>);
+}
+/** A referenced party id does not exist (or is out of the caller's scope). */
+declare class PartyNotFoundError extends PartyError {
+  constructor(id: string);
+}
+/**
+ * A merge was attempted against an illegal target — self-merge, merging into an
+ * already-merged (redirected) party, or a cross-scope pair. Carries both ids.
+ */
+declare class PartyMergeError extends PartyError {
+  constructor(message: string, sourceId: string, targetId: string);
+}
+/**
+ * `resolveOrCreate` lost the create race and the winning row could not be
+ * re-read (should be transient — surfaced rather than swallowed).
+ */
+declare class PartyResolveConflictError extends PartyError {
+  constructor(identityKey: string);
+}
+/**
+ * Optimistic-concurrency guard failed — the party was modified by another
+ * writer between read and write. Callers re-fetch and retry.
+ */
+declare class PartyVersionConflictError extends PartyError {
+  constructor(id: string, expected: number);
+}
+/**
+ * A Mongoose model name this package registers is already on the connection.
+ * Default init throws this; `forceRecreate: true` opts into delete+re-register
+ * (test fixtures / hot reload only). PACKAGE_RULES §21.
+ */
+declare class PartyModelCollisionError extends PartyError {
+  constructor(modelName: string);
+}
+/** Input failed a domain-verb precondition (before any DB write). */
+declare class PartyValidationError extends PartyError {
+  constructor(message: string, meta?: Record<string, unknown>);
+}
+//#endregion
+//#region src/events/event-constants.d.ts
+/** PACKAGE_RULES §12: `package:resource.verb`. Emit ONLY these catalog names. */
+declare const PARTY_EVENTS: {
+  readonly CREATED: 'party:party.created';
+  readonly UPDATED: 'party:party.updated';
+  readonly ROLE_ADDED: 'party:party.role_added';
+  readonly ROLE_REMOVED: 'party:party.role_removed';
+  readonly USER_LINKED: 'party:party.user_linked';
+  readonly EXTERNAL_REF_ATTACHED: 'party:party.external_ref_attached';
+  readonly ARCHIVED: 'party:party.archived';
+  readonly RESTORED: 'party:party.restored';
+  readonly MERGED: 'party:party.merged';
+};
+type PartyEventName = (typeof PARTY_EVENTS)[keyof typeof PARTY_EVENTS];
+//#endregion
+//#region src/events/event-payloads.d.ts
+interface PartyCreatedPayload {
+  partyId: string;
+  kind: PartyKind;
+  displayName: string;
+  roles: PartyRole[];
+  organizationId?: string;
+}
+interface PartyUpdatedPayload {
+  partyId: string;
+  /** Top-level fields that changed on this write. */
+  changed: string[];
+}
+interface PartyRoleChangedPayload {
+  partyId: string;
+  role: PartyRole;
+}
+interface PartyUserLinkedPayload {
+  partyId: string;
+  userId: string;
+}
+interface PartyExternalRefAttachedPayload {
+  partyId: string;
+  sourceModel: string;
+  sourceId: string;
+}
+interface PartyLifecyclePayload {
+  partyId: string;
+}
+interface PartyMergedPayload {
+  /** The party that was merged away (now a redirect). */
+  sourceId: string;
+  /** The surviving party. */
+  targetId: string;
+  /** How many identity keys the survivor absorbed. */
+  absorbedKeys: number;
+}
+/** Name → payload map — subscribers get exact typing from the event name. */
+interface PartyEventPayloads {
+  [PARTY_EVENTS.CREATED]: PartyCreatedPayload;
+  [PARTY_EVENTS.UPDATED]: PartyUpdatedPayload;
+  [PARTY_EVENTS.ROLE_ADDED]: PartyRoleChangedPayload;
+  [PARTY_EVENTS.ROLE_REMOVED]: PartyRoleChangedPayload;
+  [PARTY_EVENTS.USER_LINKED]: PartyUserLinkedPayload;
+  [PARTY_EVENTS.EXTERNAL_REF_ATTACHED]: PartyExternalRefAttachedPayload;
+  [PARTY_EVENTS.ARCHIVED]: PartyLifecyclePayload;
+  [PARTY_EVENTS.RESTORED]: PartyLifecyclePayload;
+  [PARTY_EVENTS.MERGED]: PartyMergedPayload;
+}
+//#endregion
+//#region src/events/event-catalog.d.ts
+interface PartyEventDefinition<TSchema extends z.ZodType = z.ZodType> {
+  name: string;
+  version: number;
+  description: string;
+  zodSchema: TSchema;
+  schema: Record<string, unknown>;
+  create(payload: z.infer<TSchema>, meta?: Partial<EventMeta>): DomainEvent<z.infer<TSchema>>;
+}
+declare const partyEventDefinitions: ReadonlyArray<PartyEventDefinition>;
+//#endregion
+//#region src/events/helpers.d.ts
+declare function createEvent<T>(type: string, payload: T, ctx?: PartyContext, meta?: Partial<EventMeta>): DomainEvent<T>;
+//#endregion
+//#region src/events/in-process-bus.d.ts
+declare class InProcessPartyBus implements EventTransport {
+  readonly name = "in-process-party";
+  private subs;
+  private readonly logger;
+  constructor(options?: {
+    logger?: PartyLogger | undefined;
+  });
+  publish(event: DomainEvent): Promise<void>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  close(): Promise<void>;
+}
+//#endregion
+export { ADDRESS_TYPES, type AddressType, CONTACT_POINT_TYPES, type ContactPoint, type ContactPointType, type ExternalRef, type IPartyDocument, InProcessPartyBus, PARTY_EVENTS, PARTY_KINDS, PARTY_MODEL_NAMES, PARTY_ROLES, PARTY_STATE_MACHINE, PARTY_STATUSES, PENDING_EVENTS, type PartyAddress, type PartyConfig, type PartyContext, type PartyEngine, PartyError, PartyEventDispatcher, type PartyEventName, type PartyEventPayloads, type PartyKind, type PartyLogger, PartyMergeError, PartyModelCollisionError, type PartyModels, PartyNotFoundError, type PartyPort, type PartyRepositories, PartyRepository, type PartyRepositoryDeps, PartyResolveConflictError, type PartyRole, type PartySnapshot, type PartyStatus, PartyValidationError, PartyVersionConflictError, type PersonName, type ResolvePartyInput, type ResolveResult, type ResolvedPartyConfig, type SchemaBuildConfig, type TaxIdentity, type TenantFieldType, buildContactPoints, buildPartySchema, contactPointKey, createEvent, createParty, createParty as default, createPartyModels, dedupe, deriveIdentityKeys, flushPending, normalizeEmail, normalizePhone, partyEventDefinitions, pickPrimary, repoOptionsFromCtx, resolveDisplayName, taxIdentityKey, tenantFieldDef, unionContacts, unionRefs, unionStrings };