@classytic/party 0.1.0

package/dist/index.js

@@ -0,0 +1,1269 @@
+import { Repository, isDuplicateKeyError, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
+import { Schema } 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 { 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.
+*
+* These are identity-kernel concepts (kind, role, lifecycle) — they have no
+* one-to-one primitive to subset, so they are declared here as the source of
+* truth. Domain FACETS (finance terms, CRM stage, loyalty tier) live in their
+* OWN packages keyed by `partyId`; they are deliberately NOT modelled here —
+* that separation is the whole point of the SAP-style thin identity kernel
+* (vs. Odoo's `res.partner` god-object).
+*/
+/** What kind of real-world entity a party is. */
+const PARTY_KINDS = [
+	"person",
+	"company",
+	"group"
+];
+/**
+* Roles a party plays. NON-exclusive — one party can be a customer AND a
+* supplier AND a contact simultaneously (the exact de-duplication a shared
+* identity buys you). Roles are additive flags, never separate entities.
+*/
+const PARTY_ROLES = [
+	"customer",
+	"supplier",
+	"contact",
+	"employee",
+	"partner"
+];
+/**
+* Identity lifecycle. `merged` is terminal — the row survives as a redirect
+* (`mergedInto`) so historical references (orders, invoices) still resolve.
+*/
+const PARTY_STATUSES = [
+	"active",
+	"archived",
+	"merged"
+];
+/** Channel kind for a contact point. Drives normalization + dedup keys. */
+const CONTACT_POINT_TYPES = ["email", "phone"];
+/**
+* Address role. Mirrors Odoo's `type` (contact/invoice/delivery/other) but
+* as a first-class enum. A party carries many; `isDefault` picks the fallback.
+*/
+const ADDRESS_TYPES = [
+	"billing",
+	"shipping",
+	"contact",
+	"other"
+];
+//#endregion
+//#region src/models/tenant-field.ts
+/**
+* Per PACKAGE_RULES §9.2: never hardcode the tenant column's Mongoose type —
+* the engine config drives both the schema and `multiTenantPlugin` so they
+* stay in sync. Hosts with Better Auth pick `'objectId'` (default — enables
+* `$lookup`, `.populate()`, QueryParser `?lookup=organizationId`); UUID/slug
+* hosts pick `'string'`.
+*
+* NOTE on party scoping: identity is frequently COMPANY-WIDE (one customer is
+* the same person in every branch). Such hosts wire `multiTenant: false` at the
+* engine and this field is omitted entirely. When multi-tenant IS on (SaaS,
+* true per-tenant isolation), this drives the column type.
+*/
+/**
+* Tenant-column schema definition, or `undefined` when the engine is
+* company-wide (`multiTenant: false`) so the field is simply not added.
+*/
+function tenantFieldDef(config) {
+	if (!config.multiTenant) return void 0;
+	return config.tenantFieldType === "objectId" ? {
+		type: Schema.Types.ObjectId,
+		required: true,
+		ref: "organization",
+		index: true
+	} : {
+		type: String,
+		required: true,
+		index: true
+	};
+}
+//#endregion
+//#region src/models/party.model.ts
+/**
+* Party — the single canonical identity. ONE document per real-world
+* person/company/group, carrying non-exclusive roles, contact points,
+* addresses, tax identity, B2B hierarchy, and 1:many auth-user links.
+*
+* This is a THIN identity kernel (SAP Business-Partner shape). Domain FACETS —
+* finance terms (AR/AP, credit), CRM funnel stage, loyalty tier — live in their
+* OWN packages keyed by `partyId`. Nothing here knows about accounting or CRM.
+* That is the deliberate difference from Odoo's `res.partner` god-object.
+*/
+const personNameSchema = new Schema({
+	given: {
+		type: String,
+		required: true,
+		trim: true,
+		maxlength: 120
+	},
+	family: {
+		type: String,
+		default: "",
+		trim: true,
+		maxlength: 120
+	},
+	middle: {
+		type: String,
+		trim: true,
+		maxlength: 120
+	},
+	prefix: {
+		type: String,
+		trim: true,
+		maxlength: 32
+	},
+	suffix: {
+		type: String,
+		trim: true,
+		maxlength: 32
+	},
+	preferred: {
+		type: String,
+		trim: true,
+		maxlength: 120
+	}
+}, { _id: false });
+const contactPointSchema = new Schema({
+	type: {
+		type: String,
+		enum: CONTACT_POINT_TYPES,
+		required: true
+	},
+	value: {
+		type: String,
+		required: true,
+		trim: true,
+		maxlength: 320
+	},
+	key: {
+		type: String,
+		required: true
+	},
+	isPrimary: {
+		type: Boolean,
+		default: false
+	},
+	verified: {
+		type: Boolean,
+		default: false
+	}
+}, { _id: false });
+const addressSchema = new Schema({
+	type: {
+		type: String,
+		enum: ADDRESS_TYPES,
+		default: "contact"
+	},
+	isDefault: {
+		type: Boolean,
+		default: false
+	},
+	label: {
+		type: String,
+		trim: true,
+		maxlength: 120
+	},
+	name: {
+		type: String,
+		trim: true,
+		maxlength: 200
+	},
+	phone: {
+		type: String,
+		trim: true,
+		maxlength: 50
+	},
+	email: {
+		type: String,
+		trim: true,
+		lowercase: true,
+		maxlength: 320
+	},
+	line1: {
+		type: String,
+		required: true,
+		trim: true,
+		maxlength: 300
+	},
+	line2: {
+		type: String,
+		trim: true,
+		maxlength: 300
+	},
+	city: {
+		type: String,
+		required: true,
+		trim: true,
+		maxlength: 150
+	},
+	state: {
+		type: String,
+		trim: true,
+		maxlength: 150
+	},
+	postalCode: {
+		type: String,
+		trim: true,
+		maxlength: 40
+	},
+	country: {
+		type: String,
+		required: true,
+		trim: true,
+		maxlength: 2
+	}
+}, { _id: false });
+const taxIdentitySchema = new Schema({
+	vat: {
+		type: String,
+		trim: true,
+		maxlength: 64
+	},
+	bin: {
+		type: String,
+		trim: true,
+		maxlength: 64
+	},
+	fiscalPositionCode: {
+		type: String,
+		trim: true,
+		maxlength: 64
+	},
+	countryCode: {
+		type: String,
+		trim: true,
+		maxlength: 2
+	}
+}, { _id: false });
+const externalRefSchema$1 = new Schema({
+	sourceId: {
+		type: String,
+		required: true
+	},
+	sourceModel: {
+		type: String,
+		required: true
+	}
+}, { _id: false });
+function buildPartySchema(config) {
+	const tenantField = tenantFieldDef(config);
+	const schema = new Schema({
+		...tenantField ? { organizationId: tenantField } : {},
+		kind: {
+			type: String,
+			enum: PARTY_KINDS,
+			required: true,
+			default: "person"
+		},
+		displayName: {
+			type: String,
+			required: true,
+			trim: true,
+			maxlength: 300
+		},
+		legalName: {
+			type: String,
+			trim: true,
+			maxlength: 300
+		},
+		personName: { type: personNameSchema },
+		contactPoints: {
+			type: [contactPointSchema],
+			default: []
+		},
+		identityKeys: {
+			type: [String],
+			default: []
+		},
+		addresses: {
+			type: [addressSchema],
+			default: []
+		},
+		taxIdentity: { type: taxIdentitySchema },
+		roles: {
+			type: [String],
+			enum: PARTY_ROLES,
+			default: []
+		},
+		externalRefs: {
+			type: [externalRefSchema$1],
+			default: []
+		},
+		userLinks: {
+			type: [String],
+			default: []
+		},
+		parentId: {
+			type: Schema.Types.ObjectId,
+			ref: "Party"
+		},
+		status: {
+			type: String,
+			enum: PARTY_STATUSES,
+			default: "active",
+			index: true
+		},
+		mergedInto: {
+			type: Schema.Types.ObjectId,
+			ref: "Party"
+		},
+		tags: {
+			type: [String],
+			default: []
+		},
+		metadata: { type: Schema.Types.Mixed },
+		version: {
+			type: Number,
+			default: 0
+		}
+	}, {
+		timestamps: true,
+		toJSON: { virtuals: true },
+		toObject: { virtuals: true }
+	});
+	const scoped = (fields) => config.multiTenant ? {
+		organizationId: 1,
+		...fields
+	} : fields;
+	schema.index(scoped({ identityKeys: 1 }), { unique: true });
+	schema.index(scoped({
+		roles: 1,
+		status: 1
+	}));
+	schema.index(scoped({ createdAt: -1 }));
+	schema.index(scoped({ parentId: 1 }));
+	schema.index(scoped({ userLinks: 1 }));
+	schema.index({
+		"externalRefs.sourceModel": 1,
+		"externalRefs.sourceId": 1
+	});
+	schema.virtual("primaryEmail").get(function() {
+		const cps = this.contactPoints ?? [];
+		return (cps.find((c) => c.type === "email" && c.isPrimary) ?? cps.find((c) => c.type === "email"))?.value;
+	});
+	schema.virtual("primaryPhone").get(function() {
+		const cps = this.contactPoints ?? [];
+		return (cps.find((c) => c.type === "phone" && c.isPrimary) ?? cps.find((c) => c.type === "phone"))?.value;
+	});
+	return schema;
+}
+//#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;
+	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)) });
+}
+//#endregion
+//#region src/domain/state-machine.ts
+/**
+* Party identity lifecycle FSM — the compile-time twin of the `repo.claim()`
+* CAS the repository uses for status transitions (PACKAGE_RULES §Concurrency).
+*
+*   active  ──archive──▶ archived ──restore──▶ active
+*   active  ──merge────▶ merged (terminal; row survives as a `mergedInto` redirect)
+*
+* `merged` is terminal: a merged party is never resurrected — historical
+* references resolve THROUGH it to the survivor, so the identity graph stays
+* append-only and auditable.
+*/
+const PARTY_STATE_MACHINE = defineStateMachine({
+	name: "party",
+	transitions: {
+		active: ["archived", "merged"],
+		archived: ["active", "merged"],
+		merged: []
+	}
+});
+//#endregion
+//#region src/domain/normalize.ts
+/**
+* Identity-key normalization — pure, unit-tested. Derives the `identityKeys[]`
+* an entity is deduped on: the SAME real-world email/phone always yields the
+* 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.
+*/
+/** Lowercase + trim an email. Conservative — never strips dots/plus tags. */
+function normalizeEmail(raw) {
+	return raw.trim().toLowerCase();
+}
+/**
+* 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.
+*/
+function normalizePhone(raw) {
+	const parsed = parsePhone(raw.trim());
+	if (isOk(parsed)) return parsed.value.e164;
+	const digits = raw.replace(/\D/g, "");
+	return digits ? `+${digits}` : "";
+}
+/** 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)}`;
+}
+/** A tax-identity dedup key (`vat:...` / `bin:...`) — cross-scope-stable statutory id. */
+function taxIdentityKey(kind, value) {
+	return `${kind}:${value.trim().toUpperCase().replace(/\s+/g, "")}`;
+}
+//#endregion
+//#region src/domain/identity.ts
+/**
+* Identity derivation — PURE functions that turn a `ResolvePartyInput` into the
+* contact points, dedup keys, and display name the repository persists. Kept
+* out of the repository so they are trivially unit-testable in isolation (no
+* Mongo) and the repository stays pure orchestration.
+*/
+/** De-duplicate an array preserving first-seen order. */
+function dedupe(arr) {
+	return [...new Set(arr)];
+}
+/**
+* Turn the input's `emails[]` / `phones[]` into normalized `ContactPoint`s. The
+* first email and first phone are marked primary; blanks are skipped.
+*/
+function buildContactPoints(input) {
+	const points = [];
+	(input.emails ?? []).forEach((value, i) => {
+		if (!value.trim()) return;
+		points.push({
+			type: "email",
+			value,
+			key: contactPointKey("email", value),
+			isPrimary: i === 0,
+			verified: false
+		});
+	});
+	(input.phones ?? []).forEach((value, i) => {
+		if (!value.trim()) return;
+		points.push({
+			type: "phone",
+			value,
+			key: contactPointKey("phone", value),
+			isPrimary: i === 0,
+			verified: false
+		});
+	});
+	return points;
+}
+/**
+* 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.
+*/
+function deriveIdentityKeys(contactPoints, input) {
+	const keys = contactPoints.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}`);
+	return dedupe(keys.filter((k) => k && !k.endsWith(":")));
+}
+/** Best display name from the available signals — never empty. */
+function resolveDisplayName(input, contactPoints) {
+	if (input.displayName?.trim()) return input.displayName.trim();
+	if (input.personName) {
+		const { given, family, preferred } = input.personName;
+		const composed = (preferred?.trim() || [given, family].filter(Boolean).join(" ")).trim();
+		if (composed) return composed;
+	}
+	if (input.legalName?.trim()) return input.legalName.trim();
+	const firstEmail = contactPoints.find((c) => c.type === "email");
+	if (firstEmail) return firstEmail.value;
+	const firstPhone = contactPoints.find((c) => c.type === "phone");
+	if (firstPhone) return firstPhone.value;
+	return "Unnamed party";
+}
+/** The primary (or first) contact-point value of a channel type. */
+function pickPrimary(contactPoints, type) {
+	const cps = contactPoints ?? [];
+	return (cps.find((c) => c.type === type && c.isPrimary) ?? cps.find((c) => c.type === type))?.value;
+}
+//#endregion
+//#region src/domain/merge.ts
+/** Union two string arrays, first-seen order, no duplicates. */
+function unionStrings(a, b) {
+	return [.../* @__PURE__ */ new Set([...a, ...b])];
+}
+/** Union external refs by `(sourceModel, sourceId)` identity. */
+function unionRefs(a, b) {
+	const key = (r) => `${r.sourceModel}:${r.sourceId}`;
+	const seen = new Set(a.map(key));
+	const out = [...a];
+	for (const r of b) if (!seen.has(key(r))) {
+		seen.add(key(r));
+		out.push(r);
+	}
+	return out;
+}
+/**
+* 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).
+*/
+function unionContacts(a, b) {
+	const seen = new Set(a.map((c) => c.key));
+	const out = [...a];
+	for (const c of b) if (!seen.has(c.key)) {
+		seen.add(c.key);
+		out.push({
+			...c,
+			isPrimary: false
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/events/event-constants.ts
+/** PACKAGE_RULES §12: `package:resource.verb`. Emit ONLY these catalog names. */
+const PARTY_EVENTS = {
+	CREATED: "party:party.created",
+	UPDATED: "party:party.updated",
+	ROLE_ADDED: "party:party.role_added",
+	ROLE_REMOVED: "party:party.role_removed",
+	USER_LINKED: "party:party.user_linked",
+	EXTERNAL_REF_ATTACHED: "party:party.external_ref_attached",
+	ARCHIVED: "party:party.archived",
+	RESTORED: "party:party.restored",
+	MERGED: "party:party.merged"
+};
+//#endregion
+//#region src/events/helpers.ts
+/**
+* `createEvent` — thin wrapper over primitives' `createEvent` that stamps
+* `source: 'party'` and lifts `actorId`/`organizationId`/`correlationId` off the
+* `PartyContext`. Use this instead of importing `createEvent` directly so the
+* source stamp + meta stay consistent (PACKAGE_RULES §14).
+*/
+function createEvent(type, payload, ctx, meta) {
+	return createEvent$1(type, payload, {
+		source: "party",
+		...ctx?.actorId !== void 0 ? { actorId: String(ctx.actorId) } : {},
+		...ctx?.organizationId !== void 0 ? { organizationId: String(ctx.organizationId) } : {},
+		...ctx?.correlationId !== void 0 ? { correlationId: ctx.correlationId } : {},
+		...meta
+	});
+}
+//#endregion
+//#region src/repositories/repo-options.ts
+function repoOptionsFromCtx(ctx) {
+	return {
+		...ctx.session !== void 0 ? { session: ctx.session } : {},
+		...ctx.signal !== void 0 ? { signal: ctx.signal } : {},
+		...ctx.retryPolicy !== void 0 ? { retryPolicy: ctx.retryPolicy } : {},
+		...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
+	};
+}
+//#endregion
+//#region src/repositories/party.repository.ts
+/**
+* PartyRepository — the API surface (PACKAGE_RULES §1) and the concrete
+* `PartyPort`. Domain verbs only; CRUD/pagination/query come from mongokit.
+*
+* The identity guarantees:
+*   • `resolveOrCreate` is race-safe — a unique multikey index on `identityKeys`
+*     is the authoritative guard; a concurrent create that loses re-resolves to
+*     the winner (§Concurrency: no check-then-save, E11000 → re-read).
+*   • `merge` transfers the loser's identity keys to the survivor and turns the
+*     loser into a terminal `merged` redirect — historical refs still resolve.
+*/
+const OBJECT_ID_HEX = /^[a-f0-9]{24}$/i;
+var PartyRepository = class extends Repository {
+	events;
+	constructor(model, deps, plugins = []) {
+		super(model, plugins);
+		this.events = deps.events;
+	}
+	/** `update` that never returns null — the party was loaded first; a null means a concurrent delete. */
+	async mustUpdate(id, patch, ctx) {
+		const updated = await this.update(id, patch, repoOptionsFromCtx(ctx));
+		if (!updated) throw new PartyNotFoundError(String(id));
+		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.");
+		if (keys.length > 0) {
+			const existing = await this.getByQuery({
+				identityKeys: { $in: keys },
+				status: { $ne: "merged" }
+			}, {
+				...repoOptionsFromCtx(ctx),
+				throwOnNotFound: false
+			});
+			if (existing) return {
+				party: await this.enrich(existing, input, ctx),
+				created: false
+			};
+		}
+		const displayName = resolveDisplayName(input, contactPoints);
+		try {
+			const created = await this.create({
+				kind: input.kind ?? (input.personName ? "person" : "company"),
+				displayName,
+				...input.legalName !== void 0 ? { legalName: input.legalName } : {},
+				...input.personName !== void 0 ? { personName: input.personName } : {},
+				contactPoints,
+				identityKeys: keys,
+				...input.addresses !== void 0 ? { addresses: input.addresses } : {},
+				...input.taxIdentity !== void 0 ? { taxIdentity: input.taxIdentity } : {},
+				roles: dedupe(input.roles ?? []),
+				externalRefs: input.externalRefs ?? [],
+				userLinks: input.userId ? [input.userId] : [],
+				...input.parentId !== void 0 ? { parentId: input.parentId } : {},
+				...input.metadata !== void 0 ? { metadata: input.metadata } : {}
+			}, repoOptionsFromCtx(ctx));
+			await this.dispatch(PARTY_EVENTS.CREATED, {
+				partyId: String(created._id),
+				kind: created.kind,
+				displayName: created.displayName,
+				roles: created.roles,
+				...ctx.organizationId !== void 0 ? { organizationId: String(ctx.organizationId) } : {}
+			}, created, ctx);
+			return {
+				party: created,
+				created: true
+			};
+		} catch (err) {
+			if (isDuplicateKeyError(err) && keys.length > 0) {
+				const winner = await this.getByQuery({
+					identityKeys: { $in: keys },
+					status: { $ne: "merged" }
+				}, {
+					...repoOptionsFromCtx(ctx),
+					throwOnNotFound: false
+				});
+				if (winner) return {
+					party: await this.enrich(winner, input, ctx),
+					created: false
+				};
+				throw new PartyResolveConflictError(keys[0] ?? "");
+			}
+			throw err;
+		}
+	}
+	async resolveMany(inputs, ctx) {
+		const results = [];
+		for (const input of inputs) results.push(await this.resolveOrCreate(input, ctx));
+		return results;
+	}
+	async snapshot(partyId, ctx) {
+		let party = await this.loadParty(partyId, ctx);
+		if (party.status === "merged" && party.mergedInto) party = await this.loadParty(String(party.mergedInto), ctx);
+		const primaryEmail = pickPrimary(party.contactPoints, "email");
+		const primaryPhone = pickPrimary(party.contactPoints, "phone");
+		return {
+			partyId: String(party._id),
+			kind: party.kind,
+			displayName: party.displayName,
+			...party.legalName !== void 0 ? { legalName: party.legalName } : {},
+			...primaryEmail !== void 0 ? { primaryEmail } : {},
+			...primaryPhone !== void 0 ? { primaryPhone } : {},
+			roles: party.roles,
+			status: party.status,
+			...party.taxIdentity !== void 0 ? { taxIdentity: party.taxIdentity } : {}
+		};
+	}
+	/**
+	* Sync identity onto a party — the canonical "identity changed" verb. The
+	* party OWNS identity mutation (name, contact points, addresses, tax), so
+	* hosts push a facet's current identity here instead of editing it locally.
+	* NEW contact points fold in (deduped, deriving their keys + extending
+	* `identityKeys`); existing primaries are preserved. Idempotent — syncing the
+	* same identity is a no-op. Emits `party:party.updated`.
+	*/
+	async syncIdentity(id, input, ctx) {
+		const party = await this.loadParty(id, ctx);
+		const mergedContacts = unionContacts(party.contactPoints, buildContactPoints(input));
+		const set = {
+			contactPoints: mergedContacts,
+			identityKeys: unionStrings(party.identityKeys, deriveIdentityKeys(mergedContacts, input))
+		};
+		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);
+		await this.dispatch(PARTY_EVENTS.UPDATED, {
+			partyId: String(party._id),
+			changed: Object.keys(set)
+		}, updated, ctx);
+		return updated;
+	}
+	async addRole(id, role, ctx) {
+		const party = await this.loadParty(id, ctx);
+		if (party.roles.includes(role)) return party;
+		const updated = await this.mustUpdate(party._id, { $addToSet: { roles: role } }, ctx);
+		await this.dispatch(PARTY_EVENTS.ROLE_ADDED, {
+			partyId: String(party._id),
+			role
+		}, updated, ctx);
+		return updated;
+	}
+	async removeRole(id, role, ctx) {
+		const party = await this.loadParty(id, ctx);
+		if (!party.roles.includes(role)) return party;
+		const updated = await this.mustUpdate(party._id, { $pull: { roles: role } }, ctx);
+		await this.dispatch(PARTY_EVENTS.ROLE_REMOVED, {
+			partyId: String(party._id),
+			role
+		}, updated, ctx);
+		return updated;
+	}
+	async linkUser(id, userId, ctx) {
+		const party = await this.loadParty(id, ctx);
+		if (party.userLinks.includes(userId)) return party;
+		const updated = await this.mustUpdate(party._id, { $addToSet: { userLinks: userId } }, ctx);
+		await this.dispatch(PARTY_EVENTS.USER_LINKED, {
+			partyId: String(party._id),
+			userId
+		}, 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);
+		await this.dispatch(PARTY_EVENTS.EXTERNAL_REF_ATTACHED, {
+			partyId: String(party._id),
+			sourceModel: ref.sourceModel,
+			sourceId: ref.sourceId
+		}, updated, ctx);
+		return updated;
+	}
+	async archive(id, ctx) {
+		const party = await this.loadParty(id, ctx);
+		PARTY_STATE_MACHINE.assertTransition(String(party._id), party.status, "archived");
+		const claimed = await this.claim(String(party._id), {
+			from: "active",
+			to: "archived"
+		}, void 0, repoOptionsFromCtx(ctx));
+		if (!claimed) throw new PartyVersionConflictError(id, party.version);
+		await this.dispatch(PARTY_EVENTS.ARCHIVED, { partyId: String(party._id) }, claimed, ctx);
+		return claimed;
+	}
+	async restore(id, ctx) {
+		const party = await this.loadParty(id, ctx);
+		PARTY_STATE_MACHINE.assertTransition(String(party._id), party.status, "active");
+		const claimed = await this.claim(String(party._id), {
+			from: "archived",
+			to: "active"
+		}, void 0, repoOptionsFromCtx(ctx));
+		if (!claimed) throw new PartyVersionConflictError(id, party.version);
+		await this.dispatch(PARTY_EVENTS.RESTORED, { partyId: String(party._id) }, claimed, ctx);
+		return claimed;
+	}
+	/**
+	* 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).
+	*/
+	async merge(sourceId, targetId, ctx) {
+		if (sourceId === targetId) throw new PartyMergeError("Cannot merge a party into itself.", sourceId, targetId);
+		const source = await this.loadParty(sourceId, ctx);
+		const target = await this.loadParty(targetId, ctx);
+		if (source.status === "merged") throw new PartyMergeError("Source party is already merged.", sourceId, targetId);
+		if (target.status === "merged") throw new PartyMergeError("Target party is already merged (would create a redirect chain).", sourceId, targetId);
+		const mergedKeys = unionStrings(target.identityKeys, source.identityKeys);
+		const mergedRoles = unionStrings(target.roles, source.roles);
+		const mergedUsers = unionStrings(target.userLinks, source.userLinks);
+		const mergedRefs = unionRefs(target.externalRefs, source.externalRefs);
+		const mergedContacts = unionContacts(target.contactPoints, source.contactPoints);
+		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 survivor = await this.loadParty(targetId, ctx);
+		await this.dispatch(PARTY_EVENTS.MERGED, {
+			sourceId,
+			targetId,
+			absorbedKeys: Math.max(0, absorbed)
+		}, survivor, ctx);
+		return survivor;
+	}
+	/** Load a party by ObjectId hex, or throw the typed not-found (§P9-style). */
+	async loadParty(id, ctx) {
+		const party = await this.getById(id, {
+			...repoOptionsFromCtx(ctx),
+			throwOnNotFound: false,
+			...OBJECT_ID_HEX.test(id) ? { idField: "_id" } : {}
+		});
+		if (!party) throw new PartyNotFoundError(id);
+		return party;
+	}
+	/** Add any new roles/refs/user/keys from `input` onto an already-resolved party. */
+	async enrich(party, input, ctx) {
+		const add = {};
+		const newRoles = (input.roles ?? []).filter((r) => !party.roles.includes(r));
+		if (newRoles.length > 0) add.roles = { $each: newRoles };
+		if (input.userId && !party.userLinks.includes(input.userId)) add.userLinks = input.userId;
+		const newRefs = (input.externalRefs ?? []).filter((r) => !party.externalRefs.some((e) => e.sourceModel === r.sourceModel && e.sourceId === r.sourceId));
+		if (newRefs.length > 0) add.externalRefs = { $each: newRefs };
+		if (Object.keys(add).length === 0) return party;
+		const updated = await this.mustUpdate(party._id, { $addToSet: add }, ctx);
+		for (const role of newRoles) await this.dispatch(PARTY_EVENTS.ROLE_ADDED, {
+			partyId: String(party._id),
+			role
+		}, updated, ctx);
+		return updated;
+	}
+	/** Route a domain event with meta stamped from ctx + the party's org. */
+	async dispatch(type, payload, party, ctx) {
+		await this.events.dispatch(createEvent(type, payload, ctx, {
+			resource: "party",
+			resourceId: String(party._id)
+		}), ctx);
+	}
+};
+//#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
+/**
+* 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.
+*/
+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.`);
+	}
+}
+//#endregion
+//#region src/engine/run-unit.ts
+/**
+* runUnit — transaction + post-commit-publish discipline (PACKAGE_RULES §P8.1),
+* identical in contract to crm / refit / review / cart / invoice.
+*
+*   1. Events dispatched inside the unit are QUEUED (`ctx[PENDING_EVENTS]`) and
+*      flushed only AFTER commit (the queue resets on retry) — a rollback can't
+*      leak ghost events to in-process subscribers. Outbox rows stay inside the
+*      transaction; the relay reads only committed rows.
+*   2. A caller-owned `ctx.session` reuses the caller's queue when present.
+*/
+async function runUnit(config, ctx, body) {
+	const bag = ctx;
+	const externalQueue = bag[PENDING_EVENTS];
+	if (ctx.session) return body(externalQueue ? {
+		...bag,
+		[PENDING_EVENTS]: externalQueue
+	} : ctx);
+	const pending = [];
+	const result = await withTransaction(config.connection, async (session) => {
+		pending.length = 0;
+		return body({
+			...bag,
+			session,
+			[PENDING_EVENTS]: pending
+		});
+	}, config.allowNonTransactional ? { allowFallback: true } : {});
+	await flushPending(config.events, pending, config.logger);
+	return result;
+}
+//#endregion
+//#region src/engine/create-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.
+*
+* @example
+* ```ts
+* import mongoose from 'mongoose';
+* import { createParty } from '@classytic/party';
+*
+* 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'] },
+*   {},
+* );
+* ```
+*/
+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) } } : {}
+	});
+	return Object.freeze({
+		models,
+		repositories: Object.freeze({ party: repository }),
+		port: repository,
+		events,
+		config: Object.freeze(resolved),
+		withTransaction(ctx, body) {
+			return runUnit({
+				connection: config.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()));
+		},
+		async dispose() {
+			await events.close();
+		}
+	});
+}
+//#endregion
+//#region src/events/event-catalog.ts
+/**
+* Zod-source event catalog (PACKAGE_RULES §18). One Zod schema per event is the
+* single source of truth — runtime validation, static types, and arc's
+* `EventRegistry` (OpenAPI + `arc describe`) all derive from it. Structurally
+* identical to arc's `EventDefinitionOutput`; we never import arc.
+*
+* Timestamps use `z.iso.datetime()`, never `z.coerce.date()` (§25).
+*/
+function definePartyEvent(input) {
+	const { name, version = 1, description, zodSchema } = input;
+	return {
+		name,
+		version,
+		description,
+		zodSchema,
+		schema: z.toJSONSchema(zodSchema),
+		create(payload, meta) {
+			return createEvent$1(name, payload, {
+				source: "party",
+				...meta
+			});
+		}
+	};
+}
+const partyKind = z.enum([
+	"person",
+	"company",
+	"group"
+]);
+const partyRole = z.enum([
+	"customer",
+	"supplier",
+	"contact",
+	"employee",
+	"partner"
+]);
+const createdSchema = z.object({
+	partyId: z.string(),
+	kind: partyKind,
+	displayName: z.string(),
+	roles: z.array(partyRole),
+	organizationId: z.string().optional()
+});
+const updatedSchema = z.object({
+	partyId: z.string(),
+	changed: z.array(z.string())
+});
+const roleChangedSchema = z.object({
+	partyId: z.string(),
+	role: partyRole
+});
+const userLinkedSchema = z.object({
+	partyId: z.string(),
+	userId: z.string()
+});
+const externalRefSchema = z.object({
+	partyId: z.string(),
+	sourceModel: z.string(),
+	sourceId: z.string()
+});
+const lifecycleSchema = z.object({ partyId: z.string() });
+const mergedSchema = z.object({
+	sourceId: z.string(),
+	targetId: z.string(),
+	absorbedKeys: z.number().int().nonnegative()
+});
+const partyEventDefinitions = [
+	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
+	})
+];
+//#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 };