@classytic/party 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,80 +1,14 @@
-import { Repository, isDuplicateKeyError, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
-import { Schema } from "mongoose";
+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 { LEGAL_FORMS } from "@classytic/primitives/legal-form";
+import { Schema, Types } from "mongoose";
 import { defineStateMachine } from "@classytic/primitives/state-machine";
-import { parsePhone } from "@classytic/primitives/phone";
-import { isOk } from "@classytic/primitives/result";
-import { createEvent as createEvent$1, matchEventPattern } from "@classytic/primitives/events";
+import { normalizeEmail as normalizeEmail$1 } from "@classytic/contact/email";
+import { PhoneFormatError, normalizePhone } from "@classytic/contact/phone";
+import { createEvent as createEvent$1 } from "@classytic/primitives/events";
+import { idToString } from "@classytic/primitives/reference";
 import { z } from "zod";
-//#region src/domain/errors.ts
-/** Base class so hosts can `instanceof PartyError` across every party throwable. */
-var PartyError = class extends Error {
-	status;
-	code;
-	meta;
-	constructor(status, code, message, meta) {
-		super(message);
-		this.name = new.target.name;
-		this.status = status;
-		this.code = code;
-		if (meta !== void 0) this.meta = meta;
-	}
-};
-/** A referenced party id does not exist (or is out of the caller's scope). */
-var PartyNotFoundError = class extends PartyError {
-	constructor(id) {
-		super(404, "party.not_found", `Party "${id}" not found.`, { partyId: id });
-	}
-};
-/**
-* 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.
-*/
-var PartyMergeError = class extends PartyError {
-	constructor(message, sourceId, targetId) {
-		super(409, "party.merge_conflict", message, {
-			sourceId,
-			targetId
-		});
-	}
-};
-/**
-* `resolveOrCreate` lost the create race and the winning row could not be
-* re-read (should be transient — surfaced rather than swallowed).
-*/
-var PartyResolveConflictError = class extends PartyError {
-	constructor(identityKey) {
-		super(409, "party.resolve_conflict", `Concurrent create for identity "${identityKey}" could not be reconciled.`, { identityKey });
-	}
-};
-/**
-* Optimistic-concurrency guard failed — the party was modified by another
-* writer between read and write. Callers re-fetch and retry.
-*/
-var PartyVersionConflictError = class extends PartyError {
-	constructor(id, expected) {
-		super(409, "party.version_conflict", `Party "${id}" was modified concurrently (expected v${expected}).`, {
-			partyId: id,
-			expectedVersion: expected
-		});
-	}
-};
-/**
-* 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.
-*/
-var PartyModelCollisionError = class extends PartyError {
-	constructor(modelName) {
-		super(500, "party.model_collision", `Mongoose model "${modelName}" is already registered on this connection. Another @classytic/party engine or a stale hot-reload owns it. Pass forceRecreate: true (tests / hot reload only) or use a dedicated connection.`, { modelName });
-	}
-};
-/** Input failed a domain-verb precondition (before any DB write). */
-var PartyValidationError = class extends PartyError {
-	constructor(message, meta) {
-		super(400, "party.validation", message, meta);
-	}
-};
-//#endregion
 //#region src/domain/enums.ts
 /**
 * Party-native enumerations.
@@ -116,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.
 */
@@ -125,6 +70,107 @@ 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`). */
+const PENDING_EVENTS = Symbol.for("@classytic/party:pendingEvents");
+var PartyEventDispatcher = class {
+	name;
+	transport;
+	outbox;
+	logger;
+	constructor(opts) {
+		this.transport = opts.transport;
+		this.outbox = opts.outbox;
+		this.logger = opts.logger;
+		this.name = opts.transport.name;
+	}
+	/** Raw publish — hosts and the unit-of-work flush use this. */
+	publish(event) {
+		return this.transport.publish(event);
+	}
+	subscribe(pattern, handler) {
+		const subscribe = this.transport.subscribe?.bind(this.transport);
+		if (!subscribe) throw new Error("party: configured event transport does not support subscribe");
+		return subscribe(pattern, handler);
+	}
+	/**
+	* Route a domain event with full §P8 discipline. Reads the pending queue and
+	* session off `ctx`.
+	*/
+	async dispatch(event, ctx) {
+		if (this.outbox) try {
+			await this.outbox.save(event, ctx.session !== void 0 ? { session: ctx.session } : {});
+		} catch (err) {
+			this.logger?.error?.(`[party] outbox.save failed for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
+			throw err;
+		}
+		const queue = ctx[PENDING_EVENTS];
+		if (Array.isArray(queue)) {
+			queue.push(event);
+			return;
+		}
+		try {
+			await this.transport.publish(event);
+		} catch (err) {
+			this.logger?.error?.(`[party] publish failed for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	async close() {
+		await this.transport.close?.();
+	}
+};
+/**
+* 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).
+*/
+async function flushPending(dispatcher, queue, logger) {
+	for (const event of queue) try {
+		await dispatcher.publish(event);
+	} catch (err) {
+		logger?.error?.(`[party] post-commit publish failed for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
+	}
+}
+//#endregion
+//#region src/events/in-process-bus.ts
+/**
+* In-process event bus — default fallback when no `eventTransport` is given to
+* `createParty`.
+*
+* A thin subclass of `@classytic/primitives/event-infra`'s shared
+* `InProcessEventBus`. Prior semantics preserved: glob matching via
+* `matchEventPattern`, per-handler error isolation, idempotent `close()`.
+* Party historically SWALLOWED handler errors when no logger was supplied —
+* that default is preserved by passing `logger: null` unless the host injects
+* a `PartyLogger`, whose structured `error(msg, meta)` slot is bridged onto
+* the shared error-logger contract.
+*/
+var InProcessPartyBus = class extends InProcessEventBus {
+	constructor(options) {
+		const partyLogger = options?.logger;
+		super({
+			name: "in-process-party",
+			logLabel: "party",
+			logger: partyLogger?.error ? { error: (message, ...args) => partyLogger.error?.(message, { args }) } : null
+		});
+	}
+};
 //#endregion
 //#region src/models/tenant-field.ts
 /**
@@ -144,15 +190,15 @@ const ADDRESS_TYPES = [
 * company-wide (`multiTenant: false`) so the field is simply not added.
 */
 function tenantFieldDef(config) {
-	if (!config.multiTenant) return void 0;
-	return config.tenantFieldType === "objectId" ? {
+	if (!config.tenant.enabled) return void 0;
+	return config.tenant.fieldType === "objectId" ? {
 		type: Schema.Types.ObjectId,
-		required: true,
-		ref: "organization",
+		required: config.tenant.required,
+		ref: config.tenant.ref,
 		index: true
 	} : {
 		type: String,
-		required: true,
+		required: config.tenant.required,
 		index: true
 	};
 }
@@ -202,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,
@@ -218,6 +285,11 @@ const contactPointSchema = new Schema({
 		type: String,
 		required: true
 	},
+	input: {
+		type: String,
+		trim: true,
+		maxlength: 320
+	},
 	isPrimary: {
 		type: Boolean,
 		default: false
@@ -225,7 +297,8 @@ const contactPointSchema = new Schema({
 	verified: {
 		type: Boolean,
 		default: false
-	}
+	},
+	consent: { type: channelConsentSchema }
 }, { _id: false });
 const addressSchema = new Schema({
 	type: {
@@ -314,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,
@@ -327,7 +438,7 @@ const externalRefSchema$1 = new Schema({
 function buildPartySchema(config) {
 	const tenantField = tenantFieldDef(config);
 	const schema = new Schema({
-		...tenantField ? { organizationId: tenantField } : {},
+		...tenantField ? { [config.tenant.tenantField]: tenantField } : {},
 		kind: {
 			type: String,
 			enum: PARTY_KINDS,
@@ -390,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,
@@ -400,11 +519,14 @@ function buildPartySchema(config) {
 		toJSON: { virtuals: true },
 		toObject: { virtuals: true }
 	});
-	const scoped = (fields) => config.multiTenant ? {
-		organizationId: 1,
+	const scoped = (fields) => config.tenant.enabled ? {
+		[config.tenant.tenantField]: 1,
 		...fields
 	} : fields;
-	schema.index(scoped({ identityKeys: 1 }), { unique: true });
+	schema.index(scoped({ identityKeys: 1 }), {
+		unique: true,
+		partialFilterExpression: { "identityKeys.0": { $exists: true } }
+	});
 	schema.index(scoped({
 		roles: 1,
 		status: 1
@@ -412,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
@@ -428,21 +554,127 @@ function buildPartySchema(config) {
 }
 //#endregion
 //#region src/models/create-models.ts
-/** Mongoose model names this package registers — drives the §21 collision check. */
-const PARTY_MODEL_NAMES = ["Party"];
-function createPartyModels(connection, config) {
-	const forceRecreate = config.forceRecreate ?? false;
+/**
+* Party model specification — the ONE authoritative place the Party model is described.
+*
+* `definePartyModels(config)` returns a connection-free mongokit `ModelBlueprint`; `defineParty`
+* binds it during engine construction. Collision handling, auto-index and (future) collection
+* config live here once (PACKAGE_RULES §20/§21). A name collision surfaces as mongokit's typed
+* `ModelCollisionError`.
+*/
+/**
+* Describe the Party model set as a connection-free blueprint. Pure — builds no schema and
+* registers nothing until `.bind(connection)`.
+*/
+function definePartyModels(config) {
 	const autoIndex = config.autoIndex ?? true;
-	if (forceRecreate) {
-		for (const name of PARTY_MODEL_NAMES) if (connection.models[name]) connection.deleteModel(name);
-	} else for (const name of PARTY_MODEL_NAMES) if (connection.models[name]) throw new PartyModelCollisionError(name);
-	const register = (name, schema) => {
-		schema.set("autoIndex", autoIndex);
-		return connection.model(name, schema);
-	};
-	return Object.freeze({ Party: register("Party", buildPartySchema(config)) });
+	return defineModels({
+		models: [{
+			name: "Party",
+			schema: () => {
+				const schema = buildPartySchema(config);
+				schema.set("autoIndex", autoIndex);
+				return schema;
+			},
+			existing: config.forceRecreate ? {
+				mode: "replace",
+				environment: "test"
+			} : { mode: "throw" }
+		}],
+		assemble: (models) => Object.freeze({ Party: models.get("Party") })
+	});
 }
 //#endregion
+//#region src/domain/errors.ts
+/** Base class so hosts can `instanceof PartyError` across every party throwable. */
+var PartyError = class extends Error {
+	status;
+	code;
+	meta;
+	constructor(status, code, message, meta) {
+		super(message);
+		this.name = new.target.name;
+		this.status = status;
+		this.code = code;
+		if (meta !== void 0) this.meta = meta;
+	}
+};
+/** A referenced party id does not exist (or is out of the caller's scope). */
+var PartyNotFoundError = class extends PartyError {
+	constructor(id) {
+		super(404, "party.not_found", `Party "${id}" not found.`, { partyId: id });
+	}
+};
+/**
+* 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.
+*/
+var PartyMergeError = class extends PartyError {
+	constructor(message, sourceId, targetId) {
+		super(409, "party.merge_conflict", message, {
+			sourceId,
+			targetId
+		});
+	}
+};
+/** 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).
+*/
+var PartyResolveConflictError = class extends PartyError {
+	constructor(identityKey) {
+		super(409, "party.resolve_conflict", `Concurrent create for identity "${identityKey}" could not be reconciled.`, { identityKey });
+	}
+};
+/**
+* Optimistic-concurrency guard failed — the party was modified by another
+* writer between read and write. Callers re-fetch and retry.
+*/
+var PartyVersionConflictError = class extends PartyError {
+	constructor(id, expected) {
+		super(409, "party.version_conflict", `Party "${id}" was modified concurrently (expected v${expected}).`, {
+			partyId: id,
+			expectedVersion: expected
+		});
+	}
+};
+/** Input failed a domain-verb precondition (before any DB write). */
+var PartyValidationError = class extends PartyError {
+	constructor(message, meta) {
+		super(400, "party.validation", message, meta);
+	}
+};
+/**
+* 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.
+*/
+var PartyPhoneFormatError = class extends PartyError {
+	constructor(value, defaultRegion, detail) {
+		super(400, "party.phone_invalid", `Phone ${JSON.stringify(value)} is not a valid ${defaultRegion ?? "E.164"} number (${detail}). Identity requires an E.164 phone; supply a dialable number or configure the deployment region (\`defaultPhoneRegion\`) so national formats can be interpreted. It is NOT stored as typed — a raw spelling used as an identity key is how one person becomes several parties.`, {
+			value,
+			...defaultRegion !== void 0 ? { defaultRegion } : {},
+			detail
+		});
+	}
+};
+//#endregion
 //#region src/domain/state-machine.ts
 /**
 * Party identity lifecycle FSM — the compile-time twin of the `repo.claim()`
@@ -471,32 +703,89 @@ const PARTY_STATE_MACHINE = defineStateMachine({
 * SAME key regardless of casing/spacing/punctuation, so `resolveOrCreate` finds
 * the existing party instead of forking a duplicate.
 *
-* Phone normalization DELEGATES to `@classytic/primitives/phone` (the canonical
-* E.164 parser) — we never re-implement phone parsing (PACKAGE_RULES §P12).
-* Email normalization is a conservative trim+lowercase: aggressive canonical-
-* ization (gmail dot/plus stripping) is WRONG for identity — `a+shop@x.com` is
-* a real, distinct inbox.
+* ## Both rules live in `@classytic/contact`, imported DIRECTLY
+*
+* Neither implementation is here. Both are in `@classytic/contact`, a kernel
+* below this one, and this file is a CALLER of it — not a re-export of it. That
+* distinction is the whole point: the phone rule had three implementations (here,
+* be-prod's `shared/phone.ts`, and hotel's), and a re-export would have been a
+* fourth NAME for one rule, which is how the drift started. A consumer that wants
+* to normalize a contact point imports `@classytic/contact/phone` or
+* `@classytic/contact/email`; it does not reach through party.
+*
+* `@classytic/primitives/phone` deliberately does not do the phone work — it is a
+* zero-dependency E.164 value object whose own docblock says *"deeper
+* validation … is the host's call to layer on top"*. `@classytic/contact` IS that
+* layer, and `ParsedPhone` extends the primitive rather than re-declaring it.
+*
+* ## What this file still owns: the WIRE contract
+*
+* `@classytic/contact` throws plain `Error` subclasses — it sits below every
+* domain kernel and knows nothing about HTTP. Party owns a 400 /
+* `party.phone_invalid` contract that arc serializes natively, so the boundary
+* translation happens here, once, in the one function that derives the key.
+*
+* `PhoneRegionError` is deliberately NOT translated: a misconfigured
+* `defaultPhoneRegion` is a deployment fault, not a customer's bad phone number,
+* and turning it into a 400 on `customer.phone` would blame the wrong party (in
+* both senses) for every number in the country.
+*
+* ## `@classytic/contact` is a PEER dependency, and that is load-bearing
+*
+* Not a `dependencies` entry. npm may nest a regular dependency under
+* `party/node_modules/`, which would give the host a SECOND module instance —
+* and then `err instanceof PhoneFormatError` is `false` at a host catch site
+* that imported its own copy. The guard would compile, run, and match nothing.
+* A peer forces exactly one copy per host, so class identity holds across the
+* boundary.
+*
+* ## The region is CONFIGURATION, never a constant
+*
+* `defaultRegion` is an ISO 3166-1 alpha-2 code supplied by the deployment
+* (`PartyShape.defaultPhoneRegion` → `deployment.config.ts`). This kernel names
+* no country. With no region configured, only explicit E.164 input is accepted:
+* refusing is correct, because guessing a country is how you mint a plausible
+* wrong number.
+*/
+/**
+* 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.
 */
-/** Lowercase + trim an email. Conservative — never strips dots/plus tags. */
 function normalizeEmail(raw) {
-	return raw.trim().toLowerCase();
+	return normalizeEmail$1(raw);
 }
 /**
-* 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.
+* Canonical E.164 form of a phone number, for dedup AND for storage.
+*
+* Delegates to `@classytic/contact`, then re-throws its refusal as party's own
+* `PartyPhoneFormatError` (400 / `party.phone_invalid`) so arc serializes it
+* natively. There is no fallback at either layer: the old `+${digits}`
+* degradation is precisely what split one member into several parties, and it
+* did so without erroring.
+*
+* NOT exported from this kernel's public surface. A consumer that wants to
+* normalize a phone imports `@classytic/contact/phone` directly — one rule,
+* one name. What party owns is `buildContactPoints`, the single point every
+* identity write crosses.
 */
-function normalizePhone(raw) {
-	const parsed = parsePhone(raw.trim());
-	if (isOk(parsed)) return parsed.value.e164;
-	const digits = raw.replace(/\D/g, "");
-	return digits ? `+${digits}` : "";
+function normalizePhone$1(raw, options = {}) {
+	const defaultRegion = options.defaultRegion;
+	try {
+		return normalizePhone(raw, { ...defaultRegion !== void 0 ? { defaultRegion } : {} });
+	} catch (err) {
+		if (err instanceof PhoneFormatError) throw new PartyPhoneFormatError(err.input, defaultRegion, err.detail ?? err.code);
+		throw err;
+	}
 }
 /** The stable dedup key for a contact point (`email:ada@x.com`, `phone:+8801...`). */
-function contactPointKey(type, value) {
-	return `${type}:${type === "email" ? normalizeEmail(value) : normalizePhone(value)}`;
+function contactPointKey(type, value, options = {}) {
+	return `${type}:${type === "email" ? normalizeEmail(value) : normalizePhone$1(value, options)}`;
 }
 /** A tax-identity dedup key (`vat:...` / `bin:...`) — cross-scope-stable statutory id. */
 function taxIdentityKey(kind, value) {
@@ -517,28 +806,39 @@ function dedupe(arr) {
 /**
 * 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.
 */
-function buildContactPoints(input) {
+function buildContactPoints(input, options = {}) {
 	const points = [];
-	(input.emails ?? []).forEach((value, i) => {
-		if (!value.trim()) return;
+	const seen = /* @__PURE__ */ new Set();
+	const push = (type, raw, canonical, isFirst) => {
+		const key = `${type}:${canonical}`;
+		if (seen.has(key)) return;
+		seen.add(key);
 		points.push({
-			type: "email",
-			value,
-			key: contactPointKey("email", value),
-			isPrimary: i === 0,
+			type,
+			value: canonical,
+			key,
+			...raw.trim() !== canonical ? { input: raw.trim() } : {},
+			isPrimary: isFirst,
 			verified: false
 		});
+	};
+	(input.emails ?? []).forEach((value, i) => {
+		if (!value.trim()) return;
+		push("email", value, normalizeEmail(value), i === 0);
 	});
 	(input.phones ?? []).forEach((value, i) => {
 		if (!value.trim()) return;
-		points.push({
-			type: "phone",
-			value,
-			key: contactPointKey("phone", value),
-			isPrimary: i === 0,
-			verified: false
-		});
+		push("phone", value, normalizePhone$1(value, options), i === 0);
 	});
 	return points;
 }
@@ -547,8 +847,9 @@ function buildContactPoints(input) {
 * statutory ids, and external-store refs. Blank/degenerate keys are dropped so
 * they never poison the unique index.
 */
-function deriveIdentityKeys(contactPoints, input) {
-	const keys = contactPoints.map((c) => c.key);
+function deriveIdentityKeys(contactPoints, input, options = {}) {
+	const contactTypes = options.contactTypes ?? ["email", "phone"];
+	const keys = contactPoints.filter((c) => contactTypes.includes(c.type)).map((c) => c.key);
 	if (input.taxIdentity?.vat) keys.push(taxIdentityKey("vat", input.taxIdentity.vat));
 	if (input.taxIdentity?.bin) keys.push(taxIdentityKey("bin", input.taxIdentity.bin));
 	for (const ref of input.externalRefs ?? []) keys.push(`ref:${ref.sourceModel}:${ref.sourceId}`);
@@ -592,22 +893,116 @@ 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.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
+* never produce two default addresses (mirrors `unionContacts`' primary rule).
+*/
+function unionAddresses(a, b) {
+	const key = (ad) => `${ad.type}|${(ad.line1 ?? "").trim().toLowerCase()}|${(ad.postalCode ?? "").trim().toLowerCase()}`;
+	const seen = new Set(a.map(key));
 	const out = [...a];
-	for (const c of b) if (!seen.has(c.key)) {
-		seen.add(c.key);
-		out.push({
-			...c,
-			isPrimary: false
-		});
+	let hasDefault = a.some((ad) => ad.isDefault);
+	for (const ad of b) {
+		const k = key(ad);
+		if (seen.has(k)) continue;
+		seen.add(k);
+		const next = hasDefault && ad.isDefault ? {
+			...ad,
+			isDefault: false
+		} : ad;
+		if (next.isDefault) hasDefault = true;
+		out.push(next);
 	}
 	return out;
 }
+/**
+* Shallow-merge two metadata bags: the survivor (`a`) wins on every key it
+* already holds; the loser (`b`) only FILLS keys the survivor is missing. Never
+* overwrites a populated survivor field. `undefined` when both are empty.
+*/
+function unionMetadata(a, b) {
+	if (a === void 0 && b === void 0) return void 0;
+	return {
+		...b ?? {},
+		...a ?? {}
+	};
+}
 //#endregion
 //#region src/events/event-constants.ts
 /** PACKAGE_RULES §12: `package:resource.verb`. Emit ONLY these catalog names. */
@@ -617,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
@@ -665,9 +1062,15 @@ function repoOptionsFromCtx(ctx) {
 const OBJECT_ID_HEX = /^[a-f0-9]{24}$/i;
 var PartyRepository = class extends Repository {
 	events;
+	/** The ONE interpretation of free-form contact input in this deployment. */
+	normalize;
+	/** Contact data can exist without being strong enough to collapse two parties. */
+	identityContactTypes;
 	constructor(model, deps, plugins = []) {
 		super(model, plugins);
 		this.events = deps.events;
+		this.normalize = deps.defaultPhoneRegion !== void 0 ? { defaultRegion: deps.defaultPhoneRegion } : {};
+		this.identityContactTypes = deps.identityContactTypes ?? ["email", "phone"];
 	}
 	/** `update` that never returns null — the party was loaded first; a null means a concurrent delete. */
 	async mustUpdate(id, patch, ctx) {
@@ -676,9 +1079,9 @@ var PartyRepository = class extends Repository {
 		return updated;
 	}
 	async resolveOrCreate(input, ctx) {
-		const contactPoints = buildContactPoints(input);
-		const keys = deriveIdentityKeys(contactPoints, input);
-		if (keys.length === 0 && !input.displayName && !input.personName) throw new PartyValidationError("resolveOrCreate needs at least one identity signal (email/phone/vat/bin/externalRef) or a displayName.");
+		const contactPoints = buildContactPoints(input, this.normalize);
+		const keys = deriveIdentityKeys(contactPoints, input, { contactTypes: this.identityContactTypes });
+		if (keys.length === 0 && contactPoints.length === 0 && !input.displayName?.trim() && !input.personName && !input.legalName?.trim()) throw new PartyValidationError("resolveOrCreate needs at least one contact/identity signal (email/phone/vat/bin/externalRef) or a name.");
 		if (keys.length > 0) {
 			const existing = await this.getByQuery({
 				identityKeys: { $in: keys },
@@ -770,17 +1173,24 @@ var PartyRepository = class extends Repository {
 	*/
 	async syncIdentity(id, input, ctx) {
 		const party = await this.loadParty(id, ctx);
-		const mergedContacts = unionContacts(party.contactPoints, buildContactPoints(input));
+		const mergedContacts = unionContacts(party.contactPoints, buildContactPoints(input, this.normalize));
+		const mergedKeys = unionStrings(party.identityKeys, deriveIdentityKeys(mergedContacts, input, { contactTypes: this.identityContactTypes }));
 		const set = {
 			contactPoints: mergedContacts,
-			identityKeys: unionStrings(party.identityKeys, deriveIdentityKeys(mergedContacts, input))
+			identityKeys: mergedKeys
 		};
 		if (input.displayName?.trim()) set.displayName = input.displayName.trim();
 		if (input.legalName?.trim()) set.legalName = input.legalName.trim();
 		if (input.personName !== void 0) set.personName = input.personName;
 		if (input.addresses !== void 0) set.addresses = input.addresses;
 		if (input.taxIdentity !== void 0) set.taxIdentity = input.taxIdentity;
-		const updated = await this.mustUpdate(party._id, { $set: set }, ctx);
+		let updated;
+		try {
+			updated = await this.mustUpdate(party._id, { $set: set }, ctx);
+		} catch (err) {
+			if (isDuplicateKeyError(err)) throw new PartyResolveConflictError(mergedKeys.find((k) => !party.identityKeys.includes(k)) ?? mergedKeys[0] ?? "");
+			throw err;
+		}
 		await this.dispatch(PARTY_EVENTS.UPDATED, {
 			partyId: String(party._id),
 			changed: Object.keys(set)
@@ -807,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;
@@ -817,10 +1286,64 @@ 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;
-		const updated = await this.mustUpdate(party._id, { $addToSet: { externalRefs: ref } }, ctx);
+		const refKey = `ref:${ref.sourceModel}:${ref.sourceId}`;
+		let updated;
+		try {
+			updated = await this.mustUpdate(party._id, { $addToSet: {
+				externalRefs: ref,
+				identityKeys: refKey
+			} }, ctx);
+		} catch (err) {
+			if (isDuplicateKeyError(err)) {
+				const owner = await this.getByQuery({
+					identityKeys: refKey,
+					status: { $ne: "merged" }
+				}, {
+					...repoOptionsFromCtx(ctx),
+					throwOnNotFound: false
+				});
+				if (owner && String(owner._id) === String(party._id)) return owner;
+				throw new PartyResolveConflictError(refKey);
+			}
+			throw err;
+		}
 		await this.dispatch(PARTY_EVENTS.EXTERNAL_REF_ATTACHED, {
 			partyId: String(party._id),
 			sourceModel: ref.sourceModel,
@@ -852,9 +1375,17 @@ var PartyRepository = class extends Repository {
 	}
 	/**
 	* 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.
 	*/
 	async merge(sourceId, targetId, ctx) {
 		if (sourceId === targetId) throw new PartyMergeError("Cannot merge a party into itself.", sourceId, targetId);
@@ -867,27 +1398,51 @@ var PartyRepository = class extends Repository {
 		const mergedUsers = unionStrings(target.userLinks, source.userLinks);
 		const mergedRefs = unionRefs(target.externalRefs, source.externalRefs);
 		const mergedContacts = unionContacts(target.contactPoints, source.contactPoints);
+		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;
-		await withTransaction(this.Model.db, async (session) => {
-			await this.update(source._id, { $set: {
-				status: "merged",
-				mergedInto: target._id,
-				identityKeys: []
-			} }, {
-				...repoOptionsFromCtx(ctx),
-				session
-			});
-			await this.update(target._id, { $set: {
-				identityKeys: mergedKeys,
-				roles: mergedRoles,
-				userLinks: mergedUsers,
-				externalRefs: mergedRefs,
-				contactPoints: mergedContacts
-			} }, {
-				...repoOptionsFromCtx(ctx),
-				session
-			});
-		}, { allowFallback: true });
+		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), {
+					from: ["active", "archived"],
+					to: "merged"
+				}, { $set: {
+					mergedInto: target._id,
+					identityKeys: []
+				} }, {
+					...repoOptionsFromCtx(ctx),
+					session
+				})) throw new PartyMergeError("Source party was concurrently modified (no longer mergeable).", sourceId, targetId);
+				await this.update(target._id, { $set: {
+					identityKeys: mergedKeys,
+					roles: mergedRoles,
+					userLinks: mergedUsers,
+					externalRefs: mergedRefs,
+					contactPoints: mergedContacts,
+					addresses: mergedAddresses,
+					tags: mergedTags,
+					relationships: mergedRelationships,
+					...fill,
+					...mergedMetadata !== void 0 ? { metadata: mergedMetadata } : {}
+				} }, {
+					...repoOptionsFromCtx(ctx),
+					session
+				});
+			}, { allowFallback: true });
+		} catch (err) {
+			if (isDuplicateKeyError(err)) throw new PartyMergeError("Concurrent merge collided on a shared identity key.", sourceId, targetId);
+			throw err;
+		}
 		const survivor = await this.loadParty(targetId, ctx);
 		await this.dispatch(PARTY_EVENTS.MERGED, {
 			sourceId,
@@ -930,114 +1485,45 @@ 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/events/dispatch.ts
-/** Context key carrying a post-commit publish queue (attached by `withTransaction`). */
-const PENDING_EVENTS = Symbol.for("@classytic/party:pendingEvents");
-var PartyEventDispatcher = class {
-	name;
-	transport;
-	outbox;
-	logger;
-	constructor(opts) {
-		this.transport = opts.transport;
-		this.outbox = opts.outbox;
-		this.logger = opts.logger;
-		this.name = opts.transport.name;
-	}
-	/** Raw publish — hosts and the unit-of-work flush use this. */
-	publish(event) {
-		return this.transport.publish(event);
-	}
-	subscribe(pattern, handler) {
-		return this.transport.subscribe(pattern, handler);
-	}
-	/**
-	* Route a domain event with full §P8 discipline. Reads the pending queue and
-	* session off `ctx`.
-	*/
-	async dispatch(event, ctx) {
-		if (this.outbox) try {
-			await this.outbox.save(event, ctx.session !== void 0 ? { session: ctx.session } : {});
-		} catch (err) {
-			this.logger?.error?.(`[party] outbox.save failed for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
-			throw err;
-		}
-		const queue = ctx[PENDING_EVENTS];
-		if (Array.isArray(queue)) {
-			queue.push(event);
-			return;
-		}
-		try {
-			await this.transport.publish(event);
-		} catch (err) {
-			this.logger?.error?.(`[party] publish failed for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
-		}
-	}
-	async close() {
-		await this.transport.close?.();
-	}
-};
-/**
-* 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).
-*/
-async function flushPending(dispatcher, queue, logger) {
-	for (const event of queue) try {
-		await dispatcher.publish(event);
-	} catch (err) {
-		logger?.error?.(`[party] post-commit publish failed for ${event.type}`, { error: err instanceof Error ? err.message : String(err) });
-	}
-}
-//#endregion
-//#region src/events/in-process-bus.ts
+//#region src/engine/ensure-ready.ts
 /**
-* In-process event bus — default fallback when no `eventTransport` is given to
-* `createParty`. Structurally identical to arc's `MemoryEventTransport`;
-* pattern-matching delegates to primitives' `matchEventPattern` (PACKAGE_RULES
-* §13). Handler errors are swallowed-and-logged — emission never blocks writes.
+* Boot capability gate (PACKAGE_RULES §capabilities). `resolveOrCreate`'s
+* race-safety leans on the unique-index E11000 path, and `merge` writes two
+* documents in a transaction — so the backend MUST support `upsert` +
+* `duplicateKeyError`, and `transactions` (unless the host opts out).
+* Fail loud at engine creation, not with a cryptic error on the first merge.
+*
+* ## This gate could not fire until 2026-08-05
+*
+* `repo.capabilities` used to resolve to mongokit's STATIC
+* `MONGOKIT_CAPABILITIES`, whose `transactions` was hard-coded `true`. So the
+* check below was structurally unfalsifiable for every mongoose-backed
+* repository — including one pointed at a standalone `mongod`, the exact
+* deployment it exists to catch. (party's kernel-conformance run had to SKIP
+* `bind-verifies-requirements` for precisely this reason.) mongokit now
+* OBSERVES the live deployment topology per connection, so the same code path
+* now genuinely refuses a standalone.
+*
+* ## Three answers, not two
+*
+* `transactionResolutionOf(caps)` distinguishes an OBSERVED "no" (a standalone
+* — fix the deployment) from "we could not determine it" (bound before the
+* connection opened, an unreadable driver). Both refuse, because an unobserved
+* outcome is not a positive one (AGENTS.md FAIL LOUD rule 3) — but the message
+* differs, because the operator's fix does.
 */
-var InProcessPartyBus = class {
-	name = "in-process-party";
-	subs = [];
-	logger;
-	constructor(options) {
-		this.logger = options?.logger;
-	}
-	async publish(event) {
-		const matching = this.subs.filter((s) => matchEventPattern(s.pattern, event.type));
-		for (const sub of matching) try {
-			await sub.handler(event);
-		} catch (err) {
-			this.logger?.error?.(`[party] event handler error [${event.type}]`, { error: err instanceof Error ? err.message : String(err) });
-		}
-	}
-	async subscribe(pattern, handler) {
-		const sub = {
-			pattern,
-			handler
-		};
-		this.subs.push(sub);
-		return () => {
-			this.subs = this.subs.filter((s) => s !== sub);
-		};
-	}
-	async close() {
-		this.subs = [];
-	}
-};
-//#endregion
-//#region src/engine/ensure-ready.ts
 function assertPartyCapabilities(repo, opts = {}) {
 	const caps = repo.capabilities;
 	if (!caps) throw new Error("[party] backend declares no `capabilities` descriptor (needs repo-core 0.6 / mongokit 3.16+).");
 	const missing = ["duplicateKeyError"].filter((flag) => caps[flag] !== true);
 	if (missing.length > 0) throw new Error(`[party] backend missing required capabilities: ${missing.join(", ")}. resolveOrCreate relies on unique-index conflict detection for race-safe identity dedup.`);
 	if (caps.transactions !== true) {
-		const msg = "[party] backend does not support transactions — `merge` writes two documents and needs a replica set for atomicity.";
-		if (opts.allowNonTransactional) opts.logger?.warn?.(`${msg} allowNonTransactional=true: merge falls back to sequential writes (partial-write risk).`);
-		else throw new Error(`${msg} Run MongoDB as a replica set, or pass allowNonTransactional: true.`);
+		const indeterminate = transactionResolutionOf(caps) === "unknown";
+		const cause = indeterminate ? "[party] could NOT determine whether the backend supports transactions (the connection was not open at bind time, or the driver exposed no topology). An unconfirmed answer is treated as unsupported — `merge` writes two documents and needs atomicity." : "[party] backend does not support transactions — `merge` writes two documents and needs a replica set for atomicity.";
+		if (opts.allowNonTransactional) opts.logger?.warn?.(`${cause} allowNonTransactional=true: merge falls back to sequential writes (partial-write risk).`);
+		else throw new Error(`${cause} ${indeterminate ? "Bind AFTER `await mongoose.connect(...)`, or `await probeMongoCapabilities(connection)` first, or pass allowNonTransactional: true." : "Run MongoDB as a replica set, or pass allowNonTransactional: true."}`);
 	}
 }
 //#endregion
@@ -1072,83 +1558,173 @@ async function runUnit(config, ctx, body) {
 	return result;
 }
 //#endregion
-//#region src/engine/create-party.ts
+//#region src/engine/define-party.ts
 /**
-* createParty — engine factory for @classytic/party.
-*
-*   1. Validate `connection`.
-*   2. Resolve defaults (multiTenant=true, tenantFieldType=objectId, …).
-*   3. Create the Party model on the connection (collision policy §21).
-*   4. Resolve the EventTransport (or default in-process bus) + dispatcher.
-*   5. Build the repository — plugins composed in canonical order (§9.2).
-*   6. Boot-gate required capabilities, then freeze + return the engine.
+* `defineParty` — the DESCRIBE/BIND blueprint for the party engine
+* (STANDARDIZATION-PLAN §6). Splits construction into two phases:
 *
-* @example
-* ```ts
-* import mongoose from 'mongoose';
-* import { createParty } from '@classytic/party';
+*   - **describe** (`defineParty(shape)`): pure. Validates the model set and freezes the
+*     model names via mongokit's `defineModels()`. No connection, no schema built, no I/O —
+*     safe to call at import / module-composition time.
+*   - **bind** (`blueprint.bind(connection, runtime)`): compiles the schema on the supplied
+*     connection, registers the model, wires the transport/dispatcher/repository, verifies
+*     capabilities, and returns the frozen `PartyEngine`.
 *
-* const party = await createParty({ connection: mongoose.connection, multiTenant: false });
-*
-* const { party: p } = await party.port.resolveOrCreate(
-*   { displayName: 'Ada Lovelace', emails: ['ada@x.com'], roles: ['customer'] },
-*   {},
-* );
-* ```
+* This is the sole construction API — there is no `createParty` wrapper.
 */
-async function createParty(config) {
-	if (!config.connection) throw new Error("[party] PartyConfig.connection is required");
-	const resolved = {
-		connection: config.connection,
-		multiTenant: config.multiTenant ?? true,
-		tenantFieldType: config.tenantFieldType ?? "objectId",
-		forceRecreate: config.forceRecreate ?? false,
-		autoIndex: config.autoIndex ?? true,
-		allowNonTransactional: config.allowNonTransactional ?? false,
-		...config.logger !== void 0 ? { logger: config.logger } : {},
-		...config.pagination !== void 0 ? { pagination: config.pagination } : {},
-		plugins: config.plugins ?? []
-	};
-	const models = createPartyModels(config.connection, resolved);
-	const events = new PartyEventDispatcher({
-		transport: config.eventTransport ?? new InProcessPartyBus(config.logger ? { logger: config.logger } : void 0),
-		...config.outbox !== void 0 ? { outbox: config.outbox } : {},
-		...config.logger !== void 0 ? { logger: config.logger } : {}
-	});
-	const plugins = [...resolved.multiTenant ? [multiTenantPlugin({
-		tenantField: "organizationId",
-		fieldType: resolved.tenantFieldType,
-		required: true
-	})] : [], ...resolved.plugins];
-	const repository = new PartyRepository(models.Party, {
-		events,
-		...resolved.logger !== void 0 ? { logger: resolved.logger } : {}
-	}, plugins);
-	assertPartyCapabilities(repository, {
-		allowNonTransactional: resolved.allowNonTransactional,
-		...resolved.logger?.warn !== void 0 ? { logger: { warn: (m) => resolved.logger?.warn?.(m) } } : {}
+/**
+* Describe the party engine. Pure — registers no model, builds no schema, performs no I/O.
+*/
+function defineParty(shape = {}) {
+	/**
+	* The pre-consolidation tenant keys are REFUSED, never absorbed.
+	*
+	* This entry reads `shape.tenant`, so a leftover `multiTenant` is invisible and
+	* the `?? true` default applies repo-core's defaults instead. Both outcomes
+	* return plausible data:
+	*   - `multiTenant: false` -> tenancy ON, and the host loses its company-wide reads;
+	*   - `multiTenant: { tenantField: 'business' }` -> scoping on `organizationId`,
+	*     a field those documents do not carry.
+	*
+	* tsc cannot cover this: excess-property checking does not fire for a typed
+	* variable, a spread, or a shape handed over from a dependency's dist — which is
+	* how every real host composes one. Hence a describe-time check, shared from
+	* repo-core so the nine kernels making this same rename cannot each forget it.
+	*/
+	assertNoLegacyTenantKeys(shape, "defineParty", [["tenantFieldType", "tenant.fieldType"]]);
+	const tenant = resolveTenantConfig(shape.tenant ?? true);
+	if (tenant.strategy === "custom") throw new Error("defineParty: tenant.strategy 'custom' is not supported");
+	const autoIndex = shape.autoIndex ?? true;
+	const identityContactTypes = [...new Set(shape.identityContactTypes ?? CONTACT_POINT_TYPES)];
+	const invalidIdentityContactType = identityContactTypes.find((type) => !CONTACT_POINT_TYPES.includes(type));
+	if (invalidIdentityContactType !== void 0) throw new Error(`defineParty: identityContactTypes contains unsupported value '${String(invalidIdentityContactType)}'. Expected: ${CONTACT_POINT_TYPES.join(", ")}.`);
+	const modelBlueprint = definePartyModels({
+		tenant,
+		autoIndex,
+		...shape.forceRecreate !== void 0 ? { forceRecreate: shape.forceRecreate } : {}
 	});
-	return Object.freeze({
-		models,
-		repositories: Object.freeze({ party: repository }),
-		port: repository,
-		events,
-		config: Object.freeze(resolved),
-		withTransaction(ctx, body) {
-			return runUnit({
-				connection: config.connection,
+	return {
+		id: "party",
+		modelNames: modelBlueprint.modelNames,
+		bind(connection, runtime = {}) {
+			/**
+			* BOOT GATE — an injected outbox MUST enlist `ctx.session`.
+			*
+			* FIRST statement, before the model blueprint binds: a pure config
+			* assertion should report before any resource is allocated, and a refused
+			* bind must leave the connection's model registry untouched.
+			*
+			* `OutboxWriteOptions.session` is best-effort BY CONTRACT (see
+			* `@classytic/primitives/outbox`), so a hand-rolled store satisfies
+			* `OutboxStore` and then keeps the row when the transaction aborts.
+			* `PartyEventDispatcher.dispatch` saves under `ctx.session` precisely so it
+			* cannot: identity is the ROOT every facet keys off, and a
+			* `party.merged` that survives a rolled-back merge tells every downstream
+			* consumer — customer, supplier, loyalty, accounting — to re-point at a
+			* party that was never merged. Nothing throws; the divergence shows up as
+			* facets pointing at an id that does not exist.
+			*
+			* Discovering that on the first real merge is far worse than at boot.
+			*/
+			if (runtime.outbox && runtime.outbox.transactionalSave !== true) throw new Error("defineParty.bind: the configured OutboxStore does not declare `transactionalSave: true`, so it does not promise that `save()` enlists `ctx.session` (see @classytic/primitives/outbox — the option is best-effort by contract). Party writes every event row inside the transaction of its caller; a store that ignores the session emits merge/archive events for identities that rolled back. Arc's `repositoryAsOutboxStore` declares it; the in-memory `MemoryOutboxStore` must not — pass no outbox instead.");
+			const models = modelBlueprint.bind(connection);
+			const resolved = {
+				connection,
+				tenant,
+				forceRecreate: shape.forceRecreate ?? false,
+				autoIndex,
+				identityContactTypes: Object.freeze([...identityContactTypes]),
+				...shape.defaultPhoneRegion !== void 0 ? { defaultPhoneRegion: shape.defaultPhoneRegion } : {},
+				allowNonTransactional: runtime.allowNonTransactional ?? false,
+				...runtime.logger !== void 0 ? { logger: runtime.logger } : {},
+				...runtime.pagination !== void 0 ? { pagination: runtime.pagination } : {},
+				plugins: runtime.plugins ?? []
+			};
+			const ownsTransport = runtime.eventTransport === void 0;
+			const events = new PartyEventDispatcher({
+				transport: runtime.eventTransport ?? new InProcessPartyBus(runtime.logger ? { logger: runtime.logger } : void 0),
+				...runtime.outbox !== void 0 ? { outbox: runtime.outbox } : {},
+				...runtime.logger !== void 0 ? { logger: runtime.logger } : {}
+			});
+			const plugins = [...tenant.enabled ? [multiTenantPlugin({
+				tenantField: tenant.tenantField,
+				contextKey: tenant.contextKey,
+				fieldType: tenant.fieldType,
+				required: tenant.required
+			})] : [], ...resolved.plugins];
+			const repository = new PartyRepository(models.Party, {
 				events,
 				...resolved.logger !== void 0 ? { logger: resolved.logger } : {},
-				allowNonTransactional: resolved.allowNonTransactional
-			}, ctx, body);
-		},
-		async syncIndexes() {
-			await Promise.all(Object.values(models).map((m) => m.syncIndexes()));
-		},
-		async dispose() {
-			await events.close();
+				...resolved.defaultPhoneRegion !== void 0 ? { defaultPhoneRegion: resolved.defaultPhoneRegion } : {},
+				identityContactTypes: resolved.identityContactTypes
+			}, plugins);
+			assertPartyCapabilities(repository, {
+				allowNonTransactional: resolved.allowNonTransactional,
+				...resolved.logger?.warn !== void 0 ? { logger: { warn: (m) => resolved.logger?.warn?.(m) } } : {}
+			});
+			const close = async () => {
+				if (ownsTransport) await events.close();
+			};
+			return Object.freeze({
+				models,
+				repositories: Object.freeze({ party: repository }),
+				port: repository,
+				events,
+				config: Object.freeze(resolved),
+				withTransaction(ctx, body) {
+					return runUnit({
+						connection,
+						events,
+						...resolved.logger !== void 0 ? { logger: resolved.logger } : {},
+						allowNonTransactional: resolved.allowNonTransactional
+					}, ctx, body);
+				},
+				async syncIndexes() {
+					await Promise.all(Object.values(models).map((m) => m.syncIndexes()));
+				},
+				close
+			});
 		}
-	});
+	};
+}
+//#endregion
+//#region src/domain/subject.ts
+/**
+* The canonical `subjectModel` value for a Party.
+*
+* Import this — never write `'Party'` in a host, a module, or a test.
+*/
+const PARTY_SUBJECT_MODEL = "Party";
+/**
+* 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.
+*/
+function partySubject(id) {
+	if (id === null || id === void 0) return null;
+	const subjectRef = idToString(id);
+	if (subjectRef.length === 0 || subjectRef === "undefined" || subjectRef === "null") return null;
+	return {
+		subjectRef,
+		subjectModel: PARTY_SUBJECT_MODEL
+	};
+}
+/**
+* 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.
+*/
+function isPartySubject(subject) {
+	return subject.subjectModel === PARTY_SUBJECT_MODEL;
 }
 //#endregion
 //#region src/events/event-catalog.ts
@@ -1207,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(),
@@ -1218,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_MODEL_NAMES, PARTY_ROLES, PARTY_STATE_MACHINE, PARTY_STATUSES, PENDING_EVENTS, PartyError, PartyEventDispatcher, PartyMergeError, PartyModelCollisionError, PartyNotFoundError, PartyRepository, PartyResolveConflictError, PartyValidationError, PartyVersionConflictError, 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, 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 };