@classytic/party 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,12 +1,16 @@
-import { OperationOptions, PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
+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";
 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 { SubjectRef } from "@classytic/primitives/subject";
 import { HttpError } from "@classytic/repo-core/errors";
 //#region src/domain/enums.d.ts
 /**
@@ -38,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
 /**
@@ -65,11 +88,63 @@ interface PartyAddress extends ContactAddress {
  */
 interface ContactPoint {
   type: ContactPointType;
+  /**
+   * The CANONICAL form — a lowercased email, or an E.164 phone. Identity is the
+   * normalized value only; this is also what a notification transport should
+   * dial or mail, so a stored local spelling is a second bug waiting behind the
+   * dedup one.
+   */
   value: string;
   /** Normalized dedup key — the `identityKeys` index entry. */
   key: string;
+  /**
+   * What the operator actually TYPED, kept only when it differs from `value`.
+   * Support-facing provenance ("the till shows 01712345678, the invoice shows
+   * +8801712345678 — same number"). Never an identity signal: it is not keyed,
+   * not indexed and not matched on.
+   */
+  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
@@ -177,13 +252,7 @@ interface PartyLogger {
 //#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: ResolvedTenantConfig;
 }
 /**
  * Tenant-column schema definition, or `undefined` when the engine is
@@ -192,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. */
@@ -214,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;
@@ -226,15 +312,17 @@ declare function buildPartySchema(config: SchemaBuildConfig): Schema<IPartyDocum
 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). */
+interface DefinePartyModelsConfig extends SchemaBuildConfig {
+  /** On a name collision: `false` (default) throws; `true` re-registers (test/dev fixtures). */
   forceRecreate?: boolean;
   /** Mongoose auto-index builds. Default `true` (dev); `false` in prod (§35). */
   autoIndex?: boolean;
 }
-declare function createPartyModels(connection: Connection, config: CreateModelsOptions): PartyModels;
+/**
+ * Describe the Party model set as a connection-free blueprint. Pure — builds no schema and
+ * registers nothing until `.bind(connection)`.
+ */
+declare function definePartyModels(config: DefinePartyModelsConfig): ModelBlueprint<PartyModels>;
 //#endregion
 //#region src/events/dispatch.d.ts
 /** Context key carrying a post-commit publish queue (attached by `withTransaction`). */
@@ -268,12 +356,45 @@ 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;
+  /**
+   * ISO 3166-1 alpha-2 region used to interpret phone input that carries no
+   * country code. Comes from `PartyShape.defaultPhoneRegion`, i.e. the
+   * deployment — this kernel names no country.
+   *
+   * Held on the repository rather than passed per call so `resolveOrCreate` and
+   * `syncIdentity` cannot disagree: a caller-supplied region would let the
+   * create path and the sync path key the same human differently, which is the
+   * split this whole change removes.
+   */
+  defaultPhoneRegion?: string | undefined;
+  /** Deployment-wide contact channels used as authoritative identity keys. */
+  identityContactTypes?: readonly ContactPointType[] | undefined;
 }
 declare class PartyRepository extends Repository<IPartyDocument> implements PartyPort<IPartyDocument> {
   private readonly events;
+  /** The ONE interpretation of free-form contact input in this deployment. */
+  private readonly normalize;
+  /** Contact data can exist without being strong enough to collapse two parties. */
+  private readonly identityContactTypes;
   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;
@@ -291,15 +412,46 @@ 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>;
   /**
    * 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).
+   * keys, contact points, addresses, roles, external refs, user links, tags, and
+   * metadata, and FILLS its empty scalar slots (`taxIdentity`, `personName`,
+   * `legalName`, `parentId`) from the loser — never overwriting a populated
+   * survivor field. The loser becomes a terminal `merged` redirect
+   * (`mergedInto`). Two-document write → runs in a transaction (falls back to
+   * sequential on standalone Mongo).
+   *
+   * Concurrency: the loser is claimed `active|archived → merged` via CAS
+   * (`repo.claim`), so a second concurrent merge of the same source loses the
+   * race and surfaces a typed `PartyMergeError` — never a raw `E11000`. A
+   * duplicate-key collision while adopting the loser's keys maps to the same.
    */
   merge(sourceId: string, targetId: string, ctx: PartyContext): Promise<IPartyDocument>;
   /** Load a party by ObjectId hex, or throw the typed not-found (§P9-style). */
@@ -309,46 +461,27 @@ 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 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;
+  tenant: Readonly<ResolvedTenantConfig>;
   forceRecreate: boolean;
   autoIndex: boolean;
+  /** ISO 3166-1 alpha-2 region for national-format phone input; unset ⇒ E.164 only. */
+  defaultPhoneRegion?: string;
+  /** Contact channels used as authoritative unique identity keys. */
+  identityContactTypes: readonly ContactPointType[];
   allowNonTransactional: boolean;
   logger?: PartyLogger;
   pagination?: PaginationConfig;
@@ -380,16 +513,141 @@ interface PartyEngine {
   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>;
+  /** Release resources owned by this engine. Idempotent. The kernel-standard lifecycle name. */
+  close(): Promise<void>;
 }
 //#endregion
-//#region src/engine/create-party.d.ts
-declare function createParty(config: PartyConfig): Promise<PartyEngine>;
+//#region src/engine/define-party.d.ts
+/**
+ * DESCRIBE-time shape — everything that determines the persistence SHAPE and needs no
+ * connection or I/O to inspect. Nothing here opens a socket or reads a secret.
+ */
+interface PartyShape {
+  /** Company-wide identity (`false`, no tenant column) vs isolated (`true`, default). */
+  tenant?: boolean | TenantConfig;
+  /** Mongoose auto-index builds. Default `true` (dev); pass `false` in prod (§35). */
+  autoIndex?: boolean;
+  /**
+   * On a model-name collision: default throws; `true` re-registers (test/dev fixtures).
+   * Maps to mongokit's `replace` policy, which itself throws under `NODE_ENV=production`.
+   */
+  forceRecreate?: boolean;
+  /**
+   * ISO 3166-1 alpha-2 region used to read phone input that carries no country
+   * code — `'BD'` for a Bangladeshi deployment, `'GB'` for a British one. THIS
+   * KERNEL NAMES NO COUNTRY: the value is the deployment's, and belongs in
+   * `deployment.config.ts`.
+   *
+   * It is describe-time because it determines the persisted `identityKeys`, not
+   * just a request's interpretation — two boots with different regions would key
+   * the same human differently and fork the identity.
+   *
+   * Unset ⇒ only explicit E.164 phones are accepted; a national-format number is
+   * REFUSED rather than guessed at (FAIL LOUD rule 2). That is the safe default:
+   * before this option existed, a rejected parse silently degraded to
+   * `+${digits}`, and `01309000993` / `+8801309000993` became two parties for one
+   * member with nothing reporting it.
+   */
+  defaultPhoneRegion?: string;
+  /**
+   * Contact channels authoritative enough to resolve two records as the same
+   * party. Defaults to both `email` and `phone` for backward compatibility.
+   *
+   * Set `[]` when shared household/company contact details are candidate-match
+   * signals rather than proof of identity. Contacts are still normalized and
+   * stored; tax identifiers and external references remain identity keys.
+   *
+   * Persistence-shaping configuration: changing it does not rewrite existing
+   * `identityKeys`; migrate existing rows before changing a live deployment.
+   */
+  identityContactTypes?: readonly ContactPointType[];
+}
+/**
+ * BIND-time runtime collaborators — the live connection is the first `bind` arg; these are the
+ * rest. A provider client, transport, logger or store belongs here, not in the shape.
+ */
+interface PartyRuntime {
+  eventTransport?: EventTransport;
+  outbox?: OutboxStore;
+  logger?: PartyLogger;
+  pagination?: PaginationConfig;
+  /** Downgrade the boot `transactions` capability requirement to a warning (standalone Mongo). */
+  allowNonTransactional?: boolean;
+  /** Extra mongokit plugins applied after the defaults. */
+  plugins?: PluginType[];
+}
+interface PartyBlueprint {
+  readonly id: 'party';
+  /** The model names this blueprint registers — known without a connection. */
+  readonly modelNames: readonly string[];
+  /**
+   * Compile + register the model on `connection`, wire the engine, verify capabilities.
+   * Synchronous: party's construction performs no async work (model registration and repo
+   * wiring are synchronous). The `KernelBlueprint` contract still permits async binds.
+   */
+  bind(connection: Connection, runtime?: PartyRuntime): PartyEngine;
+}
+/**
+ * Describe the party engine. Pure — registers no model, builds no schema, performs no I/O.
+ */
+declare function defineParty(shape?: PartyShape): PartyBlueprint;
 //#endregion
 //#region src/repositories/repo-options.d.ts
 declare function repoOptionsFromCtx(ctx: PartyContext): OperationOptions;
 //#endregion
+//#region src/domain/subject.d.ts
+/**
+ * The canonical `subjectModel` value for a Party.
+ *
+ * Import this — never write `'Party'` in a host, a module, or a test.
+ */
+declare const PARTY_SUBJECT_MODEL = "Party";
+/**
+ * A Party as other kernels reference it.
+ *
+ * `subjectModel` is narrowed to the literal type so assigning a hand-typed
+ * string is a compile error at the call site, not a runtime mismatch discovered
+ * when a card fails to deactivate.
+ */
+interface PartySubject extends SubjectRef {
+  /**
+   * Narrowed to the literal so assigning a hand-typed string is a COMPILE error
+   * at the call site, not a runtime mismatch discovered when a card fails to
+   * deactivate.
+   *
+   * Extends `SubjectRef` from `@classytic/primitives/subject` rather than
+   * re-declaring the pair: that primitive is the canonical shape for "who a record
+   * is about", shared by attendance, access, credentials and loyalty — and by the
+   * SDK, so a UI cannot bind a card to a different model than entitlements are
+   * granted against. (Deliberately NOT `ExternalRef`, which is the same shape for a
+   * different question — provenance, not identity. A grant carries both at once.)
+   */
+  subjectModel: typeof PARTY_SUBJECT_MODEL;
+}
+/**
+ * Build the subject pair for a Party.
+ *
+ * Accepts anything id-shaped (`ObjectId`, hex string, a document's `_id`) and
+ * stringifies through primitives' `idToString`, because the receiving kernels
+ * store `subjectRef` as a String — a raw `ObjectId` would stringify implicitly
+ * somewhere downstream and the two forms would not compare equal.
+ *
+ * Returns `null` for a missing id rather than a pair containing `"undefined"`.
+ * That string is a real hazard here: it is a *valid* `subjectRef` as far as the
+ * schema is concerned, so it persists, matches nothing, and looks like data.
+ */
+declare function partySubject(id: IdLike | null | undefined): PartySubject | null;
+/**
+ * Does this subject pair refer to a Party?
+ *
+ * For a resolver that fans a mixed subject stream out to the right kernel — an
+ * attendance list can hold Party members and, in an HR deployment, employees
+ * from another identity source.
+ */
+declare function isPartySubject(subject: {
+  subjectModel?: string | undefined;
+}): boolean;
+//#endregion
 //#region src/domain/state-machine.d.ts
 /**
  * Party identity lifecycle FSM — the compile-time twin of the `repo.claim()`
@@ -404,20 +662,62 @@ declare function repoOptionsFromCtx(ctx: PartyContext): OperationOptions;
  */
 declare const PARTY_STATE_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"active" | "archived" | "merged">;
 //#endregion
+//#region src/domain/normalize.d.ts
+/**
+ * How free-form contact input is interpreted. Threaded from the engine's
+ * resolved config so every path — `resolveOrCreate`, `syncIdentity`, merge —
+ * reads the same answer.
+ */
+interface NormalizeOptions {
+  /**
+   * ISO 3166-1 alpha-2 region applied to phone input that carries no country
+   * code (`01712345678` on a Bangladeshi till). Omitted ⇒ E.164 only.
+   */
+  defaultRegion?: string | undefined;
+}
+/**
+ * Canonical email for the dedup key. Trim + lowercase, and deliberately NOT
+ * gmail dot / `+tag` folding — `a+shop@x.com` is a real, distinct inbox, and
+ * folding it MERGES two people, which is the irreversible direction.
+ *
+ * The rule moved to `@classytic/contact/email` unchanged for the canonical case,
+ * with one addition: an address that cannot be canonicalised now THROWS instead of
+ * becoming an identity key. Same reasoning as the phone side — a malformed address
+ * still makes a perfectly stable key, so admitting it does not fail, it forks.
+ */
+declare function normalizeEmail(raw: string): string;
+/** The stable dedup key for a contact point (`email:ada@x.com`, `phone:+8801...`). */
+declare function contactPointKey(type: ContactPointType, value: string, options?: NormalizeOptions): 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/identity.d.ts
+interface IdentityKeyOptions {
+  /** Contact channels authoritative enough to resolve two records as one party. Default: both. */
+  contactTypes?: readonly ContactPointType[];
+}
 /** 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.
+ *
+ * THE SEAM. Both `resolveOrCreate` and `syncIdentity` funnel here, so this is
+ * the one place normalization can be enforced — a fix applied at N call sites
+ * is the same bug waiting at N+1.
+ *
+ * Two spellings of one number in a single input collapse to ONE point (they
+ * share a key). An unparseable phone THROWS rather than being skipped: skipping
+ * would create a party with no phone identity at all, which the next
+ * well-formed visit would not resolve onto — a silent fork by a different route.
  */
-declare function buildContactPoints(input: ResolvePartyInput): ContactPoint[];
+declare function buildContactPoints(input: ResolvePartyInput, options?: NormalizeOptions): 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[];
+declare function deriveIdentityKeys(contactPoints: readonly ContactPoint[], input: ResolvePartyInput, options?: IdentityKeyOptions): 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. */
@@ -428,29 +728,30 @@ 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
-//#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 {
@@ -470,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).
@@ -484,18 +789,28 @@ declare class PartyResolveConflictError extends PartyError {
 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>);
 }
+/**
+ * A phone contact point could not be normalized to E.164 — so it cannot become
+ * an identity key.
+ *
+ * This REFUSES rather than degrades, and that is the whole point. The previous
+ * behaviour fell back to `+${digits}`, which produced keys like
+ * `phone:+01309000993` — neither a national number nor E.164. Two spellings of
+ * one member therefore keyed differently and `resolveOrCreate` forked the
+ * identity, silently: every screen looked correct and the membership history
+ * simply split in two (FAIL LOUD rule 2 — an input we do not understand must
+ * fail, not widen).
+ *
+ * `meta` names the offending value and the region it was interpreted in, so an
+ * operator can fix the data instead of guessing which field a 400 refers to.
+ */
+declare class PartyPhoneFormatError extends PartyError {
+  constructor(value: string, defaultRegion: string | undefined, detail: string);
+}
 //#endregion
 //#region src/events/event-constants.d.ts
 /** PACKAGE_RULES §12: `package:resource.verb`. Emit ONLY these catalog names. */
@@ -505,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
@@ -533,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;
@@ -556,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;
@@ -577,16 +903,10 @@ declare const partyEventDefinitions: ReadonlyArray<PartyEventDefinition>;
 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;
+declare class InProcessPartyBus extends InProcessEventBus {
   constructor(options?: {
-    logger?: PartyLogger | undefined;
+    logger?: PartyLogger;
   });
-  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 };
+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 };