@classytic/party 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 All notable changes to `@classytic/party` are documented here. Adheres to
 [Keep a Changelog](https://keepachangelog.com/) and [SemVer](https://semver.org/).
 
+## [0.2.0] — 2026-08-17
+
+### Added
+- `defineParty(shape)` / `blueprint.bind(connection, runtime)` — describe/bind construction API replacing `createParty`; describe phase is pure and safe at import time
+- `SubjectRef` / `PARTY_MODEL_NAME` exported from `./domain/subject` — canonical polymorphic subject seam for cross-kernel refs (`@classytic/access`, `@classytic/muster`, etc.)
+- `src/maintenance/phone-identity-repair.ts` — repair utility for phone-identity drift
+
+### Removed
+- `createParty` (replaced by `defineParty`)
+
+## 1.0.0 - 2026-08-07 (unpublished)
+
+### Requirements
+
+- **New peer dependency: `@classytic/contact >=0.1.0`** — install it alongside
+  this package. It owns contact-point canonicalisation (E.164 phones, emails),
+  which `resolveOrCreate` / `syncIdentity` derive their `identityKeys` from.
+  A PEER rather than a regular dependency on purpose: npm may nest a regular one
+  under `party/node_modules`, giving the host a second module instance, and then
+  `err instanceof PhoneFormatError` is `false` at a host catch site that imported
+  its own copy — a guard that compiles, runs, and matches nothing.
+
+### Breaking
+
+- **Contact input that cannot be canonicalised now THROWS** instead of becoming
+  an identity key. A phone that is not a valid, dialable number raises
+  `PartyPhoneFormatError` (400 / `party.phone_invalid`); an unparseable email
+  raises `EmailFormatError`. `0.1.0` degraded both — a rejected phone became
+  `+${digits}`, producing keys like `phone:+01309000993` that are neither a
+  national number nor E.164, so two spellings of one person keyed differently and
+  the identity forked silently. There is no lenient variant.
+- **Phone canonicalisation requires a region for national-format input.**
+  `PartyShape.defaultPhoneRegion` (ISO 3166-1 alpha-2, supplied by the
+  deployment — this kernel names no country). Unset ⇒ E.164-only input is
+  accepted and a national format is refused rather than guessed at. An explicit
+  `+…` number is never re-read through the region.
+- **`ContactPoint.value` stores the canonical E.164**, with the caller's original
+  spelling preserved as `ContactPoint.input` (never keyed, never matched on).
+
+### Changed
+
+- Added `PartyShape.identityContactTypes` (`email | phone`, both by default).
+  A host can exclude shared contact channels from automatic identity resolution
+  while retaining normalized contact points. Tax identifiers and external
+  references remain authoritative. Existing defaults are unchanged.
+- The unique `identityKeys` index now explicitly includes only non-empty arrays.
+  This permits multiple name-only or contact-only parties when contact channels
+  are non-authoritative, without weakening uniqueness for real identity keys.
+- Canonical email output is unchanged for every valid address — trim plus
+  lowercase, and still **no** Gmail-dot or `+tag` folding, since folding a
+  provider's rule merges two distinct inboxes into one identity. No existing key
+  is re-derived.
+- `libphonenumber-js` is no longer a direct dependency.
+
+## 0.1.1 - 2026-07-22 (unpublished)
+
+### Changed
+- Internal: `InProcess*Bus` is now a thin subclass of `@classytic/primitives/event-infra`'s shared `InProcessEventBus` (dedup / error-isolation / close semantics unchanged); `MemoryOutboxStore` re-exported from the shared runtime where applicable. No public API, event-name, or wire-envelope change. Requires `@classytic/primitives >=0.13.0`.
+
 ## [0.1.0] - 2026-07-13
 
 Initial release — the Party / Business-Partner identity kernel.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Classytic
+Copyright (c) 2026 Classytic LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -48,12 +48,12 @@ Peers: `@classytic/mongokit >=3.20`, `@classytic/primitives >=0.9.1`,
 
 ```ts
 import mongoose from 'mongoose';
-import { createParty } from '@classytic/party';
+import { defineParty } from '@classytic/party';
 
-const party = await createParty({
-  connection: mongoose.connection,
+const party = defineParty({
   multiTenant: false, // identity is company-wide here; pass true for per-tenant SaaS
-});
+  defaultPhoneRegion: 'BD',
+}).bind(mongoose.connection);
 
 // Resolve-or-create by ANY identity signal — race-safe, dedup by email/phone/vat.
 const { party: ada, created } = await party.port.resolveOrCreate(
@@ -76,6 +76,27 @@ const snap = await party.port.snapshot(String(ada._id), {});
 await party.repositories.party.merge(dupId, survivorId, {});
 ```
 
+### Contacts are not always proof of identity
+
+Email and phone are authoritative identity keys by default, preserving the
+race-safe behavior existing commerce hosts rely on. Domains where people often
+share contact details can keep those values as contact data without allowing
+them to collapse two parties:
+
+```ts
+const party = defineParty({
+  multiTenant: true,
+  defaultPhoneRegion: 'GB',
+  identityContactTypes: [],
+}).bind(mongoose.connection);
+```
+
+Tax identifiers and explicit external references remain authoritative. A
+domain-specific facet (for example a legal Client) can perform candidate-match
+review and then attach its stable external reference or explicitly merge the
+confirmed duplicate. This setting shapes persisted `identityKeys`; migrate
+existing rows before changing it on a live deployment.
+
 ## The `PartyPort` — the reusable contract
 
 Consuming domains depend on `engine.port` (a `PartyPort`), not the models:
@@ -111,3 +132,7 @@ entities — that's the duplication this kernel exists to remove.
 ## License
 
 MIT
+
+## Trademark
+
+Code is MIT-licensed. "Classytic"/"arc" names + logos are trademarks of Classytic LLC — see [TRADEMARK.md](TRADEMARK.md).

package/dist/events.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { DomainEvent, EventHandler, EventMeta, EventTransport } from "@classytic/primitives/events";
+import { InProcessEventBus } from "@classytic/primitives/event-infra";
 import { Types } from "mongoose";
 import { OperationContext } from "@classytic/primitives/context";
 import "@classytic/primitives/reference";
@@ -192,16 +193,10 @@ interface PartyLogger {
 declare function createEvent<T>(type: string, payload: T, ctx?: PartyContext, meta?: Partial<EventMeta>): DomainEvent<T>;
 //#endregion
 //#region src/events/in-process-bus.d.ts
-declare class InProcessPartyBus implements EventTransport {
-  readonly name = "in-process-party";
-  private subs;
-  private readonly logger;
+declare class InProcessPartyBus extends InProcessEventBus {
   constructor(options?: {
-    logger?: PartyLogger | undefined;
+    logger?: PartyLogger;
   });
-  publish(event: DomainEvent): Promise<void>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
 }
 //#endregion
 //#region src/events/dispatch.d.ts

package/dist/events.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { createEvent as createEvent$1, matchEventPattern } from "@classytic/primitives/events";
+import { createEvent as createEvent$1 } from "@classytic/primitives/events";
+import { InProcessEventBus } from "@classytic/primitives/event-infra";
 //#region src/events/event-constants.ts
 /** PACKAGE_RULES §12: `package:resource.verb`. Emit ONLY these catalog names. */
 const PARTY_EVENTS = {
@@ -158,37 +159,24 @@ function createEvent(type, payload, ctx, meta) {
 //#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.
+* `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 {
-	name = "in-process-party";
-	subs = [];
-	logger;
+var InProcessPartyBus = class extends InProcessEventBus {
 	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 = [];
+		const partyLogger = options?.logger;
+		super({
+			name: "in-process-party",
+			logLabel: "party",
+			logger: partyLogger?.error ? { error: (message, ...args) => partyLogger.error?.(message, { args }) } : null
+		});
 	}
 };
 //#endregion
@@ -211,7 +199,9 @@ var PartyEventDispatcher = class {
 		return this.transport.publish(event);
 	}
 	subscribe(pattern, handler) {
-		return this.transport.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