@classytic/party 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to `@classytic/party` are documented here. Adheres to
 [Keep a Changelog](https://keepachangelog.com/) and [SemVer](https://semver.org/).
 
+## [0.3.0] — 2026-10-11
+
+### Added — marketing consent, per contact channel
+
+- `ContactPoint.consent` (`{ status: 'granted' | 'withdrawn', at, source?, ip? }`) records permission to MARKET to one channel. Absent means "never asked", which a sender must treat as a refusal; `withdrawn` is deliberately not "absent", because only an opt-out has to survive a merge, a re-import or the person booking again.
+- `recordConsent(id, input, ctx)` stores a decision against a channel, matching the channel by its NORMALIZED value (`07700 900000` and `+447700900000` reach the same contact point). A channel the party does not hold is a typed error, not a silent no-op. Emits `party:party.consent_recorded`.
+- Merging two parties **reconciles consent** (`reconcileConsent`, exported): a withdrawal always beats a grant, whichever record is newer, because duplicate rows' clocks record when a row was touched, not when the person spoke. Between two records of the same status the later one wins. A channel one side verified stays verified. Before this, the loser's contact row was dropped wholesale and could discard an opt-out the duplicate alone carried.
+- Contact points are copied field by field on merge: Mongoose subdocuments keep their values behind prototype getters, so spreading one yielded internals and dropped data.
+- `CONSENT_STATUSES` / `ConsentStatus` and the `ChannelConsent` type.
+
+### Added — dated related-party relationships
+
+- `relationships[]` on a party: `shareholder`, `director`, `key_management`, `partner_in_firm`, `member`, `employee`, `lessor`, `associate` (`RELATIONSHIP_KINDS`), each with `from` and an exclusive `to`, an optional `relatedTo` (absent means the reporting company), and `shareClass` / `sharePercent` for shareholders. One party can hold several at once.
+- `addRelationship`, `endRelationship` and `relationshipsOn(id, date, ctx)` (the relationships holding on a date). A bad date range, an overlap or an unknown row throws `PartyRelationshipError` (`party.relationship_invalid`, 422). Emits `party:party.relationship_changed`.
+- A party model index for "every shareholder" / "every lessor" queries.
+
+### Added — `legalForm`
+
+`legalForm` on a party (`@classytic/primitives/legal-form`): what the law treats the party as — a sole trader is an `individual`. Absent means not stated.
+
+### Changed — peer floors raised to current
+
+`@classytic/mongokit` `>=3.33.0` → **`>=3.41.0`**, `@classytic/primitives` `>=0.29.0` → **`>=0.31.1`**, `@classytic/repo-core` `>=0.24.0` → **`>=0.31.0`**, `@classytic/contact` `>=0.1.0` → **`>=0.2.0`**, `mongoose` `>=9.4.1` → **`>=9.11.0`** (mongokit 3.41 requires it). Verified on a fresh install. New parties and merges write the new fields; existing documents read unchanged (`consent` stays absent, `relationships` defaults to `[]`).
+
 ## [0.2.0] — 2026-08-17
 
 ### Added

package/dist/events.d.ts

@@ -15,10 +15,12 @@ declare const PARTY_EVENTS: {
   readonly ROLE_ADDED: 'party:party.role_added';
   readonly ROLE_REMOVED: 'party:party.role_removed';
   readonly USER_LINKED: 'party:party.user_linked';
+  readonly CONSENT_RECORDED: 'party:party.consent_recorded';
   readonly EXTERNAL_REF_ATTACHED: 'party:party.external_ref_attached';
   readonly ARCHIVED: 'party:party.archived';
   readonly RESTORED: 'party:party.restored';
   readonly MERGED: 'party:party.merged';
+  readonly RELATIONSHIP_CHANGED: 'party:party.relationship_changed';
 };
 type PartyEventName = (typeof PARTY_EVENTS)[keyof typeof PARTY_EVENTS];
 //#endregion
@@ -65,6 +67,14 @@ interface PartyUserLinkedPayload {
   partyId: string;
   userId: string;
 }
+interface PartyConsentRecordedPayload {
+  partyId: string;
+  channel: 'email' | 'phone';
+  /** The NORMALIZED channel — what a sender would actually dial or mail. */
+  value: string;
+  status: 'granted' | 'withdrawn';
+  source?: string;
+}
 interface PartyExternalRefAttachedPayload {
   partyId: string;
   sourceModel: string;
@@ -88,6 +98,7 @@ interface PartyEventPayloads {
   [PARTY_EVENTS.ROLE_ADDED]: PartyRoleChangedPayload;
   [PARTY_EVENTS.ROLE_REMOVED]: PartyRoleChangedPayload;
   [PARTY_EVENTS.USER_LINKED]: PartyUserLinkedPayload;
+  [PARTY_EVENTS.CONSENT_RECORDED]: PartyConsentRecordedPayload;
   [PARTY_EVENTS.EXTERNAL_REF_ATTACHED]: PartyExternalRefAttachedPayload;
   [PARTY_EVENTS.ARCHIVED]: PartyLifecyclePayload;
   [PARTY_EVENTS.RESTORED]: PartyLifecyclePayload;
@@ -148,6 +159,19 @@ declare const PartyUserLinked: PartyEventDefinition<z.ZodObject<{
   partyId: z.ZodString;
   userId: z.ZodString;
 }, z.core.$strip>>;
+declare const PartyConsentRecorded: PartyEventDefinition<z.ZodObject<{
+  partyId: z.ZodString;
+  channel: z.ZodEnum<{
+    email: "email";
+    phone: "phone";
+  }>;
+  value: z.ZodString;
+  status: z.ZodEnum<{
+    granted: "granted";
+    withdrawn: "withdrawn";
+  }>;
+  source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
 declare const PartyExternalRefAttached: PartyEventDefinition<z.ZodObject<{
   partyId: z.ZodString;
   sourceModel: z.ZodString;
@@ -164,6 +188,24 @@ declare const PartyMerged: PartyEventDefinition<z.ZodObject<{
   targetId: z.ZodString;
   absorbedKeys: z.ZodNumber;
 }, z.core.$strip>>;
+declare const PartyRelationshipChanged: PartyEventDefinition<z.ZodObject<{
+  partyId: z.ZodString;
+  relationshipId: z.ZodString;
+  kind: z.ZodEnum<{
+    associate: "associate";
+    director: "director";
+    employee: "employee";
+    key_management: "key_management";
+    lessor: "lessor";
+    member: "member";
+    partner_in_firm: "partner_in_firm";
+    shareholder: "shareholder";
+  }>;
+  change: z.ZodEnum<{
+    added: "added";
+    ended: "ended";
+  }>;
+}, z.core.$strip>>;
 declare const partyEventDefinitions: ReadonlyArray<PartyEventDefinition>;
 //#endregion
 //#region src/domain/ports.d.ts
@@ -230,4 +272,4 @@ declare class PartyEventDispatcher {
  */
 declare function flushPending(dispatcher: PartyEventDispatcher, queue: DomainEvent[], logger?: PartyLogger): Promise<void>;
 //#endregion
-export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyCreated, PartyCreatedPayload, PartyEventDefinition, PartyEventDispatcher, PartyEventDispatcherOptions, PartyEventName, PartyEventPayloads, PartyExternalRefAttached, PartyExternalRefAttachedPayload, PartyLifecyclePayload, PartyMerged, PartyMergedPayload, PartyRestored, PartyRoleAdded, PartyRoleChangedPayload, PartyRoleRemoved, PartyUpdated, PartyUpdatedPayload, PartyUserLinked, PartyUserLinkedPayload, createEvent, flushPending, partyEventDefinitions };
+export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyConsentRecorded, PartyConsentRecordedPayload, PartyCreated, PartyCreatedPayload, PartyEventDefinition, PartyEventDispatcher, PartyEventDispatcherOptions, PartyEventName, PartyEventPayloads, PartyExternalRefAttached, PartyExternalRefAttachedPayload, PartyLifecyclePayload, PartyMerged, PartyMergedPayload, PartyRelationshipChanged, PartyRestored, PartyRoleAdded, PartyRoleChangedPayload, PartyRoleRemoved, PartyUpdated, PartyUpdatedPayload, PartyUserLinked, PartyUserLinkedPayload, createEvent, flushPending, partyEventDefinitions };

package/dist/events.js

@@ -9,10 +9,12 @@ const PARTY_EVENTS = {
 	ROLE_ADDED: "party:party.role_added",
 	ROLE_REMOVED: "party:party.role_removed",
 	USER_LINKED: "party:party.user_linked",
+	CONSENT_RECORDED: "party:party.consent_recorded",
 	EXTERNAL_REF_ATTACHED: "party:party.external_ref_attached",
 	ARCHIVED: "party:party.archived",
 	RESTORED: "party:party.restored",
-	MERGED: "party:party.merged"
+	MERGED: "party:party.merged",
+	RELATIONSHIP_CHANGED: "party:party.relationship_changed"
 };
 //#endregion
 //#region src/events/event-catalog.ts
@@ -71,6 +73,13 @@ const userLinkedSchema = z.object({
 	partyId: z.string(),
 	userId: z.string()
 });
+const consentRecordedSchema = z.object({
+	partyId: z.string(),
+	channel: z.enum(["email", "phone"]),
+	value: z.string(),
+	status: z.enum(["granted", "withdrawn"]),
+	source: z.string().optional()
+});
 const externalRefSchema = z.object({
 	partyId: z.string(),
 	sourceModel: z.string(),
@@ -107,6 +116,11 @@ const PartyUserLinked = definePartyEvent({
 	description: "An auth user was linked to a party (1:many).",
 	zodSchema: userLinkedSchema
 });
+const PartyConsentRecorded = definePartyEvent({
+	name: PARTY_EVENTS.CONSENT_RECORDED,
+	description: "A marketing-consent decision was recorded against one contact channel.",
+	zodSchema: consentRecordedSchema
+});
 const PartyExternalRefAttached = definePartyEvent({
 	name: PARTY_EVENTS.EXTERNAL_REF_ATTACHED,
 	description: "An external-store reference was attached to a party (facet link).",
@@ -127,16 +141,38 @@ const PartyMerged = definePartyEvent({
 	description: "A duplicate party was merged into a survivor; the source becomes a redirect.",
 	zodSchema: mergedSchema
 });
+const relationshipChangedSchema = z.object({
+	partyId: z.string(),
+	relationshipId: z.string(),
+	kind: z.enum([
+		"shareholder",
+		"director",
+		"key_management",
+		"partner_in_firm",
+		"member",
+		"employee",
+		"lessor",
+		"associate"
+	]),
+	change: z.enum(["added", "ended"])
+});
+const PartyRelationshipChanged = definePartyEvent({
+	name: PARTY_EVENTS.RELATIONSHIP_CHANGED,
+	description: "A dated relationship of the party (shareholder, director, lessor, …) was added or ended.",
+	zodSchema: relationshipChangedSchema
+});
 const partyEventDefinitions = [
 	PartyCreated,
 	PartyUpdated,
 	PartyRoleAdded,
 	PartyRoleRemoved,
 	PartyUserLinked,
+	PartyConsentRecorded,
 	PartyExternalRefAttached,
 	PartyArchived,
 	PartyRestored,
-	PartyMerged
+	PartyMerged,
+	PartyRelationshipChanged
 ];
 //#endregion
 //#region src/events/helpers.ts
@@ -242,4 +278,4 @@ async function flushPending(dispatcher, queue, logger) {
 	}
 }
 //#endregion
-export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyCreated, PartyEventDispatcher, PartyExternalRefAttached, PartyMerged, PartyRestored, PartyRoleAdded, PartyRoleRemoved, PartyUpdated, PartyUserLinked, createEvent, flushPending, partyEventDefinitions };
+export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyConsentRecorded, PartyCreated, PartyEventDispatcher, PartyExternalRefAttached, PartyMerged, PartyRelationshipChanged, PartyRestored, PartyRoleAdded, PartyRoleRemoved, PartyUpdated, PartyUserLinked, createEvent, flushPending, partyEventDefinitions };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ModelBlueprint, OperationOptions, PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 import { ResolvedTenantConfig, TenantConfig } from "@classytic/repo-core/tenant";
 import { InProcessEventBus } from "@classytic/primitives/event-infra";
+import { LegalForm } from "@classytic/primitives/legal-form";
 import { Connection, Model, Schema, SchemaDefinitionProperty, Types } from "mongoose";
 import { DomainEvent, EventHandler, EventMeta, EventTransport } from "@classytic/primitives/events";
 import { ExternalRef, ExternalRef as ExternalRef$1, IdLike } from "@classytic/primitives/reference";
@@ -41,12 +42,31 @@ 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];
+/**
+ * Whether this channel may be used for MARKETING. Transactional messages (your
+ * booking is confirmed, your invoice is due) need no consent and are not what
+ * this records.
+ *
+ * Two states only, and `withdrawn` is deliberately not "absent": a channel that
+ * was never asked and a channel someone opted OUT of are the same silence to a
+ * sender but not to a regulator, and only the second one must survive a merge,
+ * a re-import, or the person booking again.
+ */
+declare const CONSENT_STATUSES: readonly ['granted', 'withdrawn'];
+type ConsentStatus = (typeof CONSENT_STATUSES)[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];
+/**
+ * How a party is related to the reporting company (or to another party) — the related-party facts tax and
+ * disclosure rules read (IAS 24 in spirit). One party can hold several at once (a director who is also a
+ * shareholder); each is dated. A pack derives its own terms from these (a "sponsor shareholder").
+ */
+declare const RELATIONSHIP_KINDS: readonly ['shareholder', 'director', 'key_management', 'partner_in_firm', 'member', 'employee', 'lessor', 'associate'];
+type RelationshipKind = (typeof RELATIONSHIP_KINDS)[number];
 //#endregion
 //#region src/domain/value-objects.d.ts
 /**
@@ -86,6 +106,45 @@ interface ContactPoint {
   input?: string;
   isPrimary: boolean;
   verified: boolean;
+  /**
+   * Permission to MARKET to this channel, and the proof of it. Absent means
+   * never asked — which is a refusal to a sender, so treat it as one.
+   *
+   * Here rather than in a CRM package because consent is a property of the
+   * CHANNEL, exactly like `verified`: it is the answer to "may I mail this
+   * address", not a domain opinion about the person. Campaign subscriptions,
+   * sequences, suppression lists and unsubscribe tokens stay in CRM keyed by
+   * `partyId` — this is the one fact they all have to agree with, and a sender
+   * that disagrees with it is the bug this field exists to make visible.
+   *
+   * In a multi-tenant deployment a party row is already per-organization, so
+   * this is one business's permission and never a platform-wide one — which is
+   * what "specific and informed" requires.
+   */
+  consent?: ChannelConsent;
+}
+/**
+ * A consent decision, with what a regulator asks for when they ask you to
+ * prove it: what was decided, WHEN, and where the person was standing.
+ *
+ * Immutable by convention — a change of mind is a new record replacing this
+ * one, never an edit, so `at` always dates the CURRENT status.
+ */
+interface ChannelConsent {
+  status: ConsentStatus;
+  /** The moment the person decided. */
+  at: Date;
+  /**
+   * The surface that asked — `'booking-form'`, `'dashboard'`, `'import:2019-mailchimp'`.
+   * Free text on purpose: the kernel cannot enumerate a host's screens, and an
+   * imported consent whose origin is unrecorded is one you cannot defend.
+   */
+  source?: string;
+  /**
+   * Caller IP at the moment of GRANT, when the host has one. Never backfilled:
+   * an IP attached later proves nothing and is then just retained PII.
+   */
+  ip?: string;
 }
 /**
  * Statutory tax identity. Country-agnostic slots — a BD deployment fills
@@ -202,6 +261,19 @@ interface SchemaBuildConfig {
 declare function tenantFieldDef(config: SchemaBuildConfig): SchemaDefinitionProperty | undefined;
 //#endregion
 //#region src/models/party.model.d.ts
+interface PartyRelationship {
+  _id: Types.ObjectId;
+  kind: RelationshipKind;
+  /** The other party; absent means the reporting company itself. */
+  relatedTo?: Types.ObjectId | string | null;
+  /** Shareholding detail when `kind: 'shareholder'`. */
+  shareClass?: string | null;
+  sharePercent?: number | null;
+  from: Date;
+  /** Exclusive end; absent while it holds. */
+  to?: Date | null;
+  note?: string | null;
+}
 interface IPartyDocument {
   _id: Types.ObjectId;
   /** Present only when the engine runs multi-tenant; absent for company-wide identity. */
@@ -224,6 +296,10 @@ interface IPartyDocument {
   /** Set when `status: 'merged'` — the survivor this party redirects to. */
   mergedInto?: Types.ObjectId | string;
   tags: string[];
+  /** What the law treats the party as (a sole trader is an `individual`). Absent: not stated. */
+  legalForm?: LegalForm;
+  /** Dated relationships to the reporting company or another party. */
+  relationships: PartyRelationship[];
   metadata?: Record<string, unknown>;
   /** Optimistic-concurrency counter (drives `claimVersion`). */
   version: number;
@@ -280,6 +356,22 @@ declare class PartyEventDispatcher {
 declare function flushPending(dispatcher: PartyEventDispatcher, queue: DomainEvent[], logger?: PartyLogger): Promise<void>;
 //#endregion
 //#region src/repositories/party.repository.d.ts
+/** What a host asks `recordConsent` to write. */
+interface RecordConsentInput {
+  channel: ContactPointType;
+  /** The channel as the person gave it; normalized here before it is matched. */
+  value: string;
+  status: ConsentStatus;
+  /** The surface that asked — see `ChannelConsent.source`. */
+  source?: string;
+  /** Caller IP. Kept only on a grant. */
+  ip?: string;
+  /**
+   * When they said it. Defaults to now; supply it only when replaying a real
+   * historical decision (a migration), never to backdate a fresh one.
+   */
+  at?: Date;
+}
 interface PartyRepositoryDeps {
   events: PartyEventDispatcher;
   logger?: PartyLogger | undefined;
@@ -320,7 +412,30 @@ declare class PartyRepository extends Repository<IPartyDocument> implements Part
   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>;
+  /**
+   * Record a dated relationship (shareholder, director, lessor, …) to the reporting company or another
+   * party. Refused when one of the same kind with the same counterpart is already in force over the dates:
+   * two overlapping rows would double a shareholding, and only one of them could be ended.
+   */
+  addRelationship(id: string, input: AddRelationshipInput, ctx: PartyContext): Promise<IPartyDocument>;
+  /** End a relationship on a date (exclusive). Ending one already ended earlier is refused, never moved. */
+  endRelationship(id: string, relationshipId: string, to: Date, ctx: PartyContext): Promise<IPartyDocument>;
+  /** The relationships in force on a date — following a merged party to its survivor. */
+  relationshipsOn(id: string, on: Date, ctx: PartyContext): Promise<PartyRelationship[]>;
   linkUser(id: string, userId: string, ctx: PartyContext): Promise<IPartyDocument>;
+  /**
+   * Record what this person said about being MARKETED to on one channel.
+   *
+   * Addressed by the channel's raw value (what they typed) and normalized here,
+   * so a host passing `07700 900000` and a host passing `+447700900000` reach
+   * the same contact point — consent landing on a second, differently-spelled
+   * row is an opt-out that no sender would ever find.
+   *
+   * A channel the party does not hold is a typed error rather than a silent
+   * no-op: a grant that went nowhere looks identical to one that was stored,
+   * and the caller is usually a booking form that will never check again.
+   */
+  recordConsent(id: string, input: RecordConsentInput, 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>;
@@ -346,6 +461,16 @@ declare class PartyRepository extends Repository<IPartyDocument> implements Part
   /** Route a domain event with meta stamped from ctx + the party's org. */
   private dispatch;
 }
+interface AddRelationshipInput {
+  kind: RelationshipKind;
+  /** The other party; omit for the reporting company. */
+  relatedTo?: string | null;
+  from: Date;
+  to?: Date | null;
+  shareClass?: string;
+  sharePercent?: number;
+  note?: string;
+}
 //#endregion
 //#region src/engine/engine-types.d.ts
 interface ResolvedPartyConfig {
@@ -603,10 +728,27 @@ declare function pickPrimary(contactPoints: readonly ContactPoint[], type: 'emai
 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[];
+/**
+ * Reconcile two consent records for the SAME channel.
+ *
+ * A withdrawal always beats a grant, regardless of which is newer. Recency is
+ * the intuitive rule and it is the wrong one here: the two records being
+ * reconciled came from duplicate rows whose clocks record when each row was
+ * TOUCHED, not the order the person actually spoke, so letting the later
+ * timestamp win means a merge can quietly re-subscribe someone who opted out.
+ * Being over-cautious costs a marketing email; being wrong costs a complaint
+ * you cannot defend. Between two records of the same status the later one wins,
+ * since only its timestamp is then load-bearing.
+ */
+declare function reconcileConsent(a: ChannelConsent | undefined, b: ChannelConsent | undefined): ChannelConsent | undefined;
 /**
  * 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).
+ *
+ * Where both sides hold the same channel the survivor's row is kept but its
+ * CONSENT is reconciled — dropping the loser's row wholesale would discard an
+ * opt-out that the duplicate was the only carrier of.
  */
 declare function unionContacts(a: readonly ContactPoint[], b: readonly ContactPoint[]): ContactPoint[];
 //#endregion
@@ -629,6 +771,10 @@ declare class PartyNotFoundError extends PartyError {
 declare class PartyMergeError extends PartyError {
   constructor(message: string, sourceId: string, targetId: string);
 }
+/** A relationship that cannot be recorded or ended as asked (overlap, bad dates, unknown row). */
+declare class PartyRelationshipError extends PartyError {
+  constructor(message: string, partyId: string);
+}
 /**
  * `resolveOrCreate` lost the create race and the winning row could not be
  * re-read (should be transient — surfaced rather than swallowed).
@@ -674,10 +820,12 @@ declare const PARTY_EVENTS: {
   readonly ROLE_ADDED: 'party:party.role_added';
   readonly ROLE_REMOVED: 'party:party.role_removed';
   readonly USER_LINKED: 'party:party.user_linked';
+  readonly CONSENT_RECORDED: 'party:party.consent_recorded';
   readonly EXTERNAL_REF_ATTACHED: 'party:party.external_ref_attached';
   readonly ARCHIVED: 'party:party.archived';
   readonly RESTORED: 'party:party.restored';
   readonly MERGED: 'party:party.merged';
+  readonly RELATIONSHIP_CHANGED: 'party:party.relationship_changed';
 };
 type PartyEventName = (typeof PARTY_EVENTS)[keyof typeof PARTY_EVENTS];
 //#endregion
@@ -702,6 +850,14 @@ interface PartyUserLinkedPayload {
   partyId: string;
   userId: string;
 }
+interface PartyConsentRecordedPayload {
+  partyId: string;
+  channel: 'email' | 'phone';
+  /** The NORMALIZED channel — what a sender would actually dial or mail. */
+  value: string;
+  status: 'granted' | 'withdrawn';
+  source?: string;
+}
 interface PartyExternalRefAttachedPayload {
   partyId: string;
   sourceModel: string;
@@ -725,6 +881,7 @@ interface PartyEventPayloads {
   [PARTY_EVENTS.ROLE_ADDED]: PartyRoleChangedPayload;
   [PARTY_EVENTS.ROLE_REMOVED]: PartyRoleChangedPayload;
   [PARTY_EVENTS.USER_LINKED]: PartyUserLinkedPayload;
+  [PARTY_EVENTS.CONSENT_RECORDED]: PartyConsentRecordedPayload;
   [PARTY_EVENTS.EXTERNAL_REF_ATTACHED]: PartyExternalRefAttachedPayload;
   [PARTY_EVENTS.ARCHIVED]: PartyLifecyclePayload;
   [PARTY_EVENTS.RESTORED]: PartyLifecyclePayload;
@@ -752,4 +909,4 @@ declare class InProcessPartyBus extends InProcessEventBus {
   });
 }
 //#endregion
-export { ADDRESS_TYPES, type AddressType, CONTACT_POINT_TYPES, type ContactPoint, type ContactPointType, type ExternalRef, type IPartyDocument, type IdentityKeyOptions, InProcessPartyBus, type NormalizeOptions, PARTY_EVENTS, PARTY_KINDS, PARTY_ROLES, PARTY_STATE_MACHINE, PARTY_STATUSES, PARTY_SUBJECT_MODEL, PENDING_EVENTS, type PartyAddress, type PartyBlueprint, type PartyContext, type PartyEngine, PartyError, PartyEventDispatcher, type PartyEventName, type PartyEventPayloads, type PartyKind, type PartyLogger, PartyMergeError, type PartyModels, PartyNotFoundError, PartyPhoneFormatError, type PartyPort, type PartyRepositories, PartyRepository, type PartyRepositoryDeps, PartyResolveConflictError, type PartyRole, type PartyRuntime, type PartyShape, type PartySnapshot, type PartyStatus, type PartySubject, PartyValidationError, PartyVersionConflictError, type PersonName, type ResolvePartyInput, type ResolveResult, type ResolvedPartyConfig, type SchemaBuildConfig, type TaxIdentity, type TenantFieldType, buildContactPoints, buildPartySchema, contactPointKey, createEvent, dedupe, defineParty, definePartyModels, deriveIdentityKeys, flushPending, isPartySubject, normalizeEmail, partyEventDefinitions, partySubject, pickPrimary, repoOptionsFromCtx, resolveDisplayName, taxIdentityKey, tenantFieldDef, unionContacts, unionRefs, unionStrings };
+export { ADDRESS_TYPES, type AddRelationshipInput, type AddressType, CONSENT_STATUSES, CONTACT_POINT_TYPES, type ChannelConsent, type ConsentStatus, type ContactPoint, type ContactPointType, type ExternalRef, type IPartyDocument, type IdentityKeyOptions, InProcessPartyBus, type NormalizeOptions, PARTY_EVENTS, PARTY_KINDS, PARTY_ROLES, PARTY_STATE_MACHINE, PARTY_STATUSES, PARTY_SUBJECT_MODEL, PENDING_EVENTS, type PartyAddress, type PartyBlueprint, type PartyContext, type PartyEngine, PartyError, PartyEventDispatcher, type PartyEventName, type PartyEventPayloads, type PartyKind, type PartyLogger, PartyMergeError, type PartyModels, PartyNotFoundError, PartyPhoneFormatError, type PartyPort, type PartyRelationship, PartyRelationshipError, type PartyRepositories, PartyRepository, type PartyRepositoryDeps, PartyResolveConflictError, type PartyRole, type PartyRuntime, type PartyShape, type PartySnapshot, type PartyStatus, type PartySubject, PartyValidationError, PartyVersionConflictError, type PersonName, RELATIONSHIP_KINDS, type RecordConsentInput, type RelationshipKind, type ResolvePartyInput, type ResolveResult, type ResolvedPartyConfig, type SchemaBuildConfig, type TaxIdentity, type TenantFieldType, buildContactPoints, buildPartySchema, contactPointKey, createEvent, dedupe, defineParty, definePartyModels, deriveIdentityKeys, flushPending, isPartySubject, normalizeEmail, partyEventDefinitions, partySubject, pickPrimary, reconcileConsent, repoOptionsFromCtx, resolveDisplayName, taxIdentityKey, tenantFieldDef, unionContacts, unionRefs, unionStrings };

package/dist/index.js

@@ -1,7 +1,8 @@
 import { Repository, defineModels, isDuplicateKeyError, multiTenantPlugin, transactionResolutionOf, withTransaction } from "@classytic/mongokit";
 import { assertNoLegacyTenantKeys, resolveTenantConfig } from "@classytic/repo-core/tenant";
 import { InProcessEventBus } from "@classytic/primitives/event-infra";
-import { Schema } from "mongoose";
+import { LEGAL_FORMS } from "@classytic/primitives/legal-form";
+import { Schema, Types } from "mongoose";
 import { defineStateMachine } from "@classytic/primitives/state-machine";
 import { normalizeEmail as normalizeEmail$1 } from "@classytic/contact/email";
 import { PhoneFormatError, normalizePhone } from "@classytic/contact/phone";
@@ -49,6 +50,17 @@ const PARTY_STATUSES = [
 /** Channel kind for a contact point. Drives normalization + dedup keys. */
 const CONTACT_POINT_TYPES = ["email", "phone"];
 /**
+* Whether this channel may be used for MARKETING. Transactional messages (your
+* booking is confirmed, your invoice is due) need no consent and are not what
+* this records.
+*
+* Two states only, and `withdrawn` is deliberately not "absent": a channel that
+* was never asked and a channel someone opted OUT of are the same silence to a
+* sender but not to a regulator, and only the second one must survive a merge,
+* a re-import, or the person booking again.
+*/
+const CONSENT_STATUSES = ["granted", "withdrawn"];
+/**
 * Address role. Mirrors Odoo's `type` (contact/invoice/delivery/other) but
 * as a first-class enum. A party carries many; `isDefault` picks the fallback.
 */
@@ -58,6 +70,21 @@ const ADDRESS_TYPES = [
 	"contact",
 	"other"
 ];
+/**
+* How a party is related to the reporting company (or to another party) — the related-party facts tax and
+* disclosure rules read (IAS 24 in spirit). One party can hold several at once (a director who is also a
+* shareholder); each is dated. A pack derives its own terms from these (a "sponsor shareholder").
+*/
+const RELATIONSHIP_KINDS = [
+	"shareholder",
+	"director",
+	"key_management",
+	"partner_in_firm",
+	"member",
+	"employee",
+	"lessor",
+	"associate"
+];
 //#endregion
 //#region src/events/dispatch.ts
 /** Context key carrying a post-commit publish queue (attached by `withTransaction`). */
@@ -221,6 +248,27 @@ const personNameSchema = new Schema({
 		maxlength: 120
 	}
 }, { _id: false });
+const channelConsentSchema = new Schema({
+	status: {
+		type: String,
+		enum: CONSENT_STATUSES,
+		required: true
+	},
+	at: {
+		type: Date,
+		required: true
+	},
+	source: {
+		type: String,
+		trim: true,
+		maxlength: 120
+	},
+	ip: {
+		type: String,
+		trim: true,
+		maxlength: 64
+	}
+}, { _id: false });
 const contactPointSchema = new Schema({
 	type: {
 		type: String,
@@ -249,7 +297,8 @@ const contactPointSchema = new Schema({
 	verified: {
 		type: Boolean,
 		default: false
-	}
+	},
+	consent: { type: channelConsentSchema }
 }, { _id: false });
 const addressSchema = new Schema({
 	type: {
@@ -338,6 +387,44 @@ const taxIdentitySchema = new Schema({
 		maxlength: 2
 	}
 }, { _id: false });
+const relationshipSchema = new Schema({
+	kind: {
+		type: String,
+		enum: RELATIONSHIP_KINDS,
+		required: true
+	},
+	relatedTo: {
+		type: Schema.Types.ObjectId,
+		ref: "Party",
+		default: null
+	},
+	shareClass: {
+		type: String,
+		trim: true,
+		maxlength: 60,
+		default: null
+	},
+	sharePercent: {
+		type: Number,
+		min: 0,
+		max: 100,
+		default: null
+	},
+	from: {
+		type: Date,
+		required: true
+	},
+	to: {
+		type: Date,
+		default: null
+	},
+	note: {
+		type: String,
+		trim: true,
+		maxlength: 300,
+		default: null
+	}
+});
 const externalRefSchema$1 = new Schema({
 	sourceId: {
 		type: String,
@@ -414,6 +501,14 @@ function buildPartySchema(config) {
 			type: [String],
 			default: []
 		},
+		legalForm: {
+			type: String,
+			enum: LEGAL_FORMS
+		},
+		relationships: {
+			type: [relationshipSchema],
+			default: []
+		},
 		metadata: { type: Schema.Types.Mixed },
 		version: {
 			type: Number,
@@ -439,6 +534,10 @@ function buildPartySchema(config) {
 	schema.index(scoped({ createdAt: -1 }));
 	schema.index(scoped({ parentId: 1 }));
 	schema.index(scoped({ userLinks: 1 }));
+	schema.index(scoped({
+		"relationships.kind": 1,
+		"relationships.relatedTo": 1
+	}));
 	schema.index({
 		"externalRefs.sourceModel": 1,
 		"externalRefs.sourceId": 1
@@ -518,6 +617,12 @@ var PartyMergeError = class extends PartyError {
 		});
 	}
 };
+/** A relationship that cannot be recorded or ended as asked (overlap, bad dates, unknown row). */
+var PartyRelationshipError = class extends PartyError {
+	constructor(message, partyId) {
+		super(422, "party.relationship_invalid", message, { partyId });
+	}
+};
 /**
 * `resolveOrCreate` lost the create race and the winning row could not be
 * re-read (should be transient — surfaced rather than swallowed).
@@ -788,23 +893,81 @@ function unionRefs(a, b) {
 	return out;
 }
 /**
+* Reconcile two consent records for the SAME channel.
+*
+* A withdrawal always beats a grant, regardless of which is newer. Recency is
+* the intuitive rule and it is the wrong one here: the two records being
+* reconciled came from duplicate rows whose clocks record when each row was
+* TOUCHED, not the order the person actually spoke, so letting the later
+* timestamp win means a merge can quietly re-subscribe someone who opted out.
+* Being over-cautious costs a marketing email; being wrong costs a complaint
+* you cannot defend. Between two records of the same status the later one wins,
+* since only its timestamp is then load-bearing.
+*/
+function reconcileConsent(a, b) {
+	if (!a) return b;
+	if (!b) return a;
+	if (a.status !== b.status) return a.status === "withdrawn" ? a : b;
+	return b.at > a.at ? b : a;
+}
+/**
 * 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).
+*
+* Where both sides hold the same channel the survivor's row is kept but its
+* CONSENT is reconciled — dropping the loser's row wholesale would discard an
+* opt-out that the duplicate was the only carrier of.
 */
 function unionContacts(a, b) {
-	const seen = new Set(a.map((c) => c.key));
-	const out = [...a];
-	for (const c of b) if (!seen.has(c.key)) {
-		seen.add(c.key);
-		out.push({
-			...c,
-			isPrimary: false
-		});
+	const out = a.map(plainPoint);
+	const at = new Map(out.map((c, i) => [c.key, i]));
+	for (const c of b) {
+		const existing = at.get(c.key);
+		if (existing === void 0) {
+			at.set(c.key, out.length);
+			out.push({
+				...plainPoint(c),
+				isPrimary: false
+			});
+			continue;
+		}
+		const survivor = out[existing];
+		const consent = reconcileConsent(survivor.consent, c.consent);
+		out[existing] = {
+			...survivor,
+			verified: survivor.verified || c.verified,
+			...consent !== void 0 ? { consent } : {}
+		};
 	}
 	return out;
 }
 /**
+* Copy a contact point FIELD BY FIELD.
+*
+* These arrive as Mongoose subdocuments, whose values live behind prototype
+* getters — spreading one yields its internals (`_doc`, `$__`) and none of its
+* data, and an override written alongside them is then dropped on cast. Reading
+* each property goes through the getter and gets the real value, so this is the
+* only shape that survives being handed back to `$set`.
+*/
+function plainPoint(c) {
+	return {
+		type: c.type,
+		value: c.value,
+		key: c.key,
+		...c.input !== void 0 ? { input: c.input } : {},
+		isPrimary: c.isPrimary,
+		verified: c.verified,
+		...c.consent !== void 0 ? { consent: {
+			status: c.consent.status,
+			at: c.consent.at,
+			...c.consent.source !== void 0 ? { source: c.consent.source } : {},
+			...c.consent.ip !== void 0 ? { ip: c.consent.ip } : {}
+		} } : {}
+	};
+}
+/**
 * Union postal addresses, deduping on `(type, line1, postalCode)` — the same
 * address arriving from both sides collapses to one. Absorbed addresses keep
 * their own recipient/label but yield `isDefault` to the survivor: a merge must
@@ -849,10 +1012,12 @@ const PARTY_EVENTS = {
 	ROLE_ADDED: "party:party.role_added",
 	ROLE_REMOVED: "party:party.role_removed",
 	USER_LINKED: "party:party.user_linked",
+	CONSENT_RECORDED: "party:party.consent_recorded",
 	EXTERNAL_REF_ATTACHED: "party:party.external_ref_attached",
 	ARCHIVED: "party:party.archived",
 	RESTORED: "party:party.restored",
-	MERGED: "party:party.merged"
+	MERGED: "party:party.merged",
+	RELATIONSHIP_CHANGED: "party:party.relationship_changed"
 };
 //#endregion
 //#region src/events/helpers.ts
@@ -1052,6 +1217,65 @@ var PartyRepository = class extends Repository {
 		}, updated, ctx);
 		return updated;
 	}
+	/**
+	* Record a dated relationship (shareholder, director, lessor, …) to the reporting company or another
+	* party. Refused when one of the same kind with the same counterpart is already in force over the dates:
+	* two overlapping rows would double a shareholding, and only one of them could be ended.
+	*/
+	async addRelationship(id, input, ctx) {
+		const party = await this.loadParty(id, ctx);
+		const relatedTo = input.relatedTo ?? null;
+		const to = input.to ?? null;
+		if (to && to <= input.from) throw new PartyRelationshipError("A relationship ends after it starts.", id);
+		if (party.relationships.find((r) => r.kind === input.kind && String(r.relatedTo ?? "") === String(relatedTo ?? "") && overlaps(r.from, r.to ?? null, input.from, to))) throw new PartyRelationshipError(`A ${input.kind} relationship already holds over those dates.`, id);
+		const row = {
+			_id: new Types.ObjectId(),
+			kind: input.kind,
+			relatedTo,
+			from: input.from,
+			to,
+			shareClass: input.shareClass ?? null,
+			sharePercent: input.sharePercent ?? null,
+			note: input.note ?? null
+		};
+		const updated = await this.mustUpdate(party._id, { $push: { relationships: row } }, ctx);
+		await this.dispatch(PARTY_EVENTS.RELATIONSHIP_CHANGED, {
+			partyId: String(party._id),
+			relationshipId: String(row._id),
+			kind: input.kind,
+			change: "added"
+		}, updated, ctx);
+		return updated;
+	}
+	/** End a relationship on a date (exclusive). Ending one already ended earlier is refused, never moved. */
+	async endRelationship(id, relationshipId, to, ctx) {
+		const party = await this.loadParty(id, ctx);
+		const row = party.relationships.find((r) => String(r._id) === relationshipId);
+		if (!row) throw new PartyRelationshipError(`Relationship ${relationshipId} not found.`, id);
+		if (row.to) throw new PartyRelationshipError("The relationship has already ended.", id);
+		if (to <= row.from) throw new PartyRelationshipError("A relationship ends after it starts.", id);
+		const updated = await this.update(party._id, { $set: { "relationships.$[r].to": to } }, {
+			...repoOptionsFromCtx(ctx),
+			arrayFilters: [{
+				"r._id": row._id,
+				"r.to": null
+			}]
+		});
+		if (!updated) throw new PartyNotFoundError(id);
+		await this.dispatch(PARTY_EVENTS.RELATIONSHIP_CHANGED, {
+			partyId: String(party._id),
+			relationshipId,
+			kind: row.kind,
+			change: "ended"
+		}, updated, ctx);
+		return updated;
+	}
+	/** The relationships in force on a date — following a merged party to its survivor. */
+	async relationshipsOn(id, on, ctx) {
+		let party = await this.loadParty(id, ctx);
+		if (party.status === "merged" && party.mergedInto) party = await this.loadParty(String(party.mergedInto), ctx);
+		return party.relationships.filter((r) => r.from <= on && (!r.to || on < r.to));
+	}
 	async linkUser(id, userId, ctx) {
 		const party = await this.loadParty(id, ctx);
 		if (party.userLinks.includes(userId)) return party;
@@ -1062,6 +1286,40 @@ var PartyRepository = class extends Repository {
 		}, updated, ctx);
 		return updated;
 	}
+	/**
+	* Record what this person said about being MARKETED to on one channel.
+	*
+	* Addressed by the channel's raw value (what they typed) and normalized here,
+	* so a host passing `07700 900000` and a host passing `+447700900000` reach
+	* the same contact point — consent landing on a second, differently-spelled
+	* row is an opt-out that no sender would ever find.
+	*
+	* A channel the party does not hold is a typed error rather than a silent
+	* no-op: a grant that went nowhere looks identical to one that was stored,
+	* and the caller is usually a booking form that will never check again.
+	*/
+	async recordConsent(id, input, ctx) {
+		const party = await this.loadParty(id, ctx);
+		const canonical = input.channel === "email" ? normalizeEmail(input.value) : normalizePhone$1(input.value, this.normalize);
+		const key = `${input.channel}:${canonical}`;
+		const index = party.contactPoints.findIndex((point) => point.key === key);
+		if (index < 0) throw new PartyValidationError(`Party ${id} has no ${input.channel} contact point for ${canonical}; consent would be unreachable.`);
+		const consent = {
+			status: input.status,
+			at: input.at ?? /* @__PURE__ */ new Date(),
+			...input.source !== void 0 ? { source: input.source } : {},
+			...input.status === "granted" && input.ip !== void 0 ? { ip: input.ip } : {}
+		};
+		const updated = await this.mustUpdate(party._id, { $set: { [`contactPoints.${index}.consent`]: consent } }, ctx);
+		await this.dispatch(PARTY_EVENTS.CONSENT_RECORDED, {
+			partyId: String(party._id),
+			channel: input.channel,
+			value: canonical,
+			status: input.status,
+			...consent.source !== void 0 ? { source: consent.source } : {}
+		}, updated, ctx);
+		return updated;
+	}
 	async attachExternalRef(id, ref, ctx) {
 		const party = await this.loadParty(id, ctx);
 		if (party.externalRefs.some((r) => r.sourceModel === ref.sourceModel && r.sourceId === ref.sourceId)) return party;
@@ -1143,12 +1401,16 @@ var PartyRepository = class extends Repository {
 		const mergedAddresses = unionAddresses(target.addresses, source.addresses);
 		const mergedTags = unionStrings(target.tags, source.tags);
 		const mergedMetadata = unionMetadata(target.metadata, source.metadata);
+		const relKey = (r) => `${r.kind}|${String(r.relatedTo ?? "")}|${new Date(r.from).toISOString()}`;
+		const ownRel = new Set(target.relationships.map(relKey));
+		const mergedRelationships = [...target.relationships, ...source.relationships.filter((r) => !ownRel.has(relKey(r)))];
 		const absorbed = mergedKeys.length - target.identityKeys.length;
 		const fill = {};
 		if (target.taxIdentity === void 0 && source.taxIdentity !== void 0) fill.taxIdentity = source.taxIdentity;
 		if (target.personName === void 0 && source.personName !== void 0) fill.personName = source.personName;
 		if (!target.legalName?.trim() && source.legalName?.trim()) fill.legalName = source.legalName;
 		if (target.parentId === void 0 && source.parentId !== void 0) fill.parentId = source.parentId;
+		if (target.legalForm === void 0 && source.legalForm !== void 0) fill.legalForm = source.legalForm;
 		try {
 			await withTransaction(this.Model.db, async (session) => {
 				if (!await this.claim(String(source._id), {
@@ -1169,6 +1431,7 @@ var PartyRepository = class extends Repository {
 					contactPoints: mergedContacts,
 					addresses: mergedAddresses,
 					tags: mergedTags,
+					relationships: mergedRelationships,
 					...fill,
 					...mergedMetadata !== void 0 ? { metadata: mergedMetadata } : {}
 				} }, {
@@ -1222,6 +1485,7 @@ var PartyRepository = class extends Repository {
 		}), ctx);
 	}
 };
+const overlaps = (aFrom, aTo, bFrom, bTo) => aFrom < (bTo ?? /* @__PURE__ */ new Date(864e13)) && bFrom < (aTo ?? /* @__PURE__ */ new Date(864e13));
 //#endregion
 //#region src/engine/ensure-ready.ts
 /**
@@ -1519,6 +1783,13 @@ const userLinkedSchema = z.object({
 	partyId: z.string(),
 	userId: z.string()
 });
+const consentRecordedSchema = z.object({
+	partyId: z.string(),
+	channel: z.enum(["email", "phone"]),
+	value: z.string(),
+	status: z.enum(["granted", "withdrawn"]),
+	source: z.string().optional()
+});
 const externalRefSchema = z.object({
 	partyId: z.string(),
 	sourceModel: z.string(),
@@ -1530,52 +1801,87 @@ const mergedSchema = z.object({
 	targetId: z.string(),
 	absorbedKeys: z.number().int().nonnegative()
 });
+const PartyCreated = definePartyEvent({
+	name: PARTY_EVENTS.CREATED,
+	description: "A new canonical party identity was created.",
+	zodSchema: createdSchema
+});
+const PartyUpdated = definePartyEvent({
+	name: PARTY_EVENTS.UPDATED,
+	description: "A party identity field changed.",
+	zodSchema: updatedSchema
+});
+const PartyRoleAdded = definePartyEvent({
+	name: PARTY_EVENTS.ROLE_ADDED,
+	description: "A role (customer/supplier/…) was granted to a party.",
+	zodSchema: roleChangedSchema
+});
+const PartyRoleRemoved = definePartyEvent({
+	name: PARTY_EVENTS.ROLE_REMOVED,
+	description: "A role was revoked from a party.",
+	zodSchema: roleChangedSchema
+});
+const PartyUserLinked = definePartyEvent({
+	name: PARTY_EVENTS.USER_LINKED,
+	description: "An auth user was linked to a party (1:many).",
+	zodSchema: userLinkedSchema
+});
+const PartyConsentRecorded = definePartyEvent({
+	name: PARTY_EVENTS.CONSENT_RECORDED,
+	description: "A marketing-consent decision was recorded against one contact channel.",
+	zodSchema: consentRecordedSchema
+});
+const PartyExternalRefAttached = definePartyEvent({
+	name: PARTY_EVENTS.EXTERNAL_REF_ATTACHED,
+	description: "An external-store reference was attached to a party (facet link).",
+	zodSchema: externalRefSchema
+});
+const PartyArchived = definePartyEvent({
+	name: PARTY_EVENTS.ARCHIVED,
+	description: "A party was archived.",
+	zodSchema: lifecycleSchema
+});
+const PartyRestored = definePartyEvent({
+	name: PARTY_EVENTS.RESTORED,
+	description: "An archived party was restored to active.",
+	zodSchema: lifecycleSchema
+});
+const PartyMerged = definePartyEvent({
+	name: PARTY_EVENTS.MERGED,
+	description: "A duplicate party was merged into a survivor; the source becomes a redirect.",
+	zodSchema: mergedSchema
+});
+const relationshipChangedSchema = z.object({
+	partyId: z.string(),
+	relationshipId: z.string(),
+	kind: z.enum([
+		"shareholder",
+		"director",
+		"key_management",
+		"partner_in_firm",
+		"member",
+		"employee",
+		"lessor",
+		"associate"
+	]),
+	change: z.enum(["added", "ended"])
+});
 const partyEventDefinitions = [
+	PartyCreated,
+	PartyUpdated,
+	PartyRoleAdded,
+	PartyRoleRemoved,
+	PartyUserLinked,
+	PartyConsentRecorded,
+	PartyExternalRefAttached,
+	PartyArchived,
+	PartyRestored,
+	PartyMerged,
 	definePartyEvent({
-		name: PARTY_EVENTS.CREATED,
-		description: "A new canonical party identity was created.",
-		zodSchema: createdSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.UPDATED,
-		description: "A party identity field changed.",
-		zodSchema: updatedSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.ROLE_ADDED,
-		description: "A role (customer/supplier/…) was granted to a party.",
-		zodSchema: roleChangedSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.ROLE_REMOVED,
-		description: "A role was revoked from a party.",
-		zodSchema: roleChangedSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.USER_LINKED,
-		description: "An auth user was linked to a party (1:many).",
-		zodSchema: userLinkedSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.EXTERNAL_REF_ATTACHED,
-		description: "An external-store reference was attached to a party (facet link).",
-		zodSchema: externalRefSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.ARCHIVED,
-		description: "A party was archived.",
-		zodSchema: lifecycleSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.RESTORED,
-		description: "An archived party was restored to active.",
-		zodSchema: lifecycleSchema
-	}),
-	definePartyEvent({
-		name: PARTY_EVENTS.MERGED,
-		description: "A duplicate party was merged into a survivor; the source becomes a redirect.",
-		zodSchema: mergedSchema
+		name: PARTY_EVENTS.RELATIONSHIP_CHANGED,
+		description: "A dated relationship of the party (shareholder, director, lessor, …) was added or ended.",
+		zodSchema: relationshipChangedSchema
 	})
 ];
 //#endregion
-export { ADDRESS_TYPES, CONTACT_POINT_TYPES, InProcessPartyBus, PARTY_EVENTS, PARTY_KINDS, PARTY_ROLES, PARTY_STATE_MACHINE, PARTY_STATUSES, PARTY_SUBJECT_MODEL, PENDING_EVENTS, PartyError, PartyEventDispatcher, PartyMergeError, PartyNotFoundError, PartyPhoneFormatError, PartyRepository, PartyResolveConflictError, PartyValidationError, PartyVersionConflictError, buildContactPoints, buildPartySchema, contactPointKey, createEvent, dedupe, defineParty, definePartyModels, deriveIdentityKeys, flushPending, isPartySubject, normalizeEmail, partyEventDefinitions, partySubject, pickPrimary, repoOptionsFromCtx, resolveDisplayName, taxIdentityKey, tenantFieldDef, unionContacts, unionRefs, unionStrings };
+export { ADDRESS_TYPES, CONSENT_STATUSES, CONTACT_POINT_TYPES, InProcessPartyBus, PARTY_EVENTS, PARTY_KINDS, PARTY_ROLES, PARTY_STATE_MACHINE, PARTY_STATUSES, PARTY_SUBJECT_MODEL, PENDING_EVENTS, PartyError, PartyEventDispatcher, PartyMergeError, PartyNotFoundError, PartyPhoneFormatError, PartyRelationshipError, PartyRepository, PartyResolveConflictError, PartyValidationError, PartyVersionConflictError, RELATIONSHIP_KINDS, buildContactPoints, buildPartySchema, contactPointKey, createEvent, dedupe, defineParty, definePartyModels, deriveIdentityKeys, flushPending, isPartySubject, normalizeEmail, partyEventDefinitions, partySubject, pickPrimary, reconcileConsent, repoOptionsFromCtx, resolveDisplayName, taxIdentityKey, tenantFieldDef, unionContacts, unionRefs, unionStrings };

package/dist/maintenance.d.ts

@@ -5,6 +5,18 @@ import "@classytic/primitives/reference";
 /** 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];
+/**
+ * Whether this channel may be used for MARKETING. Transactional messages (your
+ * booking is confirmed, your invoice is due) need no consent and are not what
+ * this records.
+ *
+ * Two states only, and `withdrawn` is deliberately not "absent": a channel that
+ * was never asked and a channel someone opted OUT of are the same silence to a
+ * sender but not to a regulator, and only the second one must survive a merge,
+ * a re-import, or the person booking again.
+ */
+declare const CONSENT_STATUSES: readonly ['granted', 'withdrawn'];
+type ConsentStatus = (typeof CONSENT_STATUSES)[number];
 //#endregion
 //#region src/domain/value-objects.d.ts
 /**
@@ -33,6 +45,45 @@ interface ContactPoint {
   input?: string;
   isPrimary: boolean;
   verified: boolean;
+  /**
+   * Permission to MARKET to this channel, and the proof of it. Absent means
+   * never asked — which is a refusal to a sender, so treat it as one.
+   *
+   * Here rather than in a CRM package because consent is a property of the
+   * CHANNEL, exactly like `verified`: it is the answer to "may I mail this
+   * address", not a domain opinion about the person. Campaign subscriptions,
+   * sequences, suppression lists and unsubscribe tokens stay in CRM keyed by
+   * `partyId` — this is the one fact they all have to agree with, and a sender
+   * that disagrees with it is the bug this field exists to make visible.
+   *
+   * In a multi-tenant deployment a party row is already per-organization, so
+   * this is one business's permission and never a platform-wide one — which is
+   * what "specific and informed" requires.
+   */
+  consent?: ChannelConsent;
+}
+/**
+ * A consent decision, with what a regulator asks for when they ask you to
+ * prove it: what was decided, WHEN, and where the person was standing.
+ *
+ * Immutable by convention — a change of mind is a new record replacing this
+ * one, never an edit, so `at` always dates the CURRENT status.
+ */
+interface ChannelConsent {
+  status: ConsentStatus;
+  /** The moment the person decided. */
+  at: Date;
+  /**
+   * The surface that asked — `'booking-form'`, `'dashboard'`, `'import:2019-mailchimp'`.
+   * Free text on purpose: the kernel cannot enumerate a host's screens, and an
+   * imported consent whose origin is unrecorded is one you cannot defend.
+   */
+  source?: string;
+  /**
+   * Caller IP at the moment of GRANT, when the host has one. Never backfilled:
+   * an IP attached later proves nothing and is then just retained PII.
+   */
+  ip?: string;
 }
 //#endregion
 //#region src/maintenance/phone-identity-repair.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/party",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Engine-factory Party / Business-Partner identity kernel — one canonical party (person | company | group) carrying customer/supplier/contact/employee roles, contact points, addresses, B2B hierarchy, tax identity, and 1:many auth-user links. Dedup + merge + resolve. SAP-BP shape (thin identity + domain facets), NOT an Odoo god-object. PACKAGE_RULES compliant; Mongoose + mongokit + arc primitives.",
   "author": "Classytic",
   "license": "MIT",
@@ -14,18 +14,22 @@
   },
   "exports": {
     ".": {
+      "@classytic/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./events": {
+      "@classytic/source": "./src/events/index.ts",
       "types": "./dist/events.d.ts",
       "default": "./dist/events.js"
     },
     "./maintenance": {
+      "@classytic/source": "./src/maintenance/phone-identity-repair.ts",
       "types": "./dist/maintenance.d.ts",
       "default": "./dist/maintenance.js"
     },
     "./schemas": {
+      "@classytic/source": "./src/schemas/index.ts",
       "types": "./dist/schemas.d.ts",
       "default": "./dist/schemas.js"
     },
@@ -61,21 +65,21 @@
     "mongodb": "7.2.0"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.33.0",
-    "@classytic/contact": ">=0.1.0",
-    "@classytic/primitives": ">=0.23.0",
-    "@classytic/repo-core": ">=0.24.0",
-    "mongoose": ">=9.4.1",
+    "@classytic/mongokit": ">=3.41.0",
+    "@classytic/contact": ">=0.2.0",
+    "@classytic/primitives": ">=0.31.1",
+    "@classytic/repo-core": ">=0.31.0",
+    "mongoose": ">=9.11.0",
     "zod": ">=4.0.0"
   },
   "devDependencies": {
-    "@classytic/mongokit": "^3.33.0",
-    "@classytic/contact": ">=0.1.0",
-    "@classytic/primitives": ">=0.23.0",
-    "@classytic/repo-core": ">=0.24.0",
+    "@classytic/mongokit": "^3.41.0",
+    "@classytic/contact": ">=0.2.0",
+    "@classytic/primitives": ">=0.31.1",
+    "@classytic/repo-core": ">=0.31.0",
     "@types/node": "^25.5.0",
     "mongodb-memory-server": "^10.1.4",
-    "mongoose": "^9.4.1",
+    "mongoose": "^9.11.1",
     "publint": "^0.3.23",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",